Previous: , Up: Non-Local Exits   [Contents][Index]


5.13.4.4 Errors

Errors are a type of non-local exit; when a form can not be evaluated for some reason an error is normally signalled. If an error-handler has been installed for that type of error, control is passed to the handler for that error, and evaluation continues. If there is no suitable handler, control is passed back to the innermost input loop and a suitable error message is printed.

Function: signal error-symbol data

Signals that an error has happened. error-symbol is a symbol classifying the type of error, it should have a property error-message (a string) which is the error message to be printed.

data is a list of objects which are relevant to the error — they will be made available to any error-handler or printed with the error message otherwise.

(signal 'void-value '(some-symbol))
    error→ Value as variable is void: some-symbol
Function: error template #!rest values

Same as (signal 'error string), where string is a string formatted by template and VALUES. (see Formatted Output)

Variable: debug-on-error

This variable controls the condition to enter the Lisp debugger. When the debugger exits the error is signalled as normal.

If it’s t, then the debugger starts if the control is not inside of any condition-case described below. Notice that the criterion is NOT if the error is actually handled by an error handler.

If it’s a symbol always, then the debugger is entered always, i.e. even if it is inside of a condition-case. If it’s a list of errer-symbols, for example (void-value bad-arg), then only when the error matches one of them, the debugger is called even inside of a condition-case.

(setq backtrace-on-error t) ;; Ordinary usage.
(setq backtrace-on-error '(void-value bad-arg)) ;; Catch them only
Variable: backtrace-on-error

Similar to debug-on-error (read WELL its description), but instead of entering the debugger, the current backtrace is printed to the standard error stream, and control continues.

When you expect an error to occur and need to be able to regain control afterwards the condition-case special form may be used.

Macro: condition-case symbol body-form error-handlers…

condition-case evaluates the body-form with the error-handlers in place. If an error occurs and one of the handles matches the error, then it is evaluated with the value of symbol set to the error information.

Each of the error-handlers is a list whose car is a symbol defining the type of error which this handler catches. The cdr of the list is a list of forms to be evaluated in a progn if the handler is invoked.

While the forms of the error handler are being evaluated the variable symbol is bound to the value (error-symbol . data) (these were the arguments to the signal form which caused the error). If symbol is the symbol nil (or the empty list ()), then the error information is not available to the handler.

The special value, the symbol error, in the car of one of the error-handlers will catch all types of errors.

(condition-case data
    (signal 'file-error '("File not found" "/tmp/foo"))
  (file-error
   data)
  (error
   (setq x z)))         ;Default handler
    ⇒ (file-error "File not found" "/tmp/foo")

Previous: , Up: Non-Local Exits   [Contents][Index]