Differences
This shows you the differences between two versions of the page.
|
cl:functions:compute-restarts [2019/11/11 05:00] |
cl:functions:compute-restarts [2020/08/03 20:00] (current) |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| + | ====== Function COMPUTE-RESTARTS ====== | ||
| + | |||
| + | ====Syntax==== | ||
| + | **compute-restarts** //''&optional'' condition// → //restarts// | ||
| + | |||
| + | ====Arguments and Values==== | ||
| + | //condition// - a //[[CL:Glossary:condition]]// //[[CL:Glossary:object]]//, or **[[CL:Constant Variables:nil]]**. | ||
| + | //restarts// - a //[[CL:Glossary:list]]// of //[[CL:Glossary:restart|restarts]]//. | ||
| + | |||
| + | ====Description==== | ||
| + | **compute-restarts** uses the dynamic state of the program to compute a //[[CL:Glossary:list]]// of the //[[CL:Glossary:restart|restarts]]// which are currently active. | ||
| + | |||
| + | The resulting //[[CL:Glossary:list]]// is ordered so that the innermost (more-recently established) restarts are nearer the head of the //[[CL:Glossary:list]]//. | ||
| + | |||
| + | When //condition// is //[[CL:Glossary:non-nil]]//, only those //[[CL:Glossary:restart|restarts]]// are considered that are either explicitly associated with that //condition//, or not associated with any //[[CL:Glossary:condition]]//; that is, the excluded //[[CL:Glossary:restart|restarts]]// are those that are associated with a non-empty set of //[[CL:Glossary:condition|conditions]]// of which the given //condition// is not an //[[CL:Glossary:element]]//. If //condition// is **[[CL:Constant Variables:nil]]**, all //[[CL:Glossary:restart|restarts]]// are considered. | ||
| + | |||
| + | **compute-restarts** returns all //[[CL:Glossary:applicable restart|restarts]]//, including anonymous ones, even if some of them have the same name as others and would therefore not be found by **[[CL:Functions:find-restart]]** when given a //[[CL:Glossary:symbol]]// argument. | ||
| + | |||
| + | Implementations are permitted, but not required, to return //[[CL:Glossary:distinct]]// //[[CL:Glossary:list|lists]]// from repeated calls to **compute-restarts** while in the same dynamic environment. The consequences are undefined if the //[[CL:Glossary:list]]// returned by **compute-restarts** is modified. | ||
| + | |||
| + | ====Examples==== | ||
| + | This example shows one possible way in which an interactive debugger might present restarts to the user. | ||
| + | <blockquote> | ||
| + | ([[CL:Macros:defun]] invoke-a-restart () | ||
| + | ([[CL:Special Operators:let]] ((restarts (compute-restarts))) | ||
| + | ([[CL:Macros:do]] ((i 0 ([[CL:Functions:math-one-plus|1+]] i)) | ||
| + | (r restarts ([[CL:Functions:cdr]] r))) | ||
| + | (([[CL:Functions:null]] r)) | ||
| + | ([[CL:Functions:format]] [[CL:Constant Variables:t]] "~&~D: ~A~%" i ([[CL:Functions:car]] r))) | ||
| + | ([[CL:Special Operators:let]] ((n [[CL:Constant Variables:nil]]) | ||
| + | (k ([[CL:Functions:length]] restarts))) | ||
| + | ([[CL:Macros:loop]] | ||
| + | ([[CL:Macros:when]] ([[CL:Macros:and]] ([[CL:Functions:typep]] n '[[CL:Types:integer]]) ([[CL:Functions:math-not-less|>=]] n 0) ([[CL:Functions:math-less|<]] n k)) | ||
| + | ([[CL:Macros:return]])) | ||
| + | ([[CL:Functions:format]] [[CL:Constant Variables:t]] "~&Option: ") | ||
| + | ([[CL:Macros:setf]] n ([[CL:Functions:read]])) | ||
| + | ([[CL:Functions:fresh-line]])) | ||
| + | ([[CL:Functions:invoke-restart-interactively]] ([[CL:Functions:nth]] n restarts))))) <r>INVOKE-A-RESTART</r> | ||
| + | |||
| + | ([[CL:Macros:restart-case]] (invoke-a-restart) | ||
| + | (one () 1) | ||
| + | (two () 2) | ||
| + | (nil () :report "Who knows?" 'anonymous) | ||
| + | (one () 'I) | ||
| + | (two () 'II)) | ||
| + | <o>0: ONE | ||
| + | 1: TWO | ||
| + | 2: Who knows? | ||
| + | 3: ONE | ||
| + | 4: TWO | ||
| + | 5: Return to Lisp Toplevel. | ||
| + | Option: 4 </o> | ||
| + | <r>II</r> | ||
| + | </blockquote> | ||
| + | |||
| + | Note that in addition to user-defined restart points, **compute-restarts** also returns information about any system-supplied [[CL:Glossary:restart|restarts]], such as the "Return to Lisp Toplevel" [[CL:Glossary:restart]] offered above. | ||
| + | |||
| + | ====Side Effects==== | ||
| + | None. | ||
| + | |||
| + | ====Affected By==== | ||
| + | Existing restarts. | ||
| + | |||
| + | ====Exceptional Situations==== | ||
| + | None. | ||
| + | |||
| + | ====See Also==== | ||
| + | **[[CL:Functions:find-restart|Function FIND-RESTART]]**, **[[CL:Functions:invoke-restart|Function INVOKE-RESTART]]**, **[[CL:Macros:restart-bind|Macro RESTART-BIND]]** | ||
| + | |||
| + | ====Notes==== | ||
| + | None. | ||
| + | |||
| + | \issue{CONDITION-RESTARTS:PERMIT-ASSOCIATION} \issue{CONDITION-RESTARTS:PERMIT-ASSOCIATION} \issue{CONDITION-RESTARTS:PERMIT-ASSOCIATION} | ||
