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

error
  syntax-error
    invalid-read-syntax
    list-formation-error
      malformed-list
        malformed-property-list
      circular-list
        circular-property-list

  invalid-argument
    wrong-type-argument
    args-out-of-range
    wrong-number-of-arguments
    invalid-function
    no-catch

  invalid-state
    void-function
    cyclic-function-indirection
    void-variable
    cyclic-variable-indirection

  invalid-operation
    invalid-change
      setting-constant
    editing-error
      beginning-of-buffer
      end-of-buffer
      buffer-read-only
    io-error
      end-of-file
    arith-error
      range-error
      domain-error
      singularity-error
      overflow-error
      underflow-error

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:

• syntax-error is for errors in complex structures: parsed strings, lists, and the like.
• invalid-argument is for errors in a simple value. Typically, the entire value, not just one part of it, is wrong.
• invalid-state means that some settings have been changed in such a way that their current state is unallowable. More and more, code is being written more carefully, and catches the error when the settings are being changed, rather than afterwards. This leads us to the next error:
• invalid-change means that an attempt is being made to change some settings into an invalid state. invalid-change is a type of invalid-operation.
• invalid-operation refers to all cases where code is trying to do something that’s disallowed. This includes file errors, buffer errors (e.g. running off the end of a buffer), invalid-change as just mentioned, and arithmetic errors.

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

• the buffer in which an editing error occurred.
• an invalid value that was encountered. (In such cases, the string should describe the purpose or \"semantics\" of the value [e.g. if the value is an argument to a function, the name of the argument; if the value is the value corresponding to a keyword, the name of the keyword; if the value is supposed to be a list length, say this and say what the purpose of the list is; etc.] as well as specifying why the value is invalid, if that’s not self-evident.)
• the file in which an error occurred. (In such cases, there should be a second frob, probably a string, specifying the exact error that occurred. This does not occur in the string that precedes the first frob, because that frob describes the exact operation that was happening.

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"
	descriptor)

(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)
  …)