User Tools


Differences

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

Link to this comparison view

cl:functions:find-restart [2019/06/15 02:00]
cl:functions:find-restart [2019/08/17 15:00] (current)
Line 1: Line 1:
 +====== Function FIND-RESTART ======
 +
 +====Syntax====
 +  * **find-restart** //​identifier ''&​optional''​ condition// → //restart//
 +
 +====Arguments and Values====
 +  * //​identifier//​ - a //​[[CL:​Glossary:​non-nil]]//​ //​[[CL:​Glossary:​symbol]]//,​ or a //​[[CL:​Glossary:​restart]]//​.
 +  * //​condition//​ - a //​[[CL:​Glossary:​condition]]//​ //​[[CL:​Glossary:​object]]//,​ or **[[CL:​Constant Variables:​nil]]**.
 +  * //restart// - a //​[[CL:​Glossary:​restart]]//​ or **[[CL:​Constant Variables:​nil]]**.
 +
 +====Description====
 +**find-restart** searches for a particular //​[[CL:​Glossary:​restart]]//​ in the current //​[[CL:​Glossary:​dynamic environment]]//​.
 +
 +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.
 +
 +If //​identifier//​ is a //​[[CL:​Glossary:​symbol]]//,​ then the innermost (most recently established) //​[[CL:​Glossary:​applicable restart]]// with that //​[[CL:​Glossary:​name]]//​ is returned. **[[CL:​Constant Variables:​nil]]** is returned if no such restart is found.
 +
 +If //​identifier//​ is a currently active restart, then it is returned. Otherwise, **[[CL:​Constant Variables:​nil]]** is returned.
 +
 +====Examples====
 +<​blockquote>​
 +([[CL:​Macros:​restart-case]]
 +    ([[CL:​Special Operators:​let]] ((r (find-restart '​my-restart)))
 +      ([[CL:​Functions:​format]] [[CL:​Constant Variables:​t]] "~S is named ~S" r ([[CL:​Functions:​restart-name]] r)))
 +  (my-restart () [[CL:​Constant Variables:​nil]]))
 +<​o>#<​RESTART 32307325>​ is named MY-RESTART</​o>​
 +<​r>​[[CL:​Constant Variables:​nil|NIL]]</​r>​
 +  ​
 +(find-restart '​my-restart) <​r>​[[CL:​Constant Variables:​nil|NIL]]</​r>​
 +</​blockquote>​
 +
 +====Side Effects====
 +None.
 +
 +====Affected By====
 +Existing restarts.
 +
 +**[[CL:​Macros:​restart-case]]**,​ **[[CL:​Macros:​restart-bind]]**,​ **[[CL:​Macros:​with-condition-restarts]]**.
 +
 +====Exceptional Situations====
 +None.
 +
 +====See Also====
 +**[[CL:​Functions:​compute-restarts|Function COMPUTE-RESTARTS]]**
 +
 +====Notes====
 +<​blockquote>​
 +(find-restart //​identifier//​)
 +  ≡ ([[CL:​Functions:​find]] //​identifier//​ ([[CL:​Functions:​compute-restarts]]) :key :​restart-name)
 +</​blockquote>​
 +
 +Although anonymous restarts have a name of **[[CL:​Constant Variables:​nil]]**,​ the consequences are unspecified if **[[CL:​Constant Variables:​nil]]** is given as an //​identifier//​. Occasionally,​ programmers lament that **[[CL:​Constant Variables:​nil]]** is not permissible as an //​identifier//​ argument. In most such cases, **[[CL:​Functions:​compute-restarts]]** can probably be used to simulate the desired effect.
 +
 +\issue{CONDITION-RESTARTS:​PERMIT-ASSOCIATION} \issue{CONDITION-RESTARTS:​PERMIT-ASSOCIATION} \issue{CONDITION-RESTARTS:​PERMIT-ASSOCIATION}