clqr-conditions-and-errors.tex

   1 % Copyright (C) 2008, 2009 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{accessor}} \\
  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 a new condition, a \VAR{slot}'s value defaults
  37   to \VAR{form} unless set via \kwd{:}\VAR{initarg-name}; it is readable
  38   via (\VAR{reader} \VAR{i}) or (\VAR{accessor} \VAR{i}), and
  39   writeable via (\VAR{writer} \VAR{i} \VAR{value}) or (\kwd{setf}
  40   (\VAR{accessor} \VAR{i}) \VAR{value}). With
  41   \kwd{:allocation :class}, \VAR{slot} is shared by all conditions of
  42   type \VAR{foo}. A condition is reported by \VAR{string} or by
  43   \VAR{report-function} of arguments condition and stream.
  44   }
  45
  46   \IT{(\FU*{MAKE-CONDITION} \VAR{type} \Goos{\kwd{:}\VAR{initarg-name} \VAR{value}})}
  47   {
  48   Return new \retval{condition of \VAR{type}}.
  49   }
  50
  51   \IT{(\xorGOO{%
  52       \FU*{SIGNAL}\\
  53       \FU*{WARN}\\
  54       \FU*{ERROR}%
  55     }{\}}
  56     \xorGOO{%
  57       \VAR{condition}\\
  58       \VAR{type}\text{ } \Goos{\kwd{:}\VAR{initarg-name} \VAR{value}}\\
  59       \VAR{control}\text{ } \OPn{\VAR{arg}}%
  60     }{\}})}
  61   {
  62   Unless handled, signal as \kwd{condition}, \kwd{warning} or \kwd{error},
  63   respectively, \VAR{condition} or a new condition of \VAR{type} or,
  64   with \FU{format} \VAR{control} and \VAR{arg}s (see p.\ \pageref{section:Format}),
  65   \kwd{simple-condition}, \kwd{simple-warning}, or \kwd{simple-error}, respectively.
  66   From \FU{SIGNAL} and \FU{WARN}, return \retval{\NIL}.
  67   }
  68
  69   \IT{(\FU*{CERROR} \VAR{continue-control}
  70     \xorGOO{%
  71       \VAR{condition}\text{ }  \OPn{\VAR{continue-arg}}\\
  72       \VAR{type}\text{ } \Goos{\kwd{:}\VAR{initarg-name} \VAR{value}}\\
  73       \VAR{control}\text{ } \OPn{\VAR{arg}}%
  74     }{\}})}
  75   {
  76   Unless handled, signal as correctable \kwd{error} \VAR{condition} or
  77   a new condition of \VAR{type} or, with \FU{format} \VAR{control} and
  78   \VAR{arg}s (see p.\ \pageref{section:Format}),
  79   \kwd{simple-error}. In the debugger, use \FU{format} arguments
  80   \VAR{continue-control} and \VAR{continue-arg}s to tag the continue
  81   option. Return \retval{\NIL}.
  82   }
  83
  84   \IT{(\MC*{IGNORE-ERRORS} \PROGN{\VAR{form}})}
  85   {
  86   Return \retval{values of \VAR{form}s} or, in case of \kwd{error}s,
  87   \retval{\NIL} and the \retvalii{condition}.
  88   }
  89
  90   \IT{(\FU*{INVOKE-DEBUGGER} \VAR{condition})}
  91   {
  92   Invoke debugger with \VAR{condition}.
  93   }
  94
  95   \IT{(\MC*{ASSERT} \VAR{test} \OP{(\OPn{\VAR{place}})
  96       \Op{%
  97         \xorGOO{%
  98           \VAR{condition}\text{ }  \OPn{\VAR{continue-arg}}\\
  99           \VAR{type}\text{ } \Goos{\kwd{:}\VAR{initarg-name} \VAR{value}}\\
 100           \VAR{control}\text{ } \OPn{\VAR{arg}}}{\}}}})}
 101   {
 102   If \VAR{test}, which may depend on \VAR{place}s, returns \NIL,
 103   signal as correctable \kwd{error} \VAR{condition} or a new condition
 104   of \VAR{type} or, with \FU{format} \VAR{control} and \VAR{arg}s (see
 105   p.\ \pageref{section:Format}), \kwd{error}. When using the
 106   debugger's continue option, \VAR{place}s can be altered before
 107   re-evaluation of \VAR{test}. Return \retval{\NIL}.
 108   }
 109
 110   \IT{(\MC*{HANDLER-CASE} \VAR{test}
 111     \OPn{(\VAR{type} (\Op{\VAR{var}})
 112       \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})} \PROGN{\VAR{condition-form}})}
 113     \Op{(\kwd{:no-error} (\OPn{\VAR{ord-$\lambda$}}) \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})}
 114       \PROGN{\VAR{form}})})}
 115   {
 116   If, on evaluation of \VAR{test}, a condition of \VAR{type} is
 117   signalled, evaluate matching \VAR{condition-form}s
 118   with \VAR{var} bound to the condition, and return \retval{their
 119     values}. Without a condition, bind \VAR{ord-$\lambda$}s to values
 120   of \VAR{test} and return \retval{values of  \VAR{form}s} or, without
 121   a \kwd{:no-error} clause, return \retval{values of \VAR{test}}. See
 122   p.\ \pageref{section:Functions} for (\OPn{\VAR{ord-$\lambda$}}).
 123   }
 124
 125   \IT{(\MC*{HANDLER-BIND} (\OPn{(\VAR{condition-type}
 126       \VAR{handler-function})}) \PROGN{\VAR{form}})}
 127   {
 128    Return \retval{values of \VAR{form}s} after evaluating them with
 129    \VAR{condition-type}s dynamically bound to their respective
 130    \VAR{handler-function}s of argument condition.
 131   }
 132
 133   \IT{(\MC*{WITH-SIMPLE-RESTART} (\xorGOO{\VAR{restart}\\
 134       \NIL}{\}} \VAR{control}
 135     \OPn{\VAR{arg}}) \PROGN{\VAR{form}})}
 136   {
 137   Return \retval{values of \VAR{form}s} unless \VAR{restart} is called
 138   during their evaluation. In this case, describe restart using
 139   \FU{format} \VAR{control} and \VAR{arg}s (see
 140   p.\ \pageref{section:Format}) and return \retval{\NIL}
 141   and \retvalii{\T}.
 142   }
 143
 144   \IT{(\MC*{RESTART-CASE} \VAR{form} \OPn{(\VAR{foo}
 145       (\OPn{\VAR{ord-$\lambda$}})
 146       \orGOO{\kwd{:interactive} \VAR{ arg-function}\\
 147         \kwd{:report } \xorGOO{%
 148           \VAR{report-function}\\
 149           \VAR{string}\DF{\LIT{"}\VAR{foo}\LIT{"}}}{.}\\
 150         \kwd{:test} \VAR{ test-function}\DF{\T}}{\}}
 151       \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})}
 152       \PROGN{\VAR{restart-form}})})}
 153   {
 154   Evaluate \VAR{form} with dynamically established restarts \VAR{foo}. Return
 155   \retval{values of \VAR{form}} or, if by (\kwd{invoke-restarts}
 156   \VAR{foo} \OPn{\VAR{arg}}) one restart \VAR{foo} is called, use
 157   \VAR{string} or \VAR{report-function} (of a stream) to print a
 158   description of restart \VAR{foo} and
 159   return the \retval{values of its \VAR{restart-form}s}.
 160   \VAR{arg-function} supplies appropriate \VAR{arg}s if \VAR{foo} is
 161   called by \kwd{invoke-restart-interactively}. If (\VAR{test-function} \VAR{condition})
 162   returns \T, \VAR{foo} is made visible under \VAR{condition}.
 163   For (\OPn{\VAR{ord-$\lambda$}}) see p.\ \pageref{section:Functions}.
 164   }
 165
 166   \IT{(\MC*{RESTART-BIND} (\OPn{(\xorGOO{\NEV{\VAR{restart}}\\
 167         \NIL}{\}}
 168       \VAR{restart-function} \orGOO{\kwd{:interactive-function}
 169         \VAR{ function}\\
 170       \kwd{:report-function} \VAR{ function}\\
 171       \kwd{:test-function} \VAR{ function}}{\}})}) \PROGN{\VAR{form}})}
 172   {
 173   Return \retval{values of \VAR{form}s} evaluated with \VAR{restart}s
 174   dynamically bound to \VAR{restart-function}s.
 175   }
 176
 177   \IT{\arrGOO{(\FU*{INVOKE-RESTART} \VAR{ restart} \OPn{\VAR{ arg}})\\
 178       (\FU*{INVOKE-RESTART-INTERACTIVELY} \VAR{ restart})}{.}}
 179   {
 180   Call function associated with \VAR{restart} with arguments given or
 181   prompted for, respectively. If \VAR{restart} function returns, return \retval{its values}.
 182   }
 183
 184   \IT{(\xorGOO{\FU*{COMPUTE-RESTARTS}\\
 185       \FU*{FIND-RESTART} \VAR{ name}}{\}} \Op{\VAR{condition}})}
 186   {
 187   Return list of \retval{all restarts}, or innermost \retval{restart}
 188   \VAR{name}, respectively, out of those either associated
 189   with \VAR{condition} or un-associated at all; or, without
 190   \VAR{condition}, out of all restarts. Return \retval{\NIL} if search
 191   is unsuccessful.
 192   }
 193
 194   \IT{(\FU*{RESTART-NAME} \VAR{restart})}
 195   {
 196   \retval{Name of \VAR{restart}}.
 197   }
 198
 199   \IT{(\xorGOO{\FU*{ABORT}\\
 200       \FU*{MUFFLE-WARNING}\\
 201       \FU*{CONTINUE}\\
 202       \FU*{STORE-VALUE} \VAR{ value}\\
 203       \FU*{USE-VALUE} \VAR{ value}}{\}} \Op{\VAR{condition}\DF{\NIL}})}
 204   {
 205   Transfer control to innermost applicable restart with same name
 206   (i.e. \kwd{abort}, \ldots, \kwd{continue} \ldots) out of those either associated
 207   with \VAR{condition} or un-associated at all; or, without
 208   \VAR{condition}, out of all restarts. If no restart is found,
 209   signal \kwd{control-error} for \FU{abort} and \FU{muffle-warning},
 210   or return \retval{\NIL} for the rest.
 211   }
 212
 213   \IT{(\MC*{WITH-CONDITION-RESTARTS} \VAR{condition}
 214     \VAR{restarts} \PROGN{\VAR{form}})}
 215   {
 216   Evaluate \VAR{form}s with \VAR{restarts}
 217   dynamically associated with \VAR{condition}. Return \retval{values
 218     of \VAR{form}s}.
 219   }
 220
 221   \begin{figure}
 222     \begin{center}
 223       \boxGOO{%
 224         \T\index{T}%
 225         \boxGOO{%
 226           \kwd*{CONDITION}\\
 227           \boxGOO{%
 228             \kwd*{WARNING}
 229             \boxGOO{%
 230               \kwd*{STYLE-WARNING}\\
 231               \kwd*{SIMPLE-CONDITION}\footnotemark[2]
 232               \boxGOO{%
 233                 \kwd*{SIMPLE-WARNING}}}\boxGOOcr
 234             \kwd*{SIMPLE-CONDITION}\boxGOOcr
 235             \kwd*{SERIOUS-CONDITION}\\
 236             \boxGOO{%
 237               \kwd*{ERROR}\\
 238               \boxGOO{%
 239                 \kwd*{SIMPLE-CONDITION}\footnotemark[2]
 240                 \boxGOO{%
 241                   \kwd*{SIMPLE-ERROR}}\boxGOOcr
 242                 \kwd*{PARSE-ERROR};\>
 243                 \kwd*{PROGRAM-ERROR};\>
 244                 \kwd*{CONTROL-ERROR}\boxGOOcr
 245                 \kwd*{TYPE-ERROR}
 246                 \boxGOO{%
 247                   \kwd*{SIMPLE-CONDITION}\footnotemark[2]
 248                   \boxGOO{%
 249                     \kwd*{SIMPLE-TYPE-ERROR}}}\boxGOOcr
 250                 \kwd*{CELL-ERROR}
 251                 \boxGOO{%
 252                   \kwd*{UNBOUND-VARIABLE};\>
 253                   \kwd*{UNBOUND-SLOT};\\
 254                   \kwd*{UNDEFINED-FUNCTION}}\boxGOOcr
 255                 \kwd*{STREAM-ERROR}
 256                 \boxGOO{%
 257                   \kwd*{END-OF-FILE}\\
 258                   \kwd*{PARSE-ERROR}\footnotemark[2]
 259                   \boxGOO{\kwd*{READER-ERROR}}}\boxGOOcr
 260                 \kwd*{PACKAGE-ERROR};\>
 261                 \kwd*{FILE-ERROR};\>
 262                 \kwd*{PRINT-NOT-READABLE}\boxGOOcr
 263                 \kwd*{ARITHMETIC-ERROR}\\
 264                 \boxGOO{%
 265                   \kwd*{DIVISION-BY-ZERO};\>
 266                   \kwd*{FLOATING-POINT-INEXACT};\\
 267                   \kwd*{FLOATING-POINT-INVALID-OPERATION};\\
 268                   \kwd*{FLOATING-POINT-OVERFLOW};\>
 269                   \kwd*{FLOATING-POINT-UNDERFLOW}}
 270               }\boxGOOcr
 271               \kwd*{STORAGE-CONDITION}}
 272       }}}\\
 273   \end{center}\vspace{-1em}
 274               {\footnotesize\footnotemark[2]For supertypes of this
 275                 type look for the instance without a \footnotemark[2].}
 276   \caption{Condition Types.}%
 277 \end{figure}
 278
 279   \IT{\arrGOO{(\FU*{ARITHMETIC-ERROR-OPERATION} \VAR{ condition})\\
 280       (\FU*{ARITHMETIC-ERROR-OPERANDS} \VAR{ condition})}{.}}
 281   {
 282   \retval{List of function} or \retval{of its operands} respectively,
 283   used in the operation which caused \VAR{condition}.
 284   }
 285
 286   \IT{(\FU*{CELL-ERROR-NAME} \VAR{condition})}
 287   {
 288   \retval{Name of cell} which caused \VAR{condition}.
 289   }
 290
 291   \IT{(\FU*{UNBOUND-SLOT-INSTANCE} \VAR{condition})}
 292   {
 293   \retval{Instance} with unbound slot which caused \VAR{condition}.
 294   }
 295
 296   \IT{(\FU*{PRINT-NOT-READABLE-OBJECT} \VAR{condition})}
 297   {
 298   The \retval{object} not readably printable under \VAR{condition}.
 299   }
 300
 301   \IT{\arrGOO{%
 302       (\FU*{PACKAGE-ERROR-PACKAGE } \VAR{condition})\\
 303       (\FU*{FILE-ERROR-PATHNAME } \VAR{condition})\\
 304       (\FU*{STREAM-ERROR-STREAM } \VAR{condition})}{.}}
 305   {
 306   \retval{Package}, \retval{path}, or \retval{stream}, respectively,
 307   which caused the \VAR{condition} of indicated type.
 308   }
 309
 310   \IT{\arrGOO{(\FU*{TYPE-ERROR-DATUM} \VAR{ condition})\\
 311       (\FU*{TYPE-ERROR-EXPECTED-TYPE} \VAR{ condition})}{.}}
 312   {
 313   \retval{Object} which caused \VAR{condition} of type \kwd{type-error}, or its
 314   \retval{expected type}, respectively.
 315   }
 316
 317   \IT{\arrGOO{(\FU*{SIMPLE-CONDITION-FORMAT-CONTROL} \VAR{ condition})\\
 318       (\FU*{SIMPLE-CONDITION-FORMAT-ARGUMENTS} \VAR{ condition})}{.}}
 319   {
 320   Return \retval{\FU{format} control} or list of \retval{\FU{format}
 321     arguments}, respectively, of \VAR{condition}.
 322   }
 323
 324   \IT{\V{\A break-on-signals\A}\DF{\NIL}}
 325   {\index{*BREAK-ON-SIGNALS*@\A BREAK-ON-SIGNALS\A}
 326   Condition type debugger is to be invoked on.
 327   }
 328
 329   \IT{\V{\A debugger-hook\A}\DF{\NIL}}
 330   {\index{*DEBUGGER-HOOK*@\A DEBUGGER-HOOK\A}
 331     Function of condition and
 332   function itself. Called before debugger.
 333   }
 334
 335 \end{LIST}
 336
 337
 338 %%% Local Variables:
 339 %%% mode: latex
 340 %%% TeX-master: "clqr"
 341 %%% End: