(lispref.info)Signaling Errors


Next: Processing of Errors Up: Errors

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 handled almost like an error.  Note: Quitting.

 - Function: error FORMAT-STRING &rest ARGS
     This function signals an error with an error message constructed by
     applying `format' (Note: String Conversion.) to FORMAT-STRING
     and ARGS.

     Typical uses of `error' is shown in the following examples:

          (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.

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

     If you want to use a user-supplied 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 different sorts of errors are
     classified.

     The number and significance of the objects in DATA depends on
     ERROR-SYMBOL.  For example, with a `wrong-type-arg' error, there
     are two objects in the list: a predicate which describes the type
     that was expected, and the object which failed to fit that type.
     Note: Error Names, for a description of error symbols.

     Both ERROR-SYMBOL and DATA are available to any error handlers
     which handle the error: a list `(ERROR-SYMBOL . DATA)' is
     constructed to become the value of the local variable bound in the
     `condition-case' form (Note: Handling Errors.).  If the error is
     not handled, both of them are used in printing the error message.

     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.


automatically generated by info2www