Copyright (C) 2000-2012 |
GNU Info (elisp)Error SymbolsError 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 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. 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, Emacs 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. automatically generated by info2www version 1.2.2.9 |