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 (шаблон, …)

: error (идентификатор, шаблон, …)

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

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

Вызов 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, управляющие последовательности в шаблоне (например, "\n" => новая строка) обрабатываются независимо от того, определен ли шаблон с одинарными кавычками, при условии, что существует два или более входных аргументов. Для отключения расширения управляющих последовательностей используйте две обратные косые черты перед последовательностью (например, "\\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 (имя)

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

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

См. также: help.

: beep ()

Издаёт звуковой сигнал (или визуальный звонок).

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

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

: значение = beep_on_error ()

: старое_значение = beep_on_error (новое_значение)

: beep_on_error (новое_значение, "локально")

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

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