Skip to main content

compute-restarts

compute-restarts Function

Syntax:

compute-restarts &optional condition → restarts

Arguments and Values:

condition—a condition object, or nil.

restarts—a list of restarts.

Description:

compute-restarts uses the dynamic state of the program to compute a list of the restarts which are currently active.

The resulting list is ordered so that the innermost (more-recently established) restarts are nearer the head of the list.

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.

compute-restarts returns all applicable restarts, including anonymous ones, even if some of them have the same name as others and would therefore not be found by find-restart when given a symbol argument.

Implementations are permitted, but not required, to return distinct lists from repeated calls to compute-restarts while in the same dynamic environment. The consequences are undefined if the list returned by compute-restarts is every modified.

Examples:

;; One possible way in which an interactive debugger might present 
;; restarts to the user. 
(defun invoke-a-restart () 
  (let ((restarts (compute-restarts))) 
    (do ((i 0 (+ i 1)) (r restarts (cdr r))) ((null r)) 
      (format t "~&~D: ~A~%" i (car r))) 
    (let ((n nil) (k (length restarts))) 
      (loop (when (and (typep n ’integer) (>= n 0) (< n k)) 
	      (return t)) 
       (format t "~&Option: ") 
       (setq n (read)) 
       (fresh-line)) 
      (invoke-restart-interactively (nth n restarts))))) 

(restart-case (invoke-a-restart) 
  (one () 1) 
  (two () 2) 
  (nil () :report "Who knows?" ’anonymous) 
  (one () ’I) 
  (two () ’II)) 
▷ 0: ONE 
▷ 1: TWO 
▷ 2: Who knows? 
▷ 3: ONE 
▷ 4: TWO 
▷ 5: Return to Lisp Toplevel. 
▷ Option: 4 
→ II 
;; Note that in addition to user-defined restart points, COMPUTE-RESTARTS 
;; also returns information about any system-supplied restarts, such as 
;; the "Return to Lisp Toplevel" restart offered above.

Affected By:

Existing restarts.

See Also:

find-restart, invoke-restart, restart-bind

Expanded Reference: compute-restarts​

Listing All Active Restarts​

compute-restarts returns a list of all currently active restarts, ordered from innermost (most recently established) to outermost. This includes both user-defined and system-supplied restarts.

(restart-case
    (mapcar #'restart-name (compute-restarts))
  (alpha () nil)
  (beta () nil))

The result will include ALPHA, BETA, and any system restarts (e.g., ABORT).

Including Anonymous Restarts​

Unlike find-restart, compute-restarts returns all restarts, including anonymous ones.

(restart-case
    (length (compute-restarts))
  (nil () :report "Anonymous restart." nil)
  (named () :report "Named restart." nil))

This returns the total number of active restarts (at least 2 plus any system restarts).

Filtering by Condition​

When an optional condition argument is provided, only restarts associated with that condition (or not associated with any condition) are returned.

(restart-case
    (handler-bind ((error (lambda (c)
                            (length (compute-restarts c)))))
      (error "test"))
  (fix () :report "Fix it." nil))

This returns the count of restarts applicable to the signaled error condition.

Practical Example: Displaying Available Restarts​

(restart-case
    (dolist (r (compute-restarts))
      (format t "~S: ~A~%" (restart-name r) r))
  (try-again () :report "Try the operation again." nil)
  (give-up () :report "Give up entirely." nil))
TRY-AGAIN: Try the operation again.
GIVE-UP: Give up entirely.
; ...plus any system restarts