Next: , Previous: , Up: Errors   [Contents][Index] 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, signal, and others.

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

SXEmacs has a rich hierarchy of error symbols predefined via deferror.





The five most common errors you will probably use or base your new errors off of are syntax-error, invalid-argument, invalid-state, invalid-operation, and invalid-change. Note the semantic differences:

Function: error datum &rest args

This function signals a non-continuable error.

datum should normally be an error symbol, i.e. a symbol defined using define-error. args will be made into a list, and datum and args passed as the two arguments to signal, the most basic error handling function.

This error is not continuable: you cannot continue execution after the error using the debugger r command. See also cerror.

The correct semantics of args varies from error to error, but for most errors that need to be generated in Lisp code, the first argument should be a string describing the *context* of the error (i.e. the exact operation being performed and what went wrong), and the remaining arguments or \"frobs\" (most often, there is one) specify the offending object(s) and/or provide additional details such as the exact error when a file error occurred, e.g.:

For historical compatibility, DATUM can also be a string. In this case, datum and args are passed together as the arguments to format, and then an error is signalled using the error symbol error and formatted string. Although this usage of error is very common, it is deprecated because it totally defeats the purpose of having structured errors. There is now a rich set of defined errors to use.

See also cerror, signal, and signal-error."

These examples show typical uses of error:

(error 'syntax-error
       "Dialog descriptor must supply at least one button"
(error "You have committed an error.
        Try something else.")
     error→ You have committed an error.
        Try something else.
(error "You have committed %d errors." 10)
     error→ You have committed 10 errors.

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: cerror datum &rest args

This function behaves like error, except that the error it signals is continuable. That means that debugger commands c and r can resume execution.

Function: signal error-symbol data

This function signals a continuable 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 SXEmacs Lisp classifies different sorts of errors.

The number and significance of the objects in data depends on error-symbol. For example, with a wrong-type-argument error, there are two objects in the list: a predicate that describes the type that was expected, and the object that failed to fit that type. See Error Symbols, for a description of error symbols.

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) (see Handling Errors). If the error is not handled, these two values are used in printing the error message.

The function signal can return, if the debugger is invoked and the user invokes the “return from signal” option. If you want the error not to be continuable, use signal-error instead.

Note: In FSF Emacs signal never returns.

(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 (no-such-error "My unknown error condition")
Function: signal-error error-symbol data

This function behaves like signal, except that the error it signals is not continuable.

Macro: check-argument-type predicate argument

This macro checks that argument satisfies predicate. If that is not the case, it signals a continuable wrong-type-argument error until the returned value satisfies predicate, and assigns the returned value to argument. In other words, execution of the program will not continue until predicate is met.

argument is not evaluated, and should be a symbol. predicate is evaluated, and should name a function.

As shown in the following example, check-argument-type is useful in low-level code that attempts to ensure the sanity of its data before proceeding.

(defun cache-object-internal (object wlist)
  ;; Before doing anything, make sure that wlist is indeed
  ;; a weak list, which is what we expect.
  (check-argument-type 'weak-list-p wlist)

Next: , Previous: , Up: Errors   [Contents][Index]