Common Lisp the Language, 2nd Edition

Next: Warnings Up: Program Interface to Previous: Establishing Restarts

## 29.4.8. Finding and Manipulating Restarts

The following functions determine what restarts are active and invoke restarts.

[Function]
`compute-restarts &optional condition`

Uses the dynamic state of the program to compute a list of the restarts that are currently active. See `restart-bind`.

If condition is `nil` or not supplied, all outstanding restarts are returned. If condition is not `nil`, only restarts associated with that condition are returned.

Each restart represents a function that can be called to perform some form of recovery action, usually a transfer of control to an outer point in the running program. Implementations are free to implement these objects in whatever manner is most convenient; the objects need have only dynamic extent (relative to the scope of the binding form that instantiates them).

The list that results from a call to `compute-restarts` is ordered so that the inner (that is, more recently established) restarts are nearer the head of the list.

Note, too, that `compute-restarts` returns all valid 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 different (that is, non-`eq`) lists from repeated calls to `compute-restarts` while in the same dynamic environment. It is an error to modify the list that is returned by `compute-restarts`.

[Function]
`restart-name restart`

Returns the name of the given restart, or `nil` if it is not named.

[Function]
`find-restart restart-identifier &optional condition`

Searches for a particular restart in the current dynamic environment.

If condition is `nil` or not supplied, all outstanding restarts are considered. If condition is not `nil`, only restarts associated with that condition are considered.

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

If restart-identifier is a restart object, then it is simply returned, unless it is not currently active, in which case `nil` is returned.

Although anonymous restarts have a name of `nil`, it is an error for the symbol `nil` to be given as the restart-identifier. Applications that would seem to require this should be rewritten to make appropriate use of `compute-restarts` instead.

[Function]
`invoke-restart restart-identifier &rest arguments`

Calls the function associated with the given restart-identifier, passing any given arguments. The restart-identifier must be a restart or the non-null name of a restart that is valid in the current dynamic context. If the argument is not valid, an error of type `control-error` will be signaled.

Implementation note: Restart functions call this function, not vice versa.

[Function]
`invoke-restart-interactively restart-identifier`

Calls the function associated with the given restart-identifier, prompting for any necessary arguments. The restart-identifier must be a restart or the non-null name of a restart that is valid in the current dynamic context. If the argument is not valid, an error of type `control-error` will be signaled.

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

If no `:interactive` or `:interactive-function` option has been supplied in the corresponding `restart-case` or `restart-bind`, then it is an error if the restart takes required arguments. If the arguments are optional, an empty argument list will be used in this case.

Once `invoke-restart-interactively` has calculated the arguments, it simply performs `(apply #'invoke-restart restart-identifier arguments)`.

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

Next: Warnings Up: Program Interface to Previous: Establishing Restarts