committed automatically by Makefile
[clqr.git] / clqr-conditions-and-errors.tex
blob789445676541b3cae1f1500e5186991f2b377ed1
1 % Copyright (C) 2008 Bert Burgemeister
3 % Permission is granted to copy, distribute and/or modify this
4 % document under the terms of the GNU Free Documentation License,
5 % Version 1.2 or any later version published by the Free Software
6 % Foundation; 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 \begin{LIST}{1cm}
15 \IT{(\MC*{DEFINE-CONDITION} \VAR{foo} (\OPn{\VAR{parent-type}}\DF{\kwd{condition}})
16 (\xorGOO{\VAR{slot}\\
17 (\VAR{slot}
18 \orGOO{\Goos{\kwd{:reader} \VAR{reader}}\\
19 \Goos{\kwd{:writer} \xorGOO{%
20 \VAR{writer}\\
21 (\kwd{setf } \VAR{writer})}{\}}}\\
22 \Goos{\kwd{:accessor} \VAR{reader}} \\
23 \kwd{:allocation } \xorGOO{\kwd{:instance}\\
24 \kwd{:class}}{\}}\DF{\kwd{:instance}}\\
25 \Goos{\kwd{:initarg} \kwd{:}\VAR{initarg-name}}\\
26 \kwd{:initform} \VAR{ form}\\
27 \kwd{:type} \VAR{ type}\\
28 \kwd{:documentation} \VAR{ slot-doc}%
29 }{\}})}{\}^{\!\!*}})
30 \orGOO{(\kwd{:default-initargs } \Goos{\VAR{name} \VAR{value}})\\
31 ({\kwd{:documentation} \VAR{ condition-doc}})\\
32 (\kwd{:report } \xorGOO{\VAR{string}\\
33 \VAR{report-function}}{\}})}{\}})}
35 Define, as a subtype of \VAR{parent-type}s, condition type
36 \retval{\VAR{foo}}. In new conditions, a \VAR{slot}'s value defaults
37 to \VAR{form} unless set via \kwd{:}\VAR{initarg-name}, and is
38 accessible by function \VAR{reader} and by generic function \VAR{writer}. With
39 \kwd{:allocation :class}, \VAR{slot} is shared by all conditions of
40 type \VAR{foo}. A condition is reported by \VAR{string} or by
41 \VAR{report-function} of arguments condition and stream.
44 \IT{(\FU*{MAKE-CONDITION} \VAR{type} \Goos{\kwd{:}\VAR{initarg-name} \VAR{value}})}
46 Return \retval{new condition of \VAR{type}}.
49 \IT{(\xorGOO{%
50 \FU*{SIGNAL}\\
51 \FU*{WARN}\\
52 \FU*{ERROR}%
53 }{\}}
54 \xorGOO{%
55 \VAR{condition}\\
56 \VAR{type}\text{ } \Goos{\kwd{:}\VAR{initarg-name} \VAR{value}}\\
57 \VAR{control}\text{ } \OPn{\VAR{arg}}%
58 }{\}})}
60 Unless handled, signal as \kwd{condition}, \kwd{warning} or \kwd{error},
61 respectively, \VAR{condition} or a new condition of \VAR{type} or,
62 with \FU{format} \VAR{control} and \VAR{arg}s (see p.\ \pageref{section:Format}),
63 \kwd{simple-condition}, \kwd{simple-warning}, or \kwd{simple-error}, respectively.
64 From \FU{SIGNAL} and \FU{WARN}, return \retval{\NIL}.
67 \IT{(\FU*{CERROR} \VAR{continue-control}
68 \xorGOO{%
69 \VAR{condition}\text{ } \OPn{\VAR{continue-arg}}\\
70 \VAR{type}\text{ } \Goos{\kwd{:}\VAR{initarg-name} \VAR{value}}\\
71 \VAR{control}\text{ } \OPn{\VAR{arg}}%
72 }{\}})}
74 Unless handled, signal as correctable \kwd{error} \VAR{condition} or
75 a new condition of \VAR{type} or, with \FU{format} \VAR{control} and
76 \VAR{arg}s (see p.\ \pageref{section:Format}),
77 \kwd{simple-error}. In the debugger, use \FU{format} arguments
78 \VAR{continue-control} and \VAR{continue-arg}s to tag the continue
79 option. Return \retval{\NIL}.
82 \IT{(\MC*{IGNORE-ERRORS} \PROGN{\VAR{form}})}
84 Return \retval{values of \VAR{form}s} or, in case of \kwd{error}s,
85 \retval{\NIL} and the \retvalii{condition}.
88 \IT{(\FU*{INVOKE-DEBUGGER} \VAR{condition})}
90 Invoke debugger with \VAR{condition}.
93 \IT{(\MC*{ASSERT} \VAR{test} \OP{(\OPn{\VAR{place}})
94 \Op{%
95 \xorGOO{%
96 \VAR{condition}\text{ } \OPn{\VAR{continue-arg}}\\
97 \VAR{type}\text{ } \Goos{\kwd{:}\VAR{initarg-name} \VAR{value}}\\
98 \VAR{control}\text{ } \OPn{\VAR{arg}}}{\}}}})}
100 If \VAR{test}, which may depend on \VAR{place}s, returns \NIL,
101 signal as correctable \kwd{error} \VAR{condition} or a new condition
102 of \VAR{type} or, with \FU{format} \VAR{control} and \VAR{arg}s (see
103 p.\ \pageref{section:Format}), \kwd{error}. When using the
104 debugger's continue option, \VAR{place}s can be altered before
105 re-evaluation of \VAR{test}. Return \retval{\NIL}.
108 \IT{(\MC*{HANDLER-CASE} \VAR{test}
109 \OPn{(\VAR{type} (\Op{\VAR{var}})
110 \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})} \PROGN{\VAR{condition-form}})}
111 \Op{(\kwd{:no-error} (\OPn{\VAR{ord-$\lambda$}}) \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})}
112 \PROGN{\VAR{form}})})}
114 If, on evaluation of \VAR{test}, a condition of \VAR{type} is
115 signalled, evaluate matching \VAR{condition-form}s
116 with \VAR{var} bound to the condition and return \retval{their
117 values}. Without a condition, bind \VAR{ord-$\lambda$}s to values
118 of \VAR{test} and return \retval{values of \VAR{form}s} or, without
119 a \kwd{:no-error} clause, return \retval{values of \VAR{test}}. See
120 p.\ \pageref{section:Functions} for (\OPn{\VAR{ord-$\lambda$}}).
123 \IT{(\MC*{HANDLER-BIND} (\OPn{(\VAR{condition-type}
124 \VAR{handler-function})}) \PROGN{\VAR{form}})}
126 Return \retval{values of \VAR{form}s} after evaluating them with
127 \VAR{condition-type}s dynamically bound to their respective
128 \VAR{handler-function}s of argument condition.
131 \IT{(\MC*{WITH-SIMPLE-RESTART} (\VAR{restart} \VAR{control}
132 \OPn{\VAR{arg}}) \PROGN{\VAR{form}})}
134 Return \retval{values of \VAR{form}s} unless \VAR{restart} is called
135 during their evaluation. In this case, describe restart using
136 \FU{format} \VAR{control} and \VAR{arg}s (see
137 p.\ \pageref{section:Format}) and return \retval{\NIL}
138 and \retvalii{\T}.
141 \IT{(\MC*{RESTART-CASE} \VAR{form} \OPn{(\VAR{foo}
142 (\OPn{\VAR{ord-$\lambda$}})
143 \orGOO{\kwd{:interactive} \VAR{ arg-function}\\
144 \kwd{:report } \xorGOO{%
145 \VAR{report-function}\\
146 \VAR{string}\DF{\LIT{"}\VAR{foo}\LIT{"}}}{.}\\
147 \kwd{:test} \VAR{ test-function}\DF{\T}}{\}}
148 \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})}
149 \PROGN{\VAR{restart-form}})})}
151 Evaluate \VAR{form} with dynamically established restarts \VAR{foo}. Return
152 \retval{values of \VAR{form}} or, if by (\kwd{invoke-restarts}
153 \VAR{foo} \OPn{\VAR{arg}}) one restart \VAR{foo} is called, use
154 \VAR{string} or \VAR{report-function} (of a stream) to print a
155 description of restart \VAR{foo} and
156 return the \retval{values of its \VAR{restart-form}s}.
157 \VAR{arg-function} supplies appropriate \VAR{arg}s if \VAR{foo} is
158 called by \kwd{invoke-restart-interactively}. If (\VAR{test-function} \VAR{condition})
159 returns \T, \VAR{foo} is made visible under \VAR{condition}.
160 For (\OPn{\VAR{ord-$\lambda$}}) see p.\ \pageref{section:Functions}.
163 \IT{(\MC*{RESTART-BIND} (\OPn{(\VAR{restart}
164 \VAR{restart-function} \orGOO{\kwd{:interactive-function}
165 \VAR{ function}\\
166 \kwd{:report-function} \VAR{ function}\\
167 \kwd{:test-function} \VAR{ function}}{\}})}) \PROGN{\VAR{form}})}
169 Return \retval{values of \VAR{form}s} evaluated with \VAR{restart}s
170 dynamically bound to \VAR{restart-function}s.
173 \IT{\arrGOO{(\FU*{INVOKE-RESTART} \VAR{ restart} \OPn{\VAR{ arg}})\\
174 (\FU*{INVOKE-RESTART-INTERACTIVELY} \VAR{ restart})}{.}}
176 Call function associated with \VAR{restart} with arguments given or
177 prompted for, respectively. If \VAR{restart} function returns, return \retval{its values}.
180 \IT{(\xorGOO{\FU*{COMPUTE-RESTARTS}\\
181 \FU*{FIND-RESTART} \VAR{ name}}{\}} \Op{\VAR{condition}})}
183 Return list of \retval{all restarts}, or innermost \retval{restart}
184 \VAR{name}, respectively, out of those either associated
185 with \VAR{condition} or un-associated at all; or, without
186 \VAR{condition}, out of all restarts. Return \retval{\NIL} if search
187 is unsuccessful.
190 \IT{(\FU*{RESTART-NAME} \VAR{restart})}
192 \retval{Name of \VAR{restart}}.
195 \IT{(\xorGOO{\FU*{ABORT}\\
196 \FU*{MUFFLE-WARNING}\\
197 \FU*{CONTINUE}\\
198 \FU*{STORE-VALUE} \VAR{ value}\\
199 \FU*{USE-VALUE} \VAR{ value}}{\}} \Op{\VAR{condition}\DF{\NIL}})}
201 Transfer control to innermost applicable restart with same name
202 (i.e. \kwd{abort}, \ldots, \kwd{continue} \ldots) out of those either associated
203 with \VAR{condition} or un-associated at all; or, without
204 \VAR{condition}, out of all restarts. If no restart is found,
205 signal \kwd{control-error} for \FU{abort} and \FU{muffle-warning},
206 or return \retval{\NIL} for the rest.
209 \IT{(\MC*{WITH-CONDITION-RESTARTS} \VAR{condition}
210 \VAR{restarts} \PROGN{\VAR{form}})}
212 Evaluate \VAR{form}s with \VAR{restarts}
213 dynamically associated with \VAR{condition}. Return \retval{values
214 of \VAR{form}s}.
217 \begin{figure}
218 \begin{center}
219 \boxGOO{%
220 \T\index{T}%
221 \boxGOO{%
222 \kwd*{CONDITION}\\
223 \boxGOO{%
224 \kwd*{WARNING}
225 \boxGOO{%
226 \kwd*{STYLE-WARNING}\\
227 \kwd*{SIMPLE-CONDITION}\footnotemark[2]
228 \boxGOO{%
229 \kwd*{SIMPLE-WARNING}}}\boxGOOcr
230 \kwd*{SIMPLE-CONDITION}\boxGOOcr
231 \kwd*{SERIOUS-CONDITION}\\
232 \boxGOO{%
233 \kwd*{ERROR}\\
234 \boxGOO{%
235 \kwd*{SIMPLE-CONDITION}\footnotemark[2]
236 \boxGOO{%
237 \kwd*{SIMPLE-ERROR}}\boxGOOcr
238 \kwd*{PARSE-ERROR};\>
239 \kwd*{PROGRAM-ERROR};\>
240 \kwd*{CONTROL-ERROR}\boxGOOcr
241 \kwd*{TYPE-ERROR}
242 \boxGOO{%
243 \kwd*{SIMPLE-CONDITION}\footnotemark[2]
244 \boxGOO{%
245 \kwd*{SIMPLE-TYPE-ERROR}}}\boxGOOcr
246 \kwd*{CELL-ERROR}
247 \boxGOO{%
248 \kwd*{UNBOUND-VARIABLE};\>
249 \kwd*{UNBOUND-SLOT};\\
250 \kwd*{UNDEFINED-FUNCTION}}\boxGOOcr
251 \kwd*{STREAM-ERROR}
252 \boxGOO{%
253 \kwd*{END-OF-FILE}\\
254 \kwd*{PARSE-ERROR}\footnotemark[2]
255 \boxGOO{\kwd*{READER-ERROR}}}\boxGOOcr
256 \kwd*{PACKAGE-ERROR};\>
257 \kwd*{FILE-ERROR};\>
258 \kwd*{PRINT-NOT-READABLE}\boxGOOcr
259 \kwd*{ARITHMETIC-ERROR}\\
260 \boxGOO{%
261 \kwd*{DIVISION-BY-ZERO};\>
262 \kwd*{FLOATING-POINT-INEXACT};\\
263 \kwd*{FLOATING-POINT-INVALID-OPERATION};\\
264 \kwd*{FLOATING-POINT-OVERFLOW};\>
265 \kwd*{FLOATING-POINT-UNDERFLOW}}
266 }\boxGOOcr
267 \kwd*{STORAGE-CONDITION}}
268 }}}\\
269 \end{center}\vspace{-1em}
270 {\footnotesize\footnotemark[2]For supertypes of this
271 type look for the instance without a \footnotemark[2].}
272 \caption{Condition Types.}%
273 \end{figure}
275 \IT{\arrGOO{(\FU*{ARITHMETIC-ERROR-OPERATION} \VAR{ condition})\\
276 (\FU*{ARITHMETIC-ERROR-OPERANDS} \VAR{ condition})}{.}}
278 \retval{List of function} or \retval{of its operands} respectively,
279 used in the operation which caused \VAR{condition}.
282 \IT{(\FU*{CELL-ERROR-NAME} \VAR{condition})}
284 \retval{Name of cell} which caused \VAR{condition}.
287 \IT{(\FU*{UNBOUND-SLOT-INSTANCE} \VAR{condition})}
289 \retval{Instance} with unbound slot which caused \VAR{condition}.
292 \IT{(\FU*{PRINT-NOT-READABLE-OBJECT} \VAR{condition})}
294 The \retval{object} not readably printable under \VAR{condition}.
297 \IT{\arrGOO{%
298 (\FU*{PACKAGE-ERROR-PACKAGE } \VAR{condition})\\
299 (\FU*{FILE-ERROR-PATHNAME } \VAR{condition})\\
300 (\FU*{STREAM-ERROR-STREAM } \VAR{condition})}{.}}
302 \retval{Package}, \retval{path}, or \retval{stream}, respectively,
303 which caused the \VAR{condition} of indicated type.
306 \IT{\arrGOO{(\FU*{TYPE-ERROR-DATUM} \VAR{ condition})\\
307 (\FU*{TYPE-ERROR-EXPECTED-TYPE} \VAR{ condition})}{.}}
309 \retval{Object} which caused \VAR{condition} of type \kwd{type-error}, or its
310 \retval{expected type}, respectively.
313 \IT{\arrGOO{(\FU*{SIMPLE-CONDITION-FORMAT-CONTROL} \VAR{ condition})\\
314 (\FU*{SIMPLE-CONDITION-FORMAT-ARGUMENTS} \VAR{ condition})}{.}}
316 Return \retval{\FU{format} control} or list of \retval{\FU{format}
317 arguments}, respectively, of \VAR{condition}.
320 \IT{\V{\A break-on-signals\A}\DF{\NIL}}
321 {\index{*BREAK-ON-SIGNALS*@\A BREAK-ON-SIGNALS\A}
322 Condition type debugger is to be invoked on.
325 \IT{\V{\A debugger-hook\A}\DF{\NIL}}
326 {\index{*DEBUGGER-HOOK*@\A DEBUGGER-HOOK\A}
327 Function of condition and
328 function itself. Called before debugger.
331 \end{LIST}
334 %%% Local Variables:
335 %%% mode: latex
336 %%% TeX-master: "clqr"
337 %%% End: