Fix bugs reported by Fengjing Xiao
[clqr.git] / clqr-clos.tex
blob3a536d60d7f72d5a3b3538eee77952c533a2ce6e
1 % Copyright (C) 2008, 2009, 2010, 2011, 2012, 2014, 2018
2 % Bert Burgemeister
4 % Permission is granted to copy, distribute and/or modify this
5 % document under the terms of the GNU Free Documentation License,
6 % Version 1.2; 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})\qquad\qquad}
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}
31 (\OPn{\VAR{superclass}}\DF{\kwd{standard-object}})
32 (\xorGOO{%
33 \VAR{slot}\\
34 (\VAR{slot }
35 \orGOO{%
36 \Goos{\kwd{:reader} \VAR{reader}}\\
37 \Goos{\kwd{:writer} \xorGOO{%
38 \VAR{writer}\\
39 ({\kwd{setf}\VAR{ writer}})}{\}}} \\
40 \Goos{\kwd{:accessor} \VAR{accessor}} \\
41 \kwd{:allocation } \xorGOO{%
42 \kwd{:instance}\\
43 \kwd{:class}}{\}}\DF{\kwd{:instance}}\\
44 \Goos{\kwd{:initarg} \Op{\kwd{:}}\VAR{initarg-name}} \\
45 \kwd{:initform} \VAR{ form}\\
46 \kwd{:type} \VAR{ type}\\
47 \kwd{:documentation}
48 \VAR{ slot-doc}}{\}})}{\}^{\!\!\!*}})
49 \orGOO{%
50 (\kwd{:default-initargs } \Goos{\VAR{name}\VAR{ value}})\\
51 (\kwd{:documentation} \VAR{ class-doc})\\
52 (\kwd{:metaclass} \VAR{ name}\DF{\kwd{standard-class}})}{\}})}
54 Define or modify \retval{class \VAR{foo}} as a subclass of
55 \VAR{superclass}es. Transform existing instances, if any,
56 by \GFU{make-instances-obsolete}. In a new instance \VAR{i} of
57 \VAR{foo}, a \VAR{slot}'s value defaults to \VAR{form} unless set
58 via \Op{\kwd{:}}\VAR{initarg-name}; it is readable via (\VAR{reader}
59 \VAR{i}) or (\VAR{accessor} \VAR{i}), and writable via
60 (\VAR{writer} \VAR{value} \VAR{i}) or (\kwd{setf} (\VAR{accessor}
61 \VAR{i}) \VAR{value}). \VAR{slot}s with \kwd{:allocation :class}
62 are shared by all instances of class \VAR{foo}.
65 \IT{(\FU*{FIND-CLASS} \VAR{symbol} \OP{\VAR{errorp}\DF{\T}
66 \Op{\VAR{environment}}})}
68 Return \retval{class} named \VAR{symbol}. \kwd{setf}able.
71 \IT{(\GFU*{MAKE-INSTANCE} \VAR{class} \Goos{\Op{\kwd{:}}\VAR{initarg}
72 \VAR{value}} \OPn{\VAR{other-keyarg}})}
74 Make new \retval{instance of \VAR{class}}.
77 \IT{(\GFU*{REINITIALIZE-INSTANCE} \VAR{instance} \Goos{\Op{\kwd{:}}\VAR{initarg}
78 \VAR{value}} \OPn{\VAR{other-keyarg}})}
80 Change local slots of \retval{\VAR{instance}} according to
81 \VAR{initarg}s by means of \GFU{shared-initialize}.
84 \IT{(\FU*{SLOT-VALUE} \VAR{foo} \VAR{slot})}
86 Return \retval{value
87 of \VAR{slot} in \VAR{foo}}. \kwd{SETF}able.
90 \IT{(\FU*{SLOT-MAKUNBOUND} \VAR{instance} \VAR{slot})}
92 Make \VAR{slot} in \retval{\VAR{instance}} unbound.
95 \IT{(\xorGOO{%
96 \MC*{WITH-SLOTS } (\Goos{\NEV{\VAR{slot}}\XOR(\NEV{\VAR{var}} \NEV{\VAR{slot}})})\\
97 \MC*{WITH-ACCESSORS } (\OPn{(\NEV{\VAR{var}}\text{ } \NEV{\VAR{accessor}})})}{\}}
98 \VAR{instance} \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})}
99 \PROGN{\VAR{form}})}
101 Return \retval{values of \VAR{form}s} after evaluating them in a
102 lexical environment with slots of \VAR{instance} visible as
103 \kwd{setf}able \VAR{slot}s or \VAR{var}s/with \VAR{accessor}s of
104 \VAR{instance} visible as \kwd{setf}able \VAR{var}s.
107 \IT{\arrGOO{(\GFU*{CLASS-NAME } \VAR{class})\\
108 ((\kwd{setf } \GFU*{CLASS-NAME}) \VAR{ new-name } \VAR{class})}{.}}
110 Get/set \retval{name of \VAR{class}}.
113 \IT{(\FU*{CLASS-OF} \VAR{foo})}
115 \retval{Class} \VAR{foo} is a direct instance of.
118 \IT{(\GFU*{CHANGE-CLASS} \DES{\VAR{instance}} \VAR{new-class}
119 \Goos{\Op{\kwd{:}}\VAR{initarg} \VAR{value}} \OPn{\VAR{other-keyarg}})}
121 Change class of \retval{\VAR{instance}} to \VAR{new-class}.
122 Retain the status of any slots that are common between
123 \VAR{instance}'s original class and \VAR{new-class}. Initialize
124 any newly added slots with the \VAR{value}s of the corresponding
125 \VAR{initarg}s if any, or with the values of their
126 \kwd{:initform} forms if not.
129 \IT{(\GFU*{MAKE-INSTANCES-OBSOLETE} \VAR{class})}
131 Update all existing instances of \VAR{class} using
132 \GFU{update-instance-for-redefined-class}.
135 \IT{(\xorGOO{%
136 \GFU*{INITIALIZE-INSTANCE } \VAR{instance}\\
137 \GFU*{UPDATE-INSTANCE-FOR-DIFFERENT-CLASS}
138 \VAR{ previous }\VAR{current}}{\}}
139 \Goos{\Op{\kwd{:}}\VAR{initarg}
140 \VAR{value}} \OPn{\VAR{other-keyarg}})}
142 Set slots on behalf of \GFU{make-instance}/of
143 \GFU{change-class} by means of \GFU{shared-initialize}.
146 \IT{(\GFU*{UPDATE-INSTANCE-FOR-REDEFINED-CLASS}
147 \VAR{new-instance}
148 \VAR{added-slots}
149 \VAR{discarded-slots}
150 \VAR{discarded-slots-property-list}
151 \Goos{%
152 \Op{\kwd{:}}\VAR{initarg}
153 \VAR{value}}
154 \OPn{\VAR{other-keyarg}})}
156 On behalf of \GFU{make-instances-obsolete} and by means of
157 \GFU{shared-initialize}, set any \VAR{initarg} slots to their
158 corresponding \VAR{value}s; set any remaining \VAR{added-slots} to
159 the values of their \kwd{:initform} forms. Not to be called by
160 user.
163 \IT{(\GFU*{ALLOCATE-INSTANCE} \VAR{class} \Goos{\Op{\kwd{:}}\VAR{initarg}
164 \VAR{value}} \OPn{\VAR{other-keyarg}})}
166 Return uninitialized \retval{instance} of \VAR{class}. Called by
167 \GFU{make-instance}.
170 \IT{(\GFU*{SHARED-INITIALIZE} \VAR{instance}
171 \xorGOO{%
172 \VAR{initform-slots}\\
173 \T}{\}}
174 \Goos{\Op{\kwd{:}}%
175 \VAR{initarg-slot}
176 \VAR{value}}
177 \OPn{\VAR{other-keyarg}})}
179 Fill the \VAR{initarg-slot}s of \VAR{instance} with the
180 corresponding \VAR{value}s, and fill those \VAR{initform-slots}
181 that are not \VAR{initarg-slot}s with the values of their
182 \kwd{:initform} forms.
185 \IT{\arrGOO{%
186 (\GFU*{SLOT-MISSING } \VAR{class } \VAR{instance } \VAR{slot }
187 \xorGOO{%
188 \kwd{setf}\\
189 \kwd{slot-boundp}\\
190 \kwd{slot-makunbound}\\
191 \kwd{slot-value}}{\}}
192 \Op{\VAR{value}})\\
193 (\GFU*{SLOT-UNBOUND } \VAR{class } \VAR{instance } \VAR{slot})}{.}}
195 Called on attempted access to non-existing or unbound
196 \VAR{slot}. Default methods signal \kwd{error}/\kwd{unbound-slot},
197 respectively. Not to be called by user.
200 \end{LIST}
203 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
204 \subsection{Generic Functions}
205 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
207 \begin{LIST}{1cm}
208 \IT{(\FU*{NEXT-METHOD-P})}
210 \retval{\T} if enclosing method has a next method.
213 \IT{(\MC*{DEFGENERIC}
214 \xorGOO{\VAR{foo}\\ (\kwd{setf} \VAR{ foo})}{\}}
215 (\OPn{\VAR{required-var}}
216 \OP{\kwd{\&optional} \xorGOO{%
217 \VAR{var}\\
218 (\VAR{var})}{\}^{\!\!*}}}
219 \OP{\kwd{\&rest} \VAR{var}}
220 \OP{\kwd{\&key} \xorGOO{%
221 \VAR{var}\\
222 (\VAR{var}\XOR(\kwd{:}\VAR{key }
223 \VAR{var}))}{\}^{\!\!*}} \Op{\kwd{\&allow-other-keys}}})
224 \orGOO{%
225 (\kwd{:argument-precedence-order}\RP{\VAR{ required-var}})\\
226 (\kwd{declare }\RP{(\kwd{optimize}\VAR{ method-selection-optimization})})\\
227 (\kwd{:documentation } \NEV{\VAR{string}})\\
228 (\kwd{:generic-function-class}
229 \VAR{ gf-class}\DF{\kwd{standard-generic-function}})\\
230 (\kwd{:method-class} \VAR{ method-class}\DF{\kwd{standard-method}})\\
231 (\kwd{:method-combination}
232 \VAR{ c-type}\DF{\kwd{standard}} \OPn{\VAR{ c-arg}})\\
233 \OPn{(\kwd{:method} \VAR{ defmethod-args})}}{\}})}
235 Define or modify \retval{generic function} \VAR{foo}. Remove any
236 methods previously defined by defgeneric. \VAR{gf-class} and the lambda
237 paramters \OPn{\VAR{required-var}} and \OPn{\VAR{var}} must be
238 compatible with existing methods. \VAR{defmethod-args}
239 resemble those of \MC{defmethod}. For \VAR{c-type} see section
240 \ref{section:Method Combination Types}.
243 \IT{(\FU*{ENSURE-GENERIC-FUNCTION}
244 \xorGOO{\VAR{foo}\\ (\kwd{setf} \VAR{ foo})}{\}}
245 \orGOO{%
246 \kwd{:argument-precedence-order}\RP{\VAR{ required-var}}\\
247 \kwd{:declare }(\kwd{optimize}\VAR{ method-selection-optimization})\\
248 \kwd{:documentation} \VAR{ string}\\
249 \kwd{:generic-function-class} \VAR{ gf-class}\\
250 \kwd{:method-class} \VAR{ method-class}\\
251 \kwd{:method-combination} \VAR{ c-type} \OPn{\VAR{ c-arg}}\\
252 \kwd{:lambda-list} \VAR{ lambda-list}\\
253 \kwd{:environment} \VAR{ environment}}{\}})}
255 Define or modify \retval{generic function}
256 \VAR{foo}. \VAR{gf-class} and \VAR{lambda-list}
257 must be compatible with a pre-existing generic function or with
258 existing methods, respectively. Changes to \VAR{method-class} do
259 not propagate to existing methods. For \VAR{c-type} see section
260 \ref{section:Method Combination Types}.
263 \IT{(\MC*{DEFMETHOD}
264 \xorGOO{\VAR{foo}\\
265 (\kwd{setf} \VAR{ foo})}{\}}
266 \Op{\xorGOO{\kwd{:before}\\
267 \kwd{:after}\\
268 \kwd{:around}\\
269 \OPn{\VAR{qualifier}}}{\}}\DF{primary method}}
270 (\xorGOO{\VAR{var}\\
271 (\VAR{spec-var } \xorGOO{\VAR{class}\\
272 (\kwd{eql} \VAR{ bar})}{\}})}{\}^{\!\!*}}
273 \OP{\kwd{\&optional} \xorGOO{\VAR{var}\\
274 (\VAR{var } \OP{\VAR{init }
275 \Op{\VAR{supplied-p}}})}{\}^{\!\!*}}}
276 \Op{\kwd{\&rest} \VAR{var}}
277 \OP{\kwd{\&key} \xorGOO{\VAR{var}\\
278 (\xorGOO{\VAR{var}\\
279 (\kwd{:}\VAR{key }
280 \VAR{var})}{\}}
281 \OP{\VAR{init }\Op{\VAR{supplied-p}}})}{\}^{\!\!*}}
282 \Op{\kwd{\&allow-other-keys}}}
283 \OP{\kwd{\&aux }\xorGOO{\VAR{var}\\
284 (\VAR{var } \Op{\VAR{init}})}{\}^{\!\!*}}})
285 \orGOO{\OPn{(\kwd{declare } \OPn{\NEV{\VAR{decl}}})}\\
286 \NEV{\VAR{doc}}}{\}}
287 \PROGN{\VAR{form}})}
289 Define \retval{new method} for generic function
290 \VAR{foo}. \VAR{spec-var}s specialize to either being of \VAR{class}
291 or being \kwd{eql} \VAR{bar}, respectively. On invocation, \VAR{var}s and
292 \VAR{spec-var}s of the \retval{new method}
293 act like parameters of a function with body
294 \OPn{\VAR{form}}. \VAR{form}s are enclosed in an implicit \SO{block}
295 \VAR{foo}. Applicable \VAR{qualifier}s depend on the
296 \kwd{method-combination} type; see
297 section \ref{section:Method Combination Types}.
300 \IT{(\xorGOO{\GFU*{ADD-METHOD}\\
301 \GFU*{REMOVE-METHOD}}{\}} \VAR{generic-function} \VAR{method})}
303 Add (if necessary) or remove (if any) \VAR{method} to/from
304 \retval{\VAR{generic-function}}.
307 \IT{(\GFU*{FIND-METHOD} \VAR{generic-function} \VAR{qualifiers}
308 \VAR{specializers} \Op{\VAR{error}\DF{\T}})}
310 Return suitable \retval{method}, or signal \kwd{error}.
313 \IT{(\GFU*{COMPUTE-APPLICABLE-METHODS} \VAR{generic-function}
314 \VAR{args})}
316 \retval{List of methods} suitable for \VAR{args}, most specific first.
319 \IT{(\FU*{CALL-NEXT-METHOD} \OPn{\VAR{arg}}\DF{current args})}
321 From within a method, call next method with \VAR{arg}s; return
322 \retval{its values}.
325 \IT{(\GFU*{NO-APPLICABLE-METHOD} \VAR{generic-function}
326 \OPn{\VAR{arg}})}
328 Called on invocation of \VAR{generic-function} on \VAR{arg}s if
329 there is no applicable method. Default method signals
330 \kwd{error}. Not to be called by user.
333 \IT{(\xorGOO{%
334 \FU*{INVALID-METHOD-ERROR} \VAR{ method}\\
335 \FU*{METHOD-COMBINATION-ERROR}}{\}}
336 \VAR{control} \OPn{\VAR{arg}})}
338 Signal \kwd{error} on applicable method with invalid qualifiers, or
339 on method combination. For \VAR{control} and \VAR{arg}s see
340 \kwd{format}, page \pageref{section:Format}.
343 \IT{(\GFU*{NO-NEXT-METHOD} \VAR{generic-function}
344 \VAR{method} \OPn{\VAR{arg}})}
346 Called on invocation of \kwd{call-next-method} when there is no next
347 method. Default method signals \kwd{error}. Not to be called by
348 user.
351 \IT{(\GFU*{FUNCTION-KEYWORDS} \VAR{method})}
353 Return list of \retval{keyword parameters} of \VAR{method} and
354 \retvalii{\T} if other keys are allowed.
357 \IT{(\GFU*{METHOD-QUALIFIERS} \VAR{method})}
359 \retval{List of qualifiers} of \VAR{method}.
363 \end{LIST}
365 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
366 \subsection{Method Combination Types}
367 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
368 \label{section:Method Combination Types}
369 \begin{LIST}{1cm}
371 \IT{\kwd*{STANDARD}}
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, call all
377 \kwd{:before} methods, most specific first, and the most specific
378 primary method which supplies the values of the calling
379 \FU{call-next-method} if any, or of the generic function; and which
380 can call less specific primary methods via
381 \FU{call-next-method}. After its return, call all \kwd{:after}
382 methods, least specific first.
385 \IT{\kwd*{AND}\XOR
386 \kwd*{OR}\XOR
387 \kwd*{APPEND}\XOR
388 \kwd*{LIST}\XOR \kwd*{NCONC}\XOR
389 \kwd*{PROGN}\XOR
390 \kwd*{MAX}\XOR
391 \kwd*{MIN}\XOR
392 \kwd*{+}}
394 Simple built-in \kwd{method-combination} types; have the same
395 usage as the
396 \VAR{c-type}s defined by the short form of
397 \MC{define-method-combination}.
400 \IT{(\MC*{DEFINE-METHOD-COMBINATION} \VAR{c-type}
401 \orGOO{%
402 \kwd{:documentation } \NEV{\VAR{string}}\\
403 \kwd{:identity-with-one-argument} \VAR{ bool}\DF{\NIL}\\
404 \kwd{:operator} \VAR{ operator}\DF{\VAR{c-type}}}{\}})}
406 \EM{Short Form. } Define new \kwd{method-combination}
407 \retval{\VAR{c-type}}. In a generic function using \VAR{c-type},
408 evaluate most specific \kwd{:around} method supplying the values of
409 the generic function. From within this method, \FU{call-next-method}
410 can call less specific \kwd{:around} methods if there are any. If
411 not, or if there are no \kwd{:around} methods at all,
412 return from the calling \kwd{call-next-method} or from the
413 generic function, respectively, the
414 values of (\VAR{operator} \OPn{(\VAR{primary-method}
415 \OPn{\VAR{gen-arg}})}), \OPn{\VAR{gen-arg}} being the arguments of the
416 generic function.
417 The \VAR{primary-method}s are ordered
418 \OP{\xorGOO{%
419 \kwd{:most-specific-first}\\
420 \kwd{:most-specific-last}%
421 }{\}}\DF{\kwd{:most-specific-first}}}
422 (specified as \VAR{c-arg} in \MC{defgeneric}).
423 Using \VAR{c-type} as the \VAR{qualifier} in \MC{defmethod}
424 makes the method primary.
427 \IT{(\MC*{DEFINE-METHOD-COMBINATION} \VAR{c-type}
428 (\OPn{\VAR{ord-$\lambda$}})
429 (\OPn{(\VAR{group} \xorGOO{%
430 \kwd{\A}\\
431 (\OPn{\VAR{qualifier}}\text{ } \OP{\kwd{\A}})\\
432 \VAR{predicate}}{\}}
433 \orGOO{%
434 \kwd{:description} \VAR{ control}\\
435 \kwd{:order }
436 \xorGOO{\kwd{:most-specific-first}\\
437 \kwd{:most-specific-last}}{\}}\DF{\kwd{:most-specific-first}}\\
438 \kwd{:required} \VAR{ bool}}{\}})})
439 \orGOO{%
440 (\kwd{:arguments } \OPn{\VAR{method-combination-$\lambda$}})\\
441 (\kwd{:generic-function} \VAR{ symbol})\\
442 \orGOO{%
443 \OPn{(\kwd{declare } \OPn{\NEV{\VAR{decl}}})}\\
444 \NEV{\VAR{doc}}}{\}}}{\}}
445 \PROGN{\VAR{body}})}
447 \EM{Long Form. } Define new \kwd{method-combination}
448 \retval{\VAR{c-type}}. A call to a generic function using
449 \VAR{c-type} will be equivalent to a call to the forms returned by
450 \OPn{\VAR{body}} with \OPn{\VAR{ord-$\lambda$}} bound to
451 \OPn{\VAR{c-arg}} (cf.\ \MC{DEFGENERIC}), with \VAR{symbol} bound to
452 the generic function, with \OPn{\VAR{method-combination-$\lambda$}}
453 bound to the arguments of the generic function, and with
454 \VAR{group}s bound to lists of methods. An applicable method becomes
455 a member of the leftmost \VAR{group} whose \VAR{predicate} or
456 \VAR{qualifier}s match. Methods can be called via
457 \MC{CALL-METHOD}. Lambda lists (\OPn{\VAR{ord-$\lambda$}}) and
458 (\OPn{\VAR{method-combination-$\lambda$}}) according to
459 \VAR{ord-$\lambda$} on page \pageref{section:Functions}, the latter
460 enhanced by an optional \kwd{\&whole} argument.
463 \IT{(\MC*{CALL-METHOD} \xorGOO{\NEV{\VAR{method}}\\
464 (\MC*{MAKE-METHOD}\text{ } \NEV{\VAR{form}})}{\}}%
465 \OP{(\xorGOO{%
466 \NEV{\VAR{next-method}}\\
467 (\MC*{MAKE-METHOD}\text{ } \NEV{\VAR{form}})}{\}^{\!\!*}})})}
469 From within an effective method form, call \VAR{method} with the
470 arguments of the generic function and
471 with information about its \VAR{next-method}s; return \retval{its
472 values}.
475 \end{LIST}
479 %%% Local Variables:
480 %%% mode: latex
481 %%% TeX-master: "clqr"
482 %%% End: