.c 	Tuesday, December 4, 1984   -*- bolio -*-


.chapter "Errors and Condition Signalling"
.setq signalling-and-handling-conditions-section-page section-page

Signalling and condition handling in lan{nil} is flavor based.  It
provides ways of defining new conditions (and errors, an error being a
kind of condition), ways of handling them (e.g., correcting an error either
directly by some code or from the Lisp debugger), and the means for
program execution to be aborted or restarted at "convenient" places in
the event that a condition is not handled.

lan{Common lisp} provides a number of facilities for doing error
signalling and type checking which are integrated into the lan{nil}
error system in well-defined ways.  As a result, it is possible for code
to signal errors, many correctable, while remaining lan{common lisp}
compatible.  There are also a number of ways in which errors can be
handled trivially which do not require extensive use of the error system
internals.

The lan{nil} signalling and condition handling system was designed to
closely follow the documentation of that provided with Symbolics lisp
machines.  Just about all of the functions and macros described there
behave the same in lan{nil}, and most of the message-passing protocol
is also identical.  Some of the incompatibilities are a result of
resolving incompatibilities with certain lan{common lisp} functions,
and some, especially those in the message-passing protocol, are
considered to be improvements.


.section "Common-Lisp Errors and Warnings"

Here are the various functions and macros defined by lan{common lisp}
which interface to the lan{nil} error system.

.subsection "Simple Error, Break, and Warning Functions"

.defun error format-string &rest format-args
3error* signals a fatal error.  2format-string* and
2format-args* are used to construct an error message using
3format*, which is printed on the stream 3*error-output**;  then,
the debugger is entered.  3error* does not return to its caller.

The above behaviour could be different if the error condition is
handled, perhaps with an explicit handler set up by
3condition-bind* or implicitly by use of 3errset* or
3ignore-errors* (described later).
.end_defun

.defun cerror continue-string error-string &rest format-args
3cerror* signals a continuable error.  2error-string*
and 2format-args* are used to construct an error message, as with
3error*.  2continue-string* and 2format-args* are similarly
used to construct a message saying what will happen if one continues
the error from the debugger (which offers this as a choice).  If the
error is continued, 3cerror* returns 3nil*.  It is up to the caller
of 3cerror* to do the continuation action (perhaps just performing
some default action, prompting for a new value, etc.).

For upwards-compatibility with old lan{nil} code, usages of
3cerror* which look like
.lisp
(cerror 2t-or-nil* nil 2symbol* 2string* 2args...*)
.end_lisp
continue to work.  Often, they succeed in mapping to a specific error
condition rather than just a "generic" error, for certain 2symbol*s.
.end_defun

.defun break format-string &rest format-args
3break* prints a message constructed from 2format-string* and
2format-args* using 3format* to 3*error-output**, and enters
the debugger.  The difference is that 3break* is not an error, so
condition-handling constructs (such as 3ignore-errors*,
(ignore-errors-fun)) do not trap it.
.end_defun

.defun warn format-string &rest format-args
3warn* prints a message constructed from 2format-string* and
2format-args* using 3format* to 3*error-output**.
.end_defun

.defvar *break-on-warnings*
This normally is 3nil*.  If it is not, then 3warn* behaves like
3break*;  it enters the debugger, rather than just printing the
message and returning.  This is intended for use in debugging
programs which issue warnings, not as a flag to be turned on all the time.
.end_defvar

.subsection "Error Checking Functions"

.defmacro check-type place type-specifier &optional descriptive-string
2place* should be a place suitable for use with 3setf*
((setf-fun)).  If the value of 2place* is of the type
2type-specifier*, then 3check-type* does nothing.  Otherwise, it
signals a
correctable error, which provides an option of supplying a new value to
use instead of 2place*--2place* will be set to this new value using
3setf*.  If 2descriptive-string* is not specified, then a
descriptive string is constructed from 2type-specifier*--for
instance, a type specifier of 3(or null integer)* results in a
description like "either NIL or an integer".  However,
2descriptive-string* may be specified to override this in complicated
or non-specific cases.  Note that 2type-specifier* is not evaluated.
3check-type* returns 3nil*.

Note that subforms of 2place* may be evaluated more than once.
.end_defmacro

.defmacro assert test-form places &optional format-string format-args
3assert* evaluates 2test-form*.  If the result is 3nil*, then
it signals a correctable error, the text of which is constructed
from 2format-string* and 2format-args* (if they are supplied).
2places* should be a list of places suitable for use with
3setf*;  presumably the value of 2test-form* depends on them.
One is given the option of updating any of the places, and trying again.
.end_defmacro

.defmacro ecase place clauses...
3ecase* is just like 3case* ((case-fun)), q.v.  However, it admits
no 3t* or 3otherwise* clause--if the 3case* falls off the end, a
fatal error which names 2place* and the possible choices is signalled.
.end_defmacro

.defmacro ccase place clauses...
3ccase* is similar to 3ecase*, but rather than signalling a fatal
error, it signals a continuable error which permits one to assign
2place* a new value (with 3setf*, hence 2place* must be
acceptable as a place form to 3setf*), and tries again.
.end_defmacro

.defmacro etypecase place clauses...
3etypecase* is to 3typecase* ((typecase-fun)) as 3ecase* (above)
is to 3case*.
.end_defmacro

.defmacro ctypecase place clauses...
Similar;  like 3etypecase*, but one may change the value of 2place*
and try again.
.end_defmacro



.section "Constructing and Signalling Conditions"

2To be written*
