10.5.3.1 How to Signal an Error

Signaling 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 (voir la section How Emacs Processes Errors). Here we describe how to signal an error.

Most errors are signaled “automatically” within Lisp primitives which you call for other purposes, such as if you try to take the CAR of an integer or move forward a character at the end of the buffer. You can also signal errors explicitly with the functions error and signal.

Quitting, which happens when the user types C-g, is not considered an error, but it is handled almost like an error. Voir la section Quitting.

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.

Function: error format-string &rest args

This function signals an error with an error message constructed by applying format (voir la section Formatting Strings) to format-string and args.

These examples show typical uses of error:

(error "That is an error -- try something else") error--> That is an error -- try something else (error "You have committed %d errors" 10) error--> You have committed 10 errors

error works by calling signal with two arguments: the error symbol error, and a list containing the string returned by format.

Warning: If you want to use your own string as an error message verbatim, don't just write (error string). If string contains ‘%’, it will be interpreted as a format specifier, with undesirable results. Instead, use (error "%s" string).

Function: signal error-symbol data

This function signals an error named by error-symbol. The argument data is a list of additional Lisp objects relevant to the circumstances of the error.

The argument error-symbol must be an error symbol—a symbol bearing a property error-conditions whose value is a list of condition names. This is how Emacs Lisp classifies different sorts of errors. Voir la section Error Symbols and Condition Names, for a description of error symbols, error conditions and condition names.

If the error is not handled, the two arguments are used in printing the error message. Normally, this error message is provided by the error-message property of error-symbol. If data is non-nil, this is followed by a colon and a comma separated list of the unevaluated elements of data. For error, the error message is the CAR of data (that must be a string). Subcategories of file-error are handled specially.

The number and significance of the objects in data depends on error-symbol. For example, with a wrong-type-arg 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.

Both error-symbol and data are available to any error handlers that handle the error: condition-case binds a local variable to a list of the form (error-symbol . data) (voir la section Writing Code to Handle Errors).

The function signal never returns (though in older Emacs versions it could sometimes return).

(signal 'wrong-number-of-arguments '(x y)) error--> Wrong number of arguments: x, y (signal 'no-such-error '("My unknown error condition")) error--> peculiar error: "My unknown error condition"

Common Lisp note: Emacs Lisp has nothing like the Common Lisp concept of continuable errors.

Ce document a été généré par Eric Reinbold le 13 Octobre 2007 en utilisant texi2html 1.78.