12.1.1 Возбуждение ошибок

Чаще всего ошибки используются для проверки входных аргументов функций. В следующем примере вызывается функция error, если функция f вызвана без входных аргументов.

function f (arg1)
  if (nargin == 0)
    error ("not enough input arguments");
  endif
endfunction

При вызове функции error она выводит указанное сообщение и возвращается к приглашению Octave. Это означает, что код после вызова error выполнен не будет.

Ошибке также можно присвоить строку идентификатора. Если у ошибки есть такой идентификатор, пользователь может перехватить эту ошибку, как описано в следующем разделе. Чтобы присвоить ошибке идентификатор, просто вызовите error с двумя строковыми аргументами: первый — это строка идентификатора, второй — собственно сообщение об ошибке. Обратите внимание, что идентификаторы ошибок имеют формат "NAMESPACE:ERROR-NAME". Пространство имён "Octave" используется для собственных ошибок Octave. Любая другая строка может использоваться как пространство имён для собственных ошибок пользователя.

: error (template, …)

: error (id, template, …)

Вывести сообщение об ошибке и остановить выполнение m-файла.

Отформатировать необязательные аргументы с помощью строки шаблона template, используя те же правила, что и для семейства функций printf (см. Форматированный вывод), и вывести полученное сообщение в поток stderr. Форматирование выполняется только для символьных векторов в одинарных кавычках, если после строки шаблона указаны дополнительные аргументы. Если дополнительных аргументов нет, строка шаблона используется буквально (то есть последовательности экранирования в символьных векторах в одинарных кавычках не интерпретируются). Перед сообщением добавляется ‘error: ’.

Необязательный аргумент id позволяет программистам пометить ошибку специальным идентификатором, чтобы пользователи могли позднее получить его (с помощью lasterr или lasterror) и определить источник ошибки. Идентификатор должен содержать как минимум один символ двоеточия (':') и не должен содержать пробельных символов. Он должен представлять собой строку вида "NAMESPACE:ERROR-NAME". Для собственных ошибок Octave используется пространство имён "Octave" (см. error_ids). Например:

error ("MyNameSpace:wrong-type-argument",
       "fcn_name: argument should be numeric");

Вызов error также устанавливает внутреннее состояние ошибки Octave, в результате чего управление возвращается на верхний уровень без выполнения дальнейших команд. Это полезно для прерывания выполнения функций или сценариев.

Если сообщение об ошибке не заканчивается символом новой строки, Octave выведет трассировку всех вызовов функций, приведших к ошибке. Например, для следующих определений функций:

function f () g (); end
function g () h (); end
function h () nargin == 1 || error ("nargin != 1"); end

вызов функции f приведёт к выводу списка сообщений, которые помогут быстро найти точное место возникновения ошибки:

f ()
error: nargin != 1
error: called from:
error:   h at line 1, column 27
error:   g at line 1, column 15
error:   f at line 1, column 15

Если сообщение об ошибке заканчивается символом новой строки, Octave выведет сообщение, но не будет отображать трассировку при возврате управления на верхний уровень. Например, если в предыдущем примере изменить сообщение об ошибке так, чтобы оно заканчивалось символом новой строки, Octave выведет только одно сообщение:

function h () nargin == 1 || error ("nargin != 1\n"); end
f ()
error: nargin != 1

Пустая строка ("") в качестве аргумента error игнорируется, и выполнение кода продолжается, как если бы инструкция была NOP. Это сделано для совместимости с MATLAB. Это также позволяет писать код, например:

err_msg = "";
if (CONDITION 1)
  err_msg = "CONDITION 1 found";
elseif (CONDITION2)
  err_msg = "CONDITION 2 found";
...
endif
error (err_msg);

который останавливает выполнение только в случае обнаружения ошибки.

Примечание по реализации: для совместимости с MATLAB последовательности экранирования в template (например, "\n" => символ новой строки) обрабатываются независимо от того, задана ли template в одинарных кавычках, если передано два или более входных аргумента. Чтобы отключить обработку последовательностей экранирования, используйте перед последовательностью ещё одну обратную косую черту (например, "\\n") или используйте функцию regexptranslate.

См. также: warning, lasterror.

Поскольку ошибки часто используются, когда входные данные функции некорректны, в Octave есть функции, упрощающие написание такого кода. При вызове функции print_usage она считывает справочный текст функции, вызвавшей print_usage, и выводит полезное сообщение об ошибке. Если справочный текст написан в Texinfo, можно вывести сообщение об ошибке, содержащее только прототипы функций, описанные в разделах @deftypefn справочного текста. Если справочный текст написан не в Texinfo, сообщение об ошибке содержит весь текст справки.

Рассмотрим следующую функцию.

## -*- texinfo -*-
## @deftypefn {} f (@var{arg1})
## Function help text goes here...
## @end deftypefn
function f (arg1)
  if (nargin == 0)
    print_usage ();
  endif
endfunction

При вызове без входных аргументов она выводит следующую ошибку.

f ()

-|  error: Invalid call to f.  Correct usage is:
-|
-|   -- f (ARG1)
-|
-|
-|  Additional help for built-in functions and operators is
-|  available in the online version of the manual.  Use the command
-|  'doc <topic>' to search the manual index.
-|
-|  Help and information about Octave is also available on the WWW
-|  at https://www.octave.org and via the help@octave.org
-|  mailing list.

: print_usage ()

: print_usage (name)

Вывести сообщение об использовании функции name.

При вызове без входных аргументов функция print_usage отображает сообщение об использовании выполняемой в данный момент функции.

См. также: help.

: beep ()

Подать звуковой сигнал через динамик (или визуальный сигнал).

Эта функция отправляет символ сигнала тревоги "\a" в терминал. В зависимости от настроек пользователя это может вызвать звуковой сигнал, визуальный сигнал или не вызвать никаких действий.

См. также: puts, fputs, printf, fprintf.

: val = beep_on_error ()

: old_val = beep_on_error (new_val)

: old_val = beep_on_error (new_val, "local")

Получить или задать внутреннюю переменную, которая определяет, будет ли Octave пытаться подать звуковой сигнал терминала перед выводом сообщения об ошибке.

При вызове из функции с параметром "local" переменная изменяется локально для этой функции и всех вызываемых ею подпрограмм. При выходе из функции восстанавливается исходное значение переменной.