+File: lispref.info, Node: Error Symbols, Prev: Handling Errors, Up: Errors
+
+Error Symbols and Condition Names
+.................................
+
+ 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 XEmacs 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.
+
+ - Function: define-error error-symbol error-message &optional
+ inherits-from
+ 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'.
+ 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 that 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 Emacs.
+
+ Naturally, XEmacs will never signal `new-error' on its own; only an
+explicit call to `signal' (*note 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.
+
+ *Note Standard Errors::, for a list of all the standard error symbols
+and their conditions.
+
+\1f
projects / chise / xemacs-chise.git.1 / blobdiff