GBBopen 1.2 Reference -- with-error-handling

with-error-handling

with-error-handling [form | (form [(:conditions type)] handler-form*) error-form* => result* [Macro]

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

Package :gbbopen-tools

Module :gbbopen-tools

Arguments and values

form		A form
type		A type specifier (default is `(and error (not interrupt-signal))` on Allegro CL; otherwise `error`)
handler-forms		Zero or more forms
error-forms		Zero or more forms
results		The values returned by evaluating `form`, the values returned by evaluating the last form in `handler-forms` or `error-forms`, or no values

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

values of evaluating error-forms, if specified, are returned
otherwise, values of evaluating handler-forms, if specified, are returned
otherwise, no values are returned

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

A lexical function, error-message, is available for use within handler-forms and error-forms. 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 handler-forms and error-forms. 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.

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
  >

The GBBopen Project

with-error-handling