Skip to main content

with-condition-restarts

with-condition-restarts Macro

Syntax:

with-condition-restarts condition-form restarts-form {form}*

→ {result}*

Arguments and Values:

condition-form—a form; evaluated to produce a condition.

condition—a condition object resulting from the evaluation of condition-form.

restart-form—a form; evaluated to produce a restart-list.

restart-list—a list of restart objects resulting from the evaluation of restart-form.

forms—an implicit progn; evaluated.

results—the values returned by forms.

Description:

First, the condition-form and restarts-form are evaluated in normal left-to-right order; the primary values yielded by these evaluations are respectively called the condition and the restart-list.

Next, the forms are evaluated in a dynamic environment in which each restart in restart-list is associated with the condition. See Section 9.1.4.2.4 (Associating a Restart with a Condition).

See Also:

restart-case

Notes:

Usually this macro is not used explicitly in code, since restart-case handles most of the common cases in a way that is syntactically more concise.

Expanded Reference: with-condition-restarts​

Associating Restarts with a Condition​

with-condition-restarts explicitly associates a list of restart objects with a condition object. This affects the behavior of find-restart and compute-restarts when given a condition argument.

(let ((c (make-condition 'simple-error :format-control "test")))
  (restart-case
      (with-condition-restarts c (list (find-restart 'fix))
        (length (compute-restarts c)))
    (fix () :report "Fix the issue." nil)))

This returns the number of restarts visible when filtered by the condition c.

Implicit Use by restart-case​

In practice, with-condition-restarts is rarely used directly. restart-case automatically associates restarts with conditions when the restartable form is a call to signal, error, cerror, or warn.

;; restart-case implicitly does this:
;; (restart-case (error condition)
;;   (fix () ...))
;;
;; is approximately equivalent to:
;; (restart-case
;;     (with-condition-restarts condition
;;         (list (find-restart 'fix))
;;       (error condition))
;;   (fix () ...))

When to Use Explicitly​

Use with-condition-restarts when you need to associate restarts with conditions outside of the standard restart-case signaling pattern, such as when building custom signaling protocols.

(let ((c (make-condition 'simple-error :format-control "problem")))
  (restart-case
      (handler-bind ((error (lambda (cond)
                              (declare (ignore cond))
                              (invoke-restart 'resolve))))
        (with-condition-restarts c (list (find-restart 'resolve))
          (error c)))
    (resolve ()
      :report "Resolve the problem."
      :resolved)))

=> :RESOLVED