Common Lisp the Language, 2nd Edition

29.5. Predefined Condition Types

[The proposal for the Common Lisp Condition System introduced a new notation for documenting types, treating them in the same syntactic manner as functions and variables. This notation is used in this section but is not reflected throughout the entire book.-GLS]

X3J13 voted in March 1989 (ZLOS-CONDITIONS)   to integrate the Condition System and the Object System. All condition types are CLOS classes and all condition objects are ordinary CLOS objects.

[Type]
restart

This is the data type used to represent a restart.

 
----------------------------------------------------------------
Table 29-1: Condition Type Hierarchy

condition 
    simple-condition 
    serious-condition 
        error 
            simple-error 
            arithmetic-error 
                division-by-zero 
                floating-point-overflow 
                floating-point-underflow 
                ... 
            cell-error 
                unbound-variable 
                undefined-function 
                ... 
            control-error 
            file-error 
            package-error 
            program-error 
            stream-error 
                end-of-file 
                ... 
            type-error 
                simple-type-error 
                ... 
            ... 
        storage-condition 
        ... 
    warning 
        simple-warning 
        ... 
    ...

----------------------------------------------------------------

The Common Lisp condition type hierarchy is illustrated in table 29-1.

The types that are not leaves in the hierarchy (that is, condition, warning, storage-condition, error, arithmetic-error, control-error, and so on) are provided primarily for type inclusion purposes. Normally they would not be directly instantiated.

Implementations are permitted to support non-portable synonyms for these types, as well as to introduce other types that are above, below, or between the types shown in this tree as long as the indicated subtype relationships are not violated.

The types simple-condition, serious-condition, and warning are pairwise disjoint. The type error is also disjoint from types simple-condition and warning.

[Type]
condition

All types of conditions, whether error or non-error, must inherit from this type.

[Type]
warning

All types of warnings should inherit from this type. This is a subtype of condition.

[Type]
serious-condition

All serious conditions (conditions serious enough to require interactive intervention if not handled) should inherit from this type. This is a subtype of condition.

This condition type is provided primarily for terminological convenience. In fact, signaling a condition that inherits from serious-condition does not force entry into the debugger. Rather, it is conventional to use error (or something built on error) to signal conditions that are of this type, and to use signal to signal conditions that are not of this type.

[Type]
error

All types of error conditions inherit from this condition. This is a subtype of serious-condition.

The default condition type for signal and warn is simple-condition. The default condition type for error and cerror is simple-error.

[Type]
simple-condition

Conditions signaled by signal when given a format string as a first argument are of this type. This is a subtype of condition. The initialization keywords :format-string and :format-arguments are supported to initialize the slots, which can be accessed using simple-condition-format-string and simple-condition-format-arguments. If :format-arguments is not supplied to make-condition, the format-arguments slot defaults to nil.

[Type]
simple-warning

Conditions signaled by warn when given a format string as a first argument are of this type. This is a subtype of warning. The initialization keywords :format-string and :format-arguments are supported to initialize the slots, which can be accessed using simple-condition-format-string and simple-condition-format-arguments. If :format-arguments is not supplied to make-condition, the format-arguments slot defaults to nil.

In implementations supporting multiple inheritance, this type will also be a subtype of simple-condition.

[Type]
simple-error

Conditions signaled by error and cerror when given a format string as a first argument are of this type. This is a subtype of error. The initialization keywords :format-string and :format-arguments are supported to initialize the slots, which can be accessed using simple-condition-format-string and simple-condition-format-arguments. If :format-arguments is not supplied to make-condition, the format-arguments slot defaults to nil.

In implementations supporting multiple inheritance, this type will also be a subtype of simple-condition.

[Function]
simple-condition-format-string condition

Accesses the format-string slot of a given condition, which must be of type simple-condition, simple-warning, simple-error, or simple-type-error.

[Function]
simple-condition-format-arguments condition

Accesses the format-arguments slot of a given condition, which must be of type simple-condition, simple-warning, simple-error, or simple-type-error.

[Type]
storage-condition

Conditions that relate to storage overflow should inherit from this type. This is a subtype of serious-condition.

[Type]
type-error

Errors in the transfer of data in a program should inherit from this type. This is a subtype of error. For example, conditions to be signaled by check-type should inherit from this type. The initialization keywords :datum and :expected-type are supported to initialize the slots, which can be accessed using type-error-datum and type-error-expected-type.

[Function]
type-error-datum condition

Accesses the datum slot of a given condition, which must be of type type-error.

[Function]
type-error-expected-type condition

Accesses the expected-type slot of a given condition, which must be of type type-error. Users of type-error conditions are expected to fill this slot with an object that is a valid Common Lisp type specifier.

[Type]
simple-type-error

Conditions signaled by facilities similar to check-type may want to use this type. The initialization keywords :format-string and :format-arguments are supported to initialize the slots, which can be accessed using simple-condition-format-string and simple-condition-format-arguments. If :format-arguments is not supplied to make-condition, the format-arguments slot defaults to nil.

In implementations supporting multiple inheritance, this type will also be a subtype of simple-condition.

[Type]
program-error

Errors relating to incorrect program syntax that are statically detectable should inherit from this type (regardless of whether they are in fact statically detected). This is a subtype of error. This is not a subtype of control-error.

[Type]
control-error

Errors in the dynamic transfer of control in a program should inherit from this type. This is a subtype of error. This is not a subtype of program-error.

The errors that result from giving throw a tag that is not active or from giving go or return-from a tag that is no longer dynamically available are control errors.

On the other hand, the errors that result from naming a go tag or return-from tag that is not lexically apparent are not control errors. They are program errors. See program-error.

[Type]
package-error

Errors that occur during operations on packages should inherit from this type. This is a subtype of error. The initialization keyword :package is supported to initialize the slot, which can be accessed using package-error-package.

[Function]
package-error-package condition

Accesses the package (or package name) that was being modified or manipulated in a condition of type package-error.

[Type]
stream-error

Errors that occur during input from, output to, or closing a stream should inherit from this type. This is a subtype of error. The initialization keyword :stream is supported to initialize the slot, which can be accessed using stream-error-stream.

[Function]
stream-error-stream condition

Accesses the offending stream of a condition of type stream-error.

[Type]
end-of-file

The error that results when a read operation is done on a stream that has no more tokens or characters should inherit from this type. This is a subtype of stream-error.

[Type]
file-error

Errors that occur during an attempt to open a file, or during some low-level transaction with a file system, should inherit from this type. This is a subtype of error. The initialization keyword :pathname is supported to initialize the slot, which can be accessed using file-error-pathname.

[Function]
file-error-pathname condition

Accesses the offending pathname of a condition of type file-error.

[Type]
cell-error

Errors that occur while accessing a location should inherit from this type. This is a subtype of error. The initialization keyword :name is supported to initialize the slot, which can be accessed using cell-error-name.

[Function]
cell-error-name condition

Accesses the offending cell name of a condition of type cell-error.

[Type]
unbound-variable

The error that results from trying to access the value of an unbound variable should inherit from this type. This is a subtype of cell-error.

[Type]
undefined-function

The error that results from trying to access the value of an undefined function should inherit from this type. This is a subtype of cell-error.

Some readers may wonder why undefined-function is not defined to inherit from some condition such as control-error. The answer is that any such arrangement would require the presence of multiple inheritance-a luxury we do not currently have (without resorting to deftype, which we are currently avoiding). When the Common Lisp Object System comes into being, we might want to consider issues like this. Multiple inheritance makes a lot of things in a condition system much more flexible to deal with.

[Type]
arithmetic-error

Errors that occur while doing arithmetic type operations should inherit from this type. This is a subtype of error. The initialization keywords :operation and :operands are supported to initialize the slots, which can be accessed using arithmetic-error-operation and arithmetic-error-operands.

[Function]
arithmetic-error-operation condition

Accesses the offending operation of a condition of type arithmetic-error.

[Function]
arithmetic-error-operands condition

Accesses a list of the offending operands in a condition of type arithmetic-error.

[Type]
division-by-zero

Errors that occur because of division by zero should inherit from this type. This is a subtype of arithmetic-error.

[Type]
floating-point-overflow

Errors that occur because of floating-point overflow should inherit from this type. This is a subtype of arithmetic-error.

[Type]
floating-point-underflow

Errors that occur because of floating-point underflow should inherit from this type. This is a subtype of arithmetic-error.