Skip to main content

invoke-restart-interactively

invoke-restart-interactively Function

Syntax:

invoke-restart-interactively restart → {result}*

Arguments and Values:

restart—a restart designator .

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

Description:

invoke-restart-interactively calls the function associated with restart, prompting for any necessary arguments. If restart is a name, it must be valid in the current dynamic environment.

invoke-restart-interactively prompts for arguments by executing the code provided in the :interactive keyword to restart-case or :interactive-function keyword to restart-bind.

If no such options have been supplied in the corresponding restart-bind or restart-case, then the consequences are undefined if the restart takes required arguments. If the arguments are optional, an argument list of nil is used.

Once the arguments have been determined, invoke-restart-interactively executes the following: (apply #’invoke-restart restart arguments)

Examples:

(defun add3 (x) (check-type x number) (+ x 3)) 
(add3 ’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-interactively ’store-value) 
▷ Type a form to evaluate and use: 7 
→ 10

Side Effects:

If prompting for arguments is necesary, some typeout may occur (on query I/O).

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

Affected By:

*query-io*, active restarts

Exceptional Situations:

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

See Also:

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

Notes:

invoke-restart-interactively is used internally by the debugger and may also be useful in implementing other portable, interactive debugging tools.

Expanded Reference: invoke-restart-interactively​

Basic Interactive Restart Invocation​

invoke-restart-interactively invokes a restart, using the :interactive option to gather arguments if the restart requires them. For restarts with no required arguments, it passes an empty argument list.

(restart-case
    (invoke-restart-interactively 'my-restart)
  (my-restart ()
    :report "Do the thing."
    :done))

=> :DONE

Restart with :interactive Option​

The :interactive option in restart-case specifies a function of no arguments that returns a list of arguments for the restart. invoke-restart-interactively calls this function to gather arguments.

(restart-case
    (invoke-restart-interactively 'use-value)
  (use-value (v)
    :report "Use a value."
    :interactive (lambda () (list 42))
    v))

=> 42

Used Internally by Debuggers​

invoke-restart-interactively is the mechanism debuggers use to invoke restarts chosen by the user. When writing custom debugger-like interfaces, it provides a standardized way to prompt for and supply restart arguments.

;; A simplified restart chooser
(defun choose-first-restart ()
  (let ((restarts (compute-restarts)))
    (when restarts
      (invoke-restart-interactively (first restarts)))))

Difference from invoke-restart​

invoke-restart requires the caller to supply arguments explicitly. invoke-restart-interactively obtains them via the :interactive facility, making it suitable for interactive (user-driven) restart selection.

;; invoke-restart: caller supplies arguments
(restart-case
    (invoke-restart 'use-value 100)
  (use-value (v) v))

=> 100
;; invoke-restart-interactively: arguments come from :interactive
(restart-case
    (invoke-restart-interactively 'use-value)
  (use-value (v)
    :interactive (lambda () (list 200))
    v))

=> 200