When you signal an error, you specify an error symbol to specify the kind of error you have in mind. Each error has one and only one error symbol to categorize it. This is the finest classification of errors defined by the Emacs Lisp language.
These narrow classifications are grouped into a hierarchy of wider
classes called error conditions, identified by condition
names. The narrowest such classes belong to the error symbols
themselves: each error symbol is also a condition name. There are also
condition names for more extensive classes, up to the condition name
error which takes in all kinds of errors (but not
Thus, each error has one or more condition names:
error symbol if that is distinct from
error, and perhaps some
In order for a symbol to be an error symbol, it must have an
error-conditions property which gives a list of condition names.
This list defines the conditions that this kind of error belongs to.
(The error symbol itself, and the symbol
error, should always be
members of this list.) Thus, the hierarchy of condition names is
defined by the
error-conditions properties of the error symbols.
Because quitting is not considered an error, the value of the
error-conditions property of
quit is just
In addition to the
error-conditions list, the error symbol
should have an
error-message property whose value is a string to
be printed when that error is signaled but not handled. If the
error symbol has no
error-message property or if the
error-message property exists, but is not a string, the error
message ‘peculiar error’ is used. See Definition of signal.
Here is how we define a new error symbol,
(put 'new-error 'error-conditions '(error my-own-errors new-error)) ⇒ (error my-own-errors new-error) (put 'new-error 'error-message "A new error") ⇒ "A new error"
This error has three condition names:
new-error, the narrowest
my-own-errors, which we imagine is a wider
error, which is the widest of all.
The error string should start with a capital letter but it should not end with a period. This is for consistency with the rest of Emacs.
Naturally, Emacs will never signal
new-error on its own; only
an explicit call to
signal (see Definition of signal) in
your code can do this:
(signal 'new-error '(x y)) error--> A new error: x, y
This error can be handled through any of the three condition names.
This example handles
new-error and any other errors in the class
(condition-case foo (bar nil t) (my-own-errors nil))
The significant way that errors are classified is by their condition
names—the names used to match errors with handlers. An error symbol
serves only as a convenient way to specify the intended error message
and list of condition names. It would be cumbersome to give
signal a list of condition names rather than one error symbol.
By contrast, using only error symbols without condition names would
seriously decrease the power of
condition-case. Condition names
make it possible to categorize errors at various levels of generality
when you write an error handler. Using error symbols alone would
eliminate all but the narrowest level of classification.
See Standard Errors, for a list of the main error symbols and their conditions.