Better reflection of comment style conventions.

[clqr.git] / clqr-clos.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{CLOS} 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

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

\begin{LIST}{1cm}

  \IT{(\FU*{SLOT-EXISTS-P} \VAR{foo} \VAR{bar})}
  {
    \retval{\T} if \VAR{foo} has a slot \VAR{bar}.
  }

  \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}})
    (\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{ class-doc})\\
      (\kwd{:metaclass} \VAR{ name}\DF{\kwd{standard-class}})}{\}})}
  {
    Define, as a subclass of \VAR{superclass}es, \retval{class
      \VAR{foo}}. In a new instance \VAR{i}, 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 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{foo} \VAR{slot})}
  {
    Return \retval{value
      of \VAR{slot} in \VAR{foo}}.  \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{\arrGOO{(\GFU*{CLASS-NAME } \VAR{class})\\
      ((\kwd{setf } \GFU*{CLASS-NAME}) \VAR{ new-name } \VAR{class})}{.}}
  {
    Get/set \retval{name of \VAR{class}}.
  }

  \IT{(\FU*{CLASS-OF} \VAR{foo})}
  {
    \retval{Class} \VAR{foo} is a direct 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}. Called by
    \GFU{make-instance}. 
  }

  \IT{(\GFU*{SHARED-INITIALIZE} \VAR{instance} 
    \xorGOO{\VAR{slots}\\
      \T}{\}}
     \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} \xorGOO{%
      \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}. \kwd{:generic-function-class} and \kwd{:lambda-list} have
    to be compatible with a pre-existing generic function or with
    existing methods, respectively. Changes to \kwd{:method-class} do
    not propagate to existing methods. 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}}}{\}}
    \PROGN{\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}}. \VAR{form}s are enclosed in an implicit \SO{block}
    \VAR{foo}. 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 (if necessary) or remove (if any) \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. Default method signals \kwd{error}.
  }

  \IT{(\xorGOO{\FU*{INVALID-METHOD-ERROR} \VAR{ method}\\
      \FU*{METHOD-COMBINATION-ERROR}}{\}}
    \VAR{control} \OPn{\VAR{arg}})}
  {
    Signal \kwd{error} on applicable method with invalid qualifiers, or
    on method combination. 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} when there is no next
    method. Default method signals \kwd{error}.
  }

  \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})}
  {
    \retval{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}}}{\}})}
  {
    \EM{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,
    return from the calling \kwd{call-next-method} or from the
    generic function, respectively, the
    values of (\VAR{operator} \OPn{(\VAR{primary-method}
      \OPn{\VAR{gen-arg}})}), \OPn{\VAR{gen-arg}} being the arguments of the
    generic function.
    The \VAR{primary-method}s are ordered
    \OP{\xorGOO{%
        \kwd{:most-specific-first}\\
        \kwd{:most-specific-last}%
      }{\}}\DF{\kwd{:most-specific-first}}}
    (specified as \VAR{c-arg} in \MC{defgeneric}).
    Using \VAR{c-type} as the \VAR{qualifier} in \MC{defmethod}
    makes the method primary.
  }

  \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}})}
  {
    \EM{Long Form. } Define new \kwd{method-combination}
    \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} \xorGOO{\NEV{\VAR{method}}\\
      (\MC*{MAKE-METHOD}\text{ } \NEV{\VAR{form}})}{\}}%
    \OP{(\xorGOO{%
      \NEV{\VAR{next-method}}\\
      (\MC*{MAKE-METHOD}\text{ } \NEV{\VAR{form}})}{\}^{\!\!*}})})}
  {
    From within an effective method form, call \VAR{method} with the
    arguments of the generic function and
    with information about its \VAR{next-method}s; return \retval{its
      values}. 
  }

\end{LIST}



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