continued work

[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{(\GFU*{MAKE-INSTANCE} \VAR{class} \Goos{\kwd{:}\VAR{initarg}
      \VAR{value}} \OPn{\VAR{other-keyarg}})}
  {
  Make new \retval{instance of \VAR{class}}.
  }

  \IT{(\GFU*{INITIALIZE-INSTANCE} (\VAR{instance}))}
  {
  Its primary method sets slots on behalf of
  \GFU*{MAKE-INSTANCE}. Return \retval{instance}.
  }

  \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{(\SF*{WITH-SLOTS} (\Goos{\VAR{slot}\XOR(\VAR{var
        slot})}) \VAR{instance} \OPn{(\kwd{declare} \OPn{\VAR{decl}})}
    \OPn{\VAR{form}})}
  {
  Evaluate \VAR{form}s with slots of \VAR{instance} locally visible as
  \VAR{slot}s or \VAR{var}s. 
  }

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

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

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

  \IT{(\SF*{DEFCLASS} \VAR{class-name} (\OPn{\VAR{superclass}})
    (\GOOs{\VAR{slot}\XOR
      (\VAR{slot} 
      \orGOO{\Goos{\kwd{:reader} \VAR{reader-fu}}\\
        \Goos{\kwd{:writer} \VAR{writer-fu}} \\
        \Goos{\kwd{:accessor} \VAR{reader-fu}} \\
        \kwd{:allocation } \Goo{\kwd{:instance}\XOR\kwd{:class}}\\
        \Goos{\kwd{:initarg} \kwd{:}\VAR{arg}} \\
        \kwd{:initform} \VAR{ form}\\
        \kwd{:type} \VAR{ type}\\
        \kwd{:documentation} \VAR{ string}}{\}})})
    \orGOO{(\kwd{:default-initargs} \Goos{\VAR{name}\VAR{ value}})\\
      (\kwd{:documentation} \VAR{ string})\\
      (\kwd{:metaclass} \VAR{ name})}{\}})} 
  {
  Define \retval{class \VAR{ class-name}} as a subclass of \VAR{superclass}es.
  }

  \IT{(\GFU*{CHANGE-CLASS} \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*{UPDATE-INSTANCE-FOR-DIFFERENT-CLASS} \VAR{previous}
    \VAR{current} \Goos{\kwd{:}\VAR{initarg}
      \VAR{value}} \OPn{\VAR{other-keyarg}})}
  {
  Called by \kwd{change-class}.
  }

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

  \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}})}
  {
  Called by \kwd{make-instances-obsolete}.
  }

  \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{init-args} and
  \kwd{:initform} forms.
  }

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

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

\end{LIST}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Generic Functions} 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

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

  \IT{(\SF*{DEFGENERIC}
    \xorGOO{\VAR{name}\\ (\kwd{setf} \VAR{ name})}{\}} 
    (\OPn{\VAR{var}}%
    \OP{\kwd*{\&optional} \Goos{\VAR{var}\XOR(\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-precendence-order}\RP{\VAR{ var}})\\
    (\kwd{declare }\RP{(\kwd{optimize}\OPn{\VAR{ arg}})})\\
    (\kwd{:documentation} \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} \OPn{\VAR{ arg}})\\
    \OPn{(\kwd{:method} \VAR{ defmethod-arguments})}}{\}})}
  {
  Define \retval{generic function \VAR{name}}. For \VAR{c-type} see
  s.\ \ref{section:Method Combination Types}.
  }

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

  \IT{(\SF*{DEFMETHOD} 
    \xorGOO{\VAR{bar}\\ (\kwd{setf} \VAR{ bar})}{\}} 
    \Op{\xorGOO{\kwd{:before}\\
        \kwd{:after}\\
        \kwd{:around}}{\}}}
    (\xorGOO{\VAR{var}\\
      (\VAR{spec-var } \xorGOO{\VAR{class}\\(\kwd{eql} \VAR{ foo})}{\}})}{\}^{\!\!*}}
    \OP{\kwd*{\&optional} \Goos{\VAR{var}\XOR(\VAR{var} \OP{\VAR{init}
      \Op{\VAR{supplied-p}}})}}
    \Op{\kwd*{\&rest} \VAR{var}}
    \OP{\kwd*{\&key} \GOos{\VAR{var}\XOR(\Goo{\VAR{var}\XOR(\kwd{:}\VAR{key}
          \VAR{var})}
        \OP{\VAR{init }\Op{\VAR{supplied-p}}})}
      \Op{\kwd*{\&allow-other-keys}}}
    \OP{\kwd*{\&aux }\Goos{\VAR{var}\XOR(\VAR{var} \Op{\VAR{init}})}})
    \orGOO{\OPn{(\kwd{declare} \OPn{\VAR{ decl}})}\\
      \VAR{documentation}}{\}}
    \OPn{\VAR{form}})}
  {
  Define \retval{new method} for generic function
  \VAR{bar}. \VAR{spec-var}s specialize to either being of \VAR{class}
  or being \kwd{eql} \VAR{foo}, respectively. On invocation, \VAR{var}s and
  \VAR{spec-var}s of the \retval{new method}
  act like parameters of a function with body \VAR{foo}.
  }

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

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

  \IT{(\SF*{CALL-METHOD} \orGOO{\VAR{method}\\
      (\SF*{MAKE-METHOD} \VAR{ form})}{\}}
    \Op{\VAR{next-methods}})}
  {
  Call \VAR{method}, return \retval{its values}.
  }

  \IT{(\GFU*{NO-APPLICABLE-METHOD} \VAR{generic-function}
    \OPn{\VAR{arg}})}
  {
  Called on invocation of \VAR{generic-function} 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} of other keys are alowed.
  }

  \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*{METHOD-QUALIFIERS} \VAR{method})}
  {
  List of qualifiers of \VAR{method}.
  }

  \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.
  }


\end{LIST}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Method Combination Types} 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{section:Method Combination Types}
\begin{LIST}{1cm}

  \IT{\arrGOO{\kwd*{AND}\\
      \kwd*{OR}\\
      \kwd*{APPEND}\\
      \kwd*{LIST}\\
      \kwd*{NCONC}\\
      \kwd*{PROGN}\\
      \kwd*{MAX}\\
      \kwd*{MIN}\\
      \kwd*{+}}{.}}
  {
  Built-in method combination types.
  }

  \IT{\kwd*{STANDARD}}
  {
  Standard method combination type, also used if no method combination
  type is given. 
  }

  \IT{(\SF*{DEFINE-METHOD-COMBINATION} \VAR{c-type} \orGOO{%
    \kwd{:documentation} \VAR{ string}\\
    \kwd{:identity-with-one-argument} \VAR{ bool}\DF{\NIL}\\
    \kwd{:operator} \VAR{ operator}\DF{\VAR{c-type}}}{\}})}
  {
  Short form. Define new method combination type
  \retval{\VAR{c-type}}. A call to a generic function using
  \VAR{c-type} will be equivalent to (\VAR{c-type}
  \OPn{\VAR{applicable-method}}). 
  }

  \IT{(\SF*{DEFINE-METHOD-COMBINATION} \VAR{c-type}
    (\OPn{\VAR{fu-arg}}) 
    (\GOOs{\VAR{name} \xorGOO{%
      \GOOp{\VAR{list}\XOR\kwd{*}}\\
      \VAR{predicate}}{\}} \orGOO{%
    \kwd{:description} \VAR{ control}\\
    \kwd{:order }
    \Goo{\kwd{:most-specific-first}\XOR\kwd{:most-specific-last}}\\ 
    \kwd{:required} \VAR{ bool}}{\}}})
    \Op{\kwd{:arguments} (\OPn{\VAR{method-combination-arg}})}
    \Op{\kwd{:generic-function} \VAR{ symbol}}
    \orGOO{\OPn{(\kwd{declare} \OPn{\VAR{ decl}})}\\
      \VAR{documentation}}{\}}
    \OPn{\VAR{body}})}
  {
  Long form. A call to a generic function using \VAR{c-type} will
  equivalent to a call to the forms returned by \VAR{body}.  Lambda
  lists (\OPn{\VAR{fu-arg}}) and (\OPn{\VAR{method-combination-arg}})
  according to \VAR{fu-arg} on p.\ \pageref{section:Functions}, the
  latter enhanced by an optional \kwd{\&whole} argument. 
  }

\end{LIST}