restart-case more elaborate

[clqr.git] / clqr-clos.tex

% Copyright (C) 2008 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{CLOS} 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Classes} 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{LIST}{1cm}

  \IT{(\FU*{SLOT-BOUNDP} \VAR{instance} \VAR{slot})}
  {
  \retval{\T} if \VAR{slot} in \VAR{instance} is bound.
  }

  \IT{(\MC*{DEFCLASS} \VAR{foo} (\OPn{\VAR{superclass}}\DF{\kwd{standard-object}})
    (\OPn{\xorGOO{\VAR{slot}\\
      (\VAR{slot} 
      \orGOO{\Goos{\kwd{:reader} \VAR{reader-function}}\\
        \Goos{\kwd{:writer} \VAR{writer-function}} \\
        \Goos{\kwd{:accessor} \VAR{reader-function}} \\
        \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{ class-doc})\\
      (\kwd{:metaclass} \VAR{ name}\DF{\kwd{standard-class}})}{\}})}
  {
  Define, as a subclass of \VAR{superclass}es, \retval{class}
  \VAR{foo}. In new instances, a \VAR{slot}'s value defaults to 
  \VAR{form} unless set via \kwd{:}\VAR{initarg-name} and is accessible
  by \VAR{reader-function} and \VAR{writer-function}. With
  \kwd{:allocation :class}, \VAR{slot} is shared by all instances of
  class \VAR{foo}.
  }

  \IT{(\FU*{FIND-CLASS} \VAR{symbol} \OP{\VAR{errorp}\DF{\T}
      \Op{\VAR{environment}}})}
  {
  Return \retval{class} named \VAR{symbol}. \kwd{setf}able.
  }

  \IT{(\GFU*{MAKE-INSTANCE} \VAR{class} \Goos{\kwd{:}\VAR{initarg}
      \VAR{value}} \OPn{\VAR{other-keyarg}})}
  {
  Make new \retval{instance of \VAR{class}}.
  }

  \IT{(\GFU*{REINITIALIZE-INSTANCE} \VAR{instance} \Goos{\kwd{:}\VAR{initarg}
      \VAR{value}} \OPn{\VAR{other-keyarg}})}
  {
  Change local slots of \retval{\VAR{instance}} according to \VAR{initarg}s.
  }

  \IT{(\FU*{SLOT-VALUE} \VAR{instance} \VAR{slot})}
  {Return \retval{value
    of \VAR{slot} in \VAR{instance}}.  \kwd{SETF}able.
  }

  \IT{(\FU*{SLOT-MAKUNBOUND} \VAR{instance} \VAR{slot})}
  {
  Make \VAR{slot} in \retval{\VAR{instance}} unbound.
  }

  \IT{(\xorGOO{%
      \MC*{WITH-SLOTS } (\Goos{\NEV{\VAR{slot}}\XOR(\NEV{\VAR{var}} \NEV{\VAR{slot}})})\\
      \MC*{WITH-ACCESSORS } (\OPn{(\NEV{\VAR{var}}\text{ } \NEV{\VAR{accessor}})})}{\}}
    \VAR{instance}  \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})}
    \PROGN{\VAR{form}})}
  {
  Return \retval{values of \VAR{form}s} after evaluating them in a
  lexical environment with slots of \VAR{instance} visible as
  \kwd{setf}able \VAR{slot}s or \VAR{var}s/with \VAR{accessor}s of
  \VAR{instance} visible as \kwd{setf}able \VAR{var}s. 
  }

  \IT{(\GFU*{CLASS-NAME} \VAR{class})}
  {
  \retval{Name of \VAR{class}}. \kwd{setf}able.
  }

  \IT{(\FU*{CLASS-OF} \VAR{foo})}
  {
  \retval{Class} \VAR{foo} is an instance of.
  }

  \IT{(\GFU*{CHANGE-CLASS} \DES{\VAR{instance}} \VAR{new-class}
    \Goos{\kwd{:}\VAR{initarg} \VAR{value}} \OPn{\VAR{other-keyarg}})} 
  {
  Change class of \retval{\VAR{instance}} to \VAR{new-class}.
  }

  \IT{(\GFU*{MAKE-INSTANCES-OBSOLETE} \VAR{class})}
  {
  Update instances of \VAR{class}.
  }

  \IT{(\xorGOO{\GFU*{INITIALIZE-INSTANCE } (\VAR{instance})\\
      \GFU*{UPDATE-INSTANCE-FOR-DIFFERENT-CLASS} \VAR{
        previous }\VAR{current}}{\}}
      \Goos{\kwd{:}\VAR{initarg}
      \VAR{value}} \OPn{\VAR{other-keyarg}})}
  {
  Its primary method sets slots on behalf of \GFU{make-instance}/of
  \GFU{change-class} by means of \GFU{shared-initialize}. 
  }

  \IT{(\GFU*{UPDATE-INSTANCE-FOR-REDEFINED-CLASS} \VAR{instances}
    \VAR{added-slots} \VAR{discarded-slots} \VAR{property-list}
     \Goos{\kwd{:}\VAR{initarg}
      \VAR{value}} \OPn{\VAR{other-keyarg}})}
  {
  Its primary method sets slots on behalf of
  \GFU{make-instances-obsolete} by means of \GFU{shared-initialize}. 
  }

  \IT{(\GFU*{ALLOCATE-INSTANCE} \VAR{class} \Goos{\kwd{:}\VAR{initarg}
      \VAR{value}} \OPn{\VAR{other-keyarg}})}
  {
  Return uninitialized \retval{instance} of \VAR{class}.
  }

  \IT{(\GFU*{SHARED-INITIALIZE} \VAR{instance} \VAR{slots}
     \Goos{\kwd{:}\VAR{initarg}
      \VAR{value}} \OPn{\VAR{other-keyarg}})}
  {
  Fill \VAR{instance}'s \VAR{slots} using \VAR{initarg}s and
  \kwd{:initform} forms.
  }

  \IT{(\GFU*{SLOT-MISSING} \VAR{class} \VAR{object} \VAR{slot}
    \xorGOO{\kwd{setf}\\
      \kwd{slot-boundp}\\
      \kwd{slot-makunbound}\\
      \kwd{slot-value}}{\}}
    \Op{\VAR{value}})}
  {
  Called in case of attempted access to missing \VAR{slot}. Its primary
  method signals \kwd{error}.
  }

  \IT{(\GFU*{SLOT-UNBOUND} \VAR{class} \VAR{instance} \VAR{slot})}
  {
  Called by \FU{slot-value} in case of unbound \VAR{slot}. Its primary
  method signals \kwd{unbound-slot}.
  }

