77 lines
10 KiB
HTML
77 lines
10 KiB
HTML
<!-- Common Lisp HyperSpec (TM), version 7.0 generated by Kent M. Pitman on Mon, 11-Apr-2005 2:31am EDT -->
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>CLHS: Macro RESTART-BIND</TITLE>
|
|
<LINK HREF="../Data/clhs.css" REL="stylesheet" TYPE="text/css" />
|
|
<META HTTP-EQUIV="Author" CONTENT="Kent M. Pitman">
|
|
<META HTTP-EQUIV="Organization" CONTENT="LispWorks Ltd.">
|
|
<LINK REL=TOP HREF="../Front/index.htm">
|
|
<LINK REL=COPYRIGHT HREF="../Front/Help.htm#Legal">
|
|
<LINK REL=DISCLAIMER HREF="../Front/Help.htm#Disclaimer">
|
|
<LINK REL=PREV HREF="f_invo_2.htm">
|
|
<LINK REL=UP HREF="c_condit.htm">
|
|
<LINK REL=NEXT HREF="m_rst_ca.htm">
|
|
</HEAD>
|
|
<BODY>
|
|
<H1><A REV=MADE HREF="http://www.lispworks.com/"><IMG WIDTH=80 HEIGHT=65 ALT="[LISPWORKS]" SRC="../Graphics/LWSmall.gif" ALIGN=Bottom></A><A REL=TOP HREF="../Front/index.htm"><IMG WIDTH=237 HEIGHT=65 ALT="[Common Lisp HyperSpec (TM)]" SRC="../Graphics/CLHS_Sm.gif" ALIGN=Bottom></A> <A REL=PREV HREF="f_invo_2.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Previous]" SRC="../Graphics/Prev.gif" ALIGN=Bottom></A><A REL=UP HREF="c_condit.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Up]" SRC="../Graphics/Up.gif" ALIGN=Bottom></A><A REL=NEXT HREF="m_rst_ca.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Next]" SRC="../Graphics/Next.gif" ALIGN=Bottom></A></H1>
|
|
|
|
<HR>
|
|
|
|
<A NAME="restart-bind"><I>Macro</I> <B>RESTART-BIND</B></A> <P>
|
|
<P><B>Syntax:</B><P>
|
|
<P>
|
|
|
|
<B>restart-bind</B> <I>({(name function {<I>key-val-pair</I>}<B>*</B>)}) <I>form</I><B>*</B></I><P> => <I><I>result</I><B>*</B></I><P>
|
|
<P>
|
|
<PRE>
|
|
key-val-pair::= :interactive-function interactive-function |
|
|
:report-function report-function |
|
|
:test-function test-function
|
|
</PRE>
|
|
<P>
|
|
<P><B>Arguments and Values:</B><P>
|
|
<P>
|
|
<I>name</I>---a <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbol</I></A>; not evaluated. <P>
|
|
<I>function</I>---a <A REL=DEFINITION HREF="26_glo_f.htm#form"><I>form</I></A>; evaluated. <P>
|
|
<I>forms</I>---an <A REL=DEFINITION HREF="26_glo_i.htm#implicit_progn"><I>implicit progn</I></A>. <P>
|
|
<I>interactive-function</I>---a <A REL=DEFINITION HREF="26_glo_f.htm#form"><I>form</I></A>; evaluated. <P>
|
|
<I>report-function</I>---a <A REL=DEFINITION HREF="26_glo_f.htm#form"><I>form</I></A>; evaluated. <P>
|
|
<I>test-function</I>---a <A REL=DEFINITION HREF="26_glo_f.htm#form"><I>form</I></A>; evaluated. <P>
|
|
<I>results</I>---the <A REL=DEFINITION HREF="26_glo_v.htm#value"><I>values</I></A> returned by the <A REL=DEFINITION HREF="26_glo_f.htm#form"><I>forms</I></A>. <P>
|
|
<P><B>Description:</B><P>
|
|
<P>
|
|
<A REL=DEFINITION HREF="#restart-bind"><B>restart-bind</B></A> executes the body of <I>forms</I> in a <A REL=DEFINITION HREF="26_glo_d.htm#dynamic_environment"><I>dynamic environment</I></A> where <A REL=DEFINITION HREF="26_glo_r.htm#restart"><I>restarts</I></A> with the given <I>names</I> are in effect. <P>
|
|
If a <I>name</I> is <A REL=DEFINITION HREF="a_nil.htm#nil"><B>nil</B></A>, it indicates an anonymous restart; if a <I>name</I> is a <A REL=DEFINITION HREF="26_glo_n.htm#non-nil"><I>non-nil</I></A> <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbol</I></A>, it indicates a named restart. <P>
|
|
The <I>function</I>, <I>interactive-function</I>, and <I>report-function</I> are unconditionally evaluated in the current lexical and dynamic environment prior to evaluation of the body. Each of these <A REL=DEFINITION HREF="26_glo_f.htm#form"><I>forms</I></A> must evaluate to a <A REL=DEFINITION HREF="26_glo_f.htm#function"><I>function</I></A>. <P>
|
|
If <A REL=DEFINITION HREF="f_invo_1.htm#invoke-restart"><B>invoke-restart</B></A> is done on that restart, the <A REL=DEFINITION HREF="26_glo_f.htm#function"><I>function</I></A> which resulted from evaluating <I>function</I> is called, in the <A REL=DEFINITION HREF="26_glo_d.htm#dynamic_environment"><I>dynamic environment</I></A> of the <A REL=DEFINITION HREF="f_invo_1.htm#invoke-restart"><B>invoke-restart</B></A>, with the <A REL=DEFINITION HREF="26_glo_a.htm#argument"><I>arguments</I></A> given to <A REL=DEFINITION HREF="f_invo_1.htm#invoke-restart"><B>invoke-restart</B></A>. The <A REL=DEFINITION HREF="26_glo_f.htm#function"><I>function</I></A> may either perform a non-local transfer of control or may return normally. <P>
|
|
If the restart is invoked interactively from the debugger (using <A REL=DEFINITION HREF="f_invo_2.htm#invoke-restart-interactively"><B>invoke-restart-interactively</B></A>), the arguments are defaulted by calling the <A REL=DEFINITION HREF="26_glo_f.htm#function"><I>function</I></A> which resulted from evaluating <I>interactive-function</I>. That <A REL=DEFINITION HREF="26_glo_f.htm#function"><I>function</I></A> may optionally prompt interactively on <A REL=DEFINITION HREF="26_glo_q.htm#query_iSLo"><I>query I/O</I></A>, and should return a <A REL=DEFINITION HREF="26_glo_l.htm#list"><I>list</I></A> of arguments to be used by <A REL=DEFINITION HREF="f_invo_2.htm#invoke-restart-interactively"><B>invoke-restart-interactively</B></A> when invoking the restart. <P>
|
|
If a restart is invoked interactively but no <I>interactive-function</I> is used, then an argument list of <A REL=DEFINITION HREF="a_nil.htm#nil"><B>nil</B></A> is used. In that case, the <A REL=DEFINITION HREF="26_glo_f.htm#function"><I>function</I></A> must be compatible with an empty argument list. <P>
|
|
If the restart is presented interactively (e.g., by the debugger), the presentation is done by calling the <A REL=DEFINITION HREF="26_glo_f.htm#function"><I>function</I></A> which resulted from evaluating <I>report-function</I>. This <A REL=DEFINITION HREF="26_glo_f.htm#function"><I>function</I></A> must be a <A REL=DEFINITION HREF="26_glo_f.htm#function"><I>function</I></A> of one argument, a <A REL=DEFINITION HREF="26_glo_s.htm#stream"><I>stream</I></A>. It is expected to print a description of the action that the restart takes to that <A REL=DEFINITION HREF="26_glo_s.htm#stream"><I>stream</I></A>. This <A REL=DEFINITION HREF="26_glo_f.htm#function"><I>function</I></A> is called any time the restart is printed while <A REL=DEFINITION HREF="v_pr_esc.htm#STprint-escapeST"><B>*print-escape*</B></A> is <A REL=DEFINITION HREF="a_nil.htm#nil"><B>nil</B></A>. <P>
|
|
In the case of interactive invocation, the result is dependent on the value of <TT>:interactive-function</TT> as follows. <P>
|
|
<P><DL><DT><TT>:interactive-function</TT> <P><DD>
|
|
<I>Value</I> is evaluated in the current lexical environment and should return a <A REL=DEFINITION HREF="26_glo_f.htm#function"><I>function</I></A> of no arguments which constructs a <A REL=DEFINITION HREF="26_glo_l.htm#list"><I>list</I></A> of arguments to be used by <A REL=DEFINITION HREF="f_invo_2.htm#invoke-restart-interactively"><B>invoke-restart-interactively</B></A> when invoking this restart. The <A REL=DEFINITION HREF="26_glo_f.htm#function"><I>function</I></A> may prompt interactively using <A REL=DEFINITION HREF="26_glo_q.htm#query_iSLo"><I>query I/O</I></A> if necessary. <P>
|
|
<DT><TT>:report-function</TT> <P><DD>
|
|
<I>Value</I> is evaluated in the current lexical environment and should return a <A REL=DEFINITION HREF="26_glo_f.htm#function"><I>function</I></A> of one argument, a <A REL=DEFINITION HREF="26_glo_s.htm#stream"><I>stream</I></A>, which prints on the <A REL=DEFINITION HREF="26_glo_s.htm#stream"><I>stream</I></A> a summary of the action that this restart takes. This <A REL=DEFINITION HREF="26_glo_f.htm#function"><I>function</I></A> is called whenever the restart is reported (printed while <A REL=DEFINITION HREF="v_pr_esc.htm#STprint-escapeST"><B>*print-escape*</B></A> is <A REL=DEFINITION HREF="a_nil.htm#nil"><B>nil</B></A>). If no <TT>:report-function</TT> option is provided, the manner in which the <A REL=DEFINITION HREF="26_glo_r.htm#restart"><I>restart</I></A> is reported is <A REL=DEFINITION HREF="26_glo_i.htm#implementation-dependent"><I>implementation-dependent</I></A>. <P>
|
|
<DT><TT>:test-function</TT> <P><DD>
|
|
<I>Value</I> is evaluated in the current lexical environment and should return a <A REL=DEFINITION HREF="26_glo_f.htm#function"><I>function</I></A> of one argument, a <A REL=DEFINITION HREF="26_glo_c.htm#condition"><I>condition</I></A>, which returns <A REL=DEFINITION HREF="26_glo_t.htm#true"><I>true</I></A> if the restart is to be considered visible. <P>
|
|
<P></DL><P>
|
|
<P><B>Side Effects:</B> None.
|
|
<P>
|
|
<P><B>Affected By:</B><P>
|
|
<P>
|
|
<A REL=DEFINITION HREF="v_debug_.htm#STquery-ioST"><B>*query-io*</B></A>. <P>
|
|
<P><B>Exceptional Situations:</B> None.
|
|
<P>
|
|
<P><B>See Also:</B><P>
|
|
<P>
|
|
<A REL=DEFINITION HREF="m_rst_ca.htm#restart-case"><B>restart-case</B></A>, <A REL=DEFINITION HREF="m_w_smp_.htm#with-simple-restart"><B>with-simple-restart</B></A> <P>
|
|
<P><B>Notes:</B><P>
|
|
<P>
|
|
<A REL=DEFINITION HREF="#restart-bind"><B>restart-bind</B></A> is primarily intended to be used to implement <A REL=DEFINITION HREF="m_rst_ca.htm#restart-case"><B>restart-case</B></A> and might be useful in implementing other macros. Programmers who are uncertain about whether to use <A REL=DEFINITION HREF="m_rst_ca.htm#restart-case"><B>restart-case</B></A> or <A REL=DEFINITION HREF="#restart-bind"><B>restart-bind</B></A> should prefer <A REL=DEFINITION HREF="m_rst_ca.htm#restart-case"><B>restart-case</B></A> for the cases where it is powerful enough, using <A REL=DEFINITION HREF="#restart-bind"><B>restart-bind</B></A> only in cases where its full generality is really needed. <P>
|
|
<P><HR>The following <A REL=META HREF="../Front/X3J13Iss.htm">X3J13 cleanup issue</A>, <I>not part of the specification</I>, applies to this section:<P><UL><LI> <A REL=CHILD HREF="../Issues/iss076.htm">CONDITION-RESTARTS:PERMIT-ASSOCIATION</A><P></UL><HR>
|
|
|
|
<A REL=NAVIGATOR HREF="../Front/StartPts.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Starting Points]" SRC="../Graphics/StartPts.gif" ALIGN=Bottom></A><A REL=TOC HREF="../Front/Contents.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Contents]" SRC="../Graphics/Contents.gif" ALIGN=Bottom></A><A REL=INDEX HREF="../Front/X_Master.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Index]" SRC="../Graphics/Index.gif" ALIGN=Bottom></A><A REL=INDEX HREF="../Front/X_Symbol.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Symbols]" SRC="../Graphics/Symbols.gif" ALIGN=Bottom></A><A REL=GLOSSARY HREF="../Body/26_a.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Glossary]" SRC="../Graphics/Glossary.gif" ALIGN=Bottom></A><A HREF="../Front/X3J13Iss.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Issues]" SRC="../Graphics/Issues.gif" ALIGN=Bottom></A><BR>
|
|
|
|
<A REL=COPYRIGHT HREF="../Front/Help.htm#Legal"><I>Copyright 1996-2005, LispWorks Ltd. All rights reserved.</I></A><P>
|
|
</BODY>
|
|
</HTML>
|