12.1.1 引发错误 ¶

错误最常见的用途是检查函数的输入参数。下面的示例中，如果函数 f 在没有任何输入参数的情况下被调用，则会调用 error 函数。

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

当 error 函数被调用时，它会打印给定的消息并返回到 Octave 提示符。这意味着调用 error 之后的任何代码都不会被执行。

也可以为错误分配一个标识字符串。如果错误具有这样的 ID，用户可以捕获此错误，这将在下一节中描述。要为错误分配 ID，只需调用 error 并传入两个字符串参数，其中第一个是标识字符串，第二个是实际的错误信息。请注意，错误 ID 的格式为 "NAMESPACE:ERROR-NAME"。命名空间 "Octave" 用于 Octave 自身的错误。任何其他字符串都可用作用户自定义错误的命名空间。

error (msg) ¶

error (template, …) ¶

error (id, template, …) ¶

error (errstruct) ¶

显示错误消息并停止 m 文件执行。

输入参数 msg 是一个简单的字符串，前面会加上文本 ‘error: ’。生成的消息将打印到 stderr 流。另外，第一个输入参数也可以是一个模板字符串 template，它使用与 printf 函数族相同的规则（参见 格式化输出）。仅当模板字符串后面有其他参数时，才对单引号字符向量进行格式化。如果没有其他参数，则模板字符串将按字面使用（即，不解释单引号字符向量中的任何转义序列）。

可选的 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);

这样只有在发现错误时才会停止执行。

该函数也可以使用错误结构体来调用，例如从 lasterror 返回的错误结构体。errstruct 参数必须包含 message、identifier 和 stack 字段。前两个字段是字符串，其含义如上所述。stack 字段必须是一个结构体或结构体数组，包含 file、name 和 line 字段。

实现说明：为了与 MATLAB 兼容，只要有两个或更多输入参数，无论 template 是使用单引号还是双引号定义，其中的转义序列（例如 "\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 (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" 选项调用时，该变量会在函数及其调用的任何子程序范围内局部更改。退出函数时将恢复原始变量值。