\end{LIST}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection[Generic~Functns]{Generic Functions} 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{LIST}{1cm}
  \IT{(\FU*{NEXT-METHOD-P})}
  {
  \retval{\T} if enclosing method has a next method.
  }

  \IT{(\MC*{DEFGENERIC}
    \xorGOO{\VAR{foo}\\ (\kwd{setf} \VAR{ foo})}{\}} 
    (\OPn{\VAR{required-var}}
    \OP{\kwd*{\&optional} \xorGOO{\VAR{var}\\
        (\VAR{var})}{\}^{\!\!*}}}
    \OP{\kwd*{\&rest} \VAR{var}}
    \OP{\kwd*{\&key} \orGOO{%
      \VAR{var}\\
      (\VAR{var}\XOR(\kwd{:}\VAR{key }
          \VAR{var}))}{\}^{\!\!*}} \Op{\kwd*{\&allow-other-keys}}})
     \orGOO{%
    (\kwd{:argument-precedence-order}\RP{\VAR{ required-var}})\\
    (\kwd{declare }\RP{(\kwd{optimize}\OPn{\VAR{ arg}})})\\
    (\kwd{:documentation } \NEV{\VAR{string}})\\
    (\kwd{:generic-function-class} \VAR{ class}\DF{\kwd{standard-generic-function}})\\
    (\kwd{:method-class} \VAR{ class}\DF{\kwd{standard-method}})\\
    (\kwd{:method-combination} \VAR{ c-type}\DF{\kwd{standard}} \OPn{\VAR{ c-arg}})\\
    \OPn{(\kwd{:method} \VAR{ defmethod-args})}}{\}})}
  {
  Define \retval{generic function} \VAR{foo}. \VAR{defmethod-args} resemble those of
  \MC{defmethod}. For \VAR{c-type} see section \ref{section:Method
    Combination Types}. 
  }

  \IT{(\FU*{ENSURE-GENERIC-FUNCTION}
    \xorGOO{\VAR{foo}\\ (\kwd{setf} \VAR{ foo})}{\}}
    \orGOO{%
      \kwd{:argument-precedence-order}\RP{\VAR{ required-var}}\\
      \kwd{:declare }\RP{(\kwd{optimize}\OPn{\VAR{ arg}})}\\
      \kwd{:documentation} \VAR{ string}\\
      \kwd{:generic-function-class} \VAR{ class}\\
      \kwd{:method-class} \VAR{ class}\\
      \kwd{:method-combination} \VAR{ c-type} \OPn{\VAR{ c-arg}}\\
      \kwd{:lambda-list} \VAR{ lambda-list}\\
      \kwd{:environment} \VAR{ environment}}{\}})}
  {
  Define or modify \retval{generic function} \VAR{foo}. For \VAR{c-type} see
  section \ref{section:Method Combination Types}.
  }

  \IT{(\MC*{DEFMETHOD} 
    \xorGOO{\VAR{foo}\\ 
      (\kwd{setf} \VAR{ foo})}{\}} 
    \Op{\xorGOO{\kwd{:before}\\
        \kwd{:after}\\
        \kwd{:around}\\
        \OPn{\VAR{qualifier}}}{\}}\DF{primary method}}
    (\xorGOO{\VAR{var}\\
      (\VAR{spec-var } \xorGOO{\VAR{class}\\
        (\kwd{eql} \VAR{ bar})}{\}})}{\}^{\!\!*}}
    \OP{\kwd*{\&optional} \xorGOO{\VAR{var}\\
        (\VAR{var } \OP{\VAR{init }
          \Op{\VAR{supplied-p}}})}{\}^{\!\!*}}}
    \Op{\kwd*{\&rest} \VAR{var}}
    \OP{\kwd*{\&key} \xorGOO{\VAR{var}\\
        (\xorGOO{\VAR{var}\\
          (\kwd{:}\VAR{key }
          \VAR{var})}{\}}
        \OP{\VAR{init }\Op{\VAR{supplied-p}}})}{\}^{\!\!*}}
      \Op{\kwd*{\&allow-other-keys}}}
    \OP{\kwd*{\&aux }\xorGOO{\VAR{var}\\
        (\VAR{var } \Op{\VAR{init}})}{\}^{\!\!*}}})
    \orGOO{\OPn{(\kwd{declare } \OPn{\NEV{\VAR{decl}}})}\\
      \NEV{\VAR{doc}}}{\}}
    \OPn{\VAR{form}})}
  {
  Define \retval{new method} for generic function
  \VAR{foo}. \VAR{spec-var}s specialize to either being of \VAR{class}
  or being \kwd{eql} \VAR{bar}, respectively. On invocation, \VAR{var}s and
  \VAR{spec-var}s of the \retval{new method}
  act like parameters of a function with body
  \OPn{\VAR{form}}. Applicable \VAR{qualifier}s depend on the
  \kwd{method-combination} type; see
  section \ref{section:Method Combination Types}.
  }

  \IT{(\xorGOO{\GFU*{ADD-METHOD}\\
      \GFU*{REMOVE-METHOD}}{\}} \VAR{generic-function} \VAR{method})}
  {
  Add, or remove, respectively, \VAR{method} to/from \retval{\VAR{generic-function}}.
  }

  \IT{(\GFU*{FIND-METHOD} \VAR{generic-function} \VAR{qualifiers}
    \VAR{specializers} \Op{\VAR{error}\DF{\T}})}
  {
  Return suitable \retval{method}, or signal \kwd{error}.
  }

  \IT{(\GFU*{COMPUTE-APPLICABLE-METHODS} \VAR{generic-function}
    \VAR{args})}
  {
  \retval{List of methods} suitable for \VAR{args}, most specific first.
  }

  \IT{(\FU*{CALL-NEXT-METHOD} \OPn{\VAR{arg}}\DF{current args})}
  {
  From within a method, call next method with \VAR{arg}s; return
  \retval{its values}.
  }

  \IT{(\GFU*{NO-APPLICABLE-METHOD} \VAR{generic-function}
    \OPn{\VAR{arg}})}
  {
  Called on invocation of \VAR{generic-function} on \VAR{arg}s if
  there is no applicable method. 
  }

  \IT{(\xorGOO{\FU*{INVALID-METHOD-ERROR} \VAR{ method}\\
      \FU*{METHOD-COMBINATION-ERROR}}{\}}
    \VAR{control} \OPn{\VAR{arg}})}
  {
  Signal \kwd{error} on applicable method, or on method combination,
  with invalid qualifiers. For \VAR{control} and \VAR{arg}s see
  \kwd{format}, p.\ \pageref{section:Format}.  
  }

  \IT{(\GFU*{NO-NEXT-METHOD} \VAR{generic-function}
    \VAR{method} \OPn{\VAR{arg}})}
  {
  Called on invocation of \kwd{call-next-method} if there is no next method.
  }

  \IT{(\GFU*{FUNCTION-KEYWORDS} \VAR{method})}
  {
  Return list of \retval{keyword parameters} of \VAR{method} and
  \retvalii{\T} if other keys are allowed.
  }

  \IT{(\GFU*{METHOD-QUALIFIERS} \VAR{method})}
  {
  List of qualifiers of \VAR{method}.
  }


