Common Lisp the Language, 2nd Edition

Next: Series Up: Conditions Previous: Debugging Utilities

# 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`.

Remark: [Note: This remark was written well before the vote by X3J13 in June 1988 (CLOS) to add the Common Lisp Object System to the forthcoming draft standard (see chapter 28) and the vote to integrate the Condition System and the Object System. I have retained the remark here for reasons of historical interest.-GLS]

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`.

Next: Series Up: Conditions Previous: Debugging Utilities