-\1f
-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 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.
-
- 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-message'
-property exists, but is not a string, the error message `peculiar
-error' is used.
-
- Here is how we define a new error symbol, `new-error':
-
- (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
-classification; `my-own-errors', which we imagine is a wider
-classification; and `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, 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.
-