clqr-conditions-and-errors.tex

   1 % Copyright (C) 2008 Bert Burgemeister
   2 %
   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.
   8 %
   9
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11 \section{Conditions and Errors}
  12 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  13
  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}}{\}})}{\}})}
  34   {
  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.
  42   }
  43
  44   \IT{(\FU*{MAKE-CONDITION} \VAR{type} \Goos{\kwd{:}\VAR{initarg-name} \VAR{value}})}
  45   {
  46   Return \retval{new condition of \VAR{type}}.
  47   }
  48
  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     }{\}})}
  59   {
  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}.
  65   }
  66
  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     }{\}})}
  73   {
  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}.
  80   }
  81
  82   \IT{(\MC*{IGNORE-ERRORS} \PROGN{\VAR{form}})}
  83   {
  84   Return \retval{values of \VAR{form}s} or, in case of \kwd{error}s,
  85   \retval{\NIL} and the \retvalii{condition}.
  86   }
  87
  88   \IT{(\FU*{INVOKE-DEBUGGER} \VAR{condition})}
  89   {
  90   Invoke debugger with \VAR{condition}.
  91   }
  92
  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}}}{\}}}})}
  99   {
 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. Return
 105   \retval{\NIL}.
 106   }
 107
 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}})})}
 113   {
 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$}}).
 121   }
 122
 123   \IT{(\MC*{HANDLER-BIND} (\OPn{(\VAR{condition-type}
 124       \VAR{handler-function})}) \PROGN{\VAR{form}})}
 125   {
 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.
 129   }
 130
 131   \IT{(\MC*{WITH-SIMPLE-RESTART} (\VAR{restart} \VAR{control}
 132     \OPn{\VAR{arg}}) \PROGN{\VAR{form}})}
 133   {
 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}.
 139   }
 140
 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}})})}
 150   {
 151   Evaluate \VAR{form} with new 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 \NIL, \VAR{foo} is to be visible under \VAR{condition}.
 160   For (\OPn{\VAR{ord-$\lambda$}}) see p.\ \pageref{section:Functions}.
 161   }
 162
 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}})}
 168   {
 169   Return \retval{values of \VAR{form}s} evaluated with \VAR{restart}s
 170   dynamically bound to \VAR{restart-function}s.
 171   }
 172
 173   \IT{\arrGOO{(\FU*{INVOKE-RESTART} \VAR{ restart} \OPn{\VAR{ arg}})\\
 174       (\FU*{INVOKE-RESTART-INTERACTIVELY} \VAR{ restart})}{.}}
 175   {
 176   Call function associated with \VAR{restart} with arguments given or
 177   prompted for, respectively. If restart function returns, return \retval{its values}.
 178   }
 179
 180   \IT{(\xorGOO{\FU*{COMPUTE-RESTARTS}\\
 181       \FU*{FIND-RESTART} \VAR{ name}}{\}} \Op{\VAR{condition}})}
 182   {
 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.
 188   }
 189
 190   \IT{(\FU*{RESTART-NAME} \VAR{restart})}
 191   {
 192   \retval{Name of \VAR{restart}}.
 193   }
 194
 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}})}
 200   {
 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.
 207   }
 208
 209   \IT{(\MC*{WITH-CONDITION-RESTARTS} \VAR{condition-form}
 210     \VAR{restarts-form} \PROGN{\VAR{form}})}
 211   {
 212   Evaluate \VAR{form}s with restarts yielded from \VAR{restarts-form}
 213   dynamically associated with conditions yielded from
 214   \VAR{condition-form}. Return \retval{values of \VAR{form}s}.
 215   }
 216
 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}
 274
 275   \IT{\arrGOO{(\FU*{ARITHMETIC-ERROR-OPERATION} \VAR{ condition})\\
 276       (\FU*{ARITHMETIC-ERROR-OPERANDS} \VAR{ condition})}{.}}
 277   {
 278   \retval{Function} or \retval{list of its operands}, respectively,
 279   used in the operation which caused \VAR{condition}.
 280   }
 281
 282   \IT{(\FU*{CELL-ERROR-NAME} \VAR{condition})}
 283   {
 284   \retval{Name of cell} which caused \VAR{condition}.
 285   }
 286
 287   \IT{(\FU*{UNBOUND-SLOT-INSTANCE} \VAR{condition})}
 288   {
 289   \retval{Instance} with unbound slot which caused \VAR{condition}.
 290   }
 291
 292   \IT{(\FU*{PRINT-NOT-READABLE-OBJECT} \VAR{condition})}
 293   {
 294   The \retval{object} not readably printable under \VAR{condition}.
 295   }
 296
 297   \IT{\arrGOO{%
 298       (\FU*{PACKAGE-ERROR-PACKAGE } \VAR{condition})\\
 299       (\FU*{FILE-ERROR-PATHNAME } \VAR{condition})\\
 300       (\FU*{STREAM-ERROR-STREAM } \VAR{condition})}{.}}
 301   {
 302   \retval{Package}, \retval{path}, or \retval{stream}, respectively,
 303   which caused \VAR{condition}.
 304   }
 305
 306   \IT{\arrGOO{(\FU*{TYPE-ERROR-DATUM} \VAR{ condition})\\
 307       (\FU*{TYPE-ERROR-EXPECTED-TYPE} \VAR{ condition})}{.}}
 308   {
 309   \retval{Object} which caused \VAR{condition}, or its expected type,
 310   respectively.
 311   }
 312
 313   \IT{\arrGOO{(\FU*{SIMPLE-CONDITION-FORMAT-CONTROL} \VAR{ condition})\\
 314       (\FU*{SIMPLE-CONDITION-FORMAT-ARGUMENTS} \VAR{ condition})}{.}}
 315   {
 316   Return \retval{\FU{format} control} or list of \retval{\FU{format}
 317     arguments}, respectively, of \VAR{condition}.
 318   }
 319
 320   \IT{\V*{\A break-on-signals\A}\DF{\NIL}}
 321   {
 322   Condition debugger is to be invoked on.
 323   }
 324
 325   \IT{\V*{\A debugger-hook\A}\DF{\NIL}}
 326   {Function of condition and
 327   function itself.
 328   }
 329
 330 \end{LIST}
 331