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{figure}[hbt]
  15   \begin{center}
  16     \boxGOO{%
  17       \T\index{T}%
  18       \boxGOO{%
  19         \kwd*{CONDITION}\\
  20         \boxGOO{%
  21           \kwd*{WARNING}
  22           \boxGOO{%
  23             \kwd*{STYLE-WARNING}\\
  24             \kwd*{SIMPLE-CONDITION}\footnotemark[2]
  25             \boxGOO{%
  26               \kwd*{SIMPLE-WARNING}}}\boxGOOcr
  27           \kwd*{SERIOUS-CONDITION}\\
  28           \boxGOO{%
  29             \kwd*{ERROR}\\
  30             \boxGOO{%
  31               \kwd*{CELL-ERROR}
  32               \boxGOO{%
  33                 \kwd*{UNBOUND-VARIABLE},\>
  34                 \kwd*{UNBOUND-SLOT},\\
  35                 \kwd*{UNDEFINED-FUNCTION}}\boxGOOcr
  36               \kwd*{STREAM-ERROR}
  37               \boxGOO{%
  38                 \kwd*{END-OF-FILE}\\
  39                 \kwd*{PARSE-ERROR}\footnotemark[2]
  40                 \boxGOO{\kwd*{READER-ERROR}}}\boxGOOcr
  41               \kwd*{ARITHMETIC-ERROR}\\
  42               \boxGOO{%
  43                 \kwd*{DIVISION-BY-ZERO},\>
  44                 \kwd*{FLOATING-POINT-INEXACT},\\
  45                 \kwd*{FLOATING-POINT-INVALID-OPERATION},\\
  46                 \kwd*{FLOATING-POINT-OVERFLOW},\>
  47                 \kwd*{FLOATING-POINT-UNDERFLOW}}\boxGOOcr
  48               \kwd*{TYPE-ERROR}
  49               \boxGOO{%
  50                 \kwd*{SIMPLE-CONDITION}\footnotemark[2]
  51                 \boxGOO{%
  52                   \kwd*{SIMPLE-TYPE-ERROR}}}\boxGOOcr
  53               \kwd*{SIMPLE-CONDITION}\footnotemark[2]
  54               \boxGOO{%
  55                 \kwd*{SIMPLE-ERROR}}\boxGOOcr
  56               \kwd*{PARSE-ERROR},\>
  57               \kwd*{PROGRAM-ERROR},\>
  58               \kwd*{CONTROL-ERROR},\\
  59               \kwd*{PACKAGE-ERROR},\>
  60               \kwd*{FILE-ERROR},\>
  61               \kwd*{PRINT-NOT-READABLE}}\boxGOOcr
  62             \kwd*{STORAGE-CONDITION}}\boxGOOcr
  63           \kwd*{SIMPLE-CONDITION}}}}\\
  64   \end{center}\vspace{-1em}
  65               {\footnotesize\footnotemark[2]For supertypes of this
  66                 type look for the instance without a \footnotemark[2].}
  67   \caption{Condition Types.}%
  68 \end{figure}
  69
  70 \begin{LIST}{1cm}
  71   \IT{(\SF*{DEFINE-CONDITION} \VAR{name} (\OPn{\VAR{parent}})
  72     (\xorGOO{\VAR{slot}\\
  73       (\VAR{slot}
  74       \orGOO{\Goos{\kwd{:reader} \VAR{reader-fu}}\\
  75         \Goos{\kwd{:writer} \VAR{writer-fu}} \\
  76         \Goos{\kwd{:accessor} \VAR{reader-fu}} \\
  77         \kwd{:allocation } \Goo{\kwd{:instance}\XOR\kwd{:class}}\\
  78         \Goos{\kwd{:initarg} \kwd{:}\VAR{arg}}\\
  79         \kwd{:initform} \VAR{ form}\\
  80         \kwd{:type} \VAR{ type}}{\}})}{\}})
  81     \orGOO{(\kwd{:default-initargs } \Goos{\VAR{name} \VAR{value}})\\
  82       ({\kwd{:documentation} \VAR{ string}})\\
  83       (\kwd{:report} \VAR{ report-name})}{\}})}
  84   {
  85   Define new condition type \retval{\VAR{name}}.
  86   }
  87
  88   \IT{(\FU*{MAKE-CONDITION} \VAR{type} \OPn{\VAR{initarg-plist}})}
  89   {
  90   Return \retval{new condition of \VAR{type}}.
  91   }
  92
  93   \IT{(\FU*{UNWIND-PROTECT} \VAR{protected} \OPn{\VAR{cleanup}})}
  94   {
  95   Evaluate \VAR{protected} and then, no matter how control leaves
  96   \VAR{protected}, \VAR{cleanup}s. Return \retval{values of
  97     \VAR{protected}}.
  98   }
  99
 100   \IT{(\xorGOO{\FU*{SIGNAL}\\
 101       \FU*{WARN}}{\}} \VAR{datum} \OPn{\VAR{arg}})}
 102   {
 103   Signal \kwd{condition} or \kwd{warning}, respectively,
 104   as denoted by \VAR{datum} and \VAR{arg}s. Return \retval{\NIL}.
 105   }
 106
 107   \IT{(\FU*{ERROR} \VAR{datum} \OPn{\VAR{arg}})}
 108   {
 109   Signal \kwd{simple-error} as denoted by \VAR{datum} and \VAR{arg}s unless
 110   error is handled.
 111   }
 112
 113   \IT{(\FU*{CERROR} \VAR{control} \VAR{datum} \OPn{arg})}
 114   {
 115   Signal correctable \kwd{simple-error} to debugger unless error is
 116   handled. Show \FU{format} \VAR{control} (see
 117   p.\ \pageref{section:Format}) with the debugger's continue option.
 118   }
 119
 120   \IT{(\SF*{IGNORE-ERRORS} \OPn{\VAR{form}})}
 121   {
 122   Return \retval{values of \VAR{form}s} as in \SF{progn} or, in case of \kwd{error}s,
 123   \retval{\NIL} and the \retvalii{condition}.
 124   }
 125
 126   \IT{(\FU*{INVOKE-DEBUGGER} \VAR{condition})}
 127   {
 128   Invoke debugger with \VAR{condition}.
 129   }
 130
 131   \IT{(\FU*{BREAK} \Op{\VAR{control} \OPn{\VAR{arg}}})}
 132   {
 133   Jump into debugger, return \retval{\NIL}.
 134   See p.\ \pageref{section:Format}, \FU{format}, for \VAR{control}
 135   and \VAR{arg}s.
 136   }
 137
 138   \IT{(\SF*{ASSERT} \VAR{test} \OP{(\OPn{\VAR{place}}) \Op{\VAR{datum}
 139     \OPn{\VAR{arg}}}})}
 140   {
 141   Signal correctable error denoted by \VAR{datum} and \VAR{arg}s if
 142   \VAR{test}, which may depend on \VAR{place}s, returns \NIL. Return
 143   \retval{\NIL}.
 144   }
 145
 146   \IT{(\SF*{HANDLER-CASE} \VAR{test}
 147     \OPn{(\VAR{type} (\Op{\VAR{condition-var}})
 148       \OPn{(\kwd{declare} \OPn{\VAR{decl}})} \OPn{\VAR{condition-form}})}
 149     \Op{(\kwd{:no-error} (\OPn{\VAR{fu-arg}}) \OPn{(\kwd{declare} \OPn{\VAR{decl}})}
 150       \OPn{\VAR{form}})})}
 151   {
 152   If, on evaluation of \VAR{test}, a condition of \VAR{type} is
 153   signalled, return \retval{values of matching \VAR{condition-form}s}
 154   with \VAR{condition-var} bound to the condition. Without a condition, bind
 155   \VAR{fu-arg}s to values of \VAR{test} and return \retval{values of
 156     \VAR{form}s} or, without a \kwd{:no-error} clause, return
 157   \retval{values of \VAR{test}}. See p.\ \pageref{section:Functions}
 158   for (\OPn{\VAR{fu-arg}}).
 159   }
 160
 161   \IT{(\kwd*{HANDLER-BIND} (\OPn{(\VAR{condition-type}
 162       \VAR{handler})}) \OPn{\VAR{form}})}
 163   {
 164   Evaluate \VAR{form}s with \VAR{condition-type}s dynamically bound to
 165   their respective \VAR{handler}. Return \retval{values of \VAR{form}s}.
 166   }
 167
 168   \IT{(\SF*{WITH-SIMPLE-RESTART} (\VAR{restart} \VAR{control}
 169     \OPn{\VAR{arg}}) \OPn{\VAR{form}})}
 170   {
 171   If \VAR{restart} is not called from \VAR{form}s, return
 172   \retval{values of last \VAR{form}}. Otherwise return \retval{\NIL}
 173   and \retvalii{\T} and describe restart using \FU{format} \VAR{control}
 174   and \VAR{arg}s (see p.\ \pageref{section:Format}).
 175   }
 176
 177   \IT{(\SF*{WITH-CONDITION-RESTARTS} \VAR{condition-form}
 178     \VAR{restarts-form} \OPn{\VAR{form}})}
 179   {
 180   Evaluate \VAR{form}s with restarts yielded from \VAR{restarts-form}
 181   dynamically associated with  condition yielded from
 182   \VAR{condition-form}. Return values of \VAR{form}s.
 183   }
 184
 185   \IT{(\SF*{RESTART-CASE} \VAR{test} \OPn{(\VAR{name} (\OPn{\VAR{fu-arg}})%
 186       \orGOO{\kwd{:interactive}
 187         \VAR{ form}\\
 188       \kwd{:report} \VAR{ form}\\
 189       \kwd{:test} \VAR{ form}}{\}} \OPn{(\kwd{declare} \OPn{\VAR{decl}})}
 190       \OPn{form})})}
 191   {
 192   Evaluate \VAR{test} with new restarts \VAR{name}. Return
 193   \retval{values of \VAR{test}} or, if any of the restarts is invoked,
 194   return \retval{values of its last \VAR{form}}.
 195   For (\OPn{\VAR{fu-arg}}) see p.\ \pageref{section:Functions}.
 196   }
 197
 198   \IT{(\SF*{RESTART-BIND} (\OPn{(\VAR{restart}
 199       \VAR{restart-function}\orGOO{\kwd{:interactive-function}
 200         \VAR{ function}\\
 201       \kwd{:report-function} \VAR{ function}\\
 202       \kwd{:test-function} \VAR{ function}}{\}})}) \OPn{\VAR{form}})}
 203   {
 204   Return \retval{value of \VAR{form}s} evaluated with \VAR{restart}s
 205   dynamically bound to \VAR{restart-function}s.
 206   }
 207
 208   \IT{\arrGOO{(\FU*{INVOKE-RESTART} \VAR{ foo} \OPn{\VAR{ arg}})\\
 209       (\FU*{INVOKE-RESTART-INTERACTIVELY} \VAR{ restart})}{.}}
 210   {
 211   Call function associated with \VAR{restart} with arguments given or
 212   prompted for, respectively. If restart function returns, return \retval{its values}.
 213   }
 214
 215   \IT{(\xorGOO{\FU*{COMPUTE-RESTARTS}\\
 216       \FU*{FIND-RESTART} \VAR{ name}}{\}} \Op{\VAR{condition}})}
 217   {
 218   Return list of \retval{all restarts}, or innermost \retval{restart}
 219   \VAR{name}, respectively, out of those either associated
 220   with \VAR{condition} or un-associated at all; or, without
 221   \VAR{condition}, out of all restarts. Return \retval{\NIL} if search
 222   is unsuccessful.
 223   }
 224
 225   \IT{(\FU*{RESTART-NAME} \VAR{restart})}
 226   {
 227   \retval{Name of \VAR{restart}}.
 228   }
 229
 230   \IT{(\xorGOO{\FU*{ABORT}\\
 231       \FU*{MUFFLE-WARNING}\\
 232       \FU*{CONTINUE}\\
 233       \FU*{STORE-VALUE} \VAR{ value}\\
 234       \FU*{USE-VALUE} \VAR{ value}}{\}} \Op{\VAR{condition}})}
 235   {
 236   Transfer control to innermost applicable restart with same name
 237   (i.e. \kwd{abort}, \ldots, \kwd{continue} \ldots) out of those either associated
 238   with \VAR{condition} or un-associated at all; or, without
 239   \VAR{condition}, out of all restarts. If no restart is found,
 240   signal \kwd{control-error} for \FU{abort} and \FU{muffle-warning},
 241   or return \retval{\NIL} for the rest.
 242   }
 243
 244   \IT{\arrGOO{(\FU*{ARITHMETIC-ERROR-OPERATION} \VAR{ condition})\\
 245       (\FU*{ARITHMETIC-ERROR-OPERANDS} \VAR{ condition})}{.}}
 246   {
 247   \retval{Function} or \retval{list of its operands}, respectively, used in signalling operation.
 248   }
 249
 250   \IT{(\FU*{CELL-ERROR-NAME} \VAR{condition})}
 251   {
 252   \retval{Name of cell} which caused \VAR{condition}.
 253   }
 254
 255   \IT{(\FU*{UNBOUND-SLOT-INSTANCE} \VAR{condition})}
 256   {
 257   \retval{Instance} with unbound slot which caused \VAR{condition}.
 258   }
 259
 260   \IT{(\FU*{PACKAGE-ERROR-PACKAGE} \VAR{condition})}
 261   {
 262   \retval{Package} which caused \VAR{condition}.
 263   }
 264
 265   \IT{(\FU*{PRINT-NOT-READABLE-OBJECT} \VAR{condition})}
 266   {
 267   The \retval{object} not readably printable under \VAR{condition}.
 268   }
 269
 270   \IT{(\FU*{FILE-ERROR-PATHNAME} \VAR{condition})}
 271   {
 272   \retval{Path} which caused condition.
 273   }
 274
 275   \IT{(\FU*{STREAM-ERROR-STREAM} \VAR{condition})}
 276   {
 277   \retval{Stream} which caused \VAR{condition}.
 278   }
 279
 280   \IT{\arrGOO{(\FU*{TYPE-ERROR-DATUM} \VAR{ condition})\\
 281       (\FU*{TYPE-ERROR-EXPECTED-TYPE} \VAR{ condition})}{.}}
 282   {
 283   \retval{Datum} which caused \VAR{condition}, or its expected type,
 284   respectively.
 285   }
 286
 287   \IT{\arrGOO{(\FU*{SIMPLE-CONDITION-FORMAT-CONTROL} \VAR{ condition})\\
 288       (\FU*{SIMPLE-CONDITION-FORMAT-ARGUMENTS} \VAR{ condition})}{.}}
 289   {
 290   Return \retval{\FU{format} control} or list of \retval{\FU{format}
 291     arguments}, respectively, of \VAR{condition}.
 292   }
 293
 294   \IT{\V*{*break-on-signals*}\DF{\NIL}}
 295   {
 296   Condition debugger is to be invoked on.
 297   }
 298
 299   \IT{\V*{*debugger-hook*}\DF{\NIL}}
 300   {Function of condition and
 301   function itself.
 302   }
 303
 304 \end{LIST}
 305