find-restart

find-restart Function

Syntax:

find-restart identifier &optional condition

restart

Arguments and Values:

identifier—a non-nil symbol, or a restart.

condition—a condition object, or nil.

restart—a restart or nil.

Description:

find-restart searches for a particular restart in the current dynamic environment.

When condition is non-nil, only those restarts are considered that are either explicitly associated with that condition, or not associated with any condition; that is, the excluded restarts are those that are associated with a non-empty set of conditions of which the given condition is not an element. If condition is nil, all restarts are considered.

If identifier is a symbol, then the innermost (most recently established) applicable restart with that name is returned. nil is returned if no such restart is found.

If identifier is a currently active restart, then it is returned. Otherwise, nil is returned.

Examples:

(restart-case 
    (let ((r (find-restart ’my-restart))) 
      (format t "~S is named ~S" r (restart-name r))) 
  (my-restart () nil)) 
▷ #<RESTART 32307325> is named MY-RESTART 
→ NIL 
(find-restart ’my-restart) 
→ NIL 

Affected By:

Existing restarts.

restart-case, restart-bind, with-condition-restarts.

See Also:

compute-restarts

Notes:

(find-restart identifier)

≡ (find identifier (compute-restarts) :key :restart-name)

Although anonymous restarts have a name of nil, the consequences are unspecified if nil is given as an identifier. Occasionally, programmers lament that nil is not permissible as an identifier argument. In most such cases, compute-restarts can probably be used to simulate the desired effect.

Expanded Reference: find-restart

Finding an Active Restart

find-restart searches for the most recently established restart with the given name. It returns the restart object if found, or nil otherwise.

(restart-case
    (let ((r (find-restart 'my-restart)))
      (if r :found :not-found))
  (my-restart () nil))

=> :FOUND

No Matching Restart

When no restart with the given name is active, find-restart returns nil.

(find-restart 'nonexistent)

=> NIL

Checking Before Invoking

A common pattern is to check whether a restart exists before invoking it. This avoids a control-error.

(handler-bind ((warning (lambda (c)
                          (let ((r (find-restart 'muffle-warning c)))
                            (when r (invoke-restart r))))))
  (warn "This will be muffled.")
  :done)

=> :DONE

Getting the Restart Name

find-restart returns a restart object. You can query its name with restart-name.

(restart-case
    (let ((r (find-restart 'do-something)))
      (restart-name r))
  (do-something () nil))

=> DO-SOMETHING

Filtering by Condition

The optional second argument restricts the search to restarts associated with a particular condition (or not associated with any condition).

(restart-case
    (handler-bind ((error (lambda (c)
                            (let ((r (find-restart 'fix c)))
                              (if r
                                  (invoke-restart r)
                                  (error "No fix restart for ~A" c))))))
      (error "something broke"))
  (fix ()
    :report "Fix the problem."
    :fixed))

=> :FIXED