Common Lisp the Language, 2nd Edition
The
functions in this section provide various mechanisms
for signaling warnings, breaks, continuable errors, and fatal errors.
[Function]
error datum &rest arguments
[This supersedes the description of error given in section 24.1.-GLS]
Invokes the signal facility on a condition. If the condition is not handled, (invoke-debugger condition) is executed. As a consequence of calling invoke-debugger, error never directly returns to its caller; the only exit from this function can come by non-local transfer of control in a handler or by use of an interactive debugging command.
If datum is a condition, then that condition is used directly. In this case, it is an error for the list of arguments to be non-empty; that is, error must have been called with exactly one argument, the condition.
If datum is a condition type (a class or class name), then the condition used is effectively the result of (apply #'make-condition datum arguments).
If datum is a string, then the condition used is effectively the result of
(make-condition 'simple-error
:format-string datum
:format-arguments arguments)
[Function]
cerror continue-format-string datum &rest arguments
[This supersedes the description of cerror given in section 24.1.-GLS]
The function cerror invokes the error facility on a condition. If the condition is not handled, (invoke-debugger condition) is executed. While signaling is going on, and while control is in the debugger (if it is reached), it is possible to continue program execution (thereby returning from the call to cerror) using the continue restart.
If datum is a condition, then that condition is used directly. In this case, the list of arguments need not be empty, but will be used only with the continue-format-string and will not be used to initialize datum.
If datum is a condition type (a class or class name), then the condition used is effectively the result of (apply #'make-condition datum arguments).
If datum is a string, then the condition used is effectively the result of
(make-condition 'simple-error
:format-string datum
:format-arguments arguments)
The continue-format-string must be a string. Note that if datum is not a string, then the format arguments used by the continue-format-string will still be the list of arguments (which is in keyword format if datum is a condition type). In this case, some care may be necessary to set up the continue-format-string correctly. The format directive ~*, which ignores and skips over format arguments, may be particularly useful in this situation.
The value returned by cerror is nil.
[Function]
signal datum &rest arguments
Invokes the signal facility on a condition. If the condition is not handled, signal returns nil.
If datum is a condition, then that condition is used directly. In this case, it is an error for the list of arguments to be non-empty; that is, error must have been called with exactly one argument, the condition.
If datum is a condition type (a class or class name), then the condition used is effectively the result of (apply #'make-condition datum arguments).
If datum is a string, then the condition used is effectively the result of
(make-condition 'simple-error
:format-string datum
:format-arguments arguments)
Note that if (typep condition *break-on-signals*) is true, then the debugger will be entered prior to beginning the process of signaling. The continue restart function may be used to continue with the signaling process; the restart is associated with the signaled condition as if by use of with-condition-restarts. This is true also for all other functions and macros that signal conditions, such as warn, error, cerror, assert, and check-type.
During the dynamic extent of a call to signal with a particular condition, the effect of calling signal again on that condition object for a distinct abstract event is not defined. For example, although a handler may resignal a condition in order to allow outer handlers first shot at handling the condition, two distinct asynchronous keyboard events must not signal an the same (eq) condition object at the same time.
For further details about signaling and handling, see the discussion of condition handlers in section 29.3.17.
[Variable]
*break-on-signals*
This variable is intended primarily for use when the user is debugging programs that do signaling. The value of *break-on-signals* should be suitable as a second argument to typep, that is, a type or type specifier.
When (typep condition *break-on-signals*) is true, then calls to signal (and to other advertised functions such as error that implicitly call signal) will enter the debugger prior to signaling that condition. The continue restart may be used to continue with the normal signaling process; the restart is associated with the signaled condition as if by use of with-condition-restarts.
Note that nil is a valid type specifier. If the value of *break-on-signals* is nil, then signal will never enter the debugger in this implicit manner.
When setting this variable, the user is encouraged to choose the most restrictive specification that suffices. Setting this flag effectively violates the modular handling of condition signaling that this chapter seeks to establish. Its complete effect may be unpredictable in some cases, since the user may not be aware of the variety or number of calls to signal that are used in programs called only incidentally.
By default-and certainly in any ``production'' use-the value of this variable should be nil, both for reasons of performance and for reasons of modularity and abstraction.
X3J13 voted in March 1989 (BREAK-ON-WARNINGS-OBSOLETE) to remove *break-on-warnings* from the language; *break-on-signals* offers all the power of *break-on-warnings* and more.
[There is no loss of generality in Common Lisp because the or type specifier may be used to indicate that any of a set of conditions should enter the debugger.-GLS]
