Better reflection of comment style conventions.

[clqr.git] / clqr-conditions-and-errors.tex

% Copyright (C) 2008, 2009, 2010 Bert Burgemeister
%
% Permission is granted to copy, distribute and/or modify this
% document under the terms of the GNU Free Documentation License,
% Version 1.2 or any later version published by the Free Software
% Foundation; with no Invariant Sections, no Front-Cover Texts and
% no Back-Cover Texts. For details see file COPYING.
%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Conditions and Errors} 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

For standardized condition types cf.\ Figure \ref{data-types} on
page \pageref{data-types}.

\begin{LIST}{1cm}
  \IT{(\MC*{DEFINE-CONDITION} \VAR{foo} (\OPn{\VAR{parent-type}}\DF{\kwd{condition}})
    (\xorGOO{\VAR{slot}\\
      (\VAR{slot } 
      \orGOO{\Goos{\kwd{:reader} \VAR{reader}}\\
        \Goos{\kwd{:writer} \xorGOO{%
            \VAR{writer}\\
            (\kwd{setf } \VAR{writer})}{\}}}\\
        \Goos{\kwd{:accessor} \VAR{accessor}} \\
        \kwd{:allocation } \xorGOO{\kwd{:instance}\\
          \kwd{:class}}{\}}\DF{\kwd{:instance}}\\
        \Goos{\kwd{:initarg} \kwd{:}\VAR{initarg-name}}\\
        \kwd{:initform} \VAR{ form}\\
        \kwd{:type} \VAR{ type}\\
        \kwd{:documentation} \VAR{ slot-doc}%
      }{\}})}{\}^{\!\!*}})
    \orGOO{(\kwd{:default-initargs } \Goos{\VAR{name} \VAR{value}})\\
      ({\kwd{:documentation} \VAR{ condition-doc}})\\
      (\kwd{:report } \xorGOO{\VAR{string}\\
        \VAR{report-function}}{\}})}{\}})}
  {
  Define, as a subtype of \VAR{parent-type}s, condition type
  \retval{\VAR{foo}}. In a new condition, a \VAR{slot}'s value defaults
  to \VAR{form} unless set via \kwd{:}\VAR{initarg-name}; it is readable
  via (\VAR{reader} \VAR{i}) or (\VAR{accessor} \VAR{i}), and
  writeable via (\VAR{writer} \VAR{i} \VAR{value}) or (\kwd{setf}
  (\VAR{accessor} \VAR{i}) \VAR{value}). With
  \kwd{:allocation :class}, \VAR{slot} is shared by all conditions of
  type \VAR{foo}. A condition is reported by \VAR{string} or by
  \VAR{report-function} of arguments condition and stream.
  }

  \IT{(\FU*{MAKE-CONDITION} \VAR{type} \Goos{\kwd{:}\VAR{initarg-name} \VAR{value}})}
  {
  Return new \retval{condition of \VAR{type}}.
  }

  \IT{(\xorGOO{%
      \FU*{SIGNAL}\\
      \FU*{WARN}\\
      \FU*{ERROR}%
    }{\}}
    \xorGOO{%
      \VAR{condition}\\
      \VAR{type}\text{ } \Goos{\kwd{:}\VAR{initarg-name} \VAR{value}}\\ 
      \VAR{control}\text{ } \OPn{\VAR{arg}}%
    }{\}})}
  {
  Unless handled, signal as \kwd{condition}, \kwd{warning} or \kwd{error},
  respectively, \VAR{condition} or a new condition of \VAR{type} or,
  with \FU{format} \VAR{control} and \VAR{arg}s (see p.\ \pageref{section:Format}),
  \kwd{simple-condition}, \kwd{simple-warning}, or \kwd{simple-error}, respectively.
  From \FU{SIGNAL} and \FU{WARN}, return \retval{\NIL}.
  }

  \IT{(\FU*{CERROR} \VAR{continue-control}
    \xorGOO{%
      \VAR{condition}\text{ }  \OPn{\VAR{continue-arg}}\\
      \VAR{type}\text{ } \Goos{\kwd{:}\VAR{initarg-name} \VAR{value}}\\
      \VAR{control}\text{ } \OPn{\VAR{arg}}%
    }{\}})}
  {
  Unless handled, signal as correctable \kwd{error} \VAR{condition} or
  a new condition of \VAR{type} or, with \FU{format} \VAR{control} and
  \VAR{arg}s (see p.\ \pageref{section:Format}),
  \kwd{simple-error}. In the debugger, use \FU{format} arguments
  \VAR{continue-control} and \VAR{continue-arg}s to tag the continue
  option. Return \retval{\NIL}.
  }

  \IT{(\MC*{IGNORE-ERRORS} \PROGN{\VAR{form}})}
  {
  Return \retval{values of \VAR{form}s} or, in case of \kwd{error}s,
  \retval{\NIL} and the \retvalii{condition}.
  }

  \IT{(\FU*{INVOKE-DEBUGGER} \VAR{condition})}
  {
  Invoke debugger with \VAR{condition}.
  }

  \IT{(\MC*{ASSERT} \VAR{test} \OP{(\OPn{\VAR{place}}) 
      \Op{%
        \xorGOO{%
          \VAR{condition}\text{ }  \OPn{\VAR{continue-arg}}\\
          \VAR{type}\text{ } \Goos{\kwd{:}\VAR{initarg-name} \VAR{value}}\\
          \VAR{control}\text{ } \OPn{\VAR{arg}}}{\}}}})}
  {
    If \VAR{test}, which may depend on \VAR{place}s, returns \NIL,
    signal as correctable \kwd{error} \VAR{condition} or a new condition
    of \VAR{type} or, with \FU{format} \VAR{control} and \VAR{arg}s (see
    p.\ \pageref{section:Format}), \kwd{error}. When using the
    debugger's continue option, \VAR{place}s can be altered before
    re-evaluation of \VAR{test}. Return \retval{\NIL}. 
  }

  \IT{(\MC*{HANDLER-CASE} \VAR{foo} 
    \OPn{(\VAR{type} (\Op{\VAR{var}})
      \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})}
      \PROGN{\VAR{condition-form}})} 
    \Op{(\kwd{:no-error} (\OPn{\VAR{ord-$\lambda$}})
      \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})}
      \PROGN{\VAR{form}})})}
  {
    If, on evaluation of \VAR{foo}, a condition of \VAR{type} is
    signalled, evaluate matching \VAR{condition-form}s with \VAR{var}
    bound to the condition, and return \retval{their values}. Without
    a condition, bind \VAR{ord-$\lambda$}s to values of \VAR{foo} and
    return \retval{values of  \VAR{form}s} or, without a
    \kwd{:no-error} clause, return \retval{values of \VAR{foo}}. See
    p.\ \pageref{section:Functions} for (\OPn{\VAR{ord-$\lambda$}}).
  }

  \IT{(\MC*{HANDLER-BIND} (\OPn{(\VAR{condition-type}
      \VAR{handler-function})}) \PROGN{\VAR{form}})}
  {
    Return \retval{values of \VAR{form}s} after evaluating them with
    \VAR{condition-type}s dynamically bound to their respective
    \VAR{handler-function}s of argument condition. 
  }

  \IT{(\MC*{WITH-SIMPLE-RESTART} (\xorGOO{\VAR{restart}\\
      \NIL}{\}} \VAR{control}
    \OPn{\VAR{arg}}) \PROGN{\VAR{form}})}
  {
    Return \retval{values of \VAR{form}s} unless \VAR{restart} is called
    during their evaluation. In this case, describe restart using
    \FU{format} \VAR{control} and \VAR{arg}s (see
    p.\ \pageref{section:Format}) and return \retval{\NIL}
    and \retvalii{\T}.
  }

  \IT{(\MC*{RESTART-CASE} \VAR{form} \OPn{(\VAR{foo}
      (\OPn{\VAR{ord-$\lambda$}}) 
      \orGOO{\kwd{:interactive} \VAR{ arg-function}\\ 
        \kwd{:report } \xorGOO{%
          \VAR{report-function}\\
          \VAR{string}\DF{\LIT{"}\VAR{foo}\LIT{"}}}{.}\\
        \kwd{:test} \VAR{ test-function}\DF{\T}}{\}}
      \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})}
      \PROGN{\VAR{restart-form}})})}
  {
    Evaluate \VAR{form} with dynamically established restarts
    \VAR{foo}. Return \retval{values of \VAR{form}} or, if by
    (\FU{invoke-restart} \VAR{foo} \OPn{\VAR{arg}}) one restart
    \VAR{foo} is called, use \VAR{string} or \VAR{report-function} (of
    a stream) to print a description of restart \VAR{foo} and return
    the \retval{values of its \VAR{restart-form}s}. \VAR{arg-function}
    supplies appropriate \VAR{arg}s if \VAR{foo} is called by
    \FU{invoke-restart-interactively}. If (\VAR{test-function}
    \VAR{condition}) returns \T, \VAR{foo} is made visible under
    \VAR{condition}. \OPn{\VAR{arg}} matches
    (\OPn{\VAR{ord-$\lambda$}}); see p.\ \pageref{section:Functions}
    for the latter.
  }

  \IT{(\MC*{RESTART-BIND} (\OPn{(\xorGOO{\NEV{\VAR{restart}}\\
        \NIL}{\}}
      \VAR{restart-function} \orGOO{\kwd{:interactive-function}
        \VAR{ function}\\ 
      \kwd{:report-function} \VAR{ function}\\
      \kwd{:test-function} \VAR{ function}}{\}})}) \PROGN{\VAR{form}})}
  {
    Return \retval{values of \VAR{form}s} evaluated with
    \VAR{restart}s dynamically bound to \VAR{restart-function}s. 
  }

  \IT{\arrGOO{(\FU*{INVOKE-RESTART} \VAR{ restart} \OPn{\VAR{ arg}})\\
      (\FU*{INVOKE-RESTART-INTERACTIVELY} \VAR{ restart})}{.}}
  {
  Call function associated with \VAR{restart} with arguments given or
  prompted for, respectively. If \VAR{restart} function returns,
  return \retval{its values}.
  }

  \IT{(\xorGOO{\FU*{COMPUTE-RESTARTS}\\
      \FU*{FIND-RESTART} \VAR{ name}}{\}} \Op{\VAR{condition}})}
  {
  Return list of \retval{all restarts}, or innermost \retval{restart}
  \VAR{name}, respectively, out of those either associated
  with \VAR{condition} or un-associated at all; or, without
  \VAR{condition}, out of all restarts. Return \retval{\NIL} if search
  is unsuccessful.
  }

  \IT{(\FU*{RESTART-NAME} \VAR{restart})}
  {
  \retval{Name of \VAR{restart}}.
  }

  \IT{(\xorGOO{\FU*{ABORT}\\
      \FU*{MUFFLE-WARNING}\\
      \FU*{CONTINUE}\\
      \FU*{STORE-VALUE} \VAR{ value}\\
      \FU*{USE-VALUE} \VAR{ value}}{\}} \Op{\VAR{condition}\DF{\NIL}})}
  {
  Transfer control to innermost applicable restart with same name
  (i.e. \kwd{abort}, \ldots, \kwd{continue} \ldots) out of those either associated
  with \VAR{condition} or un-associated at all; or, without
  \VAR{condition}, out of all restarts. If no restart is found,
  signal \kwd{control-error} for \FU{abort} and \FU{muffle-warning},
  or return \retval{\NIL} for the rest.
  }

  \IT{(\MC*{WITH-CONDITION-RESTARTS} \VAR{condition}
    \VAR{restarts} \PROGN{\VAR{form}})}
  {
  Evaluate \VAR{form}s with \VAR{restarts}
  dynamically associated with \VAR{condition}. Return \retval{values
    of \VAR{form}s}. 
  }

  \IT{\arrGOO{(\FU*{ARITHMETIC-ERROR-OPERATION} \VAR{ condition})\\
      (\FU*{ARITHMETIC-ERROR-OPERANDS} \VAR{ condition})}{.}}
  {
  \retval{List of function} or \retval{of its operands} respectively,
  used in the operation which caused \VAR{condition}.
  }

  \IT{(\FU*{CELL-ERROR-NAME} \VAR{condition})}
  {
  \retval{Name of cell} which caused \VAR{condition}.
  }

  \IT{(\FU*{UNBOUND-SLOT-INSTANCE} \VAR{condition})}
  {
  \retval{Instance} with unbound slot which caused \VAR{condition}.
  }

  \IT{(\FU*{PRINT-NOT-READABLE-OBJECT} \VAR{condition})}
  {
  The \retval{object} not readably printable under \VAR{condition}.
  }

  \IT{\arrGOO{%
      (\FU*{PACKAGE-ERROR-PACKAGE } \VAR{condition})\\
      (\FU*{FILE-ERROR-PATHNAME } \VAR{condition})\\
      (\FU*{STREAM-ERROR-STREAM } \VAR{condition})}{.}}
  {
  \retval{Package}, \retval{path}, or \retval{stream}, respectively,
  which caused the \VAR{condition} of indicated type. 
  }

  \IT{\arrGOO{(\FU*{TYPE-ERROR-DATUM} \VAR{ condition})\\
      (\FU*{TYPE-ERROR-EXPECTED-TYPE} \VAR{ condition})}{.}}
  {
  \retval{Object} which caused \VAR{condition} of type \kwd{type-error}, or its
  \retval{expected type}, respectively.
  }

  \IT{\arrGOO{(\FU*{SIMPLE-CONDITION-FORMAT-CONTROL} \VAR{ condition})\\
      (\FU*{SIMPLE-CONDITION-FORMAT-ARGUMENTS} \VAR{ condition})}{.}}
  {
  Return \retval{\FU{format} control} or list of \retval{\FU{format}
    arguments}, respectively, of \VAR{condition}.
  }

  \IT{\V{\A break-on-signals\A}\DF{\NIL}}
  {\index{*BREAK-ON-SIGNALS*@\A BREAK-ON-SIGNALS\A}
  Condition type debugger is to be invoked on.
  }

  \IT{\V{\A debugger-hook\A}\DF{\NIL}}
  {\index{*DEBUGGER-HOOK*@\A DEBUGGER-HOOK\A}
    Function of condition and
  function itself. Called before debugger.
  }

\end{LIST}


%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "clqr"
%%% End: