1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
|
<h4 class="subsubsection">How to Signal an Error</h4> <p><em>Signaling</em> an error means beginning error processing. Error processing normally aborts all or part of the running program and returns to a point that is set up to handle the error (see <a href="processing-of-errors">Processing of Errors</a>). Here we describe how to signal an error. </p> <p>Most errors are signaled automatically within Lisp primitives which you call for other purposes, such as if you try to take the <small>CAR</small> of an integer or move forward a character at the end of the buffer. You can also signal errors explicitly with the functions <code>error</code> and <code>signal</code>. </p> <p>Quitting, which happens when the user types <kbd>C-g</kbd>, is not considered an error, but it is handled almost like an error. See <a href="quitting">Quitting</a>. </p> <p>Every error specifies an error message, one way or another. The message should state what is wrong (“File does not exist”), not how things ought to be (“File must exist”). The convention in Emacs Lisp is that error messages should start with a capital letter, but should not end with any sort of punctuation. </p> <dl> <dt id="error">Function: <strong>error</strong> <em>format-string &rest args</em>
</dt> <dd>
<p>This function signals an error with an error message constructed by applying <code>format-message</code> (see <a href="formatting-strings">Formatting Strings</a>) to <var>format-string</var> and <var>args</var>. </p> <p>These examples show typical uses of <code>error</code>: </p> <div class="example"> <pre class="example">(error "That is an error -- try something else")
error→ That is an error -- try something else
</pre>
<pre class="example">(error "Invalid name `%s'" "A%%B")
error→ Invalid name ‘A%%B’
</pre>
</div> <p><code>error</code> works by calling <code>signal</code> with two arguments: the error symbol <code>error</code>, and a list containing the string returned by <code>format-message</code>. </p> <p>Typically grave accent and apostrophe in the format translate to matching curved quotes, e.g., <tt>"Missing `%s'"</tt> might result in <tt>"Missing ‘foo’"</tt>. See <a href="text-quoting-style">Text Quoting Style</a>, for how to influence or inhibit this translation. </p> <p><strong>Warning:</strong> If you want to use your own string as an error message verbatim, don’t just write <code>(error <var>string</var>)</code>. If <var>string</var> <var>string</var> contains ‘<samp>%</samp>’, ‘<samp>`</samp>’, or ‘<samp>'</samp>’ it may be reformatted, with undesirable results. Instead, use <code>(error "%s"
<var>string</var>)</code>. </p>
</dd>
</dl> <dl> <dt id="signal">Function: <strong>signal</strong> <em>error-symbol data</em>
</dt> <dd>
<p>This function signals an error named by <var>error-symbol</var>. The argument <var>data</var> is a list of additional Lisp objects relevant to the circumstances of the error. </p> <p>The argument <var>error-symbol</var> must be an <em>error symbol</em>—a symbol defined with <code>define-error</code>. This is how Emacs Lisp classifies different sorts of errors. See <a href="error-symbols">Error Symbols</a>, for a description of error symbols, error conditions and condition names. </p> <p>If the error is not handled, the two arguments are used in printing the error message. Normally, this error message is provided by the <code>error-message</code> property of <var>error-symbol</var>. If <var>data</var> is non-<code>nil</code>, this is followed by a colon and a comma separated list of the unevaluated elements of <var>data</var>. For <code>error</code>, the error message is the <small>CAR</small> of <var>data</var> (that must be a string). Subcategories of <code>file-error</code> are handled specially. </p> <p>The number and significance of the objects in <var>data</var> depends on <var>error-symbol</var>. For example, with a <code>wrong-type-argument</code> error, there should be two objects in the list: a predicate that describes the type that was expected, and the object that failed to fit that type. </p> <p>Both <var>error-symbol</var> and <var>data</var> are available to any error handlers that handle the error: <code>condition-case</code> binds a local variable to a list of the form <code>(<var>error-symbol</var> .
<var>data</var>)</code> (see <a href="handling-errors">Handling Errors</a>). </p> <p>The function <code>signal</code> never returns. </p> <div class="example"> <pre class="example">(signal 'wrong-number-of-arguments '(x y))
error→ Wrong number of arguments: x, y
</pre>
<pre class="example">(signal 'no-such-error '("My unknown error condition"))
error→ peculiar error: "My unknown error condition"
</pre>
</div> </dd>
</dl> <dl> <dt id="user-error">Function: <strong>user-error</strong> <em>format-string &rest args</em>
</dt> <dd><p>This function behaves exactly like <code>error</code>, except that it uses the error symbol <code>user-error</code> rather than <code>error</code>. As the name suggests, this is intended to report errors on the part of the user, rather than errors in the code itself. For example, if you try to use the command <code>Info-history-back</code> (<kbd>l</kbd>) to move back beyond the start of your Info browsing history, Emacs signals a <code>user-error</code>. Such errors do not cause entry to the debugger, even when <code>debug-on-error</code> is non-<code>nil</code>. See <a href="error-debugging">Error Debugging</a>. </p></dd>
</dl> <blockquote> <p><b>Common Lisp note:</b> Emacs Lisp has nothing like the Common Lisp concept of continuable errors. </p>
</blockquote><div class="_attribution">
<p class="_attribution-p">
Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
<a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Signaling-Errors.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Signaling-Errors.html</a>
</p>
</div>
|
