Error Symbols---Condition Names (Mastering Emacs

F.6.2.5 Error Symbols—Condition Names

Error Symbols Concepts

‘error’
‘error symbol’
‘error conditions’
‘condition names’
define-error function
signal function

Errors

Error Symbols

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.

Error Conditions and Condition Names

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.

Function define-error
Function: define-error name message &optional parent ¶
Define ‘NAME’ as a new ‘error’ symbol. ‘PARENT’ is either a signal or a list of signals from which it inherits. ‘MESSAGE’ is a string that will be output to the echo area if such an ‘error’ is signaled without being caught by a condition-case.
```
(define-error 'new-error "A new error" 'my-own-errors)
```
This ‘error’ has several condition names: ‘new-error’, the narrowest classification; ‘my-own-errors’, which we imagine is a wider classification; and all the conditions of ‘my-own-errors’ which should include ‘error’, which is the widest of all.

PARENT

In order for a symbol to be an error symbol, it must be defined with define-error which takes a ‘PARENT’ condition (defaults to ‘error’). This ‘PARENT’ defines the conditions that this kind of error belongs to. The transitive set of ‘PARENTS’ always includes the error symbol itself, and the symbol ‘error’.

MESSAGE

In addition to its parents, the error symbol has a message which is a string to be printed when that ‘error’ is signaled but not handled. 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.

Only an explicit call to signal in your code can signal ‘new-error’.
```
(signal 'new-error '(x y))
     error→ A new error: x, y
```
This ‘error’ can be handled through any of its 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 Power and Utility of Error Condition Names
Internally, the set of parents is stored in the ‘error-conditions’ property of the ‘error’ symbol and the message is stored in the ‘error-message’ property of the ‘error’ symbol.

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.

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.