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 &optionalcondition

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-namerestart

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

[Function]
find-restartrestart-identifier&optionalcondition

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-restartrestart-identifier&restarguments

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-interactivelyrestart-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-restartrestart-identifierarguments).

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

AI.Repository@cs.cmu.edu