https://lisp-docs.github.io/cl-language-reference/assets/js/97b4f9ca.8de194f7.js

1"use strict";(globalThis.webpackChunkcl_language_reference||=[]).push([[3246],{40745(e,n,r){r.r(n),r.d(n,{assets:()=>h,contentTitle:()=>o,default:()=>m,frontMatter:()=>a,metadata:()=>t,toc:()=>x});const t=JSON.parse('{"id":"chap-9/j-c-dictionary/find-restart_function","title":"find-restart","description":"Expanded Reference: find-restart","source":"@site/docs/chap-9/j-c-dictionary/find-restart_function.md","sourceDirName":"chap-9/j-c-dictionary","slug":"/chap-9/j-c-dictionary/find-restart_function","permalink":"/cl-language-reference/chap-9/j-c-dictionary/find-restart_function","draft":false,"unlisted":false,"editUrl":"https://github.com/lisp-docs/cl-language-reference/tree/main/docs/chap-9/j-c-dictionary/find-restart_function.md","tags":[],"version":"current","lastUpdatedBy":"daninus14","frontMatter":{"title":"find-restart"},"sidebar":"tutorialSidebar","previous":{"title":"error","permalink":"/cl-language-reference/chap-9/j-c-dictionary/error_function"},"next":{"title":"handler-bind","permalink":"/cl-language-reference/chap-9/j-c-dictionary/handler-bind_macro"}}');var i=r(74848),s=r(28453);function d(e){const n={code:"code",em:"em",p:"p",pre:"pre",strong:"strong",...(0,s.R)(),...e.components},{DictionaryLink:r,GlossaryTerm:t}=n;return r||l("DictionaryLink",!0),t||l("GlossaryTerm",!0),(0,i.jsxs)(i.Fragment,{children:[(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"find-restart"})," ",(0,i.jsx)(t,{styled:!0,term:"function",children:(0,i.jsx)("i",{children:"Function"})})]}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"Syntax:"})}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(r,{styled:!0,term:"find-restart",children:(0,i.jsx)("b",{children:"find-restart"})})," ",(0,i.jsx)(t,{styled:!0,term:"identifier",children:(0,i.jsx)("i",{children:"identifier"})})," &optional ",(0,i.jsx)(t,{styled:!0,term:"condition",children:(0,i.jsx)("i",{children:"condition"})})]}),"\n",(0,i.jsx)(n.p,{children:"restart"}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"Arguments and Values:"})}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(t,{styled:!0,term:"identifier",children:(0,i.jsx)("i",{children:"identifier"})}),"\u2014a ",(0,i.jsx)(n.em,{children:"non-nil symbol"}),", or a ",(0,i.jsx)(t,{styled:!0,term:"restart",children:(0,i.jsx)("i",{children:"restart"})}),"."]}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(t,{styled:!0,term:"condition",children:(0,i.jsx)("i",{children:"condition"})}),"\u2014a ",(0,i.jsx)(n.em,{children:"condition object"}),", or ",(0,i.jsx)(r,{styled:!0,term:"nil",children:(0,i.jsx)("b",{children:"nil"})}),"."]}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(t,{styled:!0,term:"restart",children:(0,i.jsx)("i",{children:"restart"})}),"\u2014a ",(0,i.jsx)(t,{styled:!0,term:"restart",children:(0,i.jsx)("i",{children:"restart"})})," or ",(0,i.jsx)(r,{styled:!0,term:"nil",children:(0,i.jsx)("b",{children:"nil"})}),"."]}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"Description:"})}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(r,{styled:!0,term:"find-restart",children:(0,i.jsx)("b",{children:"find-restart"})})," searches for a particular ",(0,i.jsx)(t,{styled:!0,term:"restart",children:(0,i.jsx)("i",{children:"restart"})})," in the current ",(0,i.jsx)(t,{styled:!0,term:"dynamic environment",children:(0,i.jsx)("i",{children:"dynamic environment"})}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["When ",(0,i.jsx)(t,{styled:!0,term:"condition",children:(0,i.jsx)("i",{children:"condition"})})," is ",(0,i.jsx)(t,{styled:!0,term:"non-nil",children:(0,i.jsx)("i",{children:"non-nil"})}),", only those ",(0,i.jsx)(t,{styled:!0,term:"restart",children:(0,i.jsx)("i",{children:"restarts"})})," are considered that are either explicitly associated with that ",(0,i.jsx)(t,{styled:!0,term:"condition",children:(0,i.jsx)("i",{children:"condition"})}),", or not associated with any ",(0,i.jsx)(t,{styled:!0,term:"condition",children:(0,i.jsx)("i",{children:"condition"})}),"; that is, the excluded ",(0,i.jsx)(t,{styled:!0,term:"restart",children:(0,i.jsx)("i",{children:"restarts"})})," are those that are associated with a non-empty set of ",(0,i.jsx)(t,{styled:!0,term:"

1condition",children:(0,i.jsx)("i",{children:"conditions"})})," of which the given ",(0,i.jsx)(t,{styled:!0,term:"condition",children:(0,i.jsx)("i",{children:"condition"})})," is not an ",(0,i.jsx)(t,{styled:!0,term:"element",children:(0,i.jsx)("i",{children:"element"})}),". If ",(0,i.jsx)(t,{styled:!0,term:"condition",children:(0,i.jsx)("i",{children:"condition"})})," is ",(0,i.jsx)(r,{styled:!0,term:"nil",children:(0,i.jsx)("b",{children:"nil"})}),", all ",(0,i.jsx)(t,{styled:!0,term:"restart",children:(0,i.jsx)("i",{children:"restarts"})})," are considered."]}),"\n",(0,i.jsxs)(n.p,{children:["If ",(0,i.jsx)(t,{styled:!0,term:"identifier",children:(0,i.jsx)("i",{children:"identifier"})})," is a ",(0,i.jsx)(t,{styled:!0,term:"symbol",children:(0,i.jsx)("i",{children:"symbol"})}),", then the innermost (most recently established) ",(0,i.jsx)(t,{styled:!0,term:"applicable restart",children:(0,i.jsx)("i",{children:"applicable restart"})})," with that ",(0,i.jsx)(t,{styled:!0,term:"name",children:(0,i.jsx)("i",{children:"name"})})," is returned. ",(0,i.jsx)(r,{styled:!0,term:"nil",children:(0,i.jsx)("b",{children:"nil"})})," is returned if no such restart is found."]}),"\n",(0,i.jsxs)(n.p,{children:["If ",(0,i.jsx)(t,{styled:!0,term:"identifier",children:(0,i.jsx)("i",{children:"identifier"})})," is a currently active restart, then it is returned. Otherwise, ",(0,i.jsx)(r,{styled:!0,term:"nil",children:(0,i.jsx)("b",{children:"nil"})})," is returned."]}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"Examples:"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-lisp",children:'(restart-case \n    (let ((r (find-restart \u2019my-restart))) \n      (format t "~S is named ~S" r (restart-name r))) \n  (my-restart () nil)) \n\u25b7 #<RESTART 32307325> is named MY-RESTART \n\u2192 NIL \n(find-restart \u2019my-restart) \n\u2192 NIL \n'})}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"Affected By:"})}),"\n",(0,i.jsx)(n.p,{children:"Existing restarts."}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(r,{styled:!0,term:"restart-case",children:(0,i.jsx)("b",{children:"restart-case"})}),", ",(0,i.jsx)(r,{styled:!0,term:"restart-bind",children:(0,i.jsx)("b",{children:"restart-bind"})}),", ",(0,i.jsx)(r,{styled:!0,term:"with-condition-restarts",children:(0,i.jsx)("b",{children:"with-condition-restarts"})}),"."]}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"See Also:"})}),"\n",(0,i.jsx)(r,{styled:!0,term:"compute-restarts",children:(0,i.jsx)("b",{children:"compute-restarts"})}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"Notes:"})}),"\n",(0,i.jsxs)(n.p,{children:["(find-restart ",(0,i.jsx)(t,{styled:!0,term:"identifier",children:(0,i.jsx)("i",{children:"identifier"})}),")"]}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.em,{children:"\u2261"})," (find ",(0,i.jsx)(t,{styled:!0,term:"identifier",children:(0,i.jsx)("i",{children:"identifier"})})," (compute-restarts) ",":key"," ",":restart-name",")"]}),"\n",(0,i.jsxs)(n.p,{children:["Although anonymous restarts have a name of ",(0,i.jsx)(r,{styled:!0,term:"nil",children:(0,i.jsx)("b",{children:"nil"})}),", the consequences are unspecified if ",(0,i.jsx)(r,{styled:!0,term:"nil",children:(0,i.jsx)("b",{children:"nil"})})," is given as an ",(0,i.jsx)(t,{styled:!0,term:"identifier",children:(0,i.jsx)("i",{children:"identifier"})}),". Occasionally, programmers lament that ",(0,i.jsx)(r,{styled:!0,term:"nil",children:(0,i.jsx)("b",{children:"nil"})})," is not permissible as an ",(0,i.jsx)(t,{styled:!0,term:"identifier",children:(0,i.jsx)("i",{children:"identifier"})})," argument. In most such cases, ",(0,i.jsx)(r,{styled:!0,term:"compute-restarts",children:(0,i.jsx)("b",{children:"compute-restarts"})})," can probably be used to simulate the desired effect."]})]})}function c(e={}){const{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(d,{...e})}):d(e)}function l(e,n){throw new Error("Expected "+(n?"component":"object")+" `"+e+"` to be defined: you likely forgot to import, pass, or provide it.")}const a={title:"find-restart"},o="find-restart",h={},x=[{value:"Expanded Reference: find-restart",id:"expanded-reference-find-restart",level:2},{value:"Finding an Active Restart",id:"finding-an-active-restart",level:3},{value:"No Matching Restart",id:"no-matching-restart",level:3},{value:"Checking Before Invoking",id:"checking-before-invoking",level:3},{value:"Getting the Restart Name",id:"getting-the-restart-name",level:3},{value:"Filtering by Condition",id:"filtering-by-condition",level:3}];function j(e){const n={code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",p:"p",pre:"pre",...(0,s.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.header,{children:(0,i.jsx)(n.h1,{id:"find-restart",children:"find-restart"})}),"\n","\n",(0,i.jsx)(c,{}),"\n",(0,i.jsx)(n.h2,{id:"expanded-reference-find-restart",children:"Expanded Reference: find-restart"}),"\n",(0,i.jsx)(n.h3,{id:"finding-an-active-restart",children:"Finding an Active Restart"}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"find-restart"})," searches for the most recently established restart with the given name. It returns the restart object if found, or ",(0,i.jsx)(n.code,{children:"nil"})," otherwise."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-lisp",children:"(restart-case\n    (let ((r (find-restart 'my-restart)))\n      (if r :found :not-found))\n  (my-restart () nil))\n\n=> :FOUND\n"})}),"\n",(0,i.jsx)(n.h3,{id:"no-matching-restart",children:"No Matching Restart"}),"\n",(0,i.jsxs)(n.p,{children:["When no restart with the given name is active, ",(0,i.jsx)(n.code,{children:"find-restart"})," returns ",(0,i.jsx)(n.code,{children:"nil"}),"."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-lisp",children:"(find-restart 'nonexistent)\n\n=>

1 NIL\n"})}),"\n",(0,i.jsx)(n.h3,{id:"checking-before-invoking",children:"Checking Before Invoking"}),"\n",(0,i.jsxs)(n.p,{children:["A common pattern is to check whether a restart exists before invoking it. This avoids a ",(0,i.jsx)(n.code,{children:"control-error"}),"."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-lisp",children:'(handler-bind ((warning (lambda (c)\n                          (let ((r (find-restart \'muffle-warning c)))\n                            (when r (invoke-restart r))))))\n  (warn "This will be muffled.")\n  :done)\n\n=> :DONE\n'})}),"\n",(0,i.jsx)(n.h3,{id:"getting-the-restart-name",children:"Getting the Restart Name"}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"find-restart"})," returns a restart object. You can query its name with ",(0,i.jsx)(n.code,{children:"restart-name"}),"."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-lisp",children:"(restart-case\n    (let ((r (find-restart 'do-something)))\n      (restart-name r))\n  (do-something () nil))\n\n=> DO-SOMETHING\n"})}),"\n",(0,i.jsx)(n.h3,{id:"filtering-by-condition",children:"Filtering by Condition"}),"\n",(0,i.jsx)(n.p,{children:"The optional second argument restricts the search to restarts associated with a particular condition (or not associated with any condition)."}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-lisp",children:'(restart-case\n    (handler-bind ((error (lambda (c)\n                            (let ((r (find-restart \'fix c)))\n                              (if r\n                                  (invoke-restart r)\n                                  (error "No fix restart for ~A" c))))))\n      (error "something broke"))\n  (fix ()\n    :report "Fix the problem."\n    :fixed))\n\n=> :FIXED\n'})})]})}function m(e={}){const{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(j,{...e})}):j(e)}},28453(e,n,r){r.d(n,{R:()=>d,x:()=>c});var t=r(96540);const i={},s=t.createContext(i);function d(e){const n=t.useContext(s);return t.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function c(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:d(e.components),t.createElement(s.Provider,{value:n},e.children)}}}]);