User Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

cl:functions:compute-restarts [2019/11/11 05:00]
cl:functions:compute-restarts [2019/12/08 22: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}