Previous: Handling Errors, Up: Errors [Contents][Index]
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 SXEmacs 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. Thus, each error has
one or more condition names: error
, the error symbol if that
is distinct from error
, and perhaps some intermediate
classifications.
In other words, each error condition inherits from another error
condition, with error
sitting at the top of the inheritance
hierarchy.
This function defines a new error, denoted by error-symbol.
error-message is an informative message explaining the error, and
will be printed out when an unhandled error occurs. error-symbol
is a sub-error of inherits-from (which defaults to error
).
define-error
internally works by putting on error-symbol
an error-message
property whose value is error-message, and
an error-conditions
property that is a list of error-symbol
followed by each of its super-errors, up to and including error
.
Note: You will sometimes see code that sets this up directly rather than
calling define-error
, but you should not do this yourself,
unless you wish to maintain compatibility with FSF Emacs, which does not
provide define-error
.
Here is how we define a new error symbol, new-error
, that
belongs to a range of errors called my-own-errors
:
(define-error 'my-own-errors "A whole range of errors" 'error) (define-error 'new-error "A new error" 'my-own-errors)
new-error
has three condition names: new-error
, the
narrowest classification; my-own-errors
, which we imagine is a
wider classification; and error
, which is the widest of all.
Note: It is not legal to try to define an error unless its
super-error is also defined. For instance, attempting to define
new-error
before my-own-errors
are defined will signal an
error.
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 SXEmacs.
Naturally, SXEmacs will never signal new-error
on its own; only
an explicit call to signal
(see Signaling Errors) 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
my-own-errors
:
(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 all the standard error symbols and their conditions.
Previous: Handling Errors, Up: Errors [Contents][Index]