Skip to main content

invoke-restart

invoke-restart Function

Syntax:

invoke-restart restart &rest arguments → {result}*

Arguments and Values:

restart—a restart designator .

argument—an object.

results—the values returned by the function associated with restart, if that function returns.

Description:

Calls the function associated with restart, passing arguments to it. Restart must be valid in the current dynamic environment.

Examples:

(defun add3 (x) (check-type x number) (+ x 3)) 
(foo ’seven) 
▷ Error: The value SEVEN was not of type NUMBER. 
▷ To continue, type :CONTINUE followed by an option number: 
▷ 1: Specify a different value to use. 
▷ 2: Return to Lisp Toplevel. 
▷ Debug> (invoke-restart ’store-value 7) 
→ 10

Side Effects:

A non-local transfer of control might be done by the restart.

Affected By:

Existing restarts.

Exceptional Situations:

If restart is not valid, an error of type control-error is signaled.

See Also:

find-restart, restart-bind, restart-case, invoke-restart-interactively

Notes:

The most common use for invoke-restart is in a handler . It might be used explicitly, or implicitly through invoke-restart-interactively or a restart function.

Restart functions call invoke-restart, not vice versa. That is, invoke-restart provides primitive functionality, and restart functions are non-essential “syntactic sugar.”

invoke-restart-interactively

Expanded Reference: invoke-restart​

Invoking a Named Restart​

invoke-restart calls the function associated with a restart. The restart can be specified by name (a symbol) or by a restart object.

(restart-case
    (invoke-restart 'my-restart)
  (my-restart ()
    :invoked))

=> :INVOKED

Passing Arguments to a Restart​

Any additional arguments to invoke-restart are passed to the restart function.

(restart-case
    (invoke-restart 'use-value 42)
  (use-value (v)
    (format nil "Got value: ~A" v)))

=> "Got value: 42"

Invoking a Restart from a Handler​

The most common use of invoke-restart is from within a condition handler.

(handler-bind ((error (lambda (c)
                        (declare (ignore c))
                        (invoke-restart 'skip-item))))
  (restart-case
      (error "Bad item encountered")
    (skip-item ()
      :report "Skip the bad item."
      :skipped)))

=> :SKIPPED

Invoking the store-value Restart​

invoke-restart can invoke system-defined restarts like store-value, which is established by check-type.

(let ((x "not a number"))
  (handler-bind ((type-error (lambda (c)
                               (invoke-restart 'store-value 0))))
    (check-type x number)
    x))

=> 0

Invoking the continue Restart​

The continue restart is established by cerror and allows execution to proceed.

(handler-bind ((error (lambda (c)
                        (declare (ignore c))
                        (invoke-restart 'continue))))
  (cerror "Proceed anyway." "Something is wrong.")
  :continued)

=> :CONTINUED

Error When Restart Does Not Exist​

If the named restart is not active in the current dynamic environment, invoke-restart signals a control-error.

(handler-case
    (invoke-restart 'nonexistent-restart)
  (control-error ()
    :no-such-restart))

=> :NO-SUCH-RESTART