Fix bugs reported by Fengjing Xiao
[clqr.git] / clqr-conditions-and-errors.tex
blobabb16d64e90c411f2c1eaf3a2b5cc8936fd3ff4c
1 % Copyright (C) 2008, 2009, 2010, 2011, 2012, 2014, 2018
2 % Bert Burgemeister
4 % Permission is granted to copy, distribute and/or modify this
5 % document under the terms of the GNU Free Documentation License,
6 % Version 1.2; with no Invariant Sections, no Front-Cover Texts and
7 % no Back-Cover Texts. For details see file COPYING.
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11 \section{Conditions and Errors}
12 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
14 For standardized condition types cf.\ Figure \ref{data-types} on
15 page \pageref{data-types}.
17 \begin{LIST}{1cm}
18 \IT{(\MC*{DEFINE-CONDITION}
19 \VAR{foo} (\OPn{\VAR{parent-type}}\DF{\kwd{condition}})
20 (\xorGOO{\VAR{slot}\\
21 (\VAR{slot }
22 \orGOO{\Goos{\kwd{:reader} \VAR{reader}}\\
23 \Goos{\kwd{:writer} \xorGOO{%
24 \VAR{writer}\\
25 (\kwd{setf } \VAR{writer})}{\}}}\\
26 \Goos{\kwd{:accessor} \VAR{accessor}} \\
27 \kwd{:allocation } \xorGOO{\kwd{:instance}\\
28 \kwd{:class}}{\}}\DF{\kwd{:instance}}\\
29 \Goos{\kwd{:initarg} \Op{\kwd{:}}\VAR{initarg-name}}\\
30 \kwd{:initform} \VAR{ form}\\
31 \kwd{:type} \VAR{ type}\\
32 \kwd{:documentation} \VAR{ slot-doc}%
33 }{\}})}{\}^{\!\!*}})
34 \orGOO{(\kwd{:default-initargs } \Goos{\VAR{name} \VAR{value}})\\
35 ({\kwd{:documentation} \VAR{ condition-doc}})\\
36 (\kwd{:report } \xorGOO{\VAR{string}\\
37 \VAR{report-function}}{\}})}{\}})}
39 Define, as a subtype of \VAR{parent-type}s, condition type
40 \retval{\VAR{foo}}. In a new condition, a \VAR{slot}'s value
41 defaults to \VAR{form} unless set via \Op{\kwd{:}}\VAR{initarg-name};
42 it is readable via (\VAR{reader} \VAR{i}) or (\VAR{accessor}
43 \VAR{i}), and writable via (\VAR{writer} \VAR{value} \VAR{i}) or
44 (\kwd{setf} (\VAR{accessor} \VAR{i}) \VAR{value}). With
45 \kwd{:allocation :class}, \VAR{slot} is shared by all conditions
46 of type \VAR{foo}. A condition is reported by \VAR{string} or by
47 \VAR{report-function} of arguments condition and stream.
50 \IT{(\FU*{MAKE-CONDITION}
51 \VAR{condition-type} \Goos{\Op{\kwd{:}}\VAR{initarg-name} \VAR{value}})}
53 Return new \retval{instance of \VAR{condition-type}}.
56 \IT{(\xorGOO{%
57 \FU*{SIGNAL}\\
58 \FU*{WARN}\\
59 \FU*{ERROR}%
60 }{\}}
61 \xorGOO{%
62 \VAR{condition}\\
63 \VAR{condition-type}\text{ } \Goos{\Op{\kwd{:}}\VAR{initarg-name} \VAR{value}}\\
64 \VAR{control}\text{ } \OPn{\VAR{arg}}%
65 }{\}})}
67 Unless handled, signal as \kwd{condition}, \kwd{warning} or
68 \kwd{error}, respectively, \VAR{condition} or a new instance of
69 \VAR{condition-type} or, with \FU{format} \VAR{control} and
70 \VAR{arg}s (see page \pageref{section:Format}),
71 \kwd{simple-condition}, \kwd{simple-warning}, or
72 \kwd{simple-error}, respectively. From \FU{SIGNAL} and \FU{WARN},
73 return \retval{\NIL}.
76 \IT{(\FU*{CERROR} \VAR{continue-control}
77 \xorGOO{%
78 \VAR{condition}\text{ } \OPn{\VAR{continue-arg}}\\
79 \VAR{condition-type}\text{ } \Goos{\Op{\kwd{:}}\VAR{initarg-name} \VAR{value}}\\
80 \VAR{control}\text{ } \OPn{\VAR{arg}}%
81 }{\}})}
83 Unless handled, signal as correctable \kwd{error} \VAR{condition}
84 or a new instance of \VAR{condition-type} or, with \FU{format}
85 \VAR{control} and \VAR{arg}s (see page \pageref{section:Format}),
86 \kwd{simple-error}. In the debugger, use \FU{format} arguments
87 \VAR{continue-control} and \VAR{continue-arg}s to tag the continue
88 option. Return \retval{\NIL}.
91 \IT{(\MC*{IGNORE-ERRORS} \PROGN{\VAR{form}})}
93 Return \retval{values of \VAR{form}s} or, in case of \kwd{error}s,
94 \retval{\NIL} and the \retvalii{condition}.
97 \IT{(\FU*{INVOKE-DEBUGGER} \VAR{condition})}
99 Invoke debugger with \VAR{condition}.
102 \IT{(\MC*{ASSERT} \VAR{test} \OP{(\OPn{\VAR{place}})
103 \Op{%
104 \xorGOO{%
105 \VAR{condition}\text{ } \OPn{\VAR{continue-arg}}\\
106 \VAR{condition-type}\text{ }
107 \Goos{\Op{\kwd{:}}\VAR{initarg-name} \VAR{value}}\\
108 \VAR{control}\text{ } \OPn{\VAR{arg}}}{\}}}})}
110 If \VAR{test}, which may depend on \VAR{place}s, returns \NIL,
111 signal as correctable \kwd{error} \VAR{condition} or a new
112 instance of \VAR{condition-type} or, with \FU{format}
113 \VAR{control} and \VAR{arg}s (see page \pageref{section:Format}),
114 \kwd{error}. When using the debugger's continue option,
115 \VAR{place}s can be altered before re-evaluation of
116 \VAR{test}. Return \retval{\NIL}.
119 \IT{(\MC*{HANDLER-CASE} \VAR{foo}
120 \penalty-5
121 \OPn{(\VAR{type} (\Op{\VAR{var}})
122 \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})}
123 \PROGN{\VAR{condition-form}})}
124 \penalty-5
125 \Op{(\kwd{:no-error} (\OPn{\VAR{ord-$\lambda$}})
126 \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})}
127 \PROGN{\VAR{form}})})}
129 If, on evaluation of \VAR{foo}, a condition of \VAR{type} is
130 signalled, evaluate matching \VAR{condition-form}s with \VAR{var}
131 bound to the condition, and return \retval{their values}. Without
132 a condition, bind \VAR{ord-$\lambda$}s to values of \VAR{foo} and
133 return \retval{values of \VAR{form}s} or, without a
134 \kwd{:no-error} clause, return \retval{values of \VAR{foo}}. See
135 page \pageref{section:Functions} for (\OPn{\VAR{ord-$\lambda$}}).
138 \IT{(\MC*{HANDLER-BIND} (\OPn{(\VAR{condition-type}
139 \VAR{handler-function})}) \PROGN{\VAR{form}})}
141 Return \retval{values of \VAR{form}s} after evaluating them with
142 \VAR{condition-type}s dynamically bound to their respective
143 \VAR{handler-function}s of argument condition.
146 \IT{(\MC*{WITH-SIMPLE-RESTART} (\xorGOO{\VAR{restart}\\
147 \NIL}{\}} \VAR{control}
148 \OPn{\VAR{arg}}) \PROGN{\VAR{form}})}
150 Return \retval{values of \VAR{form}s} unless \VAR{restart} is
151 called during their evaluation. In this case, describe
152 \VAR{restart} using \FU{format} \VAR{control} and \VAR{arg}s (see
153 page \pageref{section:Format}) and return \retval{\NIL} and
154 \retvalii{\T}.
157 \IT{(\MC*{RESTART-CASE} \VAR{form}
158 \OPn{(\VAR{restart}
159 (\OPn{\VAR{ord-$\lambda$}})
160 \orGOO{\kwd{:interactive} \VAR{ arg-function}\\
161 \kwd{:report } \xorGOO{%
162 \VAR{report-function}\\
163 \VAR{string}\DF{\LIT{"}\VAR{restart}\LIT{"}}}{.}\\
164 \kwd{:test} \VAR{ test-function}\DF{\T}}{\}}
165 \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})}
166 \PROGN{\VAR{restart-form}})})}
168 Return \retval{values of \VAR{form}} or, if during evaluation of
169 \VAR{form} one of the dynamically established \VAR{restart}s is
170 called, the \retval{values of its \VAR{restart-form}s}. A
171 \VAR{restart} is visible under \VAR{condition} if (\kwd{funcall}
172 \kwd{\#'}\VAR{test-function} \VAR{condition}) returns \T. If
173 presented in the debugger, \VAR{restart}s are described by
174 \VAR{string} or by \kwd{\#'}\VAR{report-function} (of a stream).
175 A \VAR{restart} can be called by (\kwd{invoke-restart}
176 \VAR{restart} \OPn{\VAR{arg}}), where \VAR{arg}s match
177 \OPn{\VAR{ord-$\lambda$}}, or by
178 (\kwd{invoke-restart-interactively} \VAR{restart}) where a list of
179 the respective \VAR{arg}s is supplied by
180 \kwd{\#'}\VAR{arg-function}. See page \pageref{section:Functions}
181 for \OPn{\VAR{ord-$\lambda$}}.
184 \IT{(\MC*{RESTART-BIND}
185 (\OPn{(\xorGOO{%
186 \NEV{\VAR{restart}}\\
187 \NIL}{\}}
188 \VAR{restart-function}
189 \orGOO{%
190 \kwd{:interactive-function} \VAR{ arg-function}\\
191 \kwd{:report-function} \VAR{ report-function}\\
192 \kwd{:test-function} \VAR{ test-function}}{\}})})
193 \PROGN{\VAR{form}})}
195 Return \retval{values of \VAR{form}s} evaluated with dynamically
196 established \VAR{restart}s whose \VAR{restart-function}s should
197 perform a non-local transfer of control. A restart is visible
198 under \VAR{condition} if (\VAR{test-function} \VAR{condition})
199 returns \T. If presented in the debugger, \VAR{restart}s are
200 described by \VAR{restart-function} (of a stream). A
201 \VAR{restart} can be called by (\kwd{invoke-restart} \VAR{restart}
202 \OPn{\VAR{arg}}), where \VAR{arg}s must be suitable for the
203 corresponding \VAR{restart-function}, or by
204 (\kwd{invoke-restart-interactively} \VAR{restart}) where a list of
205 the respective \VAR{arg}s is supplied by \VAR{arg-function}.
208 \IT{\arrGOO{(\FU*{INVOKE-RESTART} \VAR{ restart} \OPn{\VAR{ arg}})\\
209 (\FU*{INVOKE-RESTART-INTERACTIVELY} \VAR{ restart})}{.}}
211 Call function associated with \VAR{restart} with arguments given
212 or prompted for, respectively. If \VAR{restart} function returns,
213 return \retval{its values}.
216 \IT{(\xorGOO{%
217 \FU*{FIND-RESTART}\\
218 \FU*{COMPUTE-RESTARTS} \VAR{ name}}{\}} \Op{\VAR{condition}})}
220 Return innermost \retval{restart} \VAR{name}, or a \retval{list of
221 all restarts}, respectively, out of those either associated with
222 \VAR{condition} or un-associated at all; or, without
223 \VAR{condition}, out of all restarts. Return \retval{\NIL} if
224 search is unsuccessful.
227 \IT{(\FU*{RESTART-NAME} \VAR{restart})}
229 \retval{Name of \VAR{restart}}.
232 \IT{(\xorGOO{\FU*{ABORT}\\
233 \FU*{MUFFLE-WARNING}\\
234 \FU*{CONTINUE}\\
235 \FU*{STORE-VALUE} \VAR{ value}\\
236 \FU*{USE-VALUE} \VAR{ value}}{\}} \Op{\VAR{condition}\DF{\NIL}})}
238 Transfer control to innermost applicable restart with same name
239 (i.e. \kwd{abort}, \ldots, \kwd{continue} \ldots) out of those either associated
240 with \VAR{condition} or un-associated at all; or, without
241 \VAR{condition}, out of all restarts. If no restart is found,
242 signal \kwd{control-error} for \FU{abort} and \FU{muffle-warning},
243 or return \retval{\NIL} for the rest.
246 \IT{(\MC*{WITH-CONDITION-RESTARTS} \VAR{condition}
247 \VAR{restarts} \PROGN{\VAR{form}})}
249 Evaluate \VAR{form}s with \VAR{restarts}
250 dynamically associated with \VAR{condition}. Return \retval{values
251 of \VAR{form}s}.
254 \IT{\arrGOO{(\FU*{ARITHMETIC-ERROR-OPERATION} \VAR{ condition})\\
255 (\FU*{ARITHMETIC-ERROR-OPERANDS} \VAR{ condition})}{.}}
257 \retval{List of function} or \retval{of its operands} respectively,
258 used in the operation which caused \VAR{condition}.
261 \IT{(\FU*{CELL-ERROR-NAME} \VAR{condition})}
263 \retval{Name of cell} which caused \VAR{condition}.
266 \IT{(\FU*{UNBOUND-SLOT-INSTANCE} \VAR{condition})}
268 \retval{Instance} with unbound slot which caused \VAR{condition}.
271 \IT{(\FU*{PRINT-NOT-READABLE-OBJECT} \VAR{condition})}
273 The \retval{object} not readably printable under \VAR{condition}.
276 \IT{\arrGOO{%
277 (\FU*{PACKAGE-ERROR-PACKAGE } \VAR{condition})\\
278 (\FU*{FILE-ERROR-PATHNAME } \VAR{condition})\\
279 (\FU*{STREAM-ERROR-STREAM } \VAR{condition})}{.}}
281 \retval{Package}, \retval{path}, or \retval{stream}, respectively,
282 which caused the \VAR{condition} of indicated type.
285 \IT{\arrGOO{(\FU*{TYPE-ERROR-DATUM} \VAR{ condition})\\
286 (\FU*{TYPE-ERROR-EXPECTED-TYPE} \VAR{ condition})}{.}}
288 \retval{Object} which caused \VAR{condition} of type \kwd{type-error}, or its
289 \retval{expected type}, respectively.
292 \IT{\arrGOO{(\FU*{SIMPLE-CONDITION-FORMAT-CONTROL} \VAR{ condition})\\
293 (\FU*{SIMPLE-CONDITION-FORMAT-ARGUMENTS} \VAR{ condition})}{.}}
295 Return \retval{\FU{format} control} or list of \retval{\FU{format}
296 arguments}, respectively, of \VAR{condition}.
299 \IT{\V{\A break-on-signals\A}\DF{\NIL}}
300 {\index{*BREAK-ON-SIGNALS*@\A BREAK-ON-SIGNALS\A}
301 Condition type debugger is to be invoked on.
304 \IT{\V{\A debugger-hook\A}\DF{\NIL}}
305 {\index{*DEBUGGER-HOOK*@\A DEBUGGER-HOOK\A}
306 Function of condition and
307 function itself. Called before debugger.
310 \end{LIST}
313 %%% Local Variables:
314 %%% mode: latex
315 %%% TeX-master: "clqr"
316 %%% End: