html: minor changes

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

  \IT{(\GFU*{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 \GFU{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{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}}{\}}
    \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 \FU{slot-value} in case of unbound \VAR{slot}. Default 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} \OPn{\VAR{ arg}})\\
    \OPn{(\kwd{:method} \VAR{ defmethod-args})}}{\}})}
  {
  Define \retval{generic function} \VAR{foo} with \VAR{defmethod-args}
  describing some methods. \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{ 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{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} \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{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 \OPn{\VAR{form}}.
  }

  \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{arg}}\DF{current args})}
  {
  From within a method, call next method with \VAR{arg}s; return
  \retval{its values}.
  }

  \IT{(\MC*{CALL-METHOD} \orGOO{\NEV{\VAR{method}}\\
      (\MC*{MAKE-METHOD} \VAR{ form})}{\}}
    \Op{\NEV{\VAR{next-methods}}})}
  {
  From within a method form, call \VAR{method} with arguments and
  with information about its \VAR{next-methods}; 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 allowed.
  }

  \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 Combi- nation Types]{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{(\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 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}} \Op{\kwd{:order}
    \xorGOO{\kwd{:most-specific-first}\\\kwd{:most-specific-last}}{\}}}). 
  }

  \IT{(\MC*{DEFINE-METHOD-COMBINATION} \VAR{c-type}
    (\OPn{\VAR{ord-$\lambda$}}) 
    (\GOOs{\VAR{name} \xorGOO{%
      \GOOp{\VAR{list}\XOR\kwd{*}}\\
      \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 \VAR{body}.  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. 
  }

\end{LIST}