14. Assertions and Errors

This section describes two macros that test assertions, i.e.,
conditions which must be true if the program is operating correctly.
Assertions never add to the behavior of a Lisp program; they simply
make "sanity checks" to make sure everything is as it should be.

If the optimization property speed has been set to 3, and
safety is less than 3, then the byte-compiler will optimize
away the following assertions. Because assertions might be optimized
away, it is a bad idea for them to include side-effects.

Macro:asserttest-form [show-args string args...]

This form verifies that test-form is true (i.e., evaluates to
a non-nil value). If so, it returns nil. If the test
is not satisfied, assert signals an error.

A default error message will be supplied which includes test-form.
You can specify a different error message by including a string
argument plus optional extra arguments. Those arguments are simply
passed to error to signal the error.

If the optional second argument show-args is t instead
of nil, then the error message (with or without string)
will also include all non-constant arguments of the top-level
form. For example:

(assert (> x 10) t "x is too small: %d")

This usage of show-args is a change to Common Lisp. In
true Common Lisp, the second argument gives a list of places
which can be setf'd by the user before continuing from the
error.

Macro:check-typeplace type &optional string

This form verifies that place evaluates to a value of type
type. If so, it returns nil. If not, check-type
signals a continuable wrong-type-argument error. The default
error message lists the erroneous value along with type and
place themselves. If string is specified, it is included in
the error message in place of type. For example:

(check-type x (integer 1 *) "a positive integer")

See section 4.1 Type Predicates, for a description of the type specifiers
that may be used for type.

Note that as in Common Lisp, the first argument to check-type
should be a place suitable for use by setf, because
check-type signals a continuable error that allows the user to
modify place, most simply by returning a value from the debugger.

The following error-related macro is also defined:

Macro:ignore-errorsforms...

This executes forms exactly like a progn, except that
errors are ignored during the forms. More precisely, if
an error is signalled then ignore-errors immediately
aborts execution of the forms and returns nil.
If the forms complete successfully, ignore-errors
returns the result of the last form.