\end{LIST}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection[Method Combi- nation Types]{Method Combination Types} 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{section:Method Combination Types}
\begin{LIST}{1cm}

  \IT{\kwd*{STANDARD}}
  {
  Evaluate most specific \kwd{:around} method supplying the values of
  the generic function. From within this method, \FU{call-next-method}
  can call less specific \kwd{:around} methods if there are any. If
  not, or if there are no \kwd{:around} methods at all, call all
  \kwd{:before} methods, most specific first, and the most specific
  primary method which supplies the values of the calling
  \FU{call-next-method} if any, or of the generic function; and which
  can call less specific primary methods via
  \FU{call-next-method}. After its return, call all \kwd{:after}
  methods, least specific first.
  }

  \IT{\kwd*{AND}\XOR
      \kwd*{OR}\XOR
      \kwd*{APPEND}\XOR
      \kwd*{LIST}\XOR      \kwd*{NCONC}\XOR
      \kwd*{PROGN}\XOR
      \kwd*{MAX}\XOR
      \kwd*{MIN}\XOR
      \kwd*{+}}
  {
    Simple built-in \kwd{method-combination} types; have the same
    usage as the
    \VAR{c-type}s defined by the short form of
    \MC{define-method-combination}. 
  }

  \IT{(\MC*{DEFINE-METHOD-COMBINATION} \VAR{c-type} \orGOO{%
    \kwd{:documentation } \NEV{\VAR{string}}\\
    \kwd{:identity-with-one-argument} \VAR{ bool}\DF{\NIL}\\
    \kwd{:operator} \VAR{ operator}\DF{\VAR{c-type}}}{\}})}
  {
  Short form. Define new \kwd{method-combination}
  \retval{\VAR{c-type}}. In a generic function using \VAR{c-type},
  evaluate most specific \kwd{:around} method supplying the values of
  the generic function. From within this method, \FU{call-next-method}
  can call less specific \kwd{:around} methods if there are any. If
  not, or if there are no \kwd{:around} methods at all,
  have generic function applied to \OPn{\VAR{gen-arg}} return with the
  values of (\VAR{c-type} \Goos{\VAR{primary-method}
    \OPn{\VAR{gen-arg}}}), leftmost \VAR{primary-method} being the most
  specific. In \MC{defmethod}, primary methods are denoted by the
  \VAR{qualifier} \VAR{c-type}. 
    }

  \IT{(\MC*{DEFINE-METHOD-COMBINATION} \VAR{c-type}
    (\OPn{\VAR{ord-$\lambda$}}) 
    (\OPn{(\VAR{group} \xorGOO{%
        \kwd{\A}\\
        (\OPn{\VAR{qualifier}}\text{ } \OP{\kwd{\A}})\\
        \VAR{predicate}}{\}} 
      \orGOO{%
        \kwd{:description} \VAR{ control}\\
        \kwd{:order }
        \xorGOO{\kwd{:most-specific-first}\\
          \kwd{:most-specific-last}}{\}}\DF{\kwd{:most-specific-first}}\\ 
        \kwd{:required} \VAR{ bool}}{\}})})
    \orGOO{%
      (\kwd{:arguments } (\OPn{\VAR{method-combination-$\lambda$}}))\\
      (\kwd{:generic-function} \VAR{ symbol})\\
      \OPn{(\kwd{declare } \OPn{\NEV{\VAR{decl}}})}\\
      \NEV{\VAR{doc}}}{\}}
    \PROGN{\VAR{body}})}
  {
  Long form. Define new method combination type
  \retval{\VAR{c-type}}. A call to a generic function using
  \VAR{c-type} will be equivalent to a call to the forms returned by
  \OPn{\VAR{body}} with \OPn{\VAR{ord-$\lambda$}} bound to
  \OPn{\VAR{c-arg}} (cf.\ \MC{DEFGENERIC}), with \VAR{symbol} bound to
  the generic function, with \OPn{\VAR{method-combination-$\lambda$}}
  bound to the arguments of the generic function, and with
  \VAR{group}s bound to lists of methods. An applicable method becomes
  a member of the leftmost \VAR{group} whose \VAR{predicate} or
  \VAR{qualifier}s match. Methods can be called via
  \MC{CALL-METHOD}. Lambda lists (\OPn{\VAR{ord-$\lambda$}}) and
  (\OPn{\VAR{method-combination-$\lambda$}}) according to
  \VAR{ord-$\lambda$} on p.\ \pageref{section:Functions}, the latter
  enhanced by an optional \kwd{\&whole} argument.
  }

  \IT{(\MC*{CALL-METHOD} \orGOO{\NEV{\VAR{method}}\\
      (\MC*{MAKE-METHOD}\text{ } \NEV{\VAR{form}})}{\}}
    \Op{\NEV{\VAR{next-methods}}})}
  {
  From within an effective method form, call \VAR{method} with the
  arguments of the generic function and
  with information about its \VAR{next-methods}; return \retval{its
    values}. 
  }

\end{LIST}