clqr-clos.tex

   1 % Copyright (C) 2008 Bert Burgemeister
   2 %
   3 % Permission is granted to copy, distribute and/or modify this
   4 % document under the terms of the GNU Free Documentation License,
   5 % Version 1.2 or any later version published by the Free Software
   6 % Foundation; with no Invariant Sections, no Front-Cover Texts and
   7 % no Back-Cover Texts. For details see file COPYING.
   8 %
   9
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11 \section{CLOS}
  12 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  13
  14 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  15 \subsection{Classes}
  16 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  17
  18 \begin{LIST}{1cm}
  19
  20   \IT{(\GFU*{MAKE-INSTANCE} \VAR{class} \Goos{\kwd{:}\VAR{initarg}
  21       \VAR{value}} \OPn{\kwd{:}\VAR{other-key}})}
  22   Make new \retval{instance of \VAR{class}}.
  23
  24   \IT{(\GFU*{INITIALIZE-INSTANCE} (\VAR{instance}))}
  25   Its primary method sets slots on behalf of
  26   \GFU*{MAKE-INSTANCE}. Return \retval{instance}.
  27
  28   \IT{(\GFU*{REINITIALIZE-INSTANCE} \VAR{instance} \OP{\VAR{initargs}
  29       \Op{\VAR{other-args}}})}
  30   Change local slots of \retval{\VAR{instance}}.
  31
  32   \IT{(\FU*{SLOT-VALUE} \VAR{instance} \VAR{slot})} Return \retval{value
  33     of \VAR{slot} in \VAR{instance}}.  \kwd{SETF}able.
  34
  35   \IT{(\SF*{WITH-SLOTS}(\Goos{\VAR{slot}\XOR(\VAR{var
  36         slot})}) \VAR{instance} \OPn{(\kwd{declare} \OPn{\VAR{decl}})}
  37     \OPn{\VAR{form}})}
  38   Evaluate \VAR{form}s with slots of \VAR{instance} locally visible as
  39   \VAR{slot}s or \VAR{var}s.
  40
  41   \IT{(\GFU*{CLASS-NAME} \VAR{class})}
  42   \retval{Name of \VAR{class}}.
  43
  44   \IT{(\kwd*{CLASS-OF} \VAR{foo})}
  45   \retval{Class} \VAR{foo} is an instance of.
  46
  47   \IT{(\kwd*{MAKE-INSTANCES-OBSOLETE} \VAR{class})}
  48   Update instances of \VAR{class}.
  49
  50   \IT{(\SF*{DEFCLASS} \VAR{class-name} (\OPn{\VAR{superclass}})
  51     (\GOOs{\VAR{slot}\XOR
  52       (\VAR{slot}
  53       \orGOO{\Goos{\kwd{:reader} \VAR{reader-fu}}\\
  54         \Goos{\kwd{:writer} \VAR{writer-fu}} \\
  55         \Goos{\kwd{:accessor} \VAR{reader-fu}} \\
  56         \kwd{:allocation} \Goo{\kwd{:instance}\XOR\kwd{:class}}\\
  57         \Goos{\kwd{:initarg} \kwd{:}\VAR{arg}} \\
  58         \kwd{:initform} \VAR{ form}\\
  59         \kwd{:type} \VAR{ type}\\
  60         \kwd{:documentation} \VAR{ string}}{\}})})
  61
  62     \orGOO{(\kwd{:default-initargs} \Goos{\VAR{name}\VAR{ value}})\\
  63       (\kwd{:documentation} \VAR{ string})\\
  64       (\kwd{:metaclass} \VAR{ name})}{\}})}
  65   Define \retval{class \VAR{ class-name}} as a subclass of \VAR{superclass}es.
  66
  67   \IT{(\GFU*{CHANGE-CLASS} \VAR{instance} \VAR{new-class} \Op{\VAR{arg}})}
  68   Change class of \retval{\VAR{instance}} to \VAR{new-class}.
  69
  70   \IT{(\GFU*{UPDATE-INSTANCE-FOR-DIFFERENT-CLASS} \VAR{previous}
  71     \VAR{current} \Op{\VAR{initargs}} \Op{\VAR{keyargs}})}
  72   Called by \kwd{change-class}.
  73
  74   \IT{(\GFU*{UPDATE-INSTANCE-FOR-REDEFINED-CLASS} \VAR{instances}
  75     \VAR{added-slots} \VAR{discarded-slots} \VAR{property-list
  76       \Op{\VAR{initargs}} \Op{\VAR{other-args}}})}
  77   Called by \kwd{make-instances-obsolete}.
  78
  79   \IT{(\GFU*{SHARED-INITIALIZE} \VAR{instance} \VAR{slots}
  80     \Op{\VAR{init-args}} \Op{\VAR{other-keyargs}})}
  81   Used to fill \VAR{instance}'s \VAR{slots} using \VAR{init-args} and
  82   \kwd{:initform} forms.
  83
  84 \end{LIST}
  85
  86
  87 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  88 \subsection{Generic Functions}
  89 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  90
  91 \begin{LIST}{1cm}
  92   \IT{(\FU*{NEXT-METHOD-P})}
  93   \retval{\T} if enclosing method has a next method.
  94
  95   \IT{(\SF*{DEFGENERIC}
  96     \xorGOO{\VAR{name}\\ (\kwd{setf} \VAR{ name})}{\}}
  97     (\OPn{\VAR{var}}%
  98     \OP{\kwd*{\&optional} \Goos{\VAR{var}\XOR(\VAR{var})}}
  99     \OP{\kwd*{\&rest} \VAR{var}}
 100     \OP{\kwd*{\&key} \orGOO{%
 101       \VAR{var}\\
 102       (\VAR{var}\XOR(\kwd{:}\VAR{key}
 103           \VAR{var}))}{\}^{\!\!*}} \Op{\kwd*{\&allow-other-keys}}})
 104      \orGOO{%
 105     (\kwd{:argument-precendence-order}\RP{\VAR{ arg}})\\
 106     (\kwd{declare }\RP{(\kwd{optimize}\OPn{\VAR{ arg}})})\\
 107     (\kwd{:documentation} \VAR{ string})\\
 108     (\kwd{:generic-function-class} \VAR{ class})\\
 109     (\kwd{:method-class} \VAR{ class})\\
 110     (\kwd{:method-combination} \VAR{ c-type} \OPn{\VAR{ arg}})\\
 111     \OPn{(\kwd{:method} \VAR{ defmethod-symbol} \OPn{\VAR{ defmethod-arg}})}}{\}})}
 112   Define \retval{generic function \VAR{name}}. For \VAR{c-type} see
 113   s.\ \ref{section:Method Combination Types}.
 114
 115   \IT{(\FU*{ENSURE-GENERIC-FUNCTION}
 116     \xorGOO{\VAR{name}\\ (\kwd{setf} \VAR{ name})}{\}}
 117     \orGOO{%
 118       \kwd{:argument-precendence-order}\RP{\VAR{ arg}}\\
 119       \kwd{:declare}\RP{(\kwd{optimize}\OPn{\VAR{ arg}})}\\
 120     \kwd{:documentation} \VAR{ string}\\
 121     \kwd{:environment} \VAR{ environment}\\
 122     \kwd{:generic-function-class} \VAR{ class}\\
 123     \kwd{:lambda-list} \VAR{ lambda-list}\\
 124     \kwd{:method-class} \VAR{ class}\\
 125     \kwd{:method-combination} \VAR{ c-type} \OPn{\VAR{ arg}}}{\}})}
 126   Define or modify \retval{generic function \VAR{name}}. For \VAR{c-type} see
 127   s.\ \ref{section:Method Combination Types}.
 128
 129   \IT{(\SF*{DEFMETHOD}
 130     \xorGOO{\VAR{bar}\\ (\kwd{setf} \VAR{ bar})}{\}}
 131     \Op{\xorGOO{\kwd{:before}\\
 132         \kwd{:after}\\
 133         \kwd{:around}}{\}}}
 134     (\xorGOO{\VAR{var}\\
 135       (\VAR{spec-var} \xorGOO{\VAR{class}\\(\kwd{eql} \VAR{ foo})}{\}})}{\}^{\!\!*}}
 136     \OP{\kwd*{\&optional} \Goos{\VAR{var}\XOR(\VAR{var} \OP{\VAR{init}
 137       \Op{\VAR{supplied-p}}})}}
 138     \Op{\kwd*{\&rest} \VAR{var}}
 139     \OP{\kwd*{\&key} \GOos{\VAR{var}\XOR(\Goo{\VAR{var}\XOR(\kwd{:}\VAR{key}
 140           \VAR{var})}
 141         \OP{\VAR{init}\Op{\VAR{supplied-p}}})}
 142       \Op{\kwd*{\&allow-other-keys}}}
 143     \OP{\kwd*{\&aux}\Goos{\VAR{var}\XOR(\VAR{var} \Op{\VAR{init}})}})
 144     \orGOO{\OPn{(\kwd{declare} \OPn{\VAR{ decl}})}\\
 145       \VAR{documentation}}{\}}
 146     \OPn{\VAR{form}})}
 147   Define \retval{new method} for generic function
 148   \VAR{bar}. \VAR{spec-var}s specialize to either being of \VAR{class}
 149   or being \kwd{eql} \VAR{foo}, resp. On invocation, \VAR{var}s and
 150   \VAR{spec-var}s of the \retval{new method}
 151   act like parameters of a function with body \VAR{foo}.
 152
 153   \IT{(\xorGOO{\GFU*{ADD-METHOD}\\
 154       \GFU*{REMOVE-METHOD}}{\}}\VAR{generic-function} \VAR{method})}
 155   Add, or remove, resp., \VAR{method} from \retval{\VAR{generic-function}}.
 156
 157   \IT{(\FU*{CALL-NEXT-METHOD} \Op{\VAR{args}\DF{current args}})}
 158   From within a method, call next method with \VAR{args}, return
 159   \retval{its values}.
 160
 161   \IT{(\GFU*{NO-APPLICABLE-METHOD} \VAR{generic-function}
 162     \OPn{\VAR{arg}})}
 163   Called on invocation of \VAR{generic-function} if there is no applicable method.
 164
 165   \IT{(\xorGOO{(\FU*{INVALID-METHOD-ERROR} \VAR{ method}\\
 166       \FU*{METHOD-COMBINATION-ERROR})}{\}}%
 167     \VAR{control} \OPn{\VAR{arg}})}
 168   Signal \kwd{error} on applicable method, or on method combination,
 169   with invalid qualifiers. See p.\ \pageref{section:Format}.
 170
 171   \IT{(\SF*{CALL-METHOD} \orGOO{\VAR{method}\\
 172       (\SF*{MAKE-METHOD} \VAR{ form})}{\}}
 173     \Op{\VAR{next-methods}})}
 174   Call \VAR{method}, return \retval{its values}.
 175
 176   \IT{(\GFU*{NO-NEXT-METHOD} \VAR{generic-function}
 177     \VAR{method} \OPn{\VAR{arg}})}
 178   Called on invocation of \kwd{call-next-method} if there is no next method.
 179
 180   \IT{(\GFU*{FUNCTION-KEYWORDS} \VAR{method})}
 181   \retval{Keyword parameters} of method.
 182
 183   \IT{(\GFU*{ALLOCATE-INSTANCE} \VAR{class} \OP{\VAR{initargs}
 184       \Op{\VAR{other-args}}})}
 185   Return uninitialized \retval{instance} of \VAR{class}.
 186
 187   \IT{(\GFU*{METHOD-QUALIFIERS} \VAR{method})}
 188   List of qualifiers of \VAR{method}.
 189
 190   \IT{(\GFU*{FIND-METHOD} \VAR{generic-function} \VAR{qualifiers}
 191     \VAR{specializers} \Op{\VAR{error}\DF{\T}})}
 192   Return suitable \retval{method}, or \retval{\NIL}.
 193
 194   \IT{(\GFU*{COMPUTE-APPLICABLE-METHODS} \VAR{generic-function}
 195     \VAR{args})}
 196   \retval{Set of methods} suitable for \VAR{args}.
 197
 198
 199 \end{LIST}
 200
 201 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 202 \subsection{Method Combination Types}
 203 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 204 \label{section:Method Combination Types}
 205 \begin{LIST}{1cm}
 206
 207   \IT{arrGOO{\kwd*{AND}\\
 208       \kwd*{OR}\\
 209       \kwd*{APPEND}\\
 210       \kwd*{LIST}\\
 211       \kwd*{NCONC}\\
 212       \kwd*{PROGN}\\
 213       \kwd*{MAX}\\
 214       \kwd*{MIN}\\
 215       \kwd*{+}}{\}}}
 216   Built-in method combination types.
 217
 218   \IT{\kwd*{STANDARD}}
 219   Standard method combination type, also used if no method combination
 220   type is given.
 221
 222   \IT{(\SF*{DEFINE-METHOD-COMBINATION} \VAR{c-type}\orGOO{%
 223     \kwd{:documentation} \VAR{ string}\\
 224     \kwd{:identity-with-one-argument} \VAR{ bool}\DF{\NIL}\\
 225     \kwd{:operator} \VAR{ operator}\DF{\VAR{name}}}{\}})}
 226   (Short form.) Define new method combination type
 227   \retval{\VAR{c-type}}. A call to a generic function using
 228   \VAR{c-type} is equivalent to (\VAR{c-type}
 229   \OPn{\VAR{applicable-method}}).
 230
 231   \IT{(\SF*{DEFINE-METHOD-COMBINATION} \VAR{c-type}
 232     (\OPn{\VAR{fu-arg}})
 233     (\GOOs{\VAR{name} \xorGOO{%
 234       \GOOp{\VAR{list}\XOR\kwd{*}}\\
 235       \VAR{predicate}}{\}} \orGOO{%
 236     \kwd{:description} \VAR{ control}\\
 237     \kwd{:order}
 238     \Goo{\kwd{:most-specific-first}\XOR\kwd{:most-specific-last}}\\
 239     \kwd{:required} \VAR{ bool}}{\}}})
 240     \Op{\kwd{:arguments} (\OPn{\VAR{method-combination-arg}})}
 241     \Op{\kwd{:generic-function} \VAR{ symbol}}
 242     \orGOO{\OPn{(\kwd{declare} \OPn{\VAR{ decl}})}\\
 243       \VAR{documentation}}{\}}%
 244     \OPn{\VAR{body}})}
 245   (Long form.) A call to a generic function using \VAR{c-type} is
 246   equivalent to a call to the forms returned by \VAR{body}.  Lambda
 247   list \OPn{\VAR{fu-arg}} and \OPn{\VAR{method-combination-arg}}
 248   according to \VAR{fu-arg} on p.\ \pageref{section:Functions}, the
 249   latter enhanced by an optional \kwd{\&whole} argument.
 250
 251 \end{LIST}
 252
 253