marcuskammer/cl-sites
1
0
Fork 0
Code Activity
cl-sites/novaspec.org/cl/9_1_Condition_System_Concepts.html

2951 lines
71 KiB
HTML
Raw Normal View History

Add novaspec
2025-02-05 18:52:26 +01:00
<!DOCTYPE HTML>
<HTML LANG="en-us"
><HEAD
><TITLE
>9.1 Condition System Concepts | Common Lisp Nova Spec</TITLE
><META CHARSET="US-ASCII"
><LINK REL="canonical" HREF="9_1_Condition_System_Concepts.html"
><LINK REL="next" HREF="9_2_Conditions_Dictionary.html" TYPE="text/html" TITLE="9.2 Conditions Dictionary"
><LINK REL="prev" HREF="9_Conditions.html" TYPE="text/html" TITLE="9. Conditions"
><LINK REL="up" HREF="9_Conditions.html" TYPE="text/html" TITLE="9. Conditions"
><LINK REL="start" HREF="index.html" TYPE="text/html" TITLE="Common Lisp Nova Spec"
><META NAME="VIEWPORT" CONTENT="width=device-width, initial-scale=1.0"
><LINK REL="STYLESHEET" HREF="dpans.css%3F3909942064.css"
><SCRIPT SRC="dpans.js%3F3909942064"
></SCRIPT
><SCRIPT SRC="apropos.js%3F3909942064"
></SCRIPT
></HEAD
><BODY
><DIV
><DIV CLASS="topnav"
><DIV CLASS="breadcrumb"
><SPAN CLASS="breadcrumb-item"
><A HREF="index.html"
>Common Lisp Nova Spec</A
></SPAN
> <SPAN CLASS="breadcrumb-item"
>&#8594; <A HREF="9_Conditions.html"
>9. Conditions</A
></SPAN
> <SPAN CLASS="breadcrumb-item"
>&#8594; <A HREF="9_1_Condition_System_Concepts.html"
>9.1 Condition System Concepts</A
></SPAN
></DIV
><DIV CLASS="apropos"
><DIV CLASS="apropos-io"
><A HREF="9_Conditions.html" CLASS="prev"
>&#8592;</A
><SPAN ID="apropos-label"
>Apropos </SPAN
><INPUT ID="apropos" AUTOFOCUS="AUTOFOCUS" PLACEHOLDER="Type here to search" ONINPUT="aproposInput(this);" ONKEYUP="aproposKeyup(event);" ONCHANGE="aproposChange(this);" ONFOCUS="aproposFocus(this);" ONFOCUSOUT="aproposFocusout(this);"
><A HREF="9_2_Conditions_Dictionary.html" CLASS="next"
>&#8594;</A
></DIV
><DIV ID="apropos-res"
></DIV
></DIV
></DIV
><DIV CLASS="matter"
><SECTION
><H2 ID="sec_9_1" CLASS="HeadII"
>9.1 Condition System Concepts</H2
><UL CLASS="subtoc"
><LI
><A HREF="9_1_Condition_System_Concepts.html#sec_9_1_1"
>9.1.1 Condition Types</A
></LI
><LI
><A HREF="9_1_Condition_System_Concepts.html#sec_9_1_1_1"
>9.1.1.1 Serious Conditions</A
></LI
><LI
><A HREF="9_1_Condition_System_Concepts.html#sec_9_1_2"
>9.1.2 Creating Conditions</A
></LI
><LI
><A HREF="9_1_Condition_System_Concepts.html#sec_9_1_2_1"
>9.1.2.1 Condition Designators</A
></LI
><LI
><A HREF="9_1_Condition_System_Concepts.html#sec_9_1_3"
>9.1.3 Printing Conditions</A
></LI
><LI
><A HREF="9_1_Condition_System_Concepts.html#sec_9_1_3_1"
>9.1.3.1 Recommended Style in Condition Reporting</A
></LI
><LI
><A HREF="9_1_Condition_System_Concepts.html#sec_9_1_3_1_1"
>9.1.3.1.1 Capitalization and Punctuation in Condition Reports</A
></LI
><LI
><A HREF="9_1_Condition_System_Concepts.html#sec_9_1_3_1_2"
>9.1.3.1.2 Leading and Trailing Newlines in Condition Reports</A
></LI
><LI
><A HREF="9_1_Condition_System_Concepts.html#sec_9_1_3_1_3"
>9.1.3.1.3 Embedded Newlines in Condition Reports</A
></LI
><LI
><A HREF="9_1_Condition_System_Concepts.html#sec_9_1_3_1_4"
>9.1.3.1.4 Note about Tabs in Condition Reports</A
></LI
><LI
><A HREF="9_1_Condition_System_Concepts.html#sec_9_1_3_1_5"
>9.1.3.1.5 Mentioning Containing Function in Condition Reports</A
></LI
><LI
><A HREF="9_1_Condition_System_Concepts.html#sec_9_1_4"
>9.1.4 Signaling and Handling Conditions</A
></LI
><LI
><A HREF="9_1_Condition_System_Concepts.html#sec_9_1_4_1"
>9.1.4.1 Signaling</A
></LI
><LI
><A HREF="9_1_Condition_System_Concepts.html#sec_9_1_4_1_1"
>9.1.4.1.1 Resignaling a Condition</A
></LI
><LI
><A HREF="9_1_Condition_System_Concepts.html#sec_9_1_4_2"
>9.1.4.2 Restarts</A
></LI
><LI
><A HREF="9_1_Condition_System_Concepts.html#sec_9_1_4_2_1"
>9.1.4.2.1 Interactive Use of Restarts</A
></LI
><LI
><A HREF="9_1_Condition_System_Concepts.html#sec_9_1_4_2_2"
>9.1.4.2.2 Interfaces to Restarts</A
></LI
><LI
><A HREF="9_1_Condition_System_Concepts.html#sec_9_1_4_2_3"
>9.1.4.2.3 Restart Tests</A
></LI
><LI
><A HREF="9_1_Condition_System_Concepts.html#sec_9_1_4_2_4"
>9.1.4.2.4 Associating a Restart with a Condition</A
></LI
><LI
><A HREF="9_1_Condition_System_Concepts.html#sec_9_1_5"
>9.1.5 Assertions</A
></LI
><LI
><A HREF="9_1_Condition_System_Concepts.html#sec_9_1_6"
>9.1.6 Notes about the Condition System&#8217;s Background</A
></LI
></UL
><P CLASS="j"
>Common Lisp constructs are described not only in terms of their behavior in situations during which they are intended to be used (see the &#8220;Description&#8221; part of each <A HREF="26_1_Glossary.html#operator"
><EM CLASS="term"
>operator</EM
></A
> specification), but in all other situations (see the &#8220;Exceptional Situations&#8221; part of each <A HREF="26_1_Glossary.html#operator"
><EM CLASS="term"
>operator</EM
></A
> specification). </P
><P CLASS="j"
>A situation is the evaluation of an expression in a specific context. A <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> is an <A HREF="26_1_Glossary.html#object"
><EM CLASS="term"
>object</EM
></A
> that represents a specific situation that has been detected. <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>Conditions</EM
></A
> are <A HREF="26_1_Glossary.html#generalized_instance"
><EM CLASS="term"
>generalized instances</EM
></A
> of the <A HREF="26_1_Glossary.html#class"
><EM CLASS="term"
>class</EM
></A
> <A HREF="t_condition.html" CLASS="typeref"
><B
>condition</B
></A
>. A hierarchy of <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> classes is defined in Common Lisp. A <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> has <A HREF="26_1_Glossary.html#slot"
><EM CLASS="term"
>slots</EM
></A
> that contain data relevant to the situation that the <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> represents. </P
><P CLASS="j"
>An error is a situation in which normal program execution cannot continue correctly without some form of intervention (either interactively by the user or under program control). Not all errors are detected. When an error goes undetected, the effects can be <A HREF="26_1_Glossary.html#implementation-dependent"
><EM CLASS="term"
>implementation-dependent</EM
></A
>, <A HREF="26_1_Glossary.html#implementation-defined"
><EM CLASS="term"
>implementation-defined</EM
></A
>, unspecified, or undefined. See <A HREF="1_4_Definitions.html#sec_1_4" CLASS="secref"
><SPAN CLASS="cmr"
>Section</SPAN
> <SPAN CLASS="cmr"
>1.4</SPAN
> <SPAN CLASS="cmr"
>(Definitions)</SPAN
></A
>. All detected errors can be represented by <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>conditions</EM
></A
>, but not all <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>conditions</EM
></A
> represent errors. </P
><P CLASS="j"
>Signaling is the process by which a <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> can alter the flow of control in a program by raising the <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> which can then be <A HREF="26_1_Glossary.html#handle"
><EM CLASS="term"
>handled</EM
></A
>. The functions <A HREF="f_error.html" CLASS="funref"
><B
>error</B
></A
>, <A HREF="f_cerror.html" CLASS="funref"
><B
>cerror</B
></A
>, <A HREF="f_signal.html" CLASS="funref"
><B
>signal</B
></A
>, and <A HREF="f_warn.html" CLASS="funref"
><B
>warn</B
></A
> are used to signal <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>conditions</EM
></A
>. </P
><P CLASS="j"
>The process of signaling involves the selection and invocation of a <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>handler</EM
></A
> from a set of <A HREF="26_1_Glossary.html#active"
><EM CLASS="term"
>active</EM
></A
> <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>handlers</EM
></A
>. A <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>handler</EM
></A
> is a <A HREF="26_1_Glossary.html#function"
><EM CLASS="term"
>function</EM
></A
> of one argument (the <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
>) that is invoked to handle a <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
>. Each <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>handler</EM
></A
> is associated with a <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>type</EM
></A
>, and a <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>handler</EM
></A
> will be invoked only on a <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> of the <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>handler</EM
></A
>&#8217;s associated <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>type</EM
></A
>. </P
><P CLASS="j"
><A HREF="26_1_Glossary.html#active"
><EM CLASS="term"
>Active</EM
></A
> <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>handlers</EM
></A
> are <A HREF="26_1_Glossary.html#establish"
><EM CLASS="term"
>established</EM
></A
> dynamically (see <A HREF="f_handler-bind.html" CLASS="macref"
><B
>handler-bind</B
></A
> or <A HREF="f_handler-case.html" CLASS="macref"
><B
>handler-case</B
></A
>). <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>Handlers</EM
></A
> are invoked in a <A HREF="26_1_Glossary.html#dynamic_environment"
><EM CLASS="term"
>dynamic environment</EM
></A
> equivalent to that of the signaler, except that the set of <A HREF="26_1_Glossary.html#active"
><EM CLASS="term"
>active</EM
></A
> <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>handlers</EM
></A
> is bound in such a way as to include only those that were <A HREF="26_1_Glossary.html#active"
><EM CLASS="term"
>active</EM
></A
> at the time the <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>handler</EM
></A
> being invoked was <A HREF="26_1_Glossary.html#establish"
><EM CLASS="term"
>established</EM
></A
>. Signaling a <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> has no side-effect on the <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
>, and there is no dynamic state contained in a <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
>. </P
><P CLASS="j"
>If a <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>handler</EM
></A
> is invoked, it can address the <A HREF="26_1_Glossary.html#situation"
><EM CLASS="term"
>situation</EM
></A
> in one of three ways:</P
><DL
><DT
><B CLASS="b"
>Decline</B
></DT
><DD
><P CLASS="j"
>It can decline to <A HREF="26_1_Glossary.html#handle"
><EM CLASS="term"
>handle</EM
></A
> the <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
>. It does this by simply returning rather than transferring control. When this happens, any values returned by the handler are ignored and the next most recently established handler is invoked. If there is no such handler and the signaling function is <A HREF="f_error.html" CLASS="funref"
><B
>error</B
></A
> or <A HREF="f_cerror.html" CLASS="funref"
><B
>cerror</B
></A
>, the debugger is entered in the <A HREF="26_1_Glossary.html#dynamic_environment"
><EM CLASS="term"
>dynamic environment</EM
></A
> of the signaler. If there is no such handler and the signaling function is either <A HREF="f_signal.html" CLASS="funref"
><B
>signal</B
></A
> or <A HREF="f_warn.html" CLASS="funref"
><B
>warn</B
></A
>, the signaling function simply returns&#160;<SPAN CLASS="misc"
><B
>nil</B
></SPAN
>.</P
></DD
><DT
><B CLASS="b"
>Handle</B
></DT
><DD
><P CLASS="j"
>It can <A HREF="26_1_Glossary.html#handle"
><EM CLASS="term"
>handle</EM
></A
> the <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> by performing a non-local transfer of control. This can be done either primitively by using <A HREF="f_go.html" CLASS="specref"
><B
>go</B
></A
>, <A HREF="f_return.html" CLASS="macref"
><B
>return</B
></A
>, <A HREF="f_throw.html" CLASS="specref"
><B
>throw</B
></A
> or more abstractly by using a function such as <A HREF="f_abort.html" CLASS="funref"
><B
>abort</B
></A
> or <A HREF="f_invoke-restart.html" CLASS="funref"
><B
>invoke-restart</B
></A
>.</P
></DD
><DT
><B CLASS="b"
>Defer</B
></DT
><DD
><P CLASS="j"
>It can put off a decision about whether to <A HREF="26_1_Glossary.html#handle"
><EM CLASS="term"
>handle</EM
></A
> or <A HREF="26_1_Glossary.html#decline"
><EM CLASS="term"
>decline</EM
></A
>, by any of a number of actions, but most commonly by signaling another condition, resignaling the same condition, or forcing entry into the debugger.</P
></DD
></DL
><H3 ID="sec_9_1_1" CLASS="HeadIII"
>9.1.1 Condition Types</H3
><P CLASS="j"
>Figure 9&#8211;1 lists the <A HREF="26_1_Glossary.html#standardized"
><EM CLASS="term"
>standardized</EM
></A
> <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>types</EM
></A
>. Additional <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>types</EM
></A
> can be defined by using <A HREF="f_define-condition.html" CLASS="macref"
><B
>define-condition</B
></A
>.</P
><DIV CLASS="displaythree"
><FIGURE CLASS="boxfig"
><DIV CLASS="figbody"
><TABLE CELLSPACING="0" CELLPADDING="0" RULES="GROUPS" STYLE="margin: 1ex 0" WIDTH="100%"
><TBODY
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE=";padding-right:1em"
><A HREF="t_arithmetic-error.html" CLASS="misc"
><B
>arithmetic-error</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;padding-right:1em"
> <A HREF="t_floating-point-overflow.html" CLASS="misc"
><B
>floating-point-overflow</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;"
> <A HREF="t_simple-type-error.html" CLASS="misc"
><B
>simple-type-error</B
></A
></TD
></TR
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE=";padding-right:1em"
> <A HREF="t_cell-error.html" CLASS="misc"
><B
>cell-error</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;padding-right:1em"
> <A HREF="t_floating-point-underflow.html" CLASS="misc"
><B
>floating-point-underflow</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;"
> <A HREF="t_simple-warning.html" CLASS="misc"
><B
>simple-warning</B
></A
></TD
></TR
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE=";padding-right:1em"
> <A HREF="t_condition.html" CLASS="misc"
><B
>condition</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;padding-right:1em"
> <A HREF="t_package-error.html" CLASS="misc"
><B
>package-error</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;"
> <A HREF="t_storage-condition.html" CLASS="misc"
><B
>storage-condition</B
></A
></TD
></TR
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE=";padding-right:1em"
> <A HREF="t_control-error.html" CLASS="misc"
><B
>control-error</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;padding-right:1em"
> <A HREF="t_parse-error.html" CLASS="misc"
><B
>parse-error</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;"
> <A HREF="t_stream-error.html" CLASS="misc"
><B
>stream-error</B
></A
></TD
></TR
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE=";padding-right:1em"
> <A HREF="t_division-by-zero.html" CLASS="misc"
><B
>division-by-zero</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;padding-right:1em"
> <A HREF="t_print-not-readable.html" CLASS="misc"
><B
>print-not-readable</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;"
> <A HREF="t_style-warning.html" CLASS="misc"
><B
>style-warning</B
></A
></TD
></TR
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE=";padding-right:1em"
> <A HREF="t_end-of-file.html" CLASS="misc"
><B
>end-of-file</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;padding-right:1em"
> <A HREF="t_program-error.html" CLASS="misc"
><B
>program-error</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;"
> <A HREF="t_type-error.html" CLASS="misc"
><B
>type-error</B
></A
></TD
></TR
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE=";padding-right:1em"
> <A HREF="t_error.html" CLASS="typeref"
><B
>error</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;padding-right:1em"
> <A HREF="t_reader-error.html" CLASS="misc"
><B
>reader-error</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;"
> <A HREF="t_unbound-slot.html" CLASS="misc"
><B
>unbound-slot</B
></A
></TD
></TR
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE=";padding-right:1em"
> <A HREF="t_file-error.html" CLASS="misc"
><B
>file-error</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;padding-right:1em"
> <A HREF="t_serious-condition.html" CLASS="misc"
><B
>serious-condition</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;"
> <A HREF="t_unbound-variable.html" CLASS="misc"
><B
>unbound-variable</B
></A
></TD
></TR
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE=";padding-right:1em"
> <A HREF="t_floating-point-inexact.html" CLASS="misc"
><B
>floating-point-inexact</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;padding-right:1em"
> <A HREF="t_simple-condition.html" CLASS="misc"
><B
>simple-condition</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;"
> <A HREF="t_undefined-function.html" CLASS="misc"
><B
>undefined-function</B
></A
></TD
></TR
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE=";padding-right:1em"
> <A HREF="t_floating-point-invalid-operation.html" CLASS="misc"
><B
>floating-point-invalid-operation</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;padding-right:1em"
> <A HREF="t_simple-error.html" CLASS="misc"
><B
>simple-error</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;"
> <A HREF="t_warning.html" CLASS="misc"
><B
>warning</B
></A
></TD
></TR
></TBODY
></TABLE
></DIV
><FIGCAPTION CLASS="caption"
><B
>Figure 9&#8211;1. Standardized Condition Types</B
></FIGCAPTION
></FIGURE
></DIV
><P CLASS="j"
>All <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> types are <A HREF="26_1_Glossary.html#subtype"
><EM CLASS="term"
>subtypes</EM
></A
> of <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>type</EM
></A
> <A HREF="t_condition.html" CLASS="typeref"
><B
>condition</B
></A
>. That is,</P
><PRE CLASS="screen"
>(typep <VAR CLASS="param"
>c</VAR
> 'condition) <SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> <A HREF="26_1_Glossary.html#true"
><EM CLASS="term"
>true</EM
></A
></PRE
><P CLASS="j"
>if and only if <VAR CLASS="param"
>c</VAR
> is a <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
>. </P
><P CLASS="j"
><A HREF="26_1_Glossary.html#implementation"
><EM CLASS="term"
>Implementations</EM
></A
> must define all specified <A HREF="26_1_Glossary.html#subtype"
><EM CLASS="term"
>subtype</EM
></A
> relationships. Except where noted, all <A HREF="26_1_Glossary.html#subtype"
><EM CLASS="term"
>subtype</EM
></A
> relationships indicated in this document are not mutually exclusive. A <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> inherits the structure of its <A HREF="26_1_Glossary.html#supertype"
><EM CLASS="term"
>supertypes</EM
></A
>. </P
><P CLASS="j"
>The metaclass of the <A HREF="26_1_Glossary.html#class"
><EM CLASS="term"
>class</EM
></A
> <A HREF="t_condition.html" CLASS="typeref"
><B
>condition</B
></A
> is not specified. <A HREF="26_1_Glossary.html#name"
><EM CLASS="term"
>Names</EM
></A
> of <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>types</EM
></A
> may be used to specify <A HREF="26_1_Glossary.html#supertype"
><EM CLASS="term"
>supertype</EM
></A
> relationships in <A HREF="f_define-condition.html" CLASS="macref"
><B
>define-condition</B
></A
>, but the consequences are not specified if an attempt is made to use a <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>type</EM
></A
> as a <A HREF="26_1_Glossary.html#superclass"
><EM CLASS="term"
>superclass</EM
></A
> in a <A HREF="f_defclass.html" CLASS="macref"
><B
>defclass</B
></A
> <A HREF="26_1_Glossary.html#form"
><EM CLASS="term"
>form</EM
></A
>. </P
><P CLASS="j"
>Figure 9&#8211;2 shows <A HREF="26_1_Glossary.html#operator"
><EM CLASS="term"
>operators</EM
></A
> that define <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>types</EM
></A
> and creating <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>conditions</EM
></A
>.</P
><DIV CLASS="displaythree"
><FIGURE CLASS="boxfig"
><DIV CLASS="figbody"
><TABLE CELLSPACING="0" CELLPADDING="0" RULES="GROUPS" STYLE="margin: 1ex 0" WIDTH="100%"
><TBODY
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE=";padding-right:1em"
><A HREF="f_define-condition.html" CLASS="misc"
><B
>define-condition</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;padding-right:1em"
> <A HREF="f_make-condition.html" CLASS="misc"
><B
>make-condition</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;"
><SPAN CLASS="misc"
></SPAN
></TD
></TR
></TBODY
></TABLE
></DIV
><FIGCAPTION CLASS="caption"
><B
>Figure 9&#8211;2. Operators that define and create conditions.</B
></FIGCAPTION
></FIGURE
></DIV
><P CLASS="j"
>Figure 9&#8211;3 shows <A HREF="26_1_Glossary.html#operator"
><EM CLASS="term"
>operators</EM
></A
> that <A HREF="26_1_Glossary.html#read"
><EM CLASS="term"
>read</EM
></A
> the <A HREF="26_1_Glossary.html#value"
><EM CLASS="term"
>value</EM
></A
> of <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> <A HREF="26_1_Glossary.html#slot"
><EM CLASS="term"
>slots</EM
></A
>.</P
><FIGURE CLASS="boxfig"
><DIV CLASS="figbody"
><TABLE CELLSPACING="0" CELLPADDING="0" RULES="GROUPS" STYLE="margin: 1ex 0" WIDTH="100%"
><TBODY
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" STYLE=";padding-right:3px"
><A HREF="f_arithmetic-error-operands.html" CLASS="misc"
><B
>arithmetic-error-operands</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" STYLE="padding-left:3px;"
> <A HREF="f_simple-condition-format-control.html" CLASS="misc"
><B
>simple-condition-format-arguments</B
></A
></TD
></TR
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" STYLE=";padding-right:3px"
> <A HREF="f_arithmetic-error-operands.html" CLASS="misc"
><B
>arithmetic-error-operation</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" STYLE="padding-left:3px;"
> <A HREF="f_simple-condition-format-control.html" CLASS="misc"
><B
>simple-condition-format-control</B
></A
></TD
></TR
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" STYLE=";padding-right:3px"
> <A HREF="f_cell-error-name.html" CLASS="misc"
><B
>cell-error-name</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" STYLE="padding-left:3px;"
> <A HREF="f_stream-error-stream.html" CLASS="misc"
><B
>stream-error-stream</B
></A
></TD
></TR
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" STYLE=";padding-right:3px"
> <A HREF="f_file-error-pathname.html" CLASS="misc"
><B
>file-error-pathname</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" STYLE="padding-left:3px;"
> <A HREF="f_type-error-datum.html" CLASS="misc"
><B
>type-error-datum</B
></A
></TD
></TR
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" STYLE=";padding-right:3px"
> <A HREF="f_package-error-package.html" CLASS="misc"
><B
>package-error-package</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" STYLE="padding-left:3px;"
> <A HREF="f_type-error-datum.html" CLASS="misc"
><B
>type-error-expected-type</B
></A
></TD
></TR
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" STYLE=";padding-right:3px"
> <A HREF="f_print-not-readable-object.html" CLASS="misc"
><B
>print-not-readable-object</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" STYLE="padding-left:3px;"
> <A HREF="f_unbound-slot-instance.html" CLASS="misc"
><B
>unbound-slot-instance</B
></A
></TD
></TR
></TBODY
></TABLE
></DIV
><FIGCAPTION CLASS="caption"
><B
>Figure 9&#8211;3. Operators that read condition slots.</B
></FIGCAPTION
></FIGURE
><H4 ID="sec_9_1_1_1" CLASS="HeadIV"
>9.1.1.1 Serious Conditions</H4
><P CLASS="j"
>A <A HREF="26_1_Glossary.html#serious_condition"
><EM CLASS="term"
>serious condition</EM
></A
> is a <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> serious enough to require interactive intervention if not handled. <A HREF="26_1_Glossary.html#serious_condition"
><EM CLASS="term"
>Serious conditions</EM
></A
> are typically signaled with <A HREF="f_error.html" CLASS="funref"
><B
>error</B
></A
> or <A HREF="f_cerror.html" CLASS="funref"
><B
>cerror</B
></A
>; non-serious <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>conditions</EM
></A
> are typically signaled with <A HREF="f_signal.html" CLASS="funref"
><B
>signal</B
></A
> or <A HREF="f_warn.html" CLASS="funref"
><B
>warn</B
></A
>.</P
><H3 ID="sec_9_1_2" CLASS="HeadIII"
>9.1.2 Creating Conditions</H3
><P CLASS="j"
>The function <A HREF="f_make-condition.html" CLASS="funref"
><B
>make-condition</B
></A
> can be used to construct a <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> <A HREF="26_1_Glossary.html#object"
><EM CLASS="term"
>object</EM
></A
> explicitly. Functions such as <A HREF="f_error.html" CLASS="funref"
><B
>error</B
></A
>, <A HREF="f_cerror.html" CLASS="funref"
><B
>cerror</B
></A
>, <A HREF="f_signal.html" CLASS="funref"
><B
>signal</B
></A
>, and <A HREF="f_warn.html" CLASS="funref"
><B
>warn</B
></A
> operate on <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>conditions</EM
></A
> and might create <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> <A HREF="26_1_Glossary.html#object"
><EM CLASS="term"
>objects</EM
></A
> implicitly. Macros such as <A HREF="f_case.html" CLASS="macref"
><B
>ccase</B
></A
>, <A HREF="f_typecase.html" CLASS="macref"
><B
>ctypecase</B
></A
>, <A HREF="f_case.html" CLASS="macref"
><B
>ecase</B
></A
>, <A HREF="f_typecase.html" CLASS="macref"
><B
>etypecase</B
></A
>, <A HREF="f_check-type.html" CLASS="macref"
><B
>check-type</B
></A
>, and <A HREF="f_assert.html" CLASS="macref"
><B
>assert</B
></A
> might also implicitly create (and <A HREF="26_1_Glossary.html#signal"
><EM CLASS="term"
>signal</EM
></A
>) <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>conditions</EM
></A
>.</P
><H4 ID="sec_9_1_2_1" CLASS="HeadIV"
>9.1.2.1 Condition Designators</H4
><P CLASS="j"
>A number of the functions in the condition system take arguments which are identified as <DFN CLASS="newterm"
><SPAN CLASS="cmbxsl"
>condition</SPAN
> <SPAN CLASS="cmbxsl"
>designators</SPAN
></DFN
><SPAN CLASS="idx" DATA-KIND="idxterm" DATA-TERM="condition designator"
></SPAN
>. By convention, those arguments are notated as </P
><P CLASS="j"
><VAR CLASS="param"
>datum</VAR
> <SPAN CLASS="cmtt"
>&amp;rest</SPAN
> <VAR CLASS="param"
>arguments</VAR
> </P
><P CLASS="j"
>Taken together, the <VAR CLASS="param"
>datum</VAR
> and the <VAR CLASS="param"
>arguments</VAR
> are &#8220;<A HREF="26_1_Glossary.html#designator"
><EM CLASS="term"
>designators</EM
></A
> for a <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> of default type <VAR CLASS="param"
>default-type</VAR
>.&#8221; How the denoted <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> is computed depends on the type of the <VAR CLASS="param"
>datum</VAR
>:</P
><DL
><DT
><SPAN CLASS="item"
><SPAN CLASS="cmsy"
>&#8226;</SPAN
> <SPAN CLASS="cmr"
>If</SPAN
> <SPAN CLASS="cmr"
>the</SPAN
> <VAR CLASS="param"
>datum</VAR
> <SPAN CLASS="cmr"
>is</SPAN
> <SPAN CLASS="cmr"
>a</SPAN
> <A HREF="26_1_Glossary.html#symbol"
><EM CLASS="term"
>symbol</EM
></A
> <SPAN CLASS="cmr"
>naming</SPAN
> <SPAN CLASS="cmr"
>a</SPAN
> <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>type</EM
></A
> <I
>.</I
>&#8201;<I
>.</I
>&#8201;<I
>.</I
></SPAN
></DT
><DD
><P CLASS="j"
>The denoted <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> is the result of</P
><PRE CLASS="screen"
>(apply #'make-condition <VAR CLASS="param"
>datum</VAR
> <VAR CLASS="param"
>arguments</VAR
>)</PRE
></DD
><DT
><SPAN CLASS="item"
><SPAN CLASS="cmsy"
>&#8226;</SPAN
> <SPAN CLASS="cmr"
>If</SPAN
> <SPAN CLASS="cmr"
>the</SPAN
> <VAR CLASS="param"
>datum</VAR
> <SPAN CLASS="cmr"
>is</SPAN
> <SPAN CLASS="cmr"
>a</SPAN
> <A HREF="26_1_Glossary.html#format_control"
><EM CLASS="term"
>format control</EM
></A
> <I
>.</I
>&#8201;<I
>.</I
>&#8201;<I
>.</I
></SPAN
></DT
><DD
><P CLASS="j"
>The denoted <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> is the result of</P
><PRE CLASS="screen"
>(make-condition <VAR CLASS="param"
>defaulted-type</VAR
>
:format-control <VAR CLASS="param"
>datum</VAR
>
:format-arguments <VAR CLASS="param"
>arguments</VAR
>)</PRE
><P CLASS="j"
>where the <VAR CLASS="param"
>defaulted-type</VAR
> is a <A HREF="26_1_Glossary.html#subtype"
><EM CLASS="term"
>subtype</EM
></A
> of <VAR CLASS="param"
>default-type</VAR
>.</P
></DD
><DT
><SPAN CLASS="item"
><SPAN CLASS="cmsy"
>&#8226;</SPAN
> <SPAN CLASS="cmr"
>If</SPAN
> <SPAN CLASS="cmr"
>the</SPAN
> <VAR CLASS="param"
>datum</VAR
> <SPAN CLASS="cmr"
>is</SPAN
> <SPAN CLASS="cmr"
>a</SPAN
> <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> <I
>.</I
>&#8201;<I
>.</I
>&#8201;<I
>.</I
></SPAN
></DT
><DD
><P CLASS="j"
>The denoted <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> is the <VAR CLASS="param"
>datum</VAR
> itself. In this case, unless otherwise specified by the description of the <A HREF="26_1_Glossary.html#operator"
><EM CLASS="term"
>operator</EM
></A
> in question, the <A HREF="26_1_Glossary.html#argument"
><EM CLASS="term"
>arguments</EM
></A
> must be <A HREF="26_1_Glossary.html#null"
><EM CLASS="term"
>null</EM
></A
>; that is, the consequences are undefined if any <VAR CLASS="param"
>arguments</VAR
> were supplied.</P
></DD
></DL
><P CLASS="j"
>Note that the <VAR CLASS="param"
>default-type</VAR
> gets used only in the case where the <VAR CLASS="param"
>datum</VAR
> <A HREF="26_1_Glossary.html#string"
><EM CLASS="term"
>string</EM
></A
> is supplied. In the other situations, the resulting condition is not necessarily of <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>type</EM
></A
> <VAR CLASS="param"
>default-type</VAR
>. </P
><P CLASS="j"
>Here are some illustrations of how different <A HREF="26_1_Glossary.html#condition_designator"
><EM CLASS="term"
>condition designators</EM
></A
> can denote equivalent <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> <A HREF="26_1_Glossary.html#object"
><EM CLASS="term"
>objects</EM
></A
>:</P
><PRE CLASS="screen"
>(let ((c (make-condition 'arithmetic-error :operator '/ :operands '(7 0))))
(error c))
<SPAN CLASS="cmsy"
><SPAN STYLE="font-size:16px;vertical-align:-2px"
>&#8801;</SPAN
></SPAN
> (error 'arithmetic-error :operator '/ :operands '(7 0))
(error "Bad luck.")
<SPAN CLASS="cmsy"
><SPAN STYLE="font-size:16px;vertical-align:-2px"
>&#8801;</SPAN
></SPAN
> (error 'simple-error :format-control "Bad luck." :format-arguments '())</PRE
><H3 ID="sec_9_1_3" CLASS="HeadIII"
>9.1.3 Printing Conditions</H3
><P CLASS="j"
>If the <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:report</SPAN
></SPAN
> argument to <A HREF="f_define-condition.html" CLASS="macref"
><B
>define-condition</B
></A
> is used, a print function is defined that is called whenever the defined <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> is printed while the <A HREF="26_1_Glossary.html#value"
><EM CLASS="term"
>value</EM
></A
> of <A HREF="v_print-escape.html" CLASS="misc"
><B
>*print-escape*</B
></A
> is <A HREF="26_1_Glossary.html#false"
><EM CLASS="term"
>false</EM
></A
>. This function is called the <DFN CLASS="newterm"
><SPAN CLASS="cmbxsl"
>condition</SPAN
> <SPAN CLASS="cmbxsl"
>reporter</SPAN
></DFN
><SPAN CLASS="idx" DATA-KIND="idxterm" DATA-TERM="condition reporter"
></SPAN
>; the text which it outputs is called a <DFN CLASS="newterm"
><SPAN CLASS="cmbxsl"
>report</SPAN
> <SPAN CLASS="cmbxsl"
>message</SPAN
></DFN
><SPAN CLASS="idx" DATA-KIND="idxterm" DATA-TERM="report message"
></SPAN
>. </P
><P CLASS="j"
>When a <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> is printed and <A HREF="v_print-escape.html" CLASS="varref"
><B
>*print-escape*</B
></A
> is <A HREF="26_1_Glossary.html#false"
><EM CLASS="term"
>false</EM
></A
>, the <A HREF="26_1_Glossary.html#condition_reporter"
><EM CLASS="term"
>condition reporter</EM
></A
> for the <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> is invoked. <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>Conditions</EM
></A
> are printed automatically by functions such as <A HREF="f_invoke-debugger.html" CLASS="funref"
><B
>invoke-debugger</B
></A
>, <A HREF="f_break.html" CLASS="funref"
><B
>break</B
></A
>, and <A HREF="f_warn.html" CLASS="funref"
><B
>warn</B
></A
>. </P
><P CLASS="j"
>When <A HREF="v_print-escape.html" CLASS="varref"
><B
>*print-escape*</B
></A
> is <A HREF="26_1_Glossary.html#true"
><EM CLASS="term"
>true</EM
></A
>, the <A HREF="26_1_Glossary.html#object"
><EM CLASS="term"
>object</EM
></A
> should print in an abbreviated fashion according to the style of the implementation (<I CLASS="i"
><I
>e.g.</I
></I
>, by <A HREF="f_print-unreadable-object.html" CLASS="macref"
><B
>print-unreadable-object</B
></A
>). It is not required that a <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> can be recreated by reading its printed representation. </P
><P CLASS="j"
>No <A HREF="26_1_Glossary.html#function"
><EM CLASS="term"
>function</EM
></A
> is provided for directly <A HREF="26_1_Glossary.html#access"
><EM CLASS="term"
>accessing</EM
></A
> or invoking <A HREF="26_1_Glossary.html#condition_reporter"
><EM CLASS="term"
>condition reporters</EM
></A
>.</P
><H4 ID="sec_9_1_3_1" CLASS="HeadIV"
>9.1.3.1 Recommended Style in Condition Reporting</H4
><P CLASS="j"
>In order to ensure a properly aesthetic result when presenting <A HREF="26_1_Glossary.html#report_message"
><EM CLASS="term"
>report messages</EM
></A
> to the user, certain stylistic conventions are recommended. </P
><P CLASS="j"
>There are stylistic recommendations for the content of the messages output by <A HREF="26_1_Glossary.html#condition_reporter"
><EM CLASS="term"
>condition reporters</EM
></A
>, but there are no formal requirements on those <A HREF="26_1_Glossary.html#program"
><EM CLASS="term"
>programs</EM
></A
>. If a <A HREF="26_1_Glossary.html#program"
><EM CLASS="term"
>program</EM
></A
> violates the recommendations for some message, the display of that message might be less aesthetic than if the guideline had been observed, but the <A HREF="26_1_Glossary.html#program"
><EM CLASS="term"
>program</EM
></A
> is still considered a <A HREF="26_1_Glossary.html#conforming_program"
><EM CLASS="term"
>conforming program</EM
></A
>. </P
><P CLASS="j"
>The requirements on a <A HREF="26_1_Glossary.html#program"
><EM CLASS="term"
>program</EM
></A
> or <A HREF="26_1_Glossary.html#implementation"
><EM CLASS="term"
>implementation</EM
></A
> which invokes a <A HREF="26_1_Glossary.html#condition_reporter"
><EM CLASS="term"
>condition reporter</EM
></A
> are somewhat stronger. A <A HREF="26_1_Glossary.html#conforming_program"
><EM CLASS="term"
>conforming program</EM
></A
> must be permitted to assume that if these style guidelines are followed, proper aesthetics will be maintained. Where appropriate, any specific requirements on such routines are explicitly mentioned below.</P
><H5 ID="sec_9_1_3_1_1" CLASS="HeadV"
>9.1.3.1.1 Capitalization and Punctuation in Condition Reports</H5
><P CLASS="j"
>It is recommended that a <A HREF="26_1_Glossary.html#report_message"
><EM CLASS="term"
>report message</EM
></A
> be a complete sentences, in the proper case and correctly punctuated. In English, for example, this means the first letter should be uppercase, and there should be a trailing period.</P
><PRE CLASS="screen"
>(error "This is a message") ; Not recommended
(error "this is a message.") ; Not recommended
(error "This is a message.") ; Recommended instead</PRE
><H5 ID="sec_9_1_3_1_2" CLASS="HeadV"
>9.1.3.1.2 Leading and Trailing Newlines in Condition Reports</H5
><P CLASS="j"
>It is recommended that a <A HREF="26_1_Glossary.html#report_message"
><EM CLASS="term"
>report message</EM
></A
> not begin with any introductory text, such as &#8220;<CODE CLASS="f"
>Error:</CODE
> &#8221; or &#8220;<CODE CLASS="f"
>Warning:</CODE
> &#8221; or even just <A HREF="26_1_Glossary.html#freshline"
><EM CLASS="term"
>freshline</EM
></A
> or <A HREF="26_1_Glossary.html#newline"
><EM CLASS="term"
>newline</EM
></A
>. Such text is added, if appropriate to the context, by the routine invoking the <A HREF="26_1_Glossary.html#condition_reporter"
><EM CLASS="term"
>condition reporter</EM
></A
>. </P
><P CLASS="j"
>It is recommended that a <A HREF="26_1_Glossary.html#report_message"
><EM CLASS="term"
>report message</EM
></A
> not be followed by a trailing <A HREF="26_1_Glossary.html#freshline"
><EM CLASS="term"
>freshline</EM
></A
> or <A HREF="26_1_Glossary.html#newline"
><EM CLASS="term"
>newline</EM
></A
>. Such text is added, if appropriate to the context, by the routine invoking the <A HREF="26_1_Glossary.html#condition_reporter"
><EM CLASS="term"
>condition reporter</EM
></A
>.</P
><PRE CLASS="screen"
>(error "This is a message.~%") ; Not recommended
(error "~&amp;This is a message.") ; Not recommended
(error "~&amp;This is a message.~%") ; Not recommended
(error "This is a message.") ; Recommended instead</PRE
><H5 ID="sec_9_1_3_1_3" CLASS="HeadV"
>9.1.3.1.3 Embedded Newlines in Condition Reports</H5
><P CLASS="j"
>Especially if it is long, it is permissible and appropriate for a <A HREF="26_1_Glossary.html#report_message"
><EM CLASS="term"
>report message</EM
></A
> to contain one or more embedded <A HREF="26_1_Glossary.html#newline"
><EM CLASS="term"
>newlines</EM
></A
>. </P
><P CLASS="j"
>If the calling routine conventionally inserts some additional prefix (such as &#8220;<CODE CLASS="f"
>Error:</CODE
> &#8221; or &#8220;<CODE CLASS="f"
>;; Error:</CODE
> &#8221;) on the first line of the message, it must also assure that an appropriate prefix will be added to each subsequent line of the output, so that the left edge of the message output by the <A HREF="26_1_Glossary.html#condition_reporter"
><EM CLASS="term"
>condition reporter</EM
></A
> will still be properly aligned.</P
><PRE CLASS="screen"
>(defun test ()
(error "This is an error message.~%It has two lines."))
;; Implementation A
(test)
This is an error message.
It has two lines.
;; Implementation B
(test)
;; Error: This is an error message.
;; It has two lines.
;; Implementation C
(test)
&gt;&gt; Error: This is an error message.
It has two lines.</PRE
><H5 ID="sec_9_1_3_1_4" CLASS="HeadV"
>9.1.3.1.4 Note about Tabs in Condition Reports</H5
><P CLASS="j"
>Because the indentation of a <A HREF="26_1_Glossary.html#report_message"
><EM CLASS="term"
>report message</EM
></A
> might be shifted to the right or left by an arbitrary amount, special care should be taken with the semi-standard <A HREF="26_1_Glossary.html#character"
><EM CLASS="term"
>character</EM
></A
> &#10216;<I
>Tab</I
>&#10217; (in those <A HREF="26_1_Glossary.html#implementation"
><EM CLASS="term"
>implementations</EM
></A
> that support such a <A HREF="26_1_Glossary.html#character"
><EM CLASS="term"
>character</EM
></A
>). Unless the <A HREF="26_1_Glossary.html#implementation"
><EM CLASS="term"
>implementation</EM
></A
> specifically defines its behavior in this context, its use should be avoided.</P
><H5 ID="sec_9_1_3_1_5" CLASS="HeadV"
>9.1.3.1.5 Mentioning Containing Function in Condition Reports</H5
><P CLASS="j"
>The name of the containing function should generally not be mentioned in <A HREF="26_1_Glossary.html#report_message"
><EM CLASS="term"
>report messages</EM
></A
>. It is assumed that the <A HREF="26_1_Glossary.html#debugger"
><EM CLASS="term"
>debugger</EM
></A
> will make this information accessible in situations where it is necessary and appropriate.</P
><H3 ID="sec_9_1_4" CLASS="HeadIII"
>9.1.4 Signaling and Handling Conditions</H3
><P CLASS="j"
>The operation of the condition system depends on the ordering of active <A HREF="26_1_Glossary.html#applicable_handler"
><EM CLASS="term"
>applicable handlers</EM
></A
> from most recent to least recent. </P
><P CLASS="j"
>Each <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>handler</EM
></A
> is associated with a <A HREF="26_1_Glossary.html#type_specifier"
><EM CLASS="term"
>type specifier</EM
></A
> that must designate a <A HREF="26_1_Glossary.html#subtype"
><EM CLASS="term"
>subtype</EM
></A
> of <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>type</EM
></A
> <A HREF="t_condition.html" CLASS="typeref"
><B
>condition</B
></A
>. A <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>handler</EM
></A
> is said to be <A HREF="26_1_Glossary.html#applicable"
><EM CLASS="term"
>applicable</EM
></A
> to a <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> if that <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> is of the <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>type</EM
></A
> designated by the associated <A HREF="26_1_Glossary.html#type_specifier"
><EM CLASS="term"
>type specifier</EM
></A
>. </P
><P CLASS="j"
><A HREF="26_1_Glossary.html#active"
><EM CLASS="term"
>Active</EM
></A
> <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>handlers</EM
></A
> are <A HREF="26_1_Glossary.html#establish"
><EM CLASS="term"
>established</EM
></A
> by using <A HREF="f_handler-bind.html" CLASS="macref"
><B
>handler-bind</B
></A
> (or an abstraction based on <A HREF="f_handler-bind.html" CLASS="macref"
><B
>handler-bind</B
></A
>, such as <A HREF="f_handler-case.html" CLASS="macref"
><B
>handler-case</B
></A
> or <A HREF="f_ignore-errors.html" CLASS="macref"
><B
>ignore-errors</B
></A
>). </P
><P CLASS="j"
><A HREF="26_1_Glossary.html#active"
><EM CLASS="term"
>Active</EM
></A
> <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>handlers</EM
></A
> can be <A HREF="26_1_Glossary.html#establish"
><EM CLASS="term"
>established</EM
></A
> within the dynamic scope of other <A HREF="26_1_Glossary.html#active"
><EM CLASS="term"
>active</EM
></A
> <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>handlers</EM
></A
>. At any point during program execution, there is a set of <A HREF="26_1_Glossary.html#active"
><EM CLASS="term"
>active</EM
></A
> <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>handlers</EM
></A
>. When a <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> is signaled, the <A HREF="26_1_Glossary.html#most_recent"
><EM CLASS="term"
>most recent</EM
></A
> active <A HREF="26_1_Glossary.html#applicable_handler"
><EM CLASS="term"
>applicable handler</EM
></A
> for that <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> is selected from this set. Given a <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
>, the order of recentness of active <A HREF="26_1_Glossary.html#applicable_handler"
><EM CLASS="term"
>applicable handlers</EM
></A
> is defined by the following two rules:</P
><OL
><LI
><P CLASS="j"
>Each handler in a set of active handlers <I
>H</I
><SUB CLASS="sub"
><SPAN CLASS="cmr"
>1</SPAN
></SUB
> is more recent than every handler in a set <I
>H</I
><SUB CLASS="sub"
><SPAN CLASS="cmr"
>2</SPAN
></SUB
> if the handlers in <I
>H</I
><SUB CLASS="sub"
><SPAN CLASS="cmr"
>2</SPAN
></SUB
> were active when the handlers in <I
>H</I
><SUB CLASS="sub"
><SPAN CLASS="cmr"
>1</SPAN
></SUB
> were established.</P
></LI
><LI
><P CLASS="j"
>Let <I
>h</I
><SUB CLASS="sub"
><SPAN CLASS="cmr"
>1</SPAN
></SUB
> and <I
>h</I
><SUB CLASS="sub"
><SPAN CLASS="cmr"
>2</SPAN
></SUB
> be two applicable active handlers established by the same <A HREF="26_1_Glossary.html#form"
><EM CLASS="term"
>form</EM
></A
>. Then <I
>h</I
><SUB CLASS="sub"
><SPAN CLASS="cmr"
>1</SPAN
></SUB
> is more recent than <I
>h</I
><SUB CLASS="sub"
><SPAN CLASS="cmr"
>2</SPAN
></SUB
> if <I
>h</I
><SUB CLASS="sub"
><SPAN CLASS="cmr"
>1</SPAN
></SUB
> was defined to the left of <I
>h</I
><SUB CLASS="sub"
><SPAN CLASS="cmr"
>2</SPAN
></SUB
> in the <A HREF="26_1_Glossary.html#form"
><EM CLASS="term"
>form</EM
></A
> that established them.</P
></LI
></OL
><P CLASS="j"
>Once a handler in a handler binding <A HREF="26_1_Glossary.html#form"
><EM CLASS="term"
>form</EM
></A
> (such as <A HREF="f_handler-bind.html" CLASS="macref"
><B
>handler-bind</B
></A
> or <A HREF="f_handler-case.html" CLASS="macref"
><B
>handler-case</B
></A
>) has been selected, all handlers in that <A HREF="26_1_Glossary.html#form"
><EM CLASS="term"
>form</EM
></A
> become inactive for the remainder of the signaling process. While the selected <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>handler</EM
></A
> runs, no other <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>handler</EM
></A
> established by that <A HREF="26_1_Glossary.html#form"
><EM CLASS="term"
>form</EM
></A
> is active. That is, if the <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>handler</EM
></A
> declines, no other handler established by that <A HREF="26_1_Glossary.html#form"
><EM CLASS="term"
>form</EM
></A
> will be considered for possible invocation. </P
><P CLASS="j"
>Figure 9&#8211;4 shows <A HREF="26_1_Glossary.html#operator"
><EM CLASS="term"
>operators</EM
></A
> relating to the <A HREF="26_1_Glossary.html#handle"
><EM CLASS="term"
>handling</EM
></A
> of <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>conditions</EM
></A
>.</P
><DIV CLASS="displaythree"
><FIGURE CLASS="boxfig"
><DIV CLASS="figbody"
><TABLE CELLSPACING="0" CELLPADDING="0" RULES="GROUPS" STYLE="margin: 1ex 0" WIDTH="100%"
><TBODY
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE=";padding-right:1em"
><A HREF="f_handler-bind.html" CLASS="misc"
><B
>handler-bind</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;padding-right:1em"
> <A HREF="f_handler-case.html" CLASS="misc"
><B
>handler-case</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;"
> <A HREF="f_ignore-errors.html" CLASS="misc"
><B
>ignore-errors</B
></A
></TD
></TR
></TBODY
></TABLE
></DIV
><FIGCAPTION CLASS="caption"
><B
>Figure 9&#8211;4. Operators relating to handling conditions.</B
></FIGCAPTION
></FIGURE
></DIV
><H4 ID="sec_9_1_4_1" CLASS="HeadIV"
>9.1.4.1 Signaling</H4
><P CLASS="j"
>When a <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> is signaled, the most recent applicable <A HREF="26_1_Glossary.html#active"
><EM CLASS="term"
>active</EM
></A
> <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>handler</EM
></A
> is invoked. Sometimes a handler will decline by simply returning without a transfer of control. In such cases, the next most recent applicable active handler is invoked. </P
><P CLASS="j"
>If there are no applicable handlers for a <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> that has been signaled, or if all applicable handlers decline, the <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> is unhandled. </P
><P CLASS="j"
>The functions <A HREF="f_cerror.html" CLASS="funref"
><B
>cerror</B
></A
> and <A HREF="f_error.html" CLASS="funref"
><B
>error</B
></A
> invoke the interactive <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> handler (the debugger) rather than return if the <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> being signaled, regardless of its <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>type</EM
></A
>, is unhandled. In contrast, <A HREF="f_signal.html" CLASS="funref"
><B
>signal</B
></A
> returns <SPAN CLASS="misc"
><B
>nil</B
></SPAN
> if the <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> being signaled, regardless of its <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>type</EM
></A
>, is unhandled. </P
><P CLASS="j"
>The <A HREF="26_1_Glossary.html#variable"
><EM CLASS="term"
>variable</EM
></A
> <A HREF="v_break-on-signals.html" CLASS="varref"
><B
>*break-on-signals*</B
></A
> can be used to cause the debugger to be entered before the signaling process begins. </P
><P CLASS="j"
>Figure 9&#8211;5 shows <A HREF="26_1_Glossary.html#defined_name"
><EM CLASS="term"
>defined names</EM
></A
> relating to the <A HREF="26_1_Glossary.html#signal"
><EM CLASS="term"
>signaling</EM
></A
> of <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>conditions</EM
></A
>.</P
><DIV CLASS="displaythree"
><FIGURE CLASS="boxfig"
><DIV CLASS="figbody"
><TABLE CELLSPACING="0" CELLPADDING="0" RULES="GROUPS" STYLE="margin: 1ex 0" WIDTH="100%"
><TBODY
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE=";padding-right:1em"
><A HREF="v_break-on-signals.html" CLASS="misc"
><B
>*break-on-signals*</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;padding-right:1em"
> <A HREF="f_error.html" CLASS="funref"
><B
>error</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;"
> <A HREF="f_warn.html" CLASS="misc"
><B
>warn</B
></A
></TD
></TR
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE=";padding-right:1em"
> <A HREF="f_cerror.html" CLASS="misc"
><B
>cerror</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;padding-right:1em"
> <A HREF="f_signal.html" CLASS="misc"
><B
>signal</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;"
><SPAN CLASS="misc"
></SPAN
></TD
></TR
></TBODY
></TABLE
></DIV
><FIGCAPTION CLASS="caption"
><B
>Figure 9&#8211;5. Defined names relating to signaling conditions.</B
></FIGCAPTION
></FIGURE
></DIV
><H5 ID="sec_9_1_4_1_1" CLASS="HeadV"
>9.1.4.1.1 Resignaling a Condition</H5
><P CLASS="j"
>During the <A HREF="26_1_Glossary.html#dynamic_extent"
><EM CLASS="term"
>dynamic extent</EM
></A
> of the <A HREF="26_1_Glossary.html#signal"
><EM CLASS="term"
>signaling</EM
></A
> process for a particular <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> <A HREF="26_1_Glossary.html#object"
><EM CLASS="term"
>object</EM
></A
>, <SPAN CLASS="funref"
><B
>signaling</B
></SPAN
> the same <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> <A HREF="26_1_Glossary.html#object"
><EM CLASS="term"
>object</EM
></A
> again is permitted if and only if the <A HREF="26_1_Glossary.html#situation"
><EM CLASS="term"
>situation</EM
></A
> represented in both cases are the same. </P
><P CLASS="j"
>For example, a <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>handler</EM
></A
> might legitimately <A HREF="26_1_Glossary.html#signal"
><EM CLASS="term"
>signal</EM
></A
> the <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> <A HREF="26_1_Glossary.html#object"
><EM CLASS="term"
>object</EM
></A
> that is its <A HREF="26_1_Glossary.html#argument"
><EM CLASS="term"
>argument</EM
></A
> in order to allow outer <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>handlers</EM
></A
> first opportunity to <A HREF="26_1_Glossary.html#handle"
><EM CLASS="term"
>handle</EM
></A
> the condition. (Such a <A HREF="26_1_Glossary.html#handler"
><EM CLASS="term"
>handlers</EM
></A
> is sometimes called a &#8220;default handler.&#8221;) This action is permitted because the <A HREF="26_1_Glossary.html#situation"
><EM CLASS="term"
>situation</EM
></A
> which the second <A HREF="26_1_Glossary.html#signal"
><EM CLASS="term"
>signaling</EM
></A
> process is addressing is really the same <A HREF="26_1_Glossary.html#situation"
><EM CLASS="term"
>situation</EM
></A
>. </P
><P CLASS="j"
>On the other hand, in an <A HREF="26_1_Glossary.html#implementation"
><EM CLASS="term"
>implementation</EM
></A
> that implemented asynchronous keyboard events by interrupting the user process with a call to <A HREF="f_signal.html" CLASS="funref"
><B
>signal</B
></A
>, it would not be permissible for two distinct asynchronous keyboard events to <A HREF="26_1_Glossary.html#signal"
><EM CLASS="term"
>signal</EM
></A
> <A HREF="26_1_Glossary.html#identical"
><EM CLASS="term"
>identical</EM
></A
> <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> <A HREF="26_1_Glossary.html#object"
><EM CLASS="term"
>objects</EM
></A
> at the same time for different situations.</P
><H4 ID="sec_9_1_4_2" CLASS="HeadIV"
>9.1.4.2 Restarts</H4
><P CLASS="j"
>The interactive condition handler returns only through non-local transfer of control to specially defined <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restarts</EM
></A
> that can be set up either by the system or by user code. Transferring control to a restart is called &#8220;invoking&#8221; the restart. Like handlers, active <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restarts</EM
></A
> are <A HREF="26_1_Glossary.html#establish"
><EM CLASS="term"
>established</EM
></A
> dynamically, and only active <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restarts</EM
></A
> can be invoked. An active <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restart</EM
></A
> can be invoked by the user from the debugger or by a program by using <A HREF="f_invoke-restart.html" CLASS="funref"
><B
>invoke-restart</B
></A
>. </P
><P CLASS="j"
>A <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restart</EM
></A
> contains a <A HREF="26_1_Glossary.html#function"
><EM CLASS="term"
>function</EM
></A
> to be <A HREF="26_1_Glossary.html#call"
><EM CLASS="term"
>called</EM
></A
> when the <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restart</EM
></A
> is invoked, an optional name that can be used to find or invoke the <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restart</EM
></A
>, and an optional set of interaction information for the debugger to use to enable the user to manually invoke a <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restart</EM
></A
>. </P
><P CLASS="j"
>The name of a <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restart</EM
></A
> is used by <A HREF="f_invoke-restart.html" CLASS="funref"
><B
>invoke-restart</B
></A
>. <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>Restarts</EM
></A
> that can be invoked only within the debugger do not need names. </P
><P CLASS="j"
><A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>Restarts</EM
></A
> can be established by using <A HREF="f_restart-bind.html" CLASS="macref"
><B
>restart-bind</B
></A
>, <A HREF="f_restart-case.html" CLASS="macref"
><B
>restart-case</B
></A
>, and <A HREF="f_with-simple-restart.html" CLASS="macref"
><B
>with-simple-restart</B
></A
>. A <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restart</EM
></A
> function can itself invoke any other <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restart</EM
></A
> that was active at the time of establishment of the <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restart</EM
></A
> of which the <A HREF="26_1_Glossary.html#function"
><EM CLASS="term"
>function</EM
></A
> is part. </P
><P CLASS="j"
>The <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restarts</EM
></A
> <A HREF="26_1_Glossary.html#establish"
><EM CLASS="term"
>established</EM
></A
> by a <A HREF="f_restart-bind.html" CLASS="macref"
><B
>restart-bind</B
></A
> <A HREF="26_1_Glossary.html#form"
><EM CLASS="term"
>form</EM
></A
>, a <A HREF="f_restart-case.html" CLASS="macref"
><B
>restart-case</B
></A
> <A HREF="26_1_Glossary.html#form"
><EM CLASS="term"
>form</EM
></A
>, or a <A HREF="f_with-simple-restart.html" CLASS="macref"
><B
>with-simple-restart</B
></A
> <A HREF="26_1_Glossary.html#form"
><EM CLASS="term"
>form</EM
></A
> have <A HREF="26_1_Glossary.html#dynamic_extent"
><EM CLASS="term"
>dynamic extent</EM
></A
> which extends for the duration of that <A HREF="26_1_Glossary.html#form"
><EM CLASS="term"
>form</EM
></A
>&#8217;s execution. </P
><P CLASS="j"
><A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>Restarts</EM
></A
> of the same name can be ordered from least recent to most recent according to the following two rules:</P
><OL
><LI
><P CLASS="j"
>Each <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restart</EM
></A
> in a set of active restarts <I
>R</I
><SUB CLASS="sub"
><SPAN CLASS="cmr"
>1</SPAN
></SUB
> is more recent than every <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restart</EM
></A
> in a set <I
>R</I
><SUB CLASS="sub"
><SPAN CLASS="cmr"
>2</SPAN
></SUB
> if the <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restarts</EM
></A
> in <I
>R</I
><SUB CLASS="sub"
><SPAN CLASS="cmr"
>2</SPAN
></SUB
> were active when the <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restarts</EM
></A
> in <I
>R</I
><SUB CLASS="sub"
><SPAN CLASS="cmr"
>1</SPAN
></SUB
> were established.</P
></LI
><LI
><P CLASS="j"
>Let <I
>r</I
><SUB CLASS="sub"
><SPAN CLASS="cmr"
>1</SPAN
></SUB
> and <I
>r</I
><SUB CLASS="sub"
><SPAN CLASS="cmr"
>2</SPAN
></SUB
> be two active <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restarts</EM
></A
> with the same name established by the same <A HREF="26_1_Glossary.html#form"
><EM CLASS="term"
>form</EM
></A
>. Then <I
>r</I
><SUB CLASS="sub"
><SPAN CLASS="cmr"
>1</SPAN
></SUB
> is more recent than <I
>r</I
><SUB CLASS="sub"
><SPAN CLASS="cmr"
>2</SPAN
></SUB
> if <I
>r</I
><SUB CLASS="sub"
><SPAN CLASS="cmr"
>1</SPAN
></SUB
> was defined to the left of <I
>r</I
><SUB CLASS="sub"
><SPAN CLASS="cmr"
>2</SPAN
></SUB
> in the <A HREF="26_1_Glossary.html#form"
><EM CLASS="term"
>form</EM
></A
> that established them.</P
></LI
></OL
><P CLASS="j"
>If a <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restart</EM
></A
> is invoked but does not transfer control, the values resulting from the <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restart</EM
></A
> function are returned by the function that invoked the restart, either <A HREF="f_invoke-restart.html" CLASS="funref"
><B
>invoke-restart</B
></A
> or <A HREF="f_invoke-restart-interactively.html" CLASS="funref"
><B
>invoke-restart-interactively</B
></A
>.</P
><H5 ID="sec_9_1_4_2_1" CLASS="HeadV"
>9.1.4.2.1 Interactive Use of Restarts</H5
><P CLASS="j"
>For interactive handling, two pieces of information are needed from a <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restart</EM
></A
>: a report function and an interactive function. </P
><P CLASS="j"
>The report function is used by a program such as the debugger to present a description of the action the <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restart</EM
></A
> will take. The report function is specified and established by the <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:report-function</SPAN
></SPAN
> keyword to <A HREF="f_restart-bind.html" CLASS="macref"
><B
>restart-bind</B
></A
> or the <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:report</SPAN
></SPAN
> keyword to <A HREF="f_restart-case.html" CLASS="macref"
><B
>restart-case</B
></A
>. </P
><P CLASS="j"
>The interactive function, which can be specified using the <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:interactive-function</SPAN
></SPAN
> keyword to <A HREF="f_restart-bind.html" CLASS="macref"
><B
>restart-bind</B
></A
> or <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:interactive</SPAN
></SPAN
> keyword to <A HREF="f_restart-case.html" CLASS="macref"
><B
>restart-case</B
></A
>, is used when the <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restart</EM
></A
> is invoked interactively, such as from the debugger, to produce a suitable list of arguments. </P
><P CLASS="j"
><A HREF="f_invoke-restart.html" CLASS="funref"
><B
>invoke-restart</B
></A
> invokes the most recently <A HREF="26_1_Glossary.html#establish"
><EM CLASS="term"
>established</EM
></A
> <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restart</EM
></A
> whose name is the same as the first argument to <A HREF="f_invoke-restart.html" CLASS="funref"
><B
>invoke-restart</B
></A
>. If a <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restart</EM
></A
> is invoked interactively by the debugger and does not transfer control but rather returns values, the precise action of the debugger on those values is <A HREF="26_1_Glossary.html#implementation-defined"
><EM CLASS="term"
>implementation-defined</EM
></A
>.</P
><H5 ID="sec_9_1_4_2_2" CLASS="HeadV"
>9.1.4.2.2 Interfaces to Restarts</H5
><P CLASS="j"
>Some <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restarts</EM
></A
> have functional interfaces, such as <A HREF="f_abort.html" CLASS="funref"
><B
>abort</B
></A
>, <A HREF="f_abort.html" CLASS="funref"
><B
>continue</B
></A
>, <A HREF="f_abort.html" CLASS="funref"
><B
>muffle-warning</B
></A
>, <A HREF="f_abort.html" CLASS="funref"
><B
>store-value</B
></A
>, and <A HREF="f_abort.html" CLASS="funref"
><B
>use-value</B
></A
>. They are ordinary functions that use <A HREF="f_find-restart.html" CLASS="funref"
><B
>find-restart</B
></A
> and <A HREF="f_invoke-restart.html" CLASS="funref"
><B
>invoke-restart</B
></A
> internally, that have the same name as the <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restarts</EM
></A
> they manipulate, and that are provided simply for notational convenience. </P
><P CLASS="j"
>Figure 9&#8211;6 shows <A HREF="26_1_Glossary.html#defined_name"
><EM CLASS="term"
>defined names</EM
></A
> relating to <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restarts</EM
></A
>.</P
><DIV CLASS="displaythree"
><FIGURE CLASS="boxfig"
><DIV CLASS="figbody"
><TABLE CELLSPACING="0" CELLPADDING="0" RULES="GROUPS" STYLE="margin: 1ex 0" WIDTH="100%"
><TBODY
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE=";padding-right:1em"
><SPAN CLASS="misc"
><B
>abort</B
></SPAN
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;padding-right:1em"
> <A HREF="f_invoke-restart-interactively.html" CLASS="misc"
><B
>invoke-restart-interactively</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;"
> <SPAN CLASS="misc"
><B
>store-value</B
></SPAN
></TD
></TR
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE=";padding-right:1em"
> <A HREF="f_compute-restarts.html" CLASS="misc"
><B
>compute-restarts</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;padding-right:1em"
> <SPAN CLASS="misc"
><B
>muffle-warning</B
></SPAN
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;"
> <SPAN CLASS="misc"
><B
>use-value</B
></SPAN
></TD
></TR
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE=";padding-right:1em"
> <SPAN CLASS="misc"
><B
>continue</B
></SPAN
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;padding-right:1em"
> <A HREF="f_restart-bind.html" CLASS="misc"
><B
>restart-bind</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;"
> <A HREF="f_with-simple-restart.html" CLASS="misc"
><B
>with-simple-restart</B
></A
></TD
></TR
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE=";padding-right:1em"
> <A HREF="f_find-restart.html" CLASS="misc"
><B
>find-restart</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;padding-right:1em"
> <A HREF="f_restart-case.html" CLASS="misc"
><B
>restart-case</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;"
><SPAN CLASS="misc"
></SPAN
></TD
></TR
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE=";padding-right:1em"
> <A HREF="f_invoke-restart.html" CLASS="misc"
><B
>invoke-restart</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;padding-right:1em"
> <A HREF="f_restart-name.html" CLASS="misc"
><B
>restart-name</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;"
><SPAN CLASS="misc"
></SPAN
></TD
></TR
></TBODY
></TABLE
></DIV
><FIGCAPTION CLASS="caption"
><B
>Figure 9&#8211;6. Defined names relating to restarts.</B
></FIGCAPTION
></FIGURE
></DIV
><H5 ID="sec_9_1_4_2_3" CLASS="HeadV"
>9.1.4.2.3 Restart Tests</H5
><P CLASS="j"
>Each <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restart</EM
></A
> has an associated test, which is a function of one argument (a <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> or <SPAN CLASS="misc"
><B
>nil</B
></SPAN
>) which returns <A HREF="26_1_Glossary.html#true"
><EM CLASS="term"
>true</EM
></A
> if the <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restart</EM
></A
> should be visible in the current <A HREF="26_1_Glossary.html#situation"
><EM CLASS="term"
>situation</EM
></A
>. This test is created by the <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:test-function</SPAN
></SPAN
> option to <A HREF="f_restart-bind.html" CLASS="macref"
><B
>restart-bind</B
></A
> or the <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:test</SPAN
></SPAN
> option to <A HREF="f_restart-case.html" CLASS="macref"
><B
>restart-case</B
></A
>.</P
><H5 ID="sec_9_1_4_2_4" CLASS="HeadV"
>9.1.4.2.4 Associating a Restart with a Condition</H5
><P CLASS="j"
>A <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restart</EM
></A
> can be &#8220;associated with&#8221; a <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> explicitly by <A HREF="f_with-condition-restarts.html" CLASS="macref"
><B
>with-condition-restarts</B
></A
>, or implicitly by <A HREF="f_restart-case.html" CLASS="macref"
><B
>restart-case</B
></A
>. Such an assocation has <A HREF="26_1_Glossary.html#dynamic_extent"
><EM CLASS="term"
>dynamic extent</EM
></A
>. </P
><P CLASS="j"
>A single <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restart</EM
></A
> may be associated with several <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>conditions</EM
></A
> at the same time. A single <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> may have several associated <A HREF="26_1_Glossary.html#restart"
><EM CLASS="term"
>restarts</EM
></A
> at the same time. </P
><P CLASS="j"
>Active restarts associated with a particular <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> can be detected by <A HREF="26_1_Glossary.html#call"
><EM CLASS="term"
>calling</EM
></A
> a <A HREF="26_1_Glossary.html#function"
><EM CLASS="term"
>function</EM
></A
> such as <A HREF="f_find-restart.html" CLASS="funref"
><B
>find-restart</B
></A
>, supplying that <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> as the <VAR CLASS="param"
>condition</VAR
> <A HREF="26_1_Glossary.html#argument"
><EM CLASS="term"
>argument</EM
></A
>. Active restarts can also be detected without regard to any associated <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>condition</EM
></A
> by calling such a function without a <VAR CLASS="param"
>condition</VAR
> <A HREF="26_1_Glossary.html#argument"
><EM CLASS="term"
>argument</EM
></A
>, or by supplying a value of <SPAN CLASS="misc"
><B
>nil</B
></SPAN
> for such an <A HREF="26_1_Glossary.html#argument"
><EM CLASS="term"
>argument</EM
></A
>.</P
><H3 ID="sec_9_1_5" CLASS="HeadIII"
>9.1.5 Assertions</H3
><P CLASS="j"
>Conditional signaling of <A HREF="26_1_Glossary.html#condition"
><EM CLASS="term"
>conditions</EM
></A
> based on such things as key match, form evaluation, and <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>type</EM
></A
> are handled by assertion <A HREF="26_1_Glossary.html#operator"
><EM CLASS="term"
>operators</EM
></A
>. Figure 9&#8211;7 shows <A HREF="26_1_Glossary.html#operator"
><EM CLASS="term"
>operators</EM
></A
> relating to assertions.</P
><DIV CLASS="displaythree"
><FIGURE CLASS="boxfig"
><DIV CLASS="figbody"
><TABLE CELLSPACING="0" CELLPADDING="0" RULES="GROUPS" STYLE="margin: 1ex 0" WIDTH="100%"
><TBODY
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE=";padding-right:1em"
><A HREF="f_assert.html" CLASS="misc"
><B
>assert</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;padding-right:1em"
> <A HREF="f_check-type.html" CLASS="misc"
><B
>check-type</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;"
> <A HREF="f_case.html" CLASS="misc"
><B
>ecase</B
></A
></TD
></TR
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE=";padding-right:1em"
> <A HREF="f_case.html" CLASS="misc"
><B
>ccase</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;padding-right:1em"
> <A HREF="f_typecase.html" CLASS="misc"
><B
>ctypecase</B
></A
></TD
><TD ALIGN="LEFT" VALIGN="BASELINE" NOWRAP="NOWRAP" STYLE="padding-left:1em;"
> <A HREF="f_typecase.html" CLASS="misc"
><B
>etypecase</B
></A
></TD
></TR
></TBODY
></TABLE
></DIV
><FIGCAPTION CLASS="caption"
><B
>Figure 9&#8211;7. Operators relating to assertions.</B
></FIGCAPTION
></FIGURE
></DIV
><H3 ID="sec_9_1_6" CLASS="HeadIII"
>9.1.6 Notes about the Condition System&#8217;s Background</H3
><P CLASS="j"
>For a background reference to the abstract concepts detailed in this section, see <I
>Exceptional</I
> <I
>Situations</I
> <I
>in</I
> <I
>Lisp</I
>. The details of that paper are not binding on this document, but may be helpful in establishing a conceptual basis for understanding this material.</P
></SECTION
></DIV
><DIV CLASS="footer"
><DIV CLASS="btmnav"
><A HREF="9_Conditions.html" CLASS="prev"
>&#8592;</A
><A HREF="9_2_Conditions_Dictionary.html" CLASS="next"
>&#8594;</A
></DIV
><DIV CLASS="trail"
>Conversion to HTML copyright 2023 by Gilbert Baumann</DIV
></DIV
></DIV
><SCRIPT
>domReady();</SCRIPT
></BODY
></HTML
>
Copy permalink