Next: Efficiency Concerns, Previous: Structures, Up: Top
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.
This form verifies that test-form is true (i.e., evaluates to a non-
nil
value). If so, it returnsnil
. If the test is not satisfied,cl-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 ofnil
, then the error message (with or without string) will also include all non-constant arguments of the top-level form. For example:(cl-assert (> x 10) t "x is too small: %d")This usage of show-args is an extension 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. Since Emacs Lisp does not support continuable errors, it makes no sense to specify places.
This form verifies that form evaluates to a value of type type. If so, it returns
nil
. If not,cl-check-type
signals awrong-type-argument
error. The default error message lists the erroneous value along with type and form themselves. If string is specified, it is included in the error message in place of type. For example:(cl-check-type x (integer 1 *) "a positive integer")See Type Predicates, for a description of the type specifiers that may be used for type.
Note that in Common Lisp, the first argument to
check-type
must be a place suitable for use bysetf
, becausecheck-type
signals a continuable error that allows the user to modify place.