GNU Info

(cl)Assertions

---

Next: Efficiency Concerns Prev: Structures Up: Top

---

Enter node , (file) or (file)node

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.

 - Special Form: assert test-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 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.

 - Special Form: check-type form type [string]
     This form verifies that FORM evaluates to a value of type TYPE.
     If so, it returns `nil'.  If not, `check-type' signals a
     `wrong-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:

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

     Note: 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 by `setf', because `check-type'
     signals a continuable error that allows the user to modify PLACE.

   The following error-related macro is also defined:

 - Special Form: ignore-errors forms...
     This executes FORMS exactly like a `progn', except that errors are
     ignored during the FORMS.  More precisely, if an error is signaled
     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.