Change entry on tilde-slash format directive
[clqr.git] / clqr-clos.tex
blob7710c089b583c08ebd26e8beafe01d05d7886621
1 % Copyright (C) 2008, 2009, 2010 Bert Burgemeister
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.
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11 \section{CLOS}
12 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
14 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
15 \subsection{Classes}
16 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
18 \begin{LIST}{1cm}
20 \IT{(\FU*{SLOT-EXISTS-P} \VAR{foo} \VAR{bar})}
22 \retval{\T} if \VAR{foo} has a slot \VAR{bar}.
25 \IT{(\FU*{SLOT-BOUNDP} \VAR{instance} \VAR{slot})}
27 \retval{\T} if \VAR{slot} in \VAR{instance} is bound.
30 \IT{(\MC*{DEFCLASS} \VAR{foo} (\OPn{\VAR{superclass}}\DF{\kwd{standard-object}})
31 (\xorGOO{\VAR{slot}\\
32 (\VAR{slot }
33 \orGOO{\Goos{\kwd{:reader} \VAR{reader}}\\
34 \Goos{\kwd{:writer} \xorGOO{\VAR{writer}\\
35 ({\kwd{setf}\VAR{ writer}})}{\}}} \\
36 \Goos{\kwd{:accessor} \VAR{accessor}} \\
37 \kwd{:allocation } \xorGOO{\kwd{:instance}\\
38 \kwd{:class}}{\}}\DF{\kwd{:instance}}\\
39 \Goos{\kwd{:initarg} \kwd{:}\VAR{initarg-name}} \\
40 \kwd{:initform} \VAR{ form}\\
41 \kwd{:type} \VAR{ type}\\
42 \kwd{:documentation} \VAR{ slot-doc}}{\}})}{\}^{\!\!\!*}})
43 \orGOO{(\kwd{:default-initargs } \Goos{\VAR{name}\VAR{ value}})\\
44 (\kwd{:documentation} \VAR{ class-doc})\\
45 (\kwd{:metaclass} \VAR{ name}\DF{\kwd{standard-class}})}{\}})}
47 Define, as a subclass of \VAR{superclass}es, \retval{class
48 \VAR{foo}}. In a new instance \VAR{i}, a \VAR{slot}'s value defaults to
49 \VAR{form} unless set via \kwd{:}\VAR{initarg-name}; it is readable
50 via (\VAR{reader} \VAR{i}) or (\VAR{accessor} \VAR{i}), and
51 writeable via (\VAR{writer} \VAR{i} \VAR{value}) or (\kwd{setf}
52 (\VAR{accessor} \VAR{i}) \VAR{value}). With
53 \kwd{:allocation :class}, \VAR{slot} is shared by all instances of
54 class \VAR{foo}.
57 \IT{(\FU*{FIND-CLASS} \VAR{symbol} \OP{\VAR{errorp}\DF{\T}
58 \Op{\VAR{environment}}})}
60 Return \retval{class} named \VAR{symbol}. \kwd{setf}able.
63 \IT{(\GFU*{MAKE-INSTANCE} \VAR{class} \Goos{\kwd{:}\VAR{initarg}
64 \VAR{value}} \OPn{\VAR{other-keyarg}})}
66 Make new \retval{instance of \VAR{class}}.
69 \IT{(\GFU*{REINITIALIZE-INSTANCE} \VAR{instance} \Goos{\kwd{:}\VAR{initarg}
70 \VAR{value}} \OPn{\VAR{other-keyarg}})}
72 Change local slots of \retval{\VAR{instance}} according to
73 \VAR{initarg}s.
76 \IT{(\FU*{SLOT-VALUE} \VAR{foo} \VAR{slot})}
78 Return \retval{value
79 of \VAR{slot} in \VAR{foo}}. \kwd{SETF}able.
82 \IT{(\FU*{SLOT-MAKUNBOUND} \VAR{instance} \VAR{slot})}
84 Make \VAR{slot} in \retval{\VAR{instance}} unbound.
87 \IT{(\xorGOO{%
88 \MC*{WITH-SLOTS } (\Goos{\NEV{\VAR{slot}}\XOR(\NEV{\VAR{var}} \NEV{\VAR{slot}})})\\
89 \MC*{WITH-ACCESSORS } (\OPn{(\NEV{\VAR{var}}\text{ } \NEV{\VAR{accessor}})})}{\}}
90 \VAR{instance} \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})}
91 \PROGN{\VAR{form}})}
93 Return \retval{values of \VAR{form}s} after evaluating them in a
94 lexical environment with slots of \VAR{instance} visible as
95 \kwd{setf}able \VAR{slot}s or \VAR{var}s/with \VAR{accessor}s of
96 \VAR{instance} visible as \kwd{setf}able \VAR{var}s.
99 \IT{\arrGOO{(\GFU*{CLASS-NAME } \VAR{class})\\
100 ((\kwd{setf } \GFU*{CLASS-NAME}) \VAR{ new-name } \VAR{class})}{.}}
102 Get/set \retval{name of \VAR{class}}.
105 \IT{(\FU*{CLASS-OF} \VAR{foo})}
107 \retval{Class} \VAR{foo} is a direct instance of.
110 \IT{(\GFU*{CHANGE-CLASS} \DES{\VAR{instance}} \VAR{new-class}
111 \Goos{\kwd{:}\VAR{initarg} \VAR{value}} \OPn{\VAR{other-keyarg}})}
113 Change class of \retval{\VAR{instance}} to \VAR{new-class}.
116 \IT{(\GFU*{MAKE-INSTANCES-OBSOLETE} \VAR{class})}
118 Update instances of \VAR{class}.
121 \IT{(\xorGOO{\GFU*{INITIALIZE-INSTANCE } (\VAR{instance})\\
122 \GFU*{UPDATE-INSTANCE-FOR-DIFFERENT-CLASS} \VAR{
123 previous }\VAR{current}}{\}}
124 \Goos{\kwd{:}\VAR{initarg}
125 \VAR{value}} \OPn{\VAR{other-keyarg}})}
127 Its primary method sets slots on behalf of \GFU{make-instance}/of
128 \GFU{change-class} by means of \GFU{shared-initialize}.
131 \IT{(\GFU*{UPDATE-INSTANCE-FOR-REDEFINED-CLASS} \VAR{instances}
132 \VAR{added-slots} \VAR{discarded-slots} \VAR{property-list}
133 \Goos{\kwd{:}\VAR{initarg}
134 \VAR{value}} \OPn{\VAR{other-keyarg}})}
136 Its primary method sets slots on behalf of
137 \GFU{make-instances-obsolete} by means of \GFU{shared-initialize}.
140 \IT{(\GFU*{ALLOCATE-INSTANCE} \VAR{class} \Goos{\kwd{:}\VAR{initarg}
141 \VAR{value}} \OPn{\VAR{other-keyarg}})}
143 Return uninitialized \retval{instance} of \VAR{class}. Called by
144 \GFU{make-instance}.
147 \IT{(\GFU*{SHARED-INITIALIZE} \VAR{instance}
148 \xorGOO{\VAR{slots}\\
149 \T}{\}}
150 \Goos{\kwd{:}\VAR{initarg}
151 \VAR{value}} \OPn{\VAR{other-keyarg}})}
153 Fill \VAR{instance}'s \VAR{slots} using \VAR{initarg}s and
154 \kwd{:initform} forms.
157 \IT{(\GFU*{SLOT-MISSING} \VAR{class} \VAR{object} \VAR{slot}
158 \xorGOO{\kwd{setf}\\
159 \kwd{slot-boundp}\\
160 \kwd{slot-makunbound}\\
161 \kwd{slot-value}}{\}}
162 \Op{\VAR{value}})}
164 Called in case of attempted access to missing \VAR{slot}. Its primary
165 method signals \kwd{error}.
168 \IT{(\GFU*{SLOT-UNBOUND} \VAR{class} \VAR{instance} \VAR{slot})}
170 Called by \FU{slot-value} in case of unbound \VAR{slot}. Its primary
171 method signals \kwd{unbound-slot}.
174 \end{LIST}
177 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
178 \subsection[Generic~Functns]{Generic Functions}
179 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
181 \begin{LIST}{1cm}
182 \IT{(\FU*{NEXT-METHOD-P})}
184 \retval{\T} if enclosing method has a next method.
187 \IT{(\MC*{DEFGENERIC}
188 \xorGOO{\VAR{foo}\\ (\kwd{setf} \VAR{ foo})}{\}}
189 (\OPn{\VAR{required-var}}
190 \OP{\kwd{\&optional} \xorGOO{\VAR{var}\\
191 (\VAR{var})}{\}^{\!\!*}}}
192 \OP{\kwd{\&rest} \VAR{var}}
193 \OP{\kwd{\&key} \xorGOO{%
194 \VAR{var}\\
195 (\VAR{var}\XOR(\kwd{:}\VAR{key }
196 \VAR{var}))}{\}^{\!\!*}} \Op{\kwd{\&allow-other-keys}}})
197 \orGOO{%
198 (\kwd{:argument-precedence-order}\RP{\VAR{ required-var}})\\
199 (\kwd{declare }\RP{(\kwd{optimize}\OPn{\VAR{ arg}})})\\
200 (\kwd{:documentation } \NEV{\VAR{string}})\\
201 (\kwd{:generic-function-class} \VAR{ class}\DF{\kwd{standard-generic-function}})\\
202 (\kwd{:method-class} \VAR{ class}\DF{\kwd{standard-method}})\\
203 (\kwd{:method-combination} \VAR{ c-type}\DF{\kwd{standard}} \OPn{\VAR{ c-arg}})\\
204 \OPn{(\kwd{:method} \VAR{ defmethod-args})}}{\}})}
206 Define \retval{generic function} \VAR{foo}. \VAR{defmethod-args}
207 resemble those of \MC{defmethod}. For \VAR{c-type} see section
208 \ref{section:Method Combination Types}.
211 \IT{(\FU*{ENSURE-GENERIC-FUNCTION}
212 \xorGOO{\VAR{foo}\\ (\kwd{setf} \VAR{ foo})}{\}}
213 \orGOO{%
214 \kwd{:argument-precedence-order}\RP{\VAR{ required-var}}\\
215 \kwd{:declare }\RP{(\kwd{optimize}\OPn{\VAR{ arg}})}\\
216 \kwd{:documentation} \VAR{ string}\\
217 \kwd{:generic-function-class} \VAR{ class}\\
218 \kwd{:method-class} \VAR{ class}\\
219 \kwd{:method-combination} \VAR{ c-type} \OPn{\VAR{ c-arg}}\\
220 \kwd{:lambda-list} \VAR{ lambda-list}\\
221 \kwd{:environment} \VAR{ environment}}{\}})}
223 Define or modify \retval{generic function}
224 \VAR{foo}. \kwd{:generic-function-class} and \kwd{:lambda-list} have
225 to be compatible with a pre-existing generic function or with
226 existing methods, respectively. Changes to \kwd{:method-class} do
227 not propagate to existing methods. For \VAR{c-type} see section
228 \ref{section:Method Combination Types}.
231 \IT{(\MC*{DEFMETHOD}
232 \xorGOO{\VAR{foo}\\
233 (\kwd{setf} \VAR{ foo})}{\}}
234 \Op{\xorGOO{\kwd{:before}\\
235 \kwd{:after}\\
236 \kwd{:around}\\
237 \OPn{\VAR{qualifier}}}{\}}\DF{primary method}}
238 (\xorGOO{\VAR{var}\\
239 (\VAR{spec-var } \xorGOO{\VAR{class}\\
240 (\kwd{eql} \VAR{ bar})}{\}})}{\}^{\!\!*}}
241 \OP{\kwd{\&optional} \xorGOO{\VAR{var}\\
242 (\VAR{var } \OP{\VAR{init }
243 \Op{\VAR{supplied-p}}})}{\}^{\!\!*}}}
244 \Op{\kwd{\&rest} \VAR{var}}
245 \OP{\kwd{\&key} \xorGOO{\VAR{var}\\
246 (\xorGOO{\VAR{var}\\
247 (\kwd{:}\VAR{key }
248 \VAR{var})}{\}}
249 \OP{\VAR{init }\Op{\VAR{supplied-p}}})}{\}^{\!\!*}}
250 \Op{\kwd{\&allow-other-keys}}}
251 \OP{\kwd{\&aux }\xorGOO{\VAR{var}\\
252 (\VAR{var } \Op{\VAR{init}})}{\}^{\!\!*}}})
253 \orGOO{\OPn{(\kwd{declare } \OPn{\NEV{\VAR{decl}}})}\\
254 \NEV{\VAR{doc}}}{\}}
255 \PROGN{\VAR{form}})}
257 Define \retval{new method} for generic function
258 \VAR{foo}. \VAR{spec-var}s specialize to either being of \VAR{class}
259 or being \kwd{eql} \VAR{bar}, respectively. On invocation, \VAR{var}s and
260 \VAR{spec-var}s of the \retval{new method}
261 act like parameters of a function with body
262 \OPn{\VAR{form}}. \VAR{form}s are enclosed in an implicit \SO{block}
263 \VAR{foo}. Applicable \VAR{qualifier}s depend on the
264 \kwd{method-combination} type; see
265 section \ref{section:Method Combination Types}.
268 \IT{(\xorGOO{\GFU*{ADD-METHOD}\\
269 \GFU*{REMOVE-METHOD}}{\}} \VAR{generic-function} \VAR{method})}
271 Add (if necessary) or remove (if any) \VAR{method} to/from
272 \retval{\VAR{generic-function}}.
275 \IT{(\GFU*{FIND-METHOD} \VAR{generic-function} \VAR{qualifiers}
276 \VAR{specializers} \Op{\VAR{error}\DF{\T}})}
278 Return suitable \retval{method}, or signal \kwd{error}.
281 \IT{(\GFU*{COMPUTE-APPLICABLE-METHODS} \VAR{generic-function}
282 \VAR{args})}
284 \retval{List of methods} suitable for \VAR{args}, most specific first.
287 \IT{(\FU*{CALL-NEXT-METHOD} \OPn{\VAR{arg}}\DF{current args})}
289 From within a method, call next method with \VAR{arg}s; return
290 \retval{its values}.
293 \IT{(\GFU*{NO-APPLICABLE-METHOD} \VAR{generic-function}
294 \OPn{\VAR{arg}})}
296 Called on invocation of \VAR{generic-function} on \VAR{arg}s if
297 there is no applicable method. Default method signals \kwd{error}.
300 \IT{(\xorGOO{\FU*{INVALID-METHOD-ERROR} \VAR{ method}\\
301 \FU*{METHOD-COMBINATION-ERROR}}{\}}
302 \VAR{control} \OPn{\VAR{arg}})}
304 Signal \kwd{error} on applicable method with invalid qualifiers, or
305 on method combination. For \VAR{control} and \VAR{arg}s see
306 \kwd{format}, p.\ \pageref{section:Format}.
309 \IT{(\GFU*{NO-NEXT-METHOD} \VAR{generic-function}
310 \VAR{method} \OPn{\VAR{arg}})}
312 Called on invocation of \kwd{call-next-method} when there is no next
313 method. Default method signals \kwd{error}.
316 \IT{(\GFU*{FUNCTION-KEYWORDS} \VAR{method})}
318 Return list of \retval{keyword parameters} of \VAR{method} and
319 \retvalii{\T} if other keys are allowed.
322 \IT{(\GFU*{METHOD-QUALIFIERS} \VAR{method})}
324 \retval{List of qualifiers} of \VAR{method}.
328 \end{LIST}
330 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
331 \subsection[Method Combi- nation Types]{Method Combination Types}
332 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
333 \label{section:Method Combination Types}
334 \begin{LIST}{1cm}
336 \IT{\kwd*{STANDARD}}
338 Evaluate most specific \kwd{:around} method supplying the values of
339 the generic function. From within this method, \FU{call-next-method}
340 can call less specific \kwd{:around} methods if there are any. If
341 not, or if there are no \kwd{:around} methods at all, call all
342 \kwd{:before} methods, most specific first, and the most specific
343 primary method which supplies the values of the calling
344 \FU{call-next-method} if any, or of the generic function; and which
345 can call less specific primary methods via
346 \FU{call-next-method}. After its return, call all \kwd{:after}
347 methods, least specific first.
350 \IT{\kwd*{AND}\XOR
351 \kwd*{OR}\XOR
352 \kwd*{APPEND}\XOR
353 \kwd*{LIST}\XOR \kwd*{NCONC}\XOR
354 \kwd*{PROGN}\XOR
355 \kwd*{MAX}\XOR
356 \kwd*{MIN}\XOR
357 \kwd*{+}}
359 Simple built-in \kwd{method-combination} types; have the same
360 usage as the
361 \VAR{c-type}s defined by the short form of
362 \MC{define-method-combination}.
365 \IT{(\MC*{DEFINE-METHOD-COMBINATION} \VAR{c-type}
366 \orGOO{%
367 \kwd{:documentation } \NEV{\VAR{string}}\\
368 \kwd{:identity-with-one-argument} \VAR{ bool}\DF{\NIL}\\
369 \kwd{:operator} \VAR{ operator}\DF{\VAR{c-type}}}{\}})}
371 \EM{Short Form. } Define new \kwd{method-combination}
372 \retval{\VAR{c-type}}. In a generic function using \VAR{c-type},
373 evaluate most specific \kwd{:around} method supplying the values of
374 the generic function. From within this method, \FU{call-next-method}
375 can call less specific \kwd{:around} methods if there are any. If
376 not, or if there are no \kwd{:around} methods at all,
377 return from the calling \kwd{call-next-method} or from the
378 generic function, respectively, the
379 values of (\VAR{operator} \OPn{(\VAR{primary-method}
380 \OPn{\VAR{gen-arg}})}), \OPn{\VAR{gen-arg}} being the arguments of the
381 generic function.
382 The \VAR{primary-method}s are ordered
383 \OP{\xorGOO{%
384 \kwd{:most-specific-first}\\
385 \kwd{:most-specific-last}%
386 }{\}}\DF{\kwd{:most-specific-first}}}
387 (specified as \VAR{c-arg} in \MC{defgeneric}).
388 Using \VAR{c-type} as the \VAR{qualifier} in \MC{defmethod}
389 makes the method primary.
392 \IT{(\MC*{DEFINE-METHOD-COMBINATION} \VAR{c-type}
393 (\OPn{\VAR{ord-$\lambda$}})
394 (\OPn{(\VAR{group} \xorGOO{%
395 \kwd{\A}\\
396 (\OPn{\VAR{qualifier}}\text{ } \OP{\kwd{\A}})\\
397 \VAR{predicate}}{\}}
398 \orGOO{%
399 \kwd{:description} \VAR{ control}\\
400 \kwd{:order }
401 \xorGOO{\kwd{:most-specific-first}\\
402 \kwd{:most-specific-last}}{\}}\DF{\kwd{:most-specific-first}}\\
403 \kwd{:required} \VAR{ bool}}{\}})})
404 \orGOO{%
405 (\kwd{:arguments } \OPn{\VAR{method-combination-$\lambda$}})\\
406 (\kwd{:generic-function} \VAR{ symbol})\\
407 \OPn{(\kwd{declare } \OPn{\NEV{\VAR{decl}}})}\\
408 \NEV{\VAR{doc}}}{\}}
409 \PROGN{\VAR{body}})}
411 \EM{Long Form. } Define new \kwd{method-combination}
412 \retval{\VAR{c-type}}. A call to a generic function using
413 \VAR{c-type} will be equivalent to a call to the forms returned by
414 \OPn{\VAR{body}} with \OPn{\VAR{ord-$\lambda$}} bound to
415 \OPn{\VAR{c-arg}} (cf.\ \MC{DEFGENERIC}), with \VAR{symbol} bound to
416 the generic function, with \OPn{\VAR{method-combination-$\lambda$}}
417 bound to the arguments of the generic function, and with
418 \VAR{group}s bound to lists of methods. An applicable method becomes
419 a member of the leftmost \VAR{group} whose \VAR{predicate} or
420 \VAR{qualifier}s match. Methods can be called via
421 \MC{CALL-METHOD}. Lambda lists (\OPn{\VAR{ord-$\lambda$}}) and
422 (\OPn{\VAR{method-combination-$\lambda$}}) according to
423 \VAR{ord-$\lambda$} on p.\ \pageref{section:Functions}, the latter
424 enhanced by an optional \kwd{\&whole} argument.
427 \IT{(\MC*{CALL-METHOD} \xorGOO{\NEV{\VAR{method}}\\
428 (\MC*{MAKE-METHOD}\text{ } \NEV{\VAR{form}})}{\}}%
429 \OP{(\xorGOO{%
430 \NEV{\VAR{next-method}}\\
431 (\MC*{MAKE-METHOD}\text{ } \NEV{\VAR{form}})}{\}^{\!\!*}})})}
433 From within an effective method form, call \VAR{method} with the
434 arguments of the generic function and
435 with information about its \VAR{next-method}s; return \retval{its
436 values}.
439 \end{LIST}
443 %%% Local Variables:
444 %%% mode: latex
445 %%% TeX-master: "clqr"
446 %%% End: