Next: , Previous: , Up: restarts   [Index]

1.18.7 Finding and invoking restarts

Function: find-restart name
Function: find-restart name cnd

Search the current dynamic environment for the innermost restart handler associated to name, which must be a symbol. If a handler is found: return its restart object; otherwise return #f.

When the optional argument cnd is used and cnd is a condition object (simple or compound): among the installed restarts, return only the innermost that is not associated to the condition object cnd. When the optional argument cnd is used and cnd is #f: behave as if cnd was not used.

Function: invoke-restart restart-designator . rest

Given a restart designator: search the associated handler in the current dynamic environment and apply it to the given rest arguments. Return the return values of such application, if the called function returns.

restart-designator can be either a symbol representing the name of the restart or the restart object itself (as returned by find-restart).

If restart-designator is a symbol and no matching restart is found: an exception is raised with condition object of type &undefined-restart-error.

Function: compute-restarts

Return a list of symbols representing the names of the restarts currently installed in the dynamic environment. The list is ordered: the innermost restarts come first, the outermost restarts come last.

Function: restart-name rst

Given a restart object: return a symbol representing its name.

Examples about finding and invoking restarts: 

(import (vicare)
  (only (vicare checks)
        with-result
        add-result))

;;Search an UNdefined restart.
;;
(find-restart 'alpha)
⇒ #f

;;Search an UNdefined restart.
;;
(restart-case
    (find-restart 'beta)
  (alpha (lambda ()
           (add-result 'restart-alpha))))
⇒ #f

;;Search an UNdefined restart.
;;
(restart-case
    (find-restart 'gamma)
  (alpha (lambda ()
           (add-result 'restart-alpha)))
  (beta  (lambda ()
           (add-result 'restart-beta)))
  (delta (lambda ()
           (add-result 'restart-delta))))
⇒ #f

;;Invoke an UNdefined restart.
;;
(try
    (invoke-restart 'alpha)
  (catch E
    ((&undefined-restart-error)
     1)
    (else E)))
⇒ 1

;;Find then invoke a restart in two steps.
;;Invoking a restart is a non-local exit.
;;
(with-result
  (restart-case
      (begin
        (add-result 'body-in)
        (let ((restart (find-restart 'alpha)))
          (add-result 'body-invoking)
          (begin0
              (invoke-restart restart)
            (add-result 'body-out)
            1)))
    (alpha (lambda ()
             (add-result 'restart-alpha)
             2))))
⇒ (2 (body-in body-invoking restart-alpha))

;;Find and invoke a restart in a single step.
;;Invoking a restart is a non-local exit.
;;
(with-result
  (restart-case
      (begin
        (add-result 'body-in)
        (begin0
            (invoke-restart 'alpha)
          (add-result 'body-out)
          1))
    (alpha (lambda ()
             (add-result 'restart-alpha)
             2))))
⇒ (2 (body-in restart-alpha))

Usage examples on compute-restarts: 

(import (vicare)
  (only (vicare checks)
        with-result
        add-result))

(compute-restarts)
⇒ ()

(map restart-name
  (restart-case
      (compute-restarts)
    (alpha void)
    (beta  void)))
⇒ (alpha beta)

(map restart-name
  (restart-case
      (restart-case
          (compute-restarts)
        (alpha void)
        (beta  void))
    (delta void)
    (gamma void)))
⇒ (alpha beta delta gamma)

(map restart-name
  (restart-case
      (restart-case
          (restart-case
              (compute-restarts)
            (alpha void)
            (beta  void))
        (delta void)
        (gamma void))
    (chi void)
    (xi  void)))
⇒ (alpha beta delta gamma chi xi)

Next: , Previous: , Up: restarts   [Index]