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. Это форматирование выполняется только для однострочных символьных векторов, если за строкой шаблона следуют дополнительные аргументы. Если дополнительных аргументов нет, строка шаблона используется буквально (т.е. без интерпретации каких-либо escape-последовательностей в однострочных символьных векторах). Сообщение предваряется ‘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 escape-последовательности в template (например, "\n" => новая строка) обрабатываются независимо от того, определен ли template с одинарными кавычками, при условии, что есть два или более входных аргумента. Чтобы отключить расширение escape-последовательностей, используйте второй обратный слэш перед последовательностью (например, "\\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", переменная изменяется локально для функции и любых вызываемых подпрограмм. Исходное значение переменной восстанавливается при выходе из функции.