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