clqr-conditions-and-errors.tex

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