with-error-handling

Purpose
Evaluate each handler-form and each error-form if an error occurs while evaluating form.

Package   :gbbopen-tools

Module   :gbbopen-tools

Arguments and values

Returns
The values returned by evaluating form unless an error occurs during that evaluation in which case:

• the values of evaluating the last error-form form, if specified, are returned
• otherwise, the values of evaluating the last handler-form form, if specified, are returned
• otherwise, no values are returned

Description
If an error occurs while evaluating form, each handler-form is evaluated in the dynamic context of the error, then the dynamic context is unwound to that in which form was evaluated and each error-form is evaluated.

A lexical function, error-message, is available for use within each handler-form and error-form. This lexical function accepts no arguments and returns a string describing the error that occurred during the evaluation of form.

Another lexical function, error-condition, is also available for use within each handler-form and nobrerror-form. This lexical function accepts no arguments and returns the condition object that signaled the error.

The conditions that are handled can be changed by using the (:conditions type) option. Unlike other Common Lisp implementations, Allegro CL includes interrupt signals (typically generated by the user typing control-C characters in the REPL) as error conditions. Interrupt signals are excluded by default on Allegro CL.

See also
    *disable-with-error-handling*

Examples

  > (with-error-handling (values 1 2 3) ':error-occurred)
  1
  2
  3
  > (with-error-handling (values 1 2 (error "Bad")) ':error-occurred)
  :error-occurred
  > (with-error-handling (values 1 2 (/ 10 0)) (printv (error-message)) nil)
  ;;  (error-message) => "Attempt to divide 10 by zero."
  nil
  > (defparameter *x* 0)
  *x*
  > (with-error-handling 
        ((let ((*x* 1))
           (error "A silly error has occurred."))
         (printv "Handler form" (error-message) *x*)
         (values :c :b :a))
      (printv "Error form" (error-message) *x*)
      (values :a :b :c))
  ;; Handler form
  ;;  (error-message) => "A silly error has occurred."
  ;;  *x* => 1
  ;; Error form
  ;;  (error-message) => "A silly error has occurred."
  ;;  *x* => 0
  :a
  :b
  :c
  > (with-error-handling 
        ((let ((*x* 1))
           (error "A silly error has occurred."))
         (printv "Handler form" (error-message) *x*)
         (values :c :b :a)))          ; No error forms
  ;; Handler form
  ;;  (error-message) => "A silly error has occurred."
  ;;  *x* => 1
  :c
  :b
  :a
  > (with-error-handling 
        ;; No handler-forms:
        ((let ((*x* 1))
           (error "A silly error has occurred.")))
      (printv "Error form" (error-message) *x*)
      (values :a :b :c))
  ;; Error form
  ;;  (error-message) => "A silly error has occurred."
  ;;  *x* => 0
  :a
  :b
  :c
  > (with-error-handling (warn "Not too bad") ':error-occurred)
  ;; Warning: Not too bad
  nil
  > (with-error-handling ((warn "Not too bad")
                          (:conditions (or (and error
                                                #+allegro
                                                (not interrupt-signal))
                                           warning))) 
      :error-occurred)
  :error-occurred
  >

with-error-handling