Mercurial > emacs
annotate doc/misc/eieio.texi @ 111755:350f17da7963
Document byte-to-string in Lisp manual.
* objects.texi (Symbol Type):
* text.texi (Near Point):
* help.texi (Help Functions):
* functions.texi (Mapping Functions): Use string instead of
char-to-string in examples.
* nonascii.texi (Converting Representations): Document
byte-to-string.
* strings.texi (Creating Strings): Don't mention semi-obsolete
function char-to-string.
(String Conversion): Shorten discussion of semi-obsolete function
string-to-char. Link to Converting Representations.
author | Chong Yidong <cyd@stupidchicken.com> |
---|---|
date | Sun, 21 Nov 2010 13:07:47 -0500 |
parents | a91e94388547 |
children | 376148b31b5e |
rev | line source |
---|---|
105494 | 1 \input texinfo |
2 @setfilename ../../info/eieio | |
3 @set TITLE Enhanced Implementation of Emacs Interpreted Objects | |
4 @set AUTHOR Eric M. Ludlam | |
5 @settitle @value{TITLE} | |
6 | |
7 @c ************************************************************************* | |
8 @c @ Header | |
9 @c ************************************************************************* | |
10 | |
11 @copying | |
12 This manual documents EIEIO, an object framework for Emacs Lisp. | |
13 | |
106719
b7f28f66e31e
eieio.texi (Naming Conventions): Correction to xref on elisp
Eli Zaretskii <eliz@gnu.org>
parents:
105754
diff
changeset
|
14 Copyright @copyright{} 2007, 2008, 2009, 2010 Free Software Foundation, Inc. |
105494 | 15 |
16 @quotation | |
17 Permission is granted to copy, distribute and/or modify this document | |
18 under the terms of the GNU Free Documentation License, Version 1.3 or | |
19 any later version published by the Free Software Foundation; with no | |
20 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' | |
21 and with the Back-Cover Texts as in (a) below. A copy of the license | |
22 is included in the section entitled ``GNU Free Documentation License.'' | |
23 | |
24 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and | |
25 modify this GNU manual. Buying copies from the FSF supports it in | |
26 developing GNU and promoting software freedom.'' | |
27 @end quotation | |
28 @end copying | |
29 | |
107093
f412ff4a9f03
Use standard format for direntry
Mark A. Hershberger <mah@everybody.org>
parents:
106886
diff
changeset
|
30 @dircategory Emacs |
f412ff4a9f03
Use standard format for direntry
Mark A. Hershberger <mah@everybody.org>
parents:
106886
diff
changeset
|
31 @direntry |
109274
a91e94388547
Minor doc/misc/*.texi direntry fixes.
Glenn Morris <rgm@gnu.org>
parents:
109264
diff
changeset
|
32 * eieio: (eieio). Objects for Emacs. |
107093
f412ff4a9f03
Use standard format for direntry
Mark A. Hershberger <mah@everybody.org>
parents:
106886
diff
changeset
|
33 @end direntry |
105494 | 34 |
35 @titlepage | |
36 @center @titlefont{@value{TITLE}} | |
37 @sp 4 | |
38 @center by @value{AUTHOR} | |
39 @end titlepage | |
40 @page | |
41 | |
42 @macro eieio{} | |
43 @i{EIEIO} | |
44 @end macro | |
45 | |
46 @node Top, Quick Start, (dir), (dir) | |
47 @comment node-name, next, previous, up | |
48 @top EIEIO | |
49 | |
50 @eieio{} (``Enhanced Implementation of Emacs Interpreted Objects'') is | |
51 a CLOS (Common Lisp Object System) compatibility layer for Emacs Lisp. | |
52 It provides a framework for writing object-oriented applications in | |
53 Emacs. | |
54 | |
55 @ifnottex | |
56 @insertcopying | |
57 @end ifnottex | |
58 | |
59 @menu | |
60 * Quick Start:: Quick start for EIEIO. | |
61 * Introduction:: Why use @eieio{}? Basic overview, samples list. | |
62 * Building Classes:: How to write new class structures. | |
63 * Making New Objects:: How to construct new objects. | |
64 * Accessing Slots:: How to access a slot. | |
65 * Writing Methods:: How to write a method. | |
66 @c * Method Invocation:: How methods are invoked. | |
67 * Predicates:: Class-p, Object-p, etc-p. | |
68 * Association Lists:: List of objects as association lists. | |
69 * Customizing:: Customizing objects. | |
70 * Introspection:: Looking inside a class. | |
71 * Base Classes:: Additional classes you can inherit from. | |
72 * Browsing:: Browsing your class lists. | |
73 * Class Values:: Displaying information about a class or object. | |
74 * Default Superclass:: The root superclasses. | |
75 * Signals:: When you make errors | |
76 * Naming Conventions:: Name your objects in an Emacs friendly way. | |
77 * CLOS compatibility:: What are the differences? | |
78 * Wish List:: Things about EIEIO that could be improved. | |
79 * Function Index:: | |
80 @end menu | |
81 | |
82 @node Quick Start | |
83 @chapter Quick Start | |
84 | |
85 @eieio{} provides an Object Oriented layer for Emacs Lisp. You can | |
86 use @eieio{} to create classes, methods for those classes, and | |
87 instances of classes. | |
88 | |
89 Here is a simple example of a class named @code{record}, containing | |
90 three slots named @code{name}, @code{birthday}, and @code{phone}: | |
91 | |
92 @example | |
93 (defclass record () ; No superclasses | |
94 ((name :initarg :name | |
95 :initform "" | |
96 :type string | |
97 :custom string | |
98 :documentation "The name of a person.") | |
99 (birthday :initarg :birthday | |
100 :initform "Jan 1, 1970" | |
101 :custom string | |
102 :type string | |
103 :documentation "The person's birthday.") | |
104 (phone :initarg :phone | |
105 :initform "" | |
106 :documentation "Phone number.")) | |
107 "A single record for tracking people I know.") | |
108 @end example | |
109 | |
110 Each class can have methods, which are defined like this: | |
111 | |
112 @example | |
113 (defmethod call-record ((rec record) &optional scriptname) | |
114 "Dial the phone for the record REC. | |
115 Execute the program SCRIPTNAME to dial the phone." | |
116 (message "Dialing the phone for %s" (oref rec name)) | |
117 (shell-command (concat (or scriptname "dialphone.sh") | |
118 " " | |
119 (oref rec phone)))) | |
120 @end example | |
121 | |
122 @noindent | |
123 In this example, the first argument to @code{call-record} is a list, | |
124 of the form (@var{varname} @var{classname}). @var{varname} is the | |
125 name of the variable used for the first argument; @var{classname} is | |
126 the name of the class that is expected as the first argument for this | |
127 method. | |
128 | |
129 @eieio{} dispatches methods based on the type of the first argument. | |
130 You can have multiple methods with the same name for different classes | |
131 of object. When the @code{call-record} method is called, the first | |
132 argument is examined to determine the class of that argument, and the | |
133 method matching the input type is then executed. | |
134 | |
135 Once the behavior of a class is defined, you can create a new | |
136 object of type @code{record}. Objects are created by calling the | |
137 constructor. The constructor is a function with the same name as your | |
138 class which returns a new instance of that class. Here is an example: | |
139 | |
140 @example | |
141 (setq rec (record "Eric" :name "Eric" :birthday "June" :phone "555-5555")) | |
142 @end example | |
143 | |
144 @noindent | |
145 The first argument is the name given to this instance. Each instance | |
146 is given a name, so different instances can be easily distinguished | |
147 when debugging. | |
148 | |
149 It can be a bit repetitive to also have a :name slot. To avoid doing | |
150 this, it is sometimes handy to use the base class @code{eieio-named}. | |
151 @xref{eieio-named}. | |
152 | |
153 Calling methods on an object is a lot like calling any function. The | |
154 first argument should be an object of a class which has had this | |
155 method defined for it. In this example it would look like this: | |
156 | |
157 @example | |
158 (call-record rec) | |
159 @end example | |
160 | |
161 @noindent | |
162 or | |
163 | |
164 @example | |
165 (call-record rec "my-call-script") | |
166 @end example | |
167 | |
168 In these examples, @eieio{} automatically examines the class of | |
169 @code{rec}, and ensures that the method defined above is called. If | |
170 @code{rec} is some other class lacking a @code{call-record} method, or | |
171 some other data type, Emacs signals a @code{no-method-definition} | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
172 error. @ref{Signals}. |
105494 | 173 |
174 @node Introduction | |
175 @comment node-name, next, previous, up | |
176 @chapter Introduction | |
177 | |
178 Due to restrictions in the Emacs Lisp language, CLOS cannot be | |
179 completely supported, and a few functions have been added in place of | |
180 setf. | |
181 | |
182 @eieio{} supports the following features: | |
183 | |
184 @enumerate | |
185 @item | |
186 A structured framework for the creation of basic classes with attributes | |
187 and methods using singular inheritance similar to CLOS. | |
188 @item | |
189 Type checking, and slot unbinding. | |
190 @item | |
191 Method definitions similar to CLOS. | |
192 @item | |
193 Simple and complex class browsers. | |
194 @item | |
195 Edebug support for methods. | |
196 @item | |
197 Imenu updates. | |
198 @item | |
199 Byte compilation support of methods. | |
200 @item | |
201 Help system extensions for classes and methods. | |
202 @item | |
203 Automatic texinfo documentation generator. | |
204 @item | |
205 Several base classes for interesting tasks. | |
206 @item | |
207 Simple test suite. | |
208 @item | |
209 Public and private classifications for slots (extensions to CLOS) | |
210 @item | |
211 Customization support in a class (extension to CLOS) | |
212 @end enumerate | |
213 | |
214 Here are some CLOS features that @eieio{} presently lacks: | |
215 | |
216 @table @asis | |
217 @item Complete @code{defclass} tag support | |
218 All CLOS tags are currently supported, but the following are not | |
219 currently implemented correctly: | |
220 | |
221 @table @code | |
222 @item :metaclass | |
223 There is only one base superclass for all @eieio{} classes, which is | |
224 the @code{eieio-default-superclass}. | |
225 @item :default-initargs | |
226 Each slot has an @code{:initarg} tag, so this is not really necessary. | |
227 @end table | |
228 | |
229 @item Mock object initializers | |
230 Each class contains a mock object used for fast initialization of | |
231 instantiated objects. Using functions with side effects on object slot | |
232 values can potentially cause modifications in the mock object. @eieio{} | |
233 should use a deep copy but currently does not. | |
234 | |
235 @item @code{:around} method tag | |
236 This CLOS method tag is non-functional. | |
237 | |
238 @end table | |
239 | |
240 @node Building Classes | |
241 @comment node-name, next, previous, up | |
242 @chapter Building Classes | |
243 | |
244 A @dfn{class} is a definition for organizing data and methods | |
245 together. An @eieio{} class has structures similar to the classes | |
246 found in other object-oriented (OO) languages. | |
247 | |
248 To create a new class, use the @code{defclass} macro: | |
249 | |
250 @defmac defclass class-name superclass-list slot-list &rest options-and-doc | |
251 | |
252 Create a new class named @var{class-name}. The class is represented | |
253 by a self-referential symbol with the name @var{class-name}. @eieio{} | |
254 stores the structure of the class as a symbol property of | |
255 @var{class-name} (@pxref{Symbol Components,,,elisp,GNU Emacs Lisp | |
256 Reference Manual}). | |
257 | |
258 The @var{class-name} symbol's variable documentation string is a | |
259 modified version of the doc string found in @var{options-and-doc}. | |
260 Each time a method is defined, the symbol's documentation string is | |
261 updated to include the methods documentation as well. | |
262 | |
263 The parent classes for @var{class-name} is @var{superclass-list}. | |
264 Each element of @var{superclass-list} must be a class. These classes | |
265 are the parents of the class being created. Every slot that appears | |
266 in each parent class is replicated in the new class. | |
267 | |
268 If two parents share the same slot name, the parent which appears in | |
269 the @var{superclass-list} first sets the tags for that slot. If the | |
270 new class has a slot with the same name as the parent, the new slot | |
271 overrides the parent's slot. | |
272 @end defmac | |
273 | |
274 @noindent | |
275 Whenever defclass is used to create a new class, two predicates are | |
276 created for it, named @code{@var{CLASS-NAME}-p} and | |
277 @code{@var{CLASS-NAME}-child-p}: | |
278 | |
279 @defun CLASS-NAME-p object | |
280 Return @code{t} if @var{OBJECT} is of the class @var{CLASS-NAME}. | |
281 @end defun | |
282 | |
283 @defun CLASS-NAME-child-p object | |
284 Return @code{t} if @var{OBJECT} is of the class @var{CLASS-NAME}, | |
285 or is of a subclass of @var{CLASS-NAME}. | |
286 @end defun | |
287 | |
288 @defvar eieio-error-unsupported-class-tags | |
289 If non-nil, @code{defclass} signals an error if a tag in a slot | |
290 specifier is unsupported. | |
291 | |
292 This option is here to support programs written with older versions of | |
293 @eieio{}, which did not produce such errors. | |
294 @end defvar | |
295 | |
296 @menu | |
297 * Inheritance:: How to specify parents classes | |
109264 | 298 * Slot Options:: How to specify features of a slot. |
299 * Class Options:: How to specify features for this class. | |
105494 | 300 @end menu |
301 | |
302 @node Inheritance | |
303 @section Inheritance | |
304 | |
305 @dfn{Inheritance} is a basic feature of an object-oriented language. | |
306 In @eieio{}, a defined class specifies the super classes from which it | |
307 inherits by using the second argument to @code{defclass}. Here is an | |
308 example: | |
309 | |
310 @example | |
311 (defclass my-baseclass () | |
312 ((slot-A :initarg :slot-A) | |
313 (slot-B :initarg :slot-B)) | |
314 "My Baseclass.") | |
315 @end example | |
316 | |
317 @noindent | |
318 To subclass from @code{my-baseclass}, we specify it in the superclass | |
319 list: | |
320 | |
321 @example | |
322 (defclass my-subclass (my-baseclass) | |
323 ((specific-slot-A :initarg specific-slot-A) | |
324 ) | |
325 "My subclass of my-baseclass") | |
326 @end example | |
327 | |
328 @indent | |
329 Instances of @code{my-subclass} will inherit @code{slot-A} and | |
330 @code{slot-B}, in addition to having @code{specific-slot-A} from the | |
331 declaration of @code{my-subclass}. | |
332 | |
333 @eieio{} also supports multiple inheritance. Suppose we define a | |
334 second baseclass, perhaps an ``interface'' class, like this: | |
335 | |
336 @example | |
337 (defclass my-interface () | |
338 ((interface-slot :initarg :interface-slot)) | |
339 "An interface to special behavior." | |
340 :abstract t) | |
341 @end example | |
342 | |
343 @noindent | |
344 The interface class defines a special @code{interface-slot}, and also | |
345 specifies itself as abstract. Abstract classes cannot be | |
346 instantiated. It is not required to make interfaces abstract, but it | |
347 is a good programming practice. | |
348 | |
349 We can now modify our definition of @code{my-subclass} to use this | |
350 interface class, together with our original base class: | |
351 | |
352 @example | |
353 (defclass my-subclass (my-baseclass my-interface) | |
354 ((specific-slot-A :initarg specific-slot-A) | |
355 ) | |
356 "My subclass of my-baseclass") | |
357 @end example | |
358 | |
359 @noindent | |
360 With this, @code{my-subclass} also has @code{interface-slot}. | |
361 | |
362 If @code{my-baseclass} and @code{my-interface} had slots with the same | |
363 name, then the superclass showing up in the list first defines the | |
364 slot attributes. | |
365 | |
366 Inheritance in @eieio{} is more than just combining different slots. | |
367 It is also important in method invocation. @ref{Methods}. | |
368 | |
369 If a method is called on an instance of @code{my-subclass}, and that | |
370 method only has an implementation on @code{my-baseclass}, or perhaps | |
371 @code{my-interface}, then the implementation for the baseclass is | |
372 called. | |
373 | |
374 If there is a method implementation for @code{my-subclass}, and | |
375 another in @code{my-baseclass}, the implementation for | |
376 @code{my-subclass} can call up to the superclass as well. | |
377 | |
378 @node Slot Options | |
379 @section Slot Options | |
380 | |
381 The @var{slot-list} argument to @code{defclass} is a list of elements | |
382 where each element defines one slot. Each slot is a list of the form | |
383 | |
384 @example | |
385 (SLOT-NAME :TAG1 ATTRIB-VALUE1 | |
386 :TAG2 ATTRIB-VALUE2 | |
387 :TAGN ATTRIB-VALUEN) | |
388 @end example | |
389 | |
390 @noindent | |
391 where @var{SLOT-NAME} is a symbol that will be used to refer to the | |
392 slot. @var{:TAG} is a symbol that describes a feature to be set | |
393 on the slot. @var{ATTRIB-VALUE} is a lisp expression that will be | |
394 used for @var{:TAG}. | |
395 | |
396 Valid tags are: | |
397 | |
398 @table @code | |
399 @item :initarg | |
400 A symbol that can be used in the argument list of the constructor to | |
401 specify a value for the new instance being created. | |
402 | |
403 A good symbol to use for initarg is one that starts with a colon @code{:}. | |
404 | |
405 The slot specified like this: | |
406 @example | |
407 (myslot :initarg :myslot) | |
408 @end example | |
409 could then be initialized to the number 1 like this: | |
410 @example | |
411 (myobject "name" :myslot 1) | |
412 @end example | |
413 | |
414 @xref{Making New Objects}. | |
415 | |
416 @item :initform | |
417 A expression used as the default value for this slot. | |
418 | |
419 If @code{:initform} is left out, that slot defaults to being unbound. | |
420 It is an error to reference an unbound slot, so if you need | |
421 slots to always be in a bound state, you should always use an | |
422 @code{:initform} specifier. | |
423 | |
424 Use @code{slot-boundp} to test if a slot is unbound | |
425 (@pxref{Predicates}). Use @code{slot-makeunbound} to set a slot to | |
426 being unbound after giving it a value (@pxref{Accessing Slots}). | |
427 | |
428 The value passed to initform is automatically quoted. Thus, | |
429 @example | |
430 :initform (1 2 3) | |
431 @end example | |
432 appears as the specified list in the default object. | |
433 A symbol that is a function like this: | |
434 @example | |
435 :initform + | |
436 @end example | |
437 will set the initial value as that symbol. | |
438 A function that is a lambda expression, like this: | |
439 @example | |
440 :initform (lambda () some-variablename) | |
441 @end example | |
442 | |
443 will be evaluated at instantiation time to the value of | |
444 @code{some-variablename}. | |
445 @c This feature was more annoying than useful. Use the | |
446 @c `initialize-instance' function to do this. | |
447 @c | |
448 @c On the other hand, if you need code to be | |
449 @c executed at instantiation time as the initform, code like this: | |
450 @c @example | |
451 @c :initform (lambda () (+ 1 some-global-var)) | |
452 @c @end example | |
453 @c will be identified as a function call, and be executed in place. | |
454 | |
455 @cindex lambda-default | |
456 | |
457 | |
458 Lastly, using the function @code{lambda-default} instead of | |
459 @code{lambda} will let you specify a lambda expression to use as the | |
460 value, without evaluation, thus: | |
461 @example | |
462 :initform (lambda-default () some-variablename) | |
463 @end example | |
464 @c @@TODO - This will be deleted after fair warning. | |
465 will not be evaluated at instantiation time, and the value in this | |
466 slot will instead be @code{(lambda () some-variablename)}. | |
467 | |
468 After a class has been created with @code{defclass}, you can change | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
469 that default value with @code{oset-default}. @ref{Accessing Slots}. |
105494 | 470 |
471 @item :type | |
472 An unquoted type specifier used to validate data set into this slot. | |
473 @xref{(cl)Type Predicates}. | |
474 Here are some examples: | |
475 @table @code | |
476 @item symbol | |
477 A symbol. | |
478 @item number | |
479 A number type | |
480 @item my-class-name | |
481 An object of your class type. | |
482 @item (or null symbol) | |
483 A symbol, or nil. | |
484 @item function | |
485 A function symbol, or a @code{lambda-default} expression. | |
486 | |
487 @end table | |
488 | |
489 @item :allocation | |
490 Either :class or :instance (defaults to :instance) used to | |
491 specify how data is stored. Slots stored per instance have unique | |
492 values for each object. Slots stored per class have shared values for | |
493 each object. If one object changes a :class allocated slot, then all | |
494 objects for that class gain the new value. | |
495 | |
496 @item :documentation | |
497 Documentation detailing the use of this slot. This documentation is | |
498 exposed when the user describes a class, and during customization of an | |
499 object. | |
500 | |
501 @item :accessor | |
502 Name of a generic function which can be used to fetch the value of this slot. | |
503 You can call this function later on your object and retrieve the value | |
504 of the slot. | |
505 | |
506 This options is in the CLOS spec, but is not fully compliant in @eieio{}. | |
507 | |
508 @item :writer | |
509 Name of a generic function which will write this slot. | |
510 | |
511 This options is in the CLOS spec, but is not fully compliant in @eieio{}. | |
512 | |
513 @item :reader | |
514 Name of a generic function which will read this slot. | |
515 | |
516 This options is in the CLOS spec, but is not fully compliant in @eieio{}. | |
517 | |
518 @item :custom | |
519 A custom :type specifier used when editing an object of this type. | |
520 See documentation for @code{defcustom} for details. This specifier is | |
521 equivalent to the :type spec of a @code{defcustom} call. | |
522 | |
523 This options is specific to Emacs, and is not in the CLOS spec. | |
524 | |
525 @item :label | |
526 When customizing an object, the value of :label will be used instead | |
527 of the slot name. This enables better descriptions of the data than | |
528 would usually be afforded. | |
529 | |
530 This options is specific to Emacs, and is not in the CLOS spec. | |
531 | |
532 @item :group | |
533 Similar to @code{defcustom}'s :group command, this organizes different | |
534 slots in an object into groups. When customizing an object, only the | |
535 slots belonging to a specific group need be worked with, simplifying the | |
536 size of the display. | |
537 | |
538 This options is specific to Emacs, and is not in the CLOS spec. | |
539 | |
540 @item :printer | |
541 This routine takes a symbol which is a function name. The function | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
542 should accept one argument. The argument is the value from the slot |
105494 | 543 to be printed. The function in @code{object-write} will write the |
544 slot value out to a printable form on @code{standard-output}. | |
545 | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
546 The output format MUST be something that could in turn be interpreted |
105494 | 547 with @code{read} such that the object can be brought back in from the |
548 output stream. Thus, if you wanted to output a symbol, you would need | |
549 to quote the symbol. If you wanted to run a function on load, you | |
550 can output the code to do the construction of the value. | |
551 | |
552 @item :protection | |
553 When using a slot referencing function such as @code{slot-value}, and | |
554 the value behind @var{slot} is private or protected, then the current | |
555 scope of operation must be within a method of the calling object. | |
556 | |
557 Valid values are: | |
558 | |
559 @table @code | |
560 @item :public | |
561 Access this slot from any scope. | |
562 @item :protected | |
563 Access this slot only from methods of the same class or a child class. | |
564 @item :private | |
565 Access this slot only from methods of the same class. | |
566 @end table | |
567 | |
568 This options is specific to Emacs, and is not in the CLOS spec. | |
569 | |
570 @end table | |
571 | |
572 @node Class Options | |
573 @section Class Options | |
574 | |
575 In the @var{options-and-doc} arguments to @code{defclass}, the | |
576 following class options may be specified: | |
577 | |
578 @table @code | |
579 @item :documentation | |
580 A documentation string for this class. | |
581 | |
582 If an Emacs-style documentation string is also provided, then this | |
583 option is ignored. An Emacs-style documentation string is not | |
584 prefixed by the @code{:documentation} tag, and appears after the list | |
585 of slots, and before the options. | |
586 | |
587 @item :allow-nil-initform | |
588 If this option is non-nil, and the @code{:initform} is @code{nil}, but | |
589 the @code{:type} is specifies something such as @code{string} then allow | |
590 this to pass. The default is to have this option be off. This is | |
591 implemented as an alternative to unbound slots. | |
592 | |
593 This options is specific to Emacs, and is not in the CLOS spec. | |
594 | |
595 @item :abstract | |
596 A class which is @code{:abstract} cannot be instantiated, and instead | |
597 is used to define an interface which subclasses should implement. | |
598 | |
599 This option is specific to Emacs, and is not in the CLOS spec. | |
600 | |
601 @item :custom-groups | |
602 This is a list of groups that can be customized within this class. This | |
603 slot is auto-generated when a class is created and need not be | |
604 specified. It can be retrieved with the @code{class-option} command, | |
605 however, to see what groups are available. | |
606 | |
607 This option is specific to Emacs, and is not in the CLOS spec. | |
608 | |
609 @item :method-invocation-order | |
610 This controls the order in which method resolution occurs for | |
611 @code{:primary} methods in cases of multiple inheritance. The order | |
612 affects which method is called first in a tree, and if | |
613 @code{call-next-method} is used, it controls the order in which the | |
614 stack of methods are run. | |
615 | |
616 Valid values are: | |
617 | |
618 @table @code | |
619 @item :breadth-first | |
620 Search for methods in the class hierarchy in breadth first order. | |
621 This is the default. | |
622 @item :depth-first | |
623 Search for methods in the class hierarchy in a depth first order. | |
624 @end table | |
625 | |
626 @c @xref{Method Invocation}, for more on method invocation order. | |
627 | |
628 @item :metaclass | |
629 Unsupported CLOS option. Enables the use of a different base class other | |
630 than @code{standard-class}. | |
631 | |
632 @item :default-initargs | |
633 Unsupported CLOS option. Specifies a list of initargs to be used when | |
634 creating new objects. As far as I can tell, this duplicates the | |
635 function of @code{:initform}. | |
636 @end table | |
637 | |
638 @xref{CLOS compatibility}, for more details on CLOS tags versus | |
639 @eieio{}-specific tags. | |
640 | |
641 @node Making New Objects | |
642 @comment node-name, next, previous, up | |
643 @chapter Making New Objects | |
644 | |
106886
a50b302b7928
Minor Semantic and EIEIO manual fixes.
Chong Yidong <cyd@stupidchicken.com>
parents:
106719
diff
changeset
|
645 Suppose we have a simple class is defined, such as: |
105494 | 646 |
647 @example | |
648 (defclass record () | |
649 ( ) "Doc String") | |
650 @end example | |
651 | |
652 @noindent | |
653 It is now possible to create objects of that class type. | |
654 | |
655 Calling @code{defclass} has defined two new functions. One is the | |
656 constructor @var{record}, and the other is the predicate, | |
657 @var{record-p}. | |
658 | |
659 @defun record object-name &rest slots | |
660 | |
661 This creates and returns a new object. This object is not assigned to | |
662 anything, and will be garbage collected if not saved. This object | |
663 will be given the string name @var{object-name}. There can be | |
664 multiple objects of the same name, but the name slot provides a handy | |
665 way to keep track of your objects. @var{slots} is just all the slots | |
666 you wish to preset. Any slot set as such @emph{will not} get its | |
667 default value, and any side effects from a slot's @code{:initform} | |
668 that may be a function will not occur. | |
669 | |
670 An example pair would appear simply as @code{:value 1}. Of course you | |
671 can do any valid Lispy thing you want with it, such as | |
672 @code{:value (if (boundp 'special-symbol) special-symbol nil)} | |
673 | |
674 Example of creating an object from a class: | |
675 | |
676 @example | |
677 (record "test" :value 3 :reference nil) | |
678 @end example | |
679 | |
680 @end defun | |
681 | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
682 To create an object from a class symbol, use @code{make-instance}. |
105494 | 683 |
684 @defun make-instance class &rest initargs | |
685 @anchor{make-instance} | |
686 Make a new instance of @var{class} based on @var{initargs}. | |
687 @var{class} is a class symbol. For example: | |
688 | |
689 @example | |
690 (make-instance 'foo) | |
691 @end example | |
692 | |
693 @var{initargs} is a property list with keywords based on the @code{:initarg} | |
694 for each slot. For example: | |
695 | |
696 @example | |
697 (make-instance @code{'foo} @code{:slot1} value1 @code{:slotN} valueN) | |
698 @end example | |
699 | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
700 Compatibility note: |
105494 | 701 |
702 If the first element of @var{initargs} is a string, it is used as the | |
703 name of the class. | |
704 | |
705 In @eieio{}, the class' constructor requires a name for use when printing. | |
706 @dfn{make-instance} in CLOS doesn't use names the way Emacs does, so the | |
707 class is used as the name slot instead when @var{initargs} doesn't start with | |
708 a string. | |
709 @end defun | |
710 | |
711 @node Accessing Slots | |
712 @comment node-name, next, previous, up | |
713 @chapter Accessing Slots | |
714 | |
715 There are several ways to access slot values in an object. The naming | |
716 and argument-order conventions are similar to those used for | |
717 referencing vectors (@pxref{Vectors,,,elisp,GNU Emacs Lisp Reference | |
718 Manual}). | |
719 | |
720 @defmac oset object slot value | |
721 This macro sets the value behind @var{slot} to @var{value} in | |
722 @var{object}. It returns @var{value}. | |
723 @end defmac | |
724 | |
725 @defmac oset-default class slot value | |
726 This macro sets the @code{:initform} for @var{slot} in @var{class} to | |
727 @var{value}. | |
728 | |
729 This allows the user to set both public and private defaults after the | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
730 class has been constructed, and provides a way to configure the |
105494 | 731 default behavior of packages built with classes (the same way |
732 @code{setq-default} does for buffer-local variables). | |
733 | |
734 For example, if a user wanted all @code{data-objects} (@pxref{Building | |
735 Classes}) to inform a special object of his own devising when they | |
736 changed, this can be arranged by simply executing this bit of code: | |
737 | |
738 @example | |
739 (oset-default data-object reference (list my-special-object)) | |
740 @end example | |
741 @end defmac | |
742 | |
743 @defmac oref obj slot | |
744 @anchor{oref} | |
745 Retrieve the value stored in @var{obj} in the slot named by @var{slot}. | |
746 Slot is the name of the slot when created by @dfn{defclass} or the label | |
747 created by the @code{:initarg} tag. | |
748 @end defmac | |
749 | |
750 @defmac oref-default obj slot | |
751 @anchor{oref-default} | |
752 Gets the default value of @var{obj} (maybe a class) for @var{slot}. | |
753 The default value is the value installed in a class with the @code{:initform} | |
754 tag. @var{slot} can be the slot name, or the tag specified by the @code{:initarg} | |
755 tag in the @dfn{defclass} call. | |
756 @end defmac | |
757 | |
758 The following accessors are defined by CLOS to reference or modify | |
759 slot values, and use the previously mentioned set/ref routines. | |
760 | |
761 @defun slot-value object slot | |
762 @anchor{slot-value} | |
763 This function retrieves the value of @var{slot} from @var{object}. | |
764 Unlike @code{oref}, the symbol for @var{slot} must be quoted. | |
765 @end defun | |
766 | |
767 @defun set-slot-value object slot value | |
768 @anchor{set-slot-value} | |
769 This is not a CLOS function, but is meant to mirror @code{slot-value} if | |
770 you don't want to use the cl package's @code{setf} function. This | |
771 function sets the value of @var{slot} from @var{object}. Unlike | |
772 @code{oset}, the symbol for @var{slot} must be quoted. | |
773 @end defun | |
774 | |
775 @defun slot-makeunbound object slot | |
776 This function unbinds @var{slot} in @var{object}. Referencing an | |
777 unbound slot can signal an error. | |
778 @end defun | |
779 | |
780 @defun object-add-to-list object slot item &optional append | |
781 @anchor{object-add-to-list} | |
782 In OBJECT's @var{slot}, add @var{item} to the list of elements. | |
783 Optional argument @var{append} indicates we need to append to the list. | |
784 If @var{item} already exists in the list in @var{slot}, then it is not added. | |
785 Comparison is done with @dfn{equal} through the @dfn{member} function call. | |
786 If @var{slot} is unbound, bind it to the list containing @var{item}. | |
787 @end defun | |
788 | |
789 @defun object-remove-from-list object slot item | |
790 @anchor{object-remove-from-list} | |
791 In OBJECT's @var{slot}, remove occurrences of @var{item}. | |
792 Deletion is done with @dfn{delete}, which deletes by side effect | |
793 and comparisons are done with @dfn{equal}. | |
794 If @var{slot} is unbound, do nothing. | |
795 @end defun | |
796 | |
797 @defun with-slots spec-list object &rest body | |
798 @anchor{with-slots} | |
799 Bind @var{spec-list} lexically to slot values in @var{object}, and execute @var{body}. | |
800 This establishes a lexical environment for referring to the slots in | |
801 the instance named by the given slot-names as though they were | |
802 variables. Within such a context the value of the slot can be | |
803 specified by using its slot name, as if it were a lexically bound | |
804 variable. Both setf and setq can be used to set the value of the | |
805 slot. | |
806 | |
807 @var{spec-list} is of a form similar to @dfn{let}. For example: | |
808 | |
809 @example | |
810 ((VAR1 SLOT1) | |
811 SLOT2 | |
812 SLOTN | |
813 (VARN+1 SLOTN+1)) | |
814 @end example | |
815 | |
816 Where each @var{var} is the local variable given to the associated | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
817 @var{slot}. A slot specified without a variable name is given a |
105494 | 818 variable name of the same name as the slot. |
819 | |
820 @example | |
821 (defclass myclass () (x :initarg 1)) | |
822 (setq mc (make-instance 'myclass)) | |
823 (with-slots (x) mc x) => 1 | |
824 (with-slots ((something x)) mc something) => 1 | |
825 @end example | |
826 @end defun | |
827 | |
828 @node Writing Methods | |
829 @comment node-name, next, previous, up | |
830 @chapter Writing Methods | |
831 | |
832 Writing a method in @eieio{} is similar to writing a function. The | |
833 differences are that there are some extra options and there can be | |
834 multiple definitions under the same function symbol. | |
835 | |
836 Where a method defines an implementation for a particular data type, a | |
837 @dfn{generic method} accepts any argument, but contains no code. It | |
838 is used to provide the dispatching to the defined methods. A generic | |
839 method has no body, and is merely a symbol upon which methods are | |
840 attached. It also provides the base documentation for what methods | |
841 with that name do. | |
842 | |
843 @menu | |
844 * Generics:: | |
845 * Methods:: | |
846 * Static Methods:: | |
847 @end menu | |
848 | |
849 @node Generics | |
850 @section Generics | |
851 | |
852 Each @eieio{} method has one corresponding generic. This generic | |
853 provides a function binding and the base documentation for the method | |
854 symbol (@pxref{Symbol Components,,,elisp,GNU Emacs Lisp Reference | |
855 Manual}). | |
856 | |
857 @defmac defgeneric method arglist [doc-string] | |
858 This macro turns the (unquoted) symbol @var{method} into a function. | |
859 @var{arglist} is the default list of arguments to use (not implemented | |
860 yet). @var{doc-string} is the documentation used for this symbol. | |
861 | |
862 A generic function acts as a placeholder for methods. There is no | |
863 need to call @code{defgeneric} yourself, as @code{defmethod} will call | |
864 it if necessary. Currently the argument list is unused. | |
865 | |
866 @code{defgeneric} signals an error if you attempt to turn an existing | |
867 Emacs Lisp function into a generic function. | |
868 | |
869 You can also create a generic method with @code{defmethod} | |
870 (@pxref{Methods}). When a method is created and there is no generic | |
871 method in place with that name, then a new generic will be created, | |
872 and the new method will use it. | |
873 @end defmac | |
874 | |
875 In CLOS, a generic call also be used to provide an argument list and | |
876 dispatch precedence for all the arguments. In @eieio{}, dispatching | |
877 only occurs for the first argument, so the @var{arglist} is not used. | |
878 | |
879 @node Methods | |
880 @section Methods | |
881 | |
882 A method is a function that is executed if the first argument passed | |
883 to it matches the method's class. Different @eieio{} classes may | |
884 share the same method names. | |
885 | |
886 Methods are created with the @code{defmethod} macro, which is similar | |
887 to @code{defun}. | |
888 | |
889 @defmac defmethod method [:before | :primary | :after | :static ] arglist [doc-string] forms | |
890 | |
891 @var{method} is the name of the function to create. | |
892 | |
893 @code{:before} and @code{:after} specify execution order (i.e., when | |
894 this form is called). If neither of these symbols are present, the | |
895 default priority is used (before @code{:after} and after | |
896 @code{:before}); this default priority is represented in CLOS as | |
897 @code{:primary}. | |
898 | |
899 @b{Note:} The @code{:BEFORE}, @code{:PRIMARY}, @code{:AFTER}, and | |
900 @code{:STATIC} method tags were in all capital letters in previous | |
901 versions of @eieio{}. | |
902 | |
903 @var{arglist} is the list of arguments to this method. The first | |
904 argument in this list---and @emph{only} the first argument---may have | |
905 a type specifier (see the example below). If no type specifier is | |
906 supplied, the method applies to any object. | |
907 | |
908 @var{doc-string} is the documentation attached to the implementation. | |
909 All method doc-strings are incorporated into the generic method's | |
910 function documentation. | |
911 | |
912 @var{forms} is the body of the function. | |
913 | |
914 @end defmac | |
915 | |
916 @noindent | |
917 In the following example, we create a method @code{mymethod} for the | |
918 @code{classname} class: | |
919 | |
920 @example | |
921 (defmethod mymethod ((obj classname) secondarg) | |
922 "Doc string" ) | |
923 @end example | |
924 | |
925 @noindent | |
926 This method only executes if the @var{obj} argument passed to it is an | |
927 @eieio{} object of class @code{classname}. | |
928 | |
929 A method with no type specifier is a @dfn{default method}. If a given | |
930 class has no implementation, then the default method is called when | |
931 that method is used on a given object of that class. | |
932 | |
933 Only one default method per execution specifier (@code{:before}, | |
934 @code{:primary}, or @code{:after}) is allowed. If two | |
935 @code{defmethod}s appear with @var{arglist}s lacking a type specifier, | |
936 and having the same execution specifier, then the first implementation | |
937 is replaced. | |
938 | |
939 When a method is called on an object, but there is no method specified | |
940 for that object, but there is a method specified for object's parent | |
941 class, the parent class' method is called. If there is a method | |
942 defined for both, only the child's method is called. A child method | |
943 may call a parent's method using @code{call-next-method}, described | |
944 below. | |
945 | |
946 If multiple methods and default methods are defined for the same | |
947 method and class, they are executed in this order: | |
948 | |
949 @enumerate | |
950 @item method :before | |
951 @item default :before | |
952 @item method :primary | |
953 @item default :primary | |
954 @item method :after | |
955 @item default :after | |
956 @end enumerate | |
957 | |
958 If no methods exist, Emacs signals a @code{no-method-definition} | |
959 error. @xref{Signals}. | |
960 | |
961 @defun call-next-method &rest replacement-args | |
962 @anchor{call-next-method} | |
963 | |
964 This function calls the superclass method from a subclass method. | |
965 This is the ``next method'' specified in the current method list. | |
966 | |
967 If @var{replacement-args} is non-@code{nil}, then use them instead of | |
968 @code{eieio-generic-call-arglst}. At the top level, the generic | |
969 argument list is passed in. | |
970 | |
971 Use @code{next-method-p} to find out if there is a next method to | |
972 call. | |
973 @end defun | |
974 | |
975 @defun next-method-p | |
976 @anchor{next-method-p} | |
977 Non-@code{nil} if there is a next method. | |
978 Returns a list of lambda expressions which is the @code{next-method} | |
979 order. | |
980 @end defun | |
981 | |
982 At present, @eieio{} does not implement all the features of CLOS: | |
983 | |
984 @enumerate | |
985 @item | |
986 There is currently no @code{:around} tag. | |
987 @item | |
988 CLOS allows multiple sets of type-cast arguments, but @eieio{} only | |
989 allows the first argument to be cast. | |
990 @end enumerate | |
991 | |
992 @node Static Methods | |
993 @section Static Methods | |
994 | |
995 Static methods do not depend on an object instance, but instead | |
996 operate on an object's class. You can create a static method by using | |
997 the @code{:static} key with @code{defmethod}. | |
998 | |
999 Do not treat the first argument of a @code{:static} method as an | |
1000 object unless you test it first. Use the functions | |
1001 @code{oref-default} or @code{oset-default} which will work on a class, | |
1002 or on the class of an object. | |
1003 | |
1004 A Class' @code{constructor} method is defined as a @code{:static} | |
1005 method. | |
1006 | |
1007 @b{Note:} The @code{:static} keyword is unique to @eieio{}. | |
1008 | |
1009 @c TODO - Write some more about static methods here | |
1010 | |
1011 @c @node Method Invocation | |
1012 @c @chapter Method Invocation | |
1013 | |
1014 @c TODO - writeme | |
1015 | |
1016 @node Predicates | |
1017 @comment node-name, next, previous, up | |
1018 @chapter Predicates and Utilities | |
1019 | |
1020 Now that we know how to create classes, access slots, and define | |
1021 methods, it might be useful to verify that everything is doing ok. To | |
1022 help with this a plethora of predicates have been created. | |
1023 | |
1024 @defun find-class symbol &optional errorp | |
1025 @anchor{find-class} | |
1026 Return the class that @var{symbol} represents. | |
1027 If there is no class, @code{nil} is returned if @var{errorp} is @code{nil}. | |
1028 If @var{errorp} is non-@code{nil}, @code{wrong-argument-type} is signaled. | |
1029 @end defun | |
1030 | |
1031 @defun class-p class | |
1032 @anchor{class-p} | |
1033 Return @code{t} if @var{class} is a valid class vector. | |
1034 @var{class} is a symbol. | |
1035 @end defun | |
1036 | |
1037 @defun slot-exists-p object-or-class slot | |
1038 @anchor{slot-exists-p} | |
1039 Non-@code{nil} if @var{object-or-class} has @var{slot}. | |
1040 @end defun | |
1041 | |
1042 @defun slot-boundp object slot | |
1043 @anchor{slot-boundp} | |
1044 Non-@code{nil} if OBJECT's @var{slot} is bound. | |
1045 Setting a slot's value makes it bound. Calling @dfn{slot-makeunbound} will | |
1046 make a slot unbound. | |
1047 @var{object} can be an instance or a class. | |
1048 @end defun | |
1049 | |
1050 @defun class-name class | |
1051 Return a string of the form @samp{#<class myclassname>} which should look | |
1052 similar to other Lisp objects like buffers and processes. Printing a | |
1053 class results only in a symbol. | |
1054 @end defun | |
1055 | |
1056 @defun class-option class option | |
1057 Return the value in @var{CLASS} of a given @var{OPTION}. | |
1058 For example: | |
1059 | |
1060 @example | |
1061 (class-option eieio-default-superclass :documentation) | |
1062 @end example | |
1063 | |
1064 Will fetch the documentation string for @code{eieio-default-superclass}. | |
1065 @end defun | |
1066 | |
1067 @defun class-constructor class | |
1068 Return a symbol used as a constructor for @var{class}. The | |
1069 constructor is a function used to create new instances of | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
1070 @var{CLASS}. This function provides a way to make an object of a class |
105494 | 1071 without knowing what it is. This is not a part of CLOS. |
1072 @end defun | |
1073 | |
1074 @defun object-name obj | |
1075 Return a string of the form @samp{#<object-class myobjname>} for @var{obj}. | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
1076 This should look like Lisp symbols from other parts of Emacs such as |
105494 | 1077 buffers and processes, and is shorter and cleaner than printing the |
1078 object's vector. It is more useful to use @code{object-print} to get | |
1079 and object's print form, as this allows the object to add extra display | |
1080 information into the symbol. | |
1081 @end defun | |
1082 | |
1083 @defun object-class obj | |
1084 Returns the class symbol from @var{obj}. | |
1085 @end defun | |
1086 | |
1087 @defun class-of obj | |
1088 CLOS symbol which does the same thing as @code{object-class} | |
1089 @end defun | |
1090 | |
1091 @defun object-class-fast obj | |
1092 Same as @code{object-class} except this is a macro, and no | |
1093 type-checking is performed. | |
1094 @end defun | |
1095 | |
1096 @defun object-class-name obj | |
1097 Returns the symbol of @var{obj}'s class. | |
1098 @end defun | |
1099 | |
1100 @defun class-parents class | |
1101 Returns the direct parents class of @var{class}. Returns @code{nil} if | |
1102 it is a superclass. | |
1103 @end defun | |
1104 | |
1105 @defun class-parents-fast class | |
1106 Just like @code{class-parent} except it is a macro and no type checking | |
1107 is performed. | |
1108 @end defun | |
1109 | |
1110 @defun class-parent class | |
1111 Deprecated function which returns the first parent of @var{class}. | |
1112 @end defun | |
1113 | |
1114 @defun class-children class | |
1115 Return the list of classes inheriting from @var{class}. | |
1116 @end defun | |
1117 | |
1118 @defun class-children-fast class | |
1119 Just like @code{class-children}, but with no checks. | |
1120 @end defun | |
1121 | |
1122 @defun same-class-p obj class | |
1123 Returns @code{t} if @var{obj}'s class is the same as @var{class}. | |
1124 @end defun | |
1125 | |
1126 @defun same-class-fast-p obj class | |
1127 Same as @code{same-class-p} except this is a macro and no type checking | |
1128 is performed. | |
1129 @end defun | |
1130 | |
1131 @defun object-of-class-p obj class | |
1132 Returns @code{t} if @var{obj} inherits anything from @var{class}. This | |
1133 is different from @code{same-class-p} because it checks for inheritance. | |
1134 @end defun | |
1135 | |
1136 @defun child-of-class-p child class | |
1137 Returns @code{t} if @var{child} is a subclass of @var{class}. | |
1138 @end defun | |
1139 | |
1140 @defun generic-p method-symbol | |
1141 Returns @code{t} if @code{method-symbol} is a generic function, as | |
1142 opposed to a regular Emacs Lisp function. | |
1143 @end defun | |
1144 | |
1145 @node Association Lists | |
1146 @chapter Association Lists | |
1147 | |
1148 Lisp offers the concept of association lists, with primitives such as | |
1149 @code{assoc} used to access them. The following functions can be used | |
1150 to manage association lists of @eieio{} objects: | |
1151 | |
1152 @defun object-assoc key slot list | |
1153 @anchor{object-assoc} | |
1154 Return an object if @var{key} is @dfn{equal} to SLOT's value of an object in @var{list}. | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
1155 @var{list} is a list of objects whose slots are searched. |
105494 | 1156 Objects in @var{list} do not need to have a slot named @var{slot}, nor does |
1157 @var{slot} need to be bound. If these errors occur, those objects will | |
1158 be ignored. | |
1159 @end defun | |
1160 | |
1161 | |
1162 @defun object-assoc-list slot list | |
1163 Return an association list generated by extracting @var{slot} from all | |
1164 objects in @var{list}. For each element of @var{list} the @code{car} is | |
1165 the value of @var{slot}, and the @code{cdr} is the object it was | |
1166 extracted from. This is useful for generating completion tables. | |
1167 @end defun | |
1168 | |
1169 @defun eieio-build-class-alist &optional base-class | |
1170 Returns an alist of all currently defined classes. This alist is | |
1171 suitable for completion lists used by interactive functions to select a | |
1172 class. The optional argument @var{base-class} allows the programmer to | |
1173 select only a subset of classes which includes @var{base-class} and | |
1174 all its subclasses. | |
1175 @end defun | |
1176 | |
1177 @node Customizing | |
1178 @comment node-name, next, previous, up | |
1179 @chapter Customizing Objects | |
1180 | |
1181 @eieio{} supports the Custom facility through two new widget types. | |
1182 If a variable is declared as type @code{object}, then full editing of | |
1183 slots via the widgets is made possible. This should be used | |
1184 carefully, however, because modified objects are cloned, so if there | |
1185 are other references to these objects, they will no longer be linked | |
1186 together. | |
1187 | |
1188 If you want in place editing of objects, use the following methods: | |
1189 | |
1190 @defun eieio-customize-object object | |
1191 Create a custom buffer and insert a widget for editing @var{object}. At | |
1192 the end, an @code{Apply} and @code{Reset} button are available. This | |
1193 will edit the object "in place" so references to it are also changed. | |
1194 There is no effort to prevent multiple edits of a singular object, so | |
1195 care must be taken by the user of this function. | |
1196 @end defun | |
1197 | |
1198 @defun eieio-custom-widget-insert object flags | |
1199 This method inserts an edit object into the current buffer in place. | |
1200 It is implemented as @code{(widget-create 'object-edit :value object)}. | |
1201 This method is provided as a locale for adding tracking, or | |
1202 specializing the widget insert procedure for any object. | |
1203 @end defun | |
1204 | |
1205 To define a slot with an object in it, use the @code{object} tag. This | |
1206 widget type will be automatically converted to @code{object-edit} if you | |
1207 do in place editing of you object. | |
1208 | |
1209 If you want to have additional actions taken when a user clicks on the | |
1210 @code{Apply} button, then overload the method @code{eieio-done-customizing}. | |
1211 This method does nothing by default, but that may change in the future. | |
1212 This would be the best way to make your objects persistent when using | |
1213 in-place editing. | |
1214 | |
1215 @section Widget extention | |
1216 | |
1217 When widgets are being created, one new widget extention has been added, | |
1218 called the @code{:slotofchoices}. When this occurs in a widget | |
1219 definition, all elements after it are removed, and the slot is specifies | |
1220 is queried and converted into a series of constants. | |
1221 | |
1222 @example | |
1223 (choice (const :tag "None" nil) | |
1224 :slotofchoices morestuff) | |
1225 @end example | |
1226 | |
1227 and if the slot @code{morestuff} contains @code{(sym1 sym2 sym3)}, the | |
1228 above example is converted into: | |
1229 | |
1230 @example | |
1231 (choice (const :tag "None" nil) | |
1232 (const sym1) | |
1233 (const sym2) | |
1234 (const sym3)) | |
1235 @end example | |
1236 | |
1237 This is useful when a given item needs to be selected from a list of | |
1238 items defined in this second slot. | |
1239 | |
1240 @node Introspection | |
1241 @chapter Introspection | |
1242 | |
1243 Introspection permits a programmer to peek at the contents of a class | |
1244 without any previous knowledge of that class. While @eieio{} implements | |
1245 objects on top of vectors, and thus everything is technically visible, | |
1246 some functions have been provided. None of these functions are a part | |
1247 of CLOS. | |
1248 | |
1249 @defun object-slots obj | |
1250 Return the list of public slots for @var{obj}. | |
1251 @end defun | |
1252 | |
1253 @defun class-slot-initarg class slot | |
1254 For the given @var{class} return the :initarg associated with | |
1255 @var{slot}. Not all slots have initargs, so the return value can be | |
1256 nil. | |
1257 @end defun | |
1258 | |
1259 @node Base Classes | |
1260 @comment node-name, next, previous, up | |
1261 @chapter Base Classes | |
1262 | |
1263 All defined classes, if created with no specified parent class, | |
1264 inherit from a special class called @code{eieio-default-superclass}. | |
1265 @xref{Default Superclass}. | |
1266 | |
1267 Often, it is more convenient to inherit from one of the other base | |
1268 classes provided by @eieio{}, which have useful pre-defined | |
1269 properties. (Since @eieio{} supports multiple inheritance, you can | |
1270 even inherit from more than one of these classes at once.) | |
1271 | |
1272 @menu | |
1273 * eieio-instance-inheritor:: Enable value inheritance between instances. | |
1274 * eieio-instance-tracker:: Enable self tracking instances. | |
1275 * eieio-singleton:: Only one instance of a given class. | |
1276 * eieio-persistent:: Enable persistence for a class. | |
1277 * eieio-named:: Use the object name as a :name slot. | |
1278 * eieio-speedbar:: Enable speedbar support in your objects. | |
1279 @end menu | |
1280 | |
1281 @node eieio-instance-inheritor | |
1282 @comment node-name, next, previous, up | |
1283 @section @code{eieio-instance-inheritor} | |
1284 | |
1285 This class is defined in the package @file{eieio-base}. | |
1286 | |
1287 Instance inheritance is a mechanism whereby the value of a slot in | |
1288 object instance can reference the parent instance. If the parent's slot | |
1289 value is changed, then the child instance is also changed. If the | |
1290 child's slot is set, then the parent's slot is not modified. | |
1291 | |
1292 @deftp {Class} eieio-instance-inheritor parent-instance | |
1293 A class whose instances are enabled with instance inheritance. | |
1294 The @var{parent-instance} slot indicates the instance which is | |
1295 considered the parent of the current instance. Default is @code{nil}. | |
1296 @end deftp | |
1297 | |
1298 @cindex clone | |
1299 To use this class, inherit from it with your own class. | |
1300 To make a new instance that inherits from and existing instance of your | |
1301 class, use the @code{clone} method with additional parameters | |
1302 to specify local values. | |
1303 | |
1304 @cindex slot-unbound | |
1305 The @code{eieio-instance-inheritor} class works by causing cloned | |
1306 objects to have all slots unbound. This class' @code{slot-unbound} | |
1307 method will cause references to unbound slots to be redirected to the | |
1308 parent instance. If the parent slot is also unbound, then | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
1309 @code{slot-unbound} will signal an error named @code{slot-unbound}. |
105494 | 1310 |
1311 @node eieio-instance-tracker | |
1312 @section @code{eieio-instance-tracker} | |
1313 | |
1314 This class is defined in the package @file{eieio-base}. | |
1315 | |
1316 Sometimes it is useful to keep a master list of all instances of a given | |
1317 class. The class @code{eieio-instance-tracker} performs this task. | |
1318 | |
1319 @deftp {Class} eieio-instance-tracker tracker-symbol | |
1320 Enable instance tracking for this class. | |
1321 The slot @var{tracker-symbol} should be initialized in inheritors of | |
1322 this class to a symbol created with @code{defvar}. This symbol will | |
1323 serve as the variable used as a master list of all objects of the given | |
1324 class. | |
1325 @end deftp | |
1326 | |
1327 @defmethod eieio-instance-tracker initialize-instance obj slot | |
1328 This method is defined as an @code{:after} method. | |
1329 It adds new instances to the master list. Do not overload this method | |
1330 unless you use @code{call-next-method.} | |
1331 @end defmethod | |
1332 | |
1333 @defmethod eieio-instance-tracker delete-instance obj | |
1334 Remove @var{obj} from the master list of instances of this class. | |
1335 This may let the garbage collector nab this instance. | |
1336 @end defmethod | |
1337 | |
1338 @deffn eieio-instance-tracker-find key slot list-symbol | |
1339 This convenience function lets you find instances. @var{key} is the | |
1340 value to search for. @var{slot} is the slot to compare @var{KEY} | |
1341 against. The function @code{equal} is used for comparison. | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
1342 The parameter @var{list-symbol} is the variable symbol which contains the |
105494 | 1343 list of objects to be searched. |
1344 @end deffn | |
1345 | |
1346 @node eieio-singleton | |
1347 @comment node-name, next, previous, up | |
1348 @section @code{eieio-singleton} | |
1349 | |
1350 This class is defined in the package @file{eieio-base}. | |
1351 | |
1352 @deftp {Class} eieio-singleton | |
1353 Inheriting from the singleton class will guarantee that there will | |
1354 only ever be one instance of this class. Multiple calls to | |
1355 @code{make-instance} will always return the same object. | |
1356 @end deftp | |
1357 | |
1358 @node eieio-persistent | |
1359 @comment node-name, next, previous, up | |
1360 @section @code{eieio-persistent} | |
1361 | |
1362 This class is defined in the package @file{eieio-base}. | |
1363 | |
1364 If you want an object, or set of objects to be persistent, meaning the | |
1365 slot values are important to keep saved between sessions, then you will | |
1366 want your top level object to inherit from @code{eieio-persistent}. | |
1367 | |
1368 To make sure your persistent object can be moved, make sure all file | |
1369 names stored to disk are made relative with | |
1370 @code{eieio-persistent-path-relative}. | |
1371 | |
1372 @deftp {Class} eieio-persistent file file-header-line | |
1373 Enables persistence for instances of this class. | |
1374 Slot @var{file} with initarg @code{:file} is the file name in which this | |
1375 object will be saved. | |
1376 Class allocated slot @var{file-header-line} is used with method | |
1377 @code{object-write} as a header comment. | |
1378 @end deftp | |
1379 | |
1380 All objects can write themselves to a file, but persistent objects have | |
1381 several additional methods that aid in maintaining them. | |
1382 | |
1383 @defmethod eieio-persistent eieio-persistent-save obj &optional file | |
1384 Write the object @var{obj} to its file. | |
1385 If optional argument @var{file} is specified, use that file name | |
1386 instead. | |
1387 @end defmethod | |
1388 | |
1389 @defmethod eieio-persistent eieio-persistent-path-relative obj file | |
1390 Return a file name derived from @var{file} which is relative to the | |
1391 stored location of @var{OBJ}. This method should be used to convert | |
1392 file names so that they are relative to the save file, making any system | |
1393 of files movable from one location to another. | |
1394 @end defmethod | |
1395 | |
1396 @defmethod eieio-persistent object-write obj &optional comment | |
1397 Like @code{object-write} for @code{standard-object}, but will derive | |
1398 a header line comment from the class allocated slot if one is not | |
1399 provided. | |
1400 @end defmethod | |
1401 | |
1402 @defun eieio-persistent-read filename | |
1403 Read @var{filename} which contains an @code{eieio-persistent} object | |
1404 previously written with @code{eieio-persistent-save}. | |
1405 @end defun | |
1406 | |
1407 @node eieio-named | |
1408 @comment node-name, next, previous, up | |
1409 @section @code{eieio-named} | |
1410 | |
1411 This class is defined in the package @file{eieio-base}. | |
1412 | |
1413 @deftp {Class} eieio-named | |
1414 Object with a name. | |
1415 Name storage already occurs in an object. This object provides get/set | |
1416 access to it. | |
1417 @end deftp | |
1418 | |
1419 @node eieio-speedbar | |
1420 @comment node-name, next, previous, up | |
1421 @section @code{eieio-speedbar} | |
1422 | |
1423 This class is in package @file{eieio-speedbar}. | |
1424 | |
1425 If a series of class instances map to a tree structure, it is possible | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
1426 to cause your classes to be displayable in Speedbar. @xref{Top,,,speedbar}. |
105494 | 1427 Inheriting from these classes will enable a speedbar major display mode |
1428 with a minimum of effort. | |
1429 | |
1430 @deftp {Class} eieio-speedbar buttontype buttonface | |
1431 Enables base speedbar display for a class. | |
1432 @cindex speedbar-make-tag-line | |
1433 The slot @var{buttontype} is any of the symbols allowed by the | |
1434 function @code{speedbar-make-tag-line} for the @var{exp-button-type} | |
1435 argument @xref{Extending,,,speedbar}. | |
1436 The slot @var{buttonface} is the face to use for the text of the string | |
1437 displayed in speedbar. | |
1438 The slots @var{buttontype} and @var{buttonface} are class allocated | |
1439 slots, and do not take up space in your instances. | |
1440 @end deftp | |
1441 | |
1442 @deftp {Class} eieio-speedbar-directory-button buttontype buttonface | |
1443 This class inherits from @code{eieio-speedbar} and initializes | |
1444 @var{buttontype} and @var{buttonface} to appear as directory level lines. | |
1445 @end deftp | |
1446 | |
1447 @deftp {Class} eieio-speedbar-file-button buttontype buttonface | |
1448 This class inherits from @code{eieio-speedbar} and initializes | |
1449 @var{buttontype} and @var{buttonface} to appear as file level lines. | |
1450 @end deftp | |
1451 | |
1452 To use these classes, inherit from one of them in you class. You can | |
1453 use multiple inheritance with them safely. To customize your class for | |
1454 speedbar display, override the default values for @var{buttontype} and | |
1455 @var{buttonface} to get the desired effects. | |
1456 | |
1457 Useful methods to define for your new class include: | |
1458 | |
1459 @defmethod eieio-speedbar eieio-speedbar-derive-line-path obj depth | |
1460 Return a string representing a directory associated with an instance | |
1461 of @var{obj}. @var{depth} can be used to indice how many levels of | |
1462 indentation have been opened by the user where @var{obj} is shown. | |
1463 @end defmethod | |
1464 | |
1465 | |
1466 @defmethod eieio-speedbar eieio-speedbar-description obj | |
1467 Return a string description of @var{OBJ}. | |
1468 This is shown in the minibuffer or tooltip when the mouse hovers over | |
1469 this instance in speedbar. | |
1470 @end defmethod | |
1471 | |
1472 @defmethod eieio-speedbar eieio-speedbar-child-description obj | |
1473 Return a string representing a description of a child node of @var{obj} | |
1474 when that child is not an object. It is often useful to just use | |
1475 item info helper functions such as @code{speedbar-item-info-file-helper}. | |
1476 @end defmethod | |
1477 | |
1478 @defmethod eieio-speedbar eieio-speedbar-object-buttonname obj | |
1479 Return a string which is the text displayed in speedbar for @var{obj}. | |
1480 @end defmethod | |
1481 | |
1482 @defmethod eieio-speedbar eieio-speedbar-object-children obj | |
1483 Return a list of children of @var{obj}. | |
1484 @end defmethod | |
1485 | |
1486 @defmethod eieio-speedbar eieio-speedbar-child-make-tag-lines obj depth | |
1487 This method inserts a list of speedbar tag lines for @var{obj} to | |
1488 represent its children. Implement this method for your class | |
1489 if your children are not objects themselves. You still need to | |
1490 implement @code{eieio-speedbar-object-children}. | |
1491 | |
1492 In this method, use techniques specified in the Speedbar manual. | |
1493 @xref{Extending,,,speedbar}. | |
1494 @end defmethod | |
1495 | |
1496 Some other functions you will need to learn to use are: | |
1497 | |
1498 @deffn eieio-speedbar-create make-map key-map menu name toplevelfn | |
1499 Register your object display mode with speedbar. | |
1500 @var{make-map} is a function which initialized you keymap. | |
1501 @var{key-map} is a symbol you keymap is installed into. | |
1502 @var{menu} is an easy menu vector representing menu items specific to your | |
1503 object display. | |
1504 @var{name} is a short string to use as a name identifying you mode. | |
1505 @var{toplevelfn} is a function called which must return a list of | |
1506 objects representing those in the instance system you wish to browse in | |
1507 speedbar. | |
1508 | |
1509 Read the Extending chapter in the speedbar manual for more information | |
1510 on how speedbar modes work | |
1511 @xref{Extending,,,speedbar}. | |
1512 @end deffn | |
1513 | |
1514 @node Browsing | |
1515 @comment node-name, next, previous, up | |
1516 @chapter Browsing class trees | |
1517 | |
1518 The command @kbd{M-x eieio-browse} displays a buffer listing all the | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
1519 currently loaded classes in Emacs. The classes are listed in an |
105494 | 1520 indented tree structure, starting from @code{eieio-default-superclass} |
1521 (@pxref{Default Superclass}). | |
1522 | |
1523 With a prefix argument, this command prompts for a class name; it then | |
1524 lists only that class and its subclasses. | |
1525 | |
1526 Here is a sample tree from our current example: | |
1527 | |
1528 @example | |
1529 eieio-default-superclass | |
1530 +--data-object | |
1531 +--data-object-symbol | |
1532 @end example | |
1533 | |
1534 Note: new classes are consed into the inheritance lists, so the tree | |
1535 comes out upside-down. | |
1536 | |
1537 @node Class Values | |
1538 @comment node-name, next, previous, up | |
1539 @chapter Class Values | |
1540 | |
1541 Details about any class or object can be retrieved using the function | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
1542 @code{eieio-describe-class}. Interactively, type in the name of |
105494 | 1543 a class. In a program, pass it a string with the name of a class, a |
1544 class symbol, or an object. The resulting buffer will display all slot | |
1545 names. | |
1546 | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
1547 Additionally, all methods defined to have functionality on this class |
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
1548 are displayed. |
105494 | 1549 |
1550 @node Default Superclass | |
1551 @comment node-name, next, previous, up | |
1552 @chapter Default Superclass | |
1553 | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
1554 All defined classes, if created with no specified parent class, will |
105494 | 1555 inherit from a special class stored in |
1556 @code{eieio-default-superclass}. This superclass is quite simple, but | |
1557 with it, certain default methods or attributes can be added to all | |
1558 objects. In CLOS, this would be named @code{STANDARD-CLASS}, and that | |
1559 symbol is an alias to @code{eieio-default-superclass}. | |
1560 @refill | |
1561 | |
1562 Currently, the default superclass is defined as follows: | |
1563 | |
1564 @example | |
1565 (defclass eieio-default-superclass nil | |
1566 nil | |
1567 "Default parent class for classes with no specified parent class. | |
1568 Its slots are automatically adopted by classes with no specified | |
1569 parents. This class is not stored in the `parent' slot of a class vector." | |
1570 :abstract t) | |
1571 @end example | |
1572 | |
1573 The default superclass implements several methods providing a default | |
1574 behavior for all objects created by @eieio{}. | |
1575 | |
1576 @menu | |
1577 * Initialization:: How objects are initialized | |
1578 * Basic Methods:: Clone, print, and write | |
1579 * Signal Handling:: Methods for managing signals. | |
1580 @end menu | |
1581 | |
1582 @node Initialization | |
1583 @section Initialization | |
1584 | |
1585 When creating an object of any type, you can use its constructor, or | |
1586 @code{make-instance}. This, in turns calls the method | |
1587 @code{initialize-instance}, which then calls the method | |
1588 @code{shared-initialize}. | |
1589 | |
1590 These methods are all implemented on the default superclass so you do | |
1591 not need to write them yourself, unless you need to override one of | |
1592 their behaviors. | |
1593 | |
1594 Users should not need to call @code{initialize-instance} or | |
1595 @code{shared-initialize}, as these are used by @code{make-instance} to | |
1596 initialize the object. They are instead provided so that users can | |
1597 augment these behaviors. | |
1598 | |
1599 @defun initialize-instance obj &rest slots | |
1600 Initialize @var{obj}. Sets slots of @var{obj} with @var{slots} which | |
1601 is a list of name/value pairs. These are actually just passed to | |
1602 @code{shared-initialize}. | |
1603 @end defun | |
1604 | |
1605 @defun shared-initialize obj &rest slots | |
1606 Sets slots of @var{obj} with @var{slots} which is a list of name/value | |
1607 pairs. | |
1608 | |
1609 This is called from the default @code{constructor}. | |
1610 @end defun | |
1611 | |
1612 @node Basic Methods | |
1613 @section Basic Methods | |
1614 | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
1615 Additional useful methods defined on the base subclass are: |
105494 | 1616 |
1617 @defun clone obj &rest params | |
1618 @anchor{clone} | |
1619 Make a copy of @var{obj}, and then apply @var{params}. | |
1620 @var{params} is a parameter list of the same form as @var{initialize-instance} | |
1621 which are applied to change the object. When overloading @dfn{clone}, be | |
1622 sure to call @dfn{call-next-method} first and modify the returned object. | |
1623 @end defun | |
1624 | |
1625 @defun object-print this &rest strings | |
1626 @anchor{object-print} | |
1627 Pretty printer for object @var{this}. Call function @dfn{object-name} with @var{strings}. | |
1628 The default method for printing object @var{this} is to use the | |
1629 function @dfn{object-name}. | |
1630 | |
1631 It is sometimes useful to put a summary of the object into the | |
1632 default #<notation> string when using eieio browsing tools. | |
1633 | |
1634 Implement this function and specify @var{strings} in a call to | |
1635 @dfn{call-next-method} to provide additional summary information. | |
1636 When passing in extra strings from child classes, always remember | |
1637 to prepend a space. | |
1638 | |
1639 @example | |
1640 (defclass data-object () | |
1641 (value) | |
1642 "Object containing one data slot.") | |
1643 | |
1644 (defmethod object-print ((this data-object) &optional strings) | |
1645 "Return a string with a summary of the data object as part of the name." | |
1646 (apply 'call-next-method this | |
1647 (cons (format " value: %s" (render this)) strings))) | |
1648 @end example | |
1649 | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
1650 Here is what some output could look like: |
105494 | 1651 @example |
1652 (object-print test-object) | |
1653 => #<data-object test-object value: 3> | |
1654 @end example | |
1655 @end defun | |
1656 | |
1657 @defun object-write obj &optional comment | |
1658 Write @var{obj} onto a stream in a readable fashion. The resulting | |
1659 output will be Lisp code which can be used with @code{read} and | |
1660 @code{eval} to recover the object. Only slots with @code{:initarg}s | |
1661 are written to the stream. | |
1662 @end defun | |
1663 | |
1664 @node Signal Handling | |
1665 @section Signal Handling | |
1666 | |
1667 The default superclass defines methods for managing error conditions. | |
1668 These methods all throw a signal for a particular error condition. | |
1669 | |
1670 By implementing one of these methods for a class, you can change the | |
1671 behavior that occurs during one of these error cases, or even ignore | |
1672 the error by providing some behavior. | |
1673 | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
1674 @defun slot-missing object slot-name operation &optional new-value |
105494 | 1675 @anchor{slot-missing} |
1676 Method invoked when an attempt to access a slot in @var{object} fails. | |
1677 @var{slot-name} is the name of the failed slot, @var{operation} is the type of access | |
1678 that was requested, and optional @var{new-value} is the value that was desired | |
1679 to be set. | |
1680 | |
1681 This method is called from @code{oref}, @code{oset}, and other functions which | |
1682 directly reference slots in EIEIO objects. | |
1683 | |
1684 The default method signals an error of type @code{invalid-slot-name}. | |
1685 @xref{Signals}. | |
1686 | |
1687 You may override this behavior, but it is not expected to return in the | |
1688 current implementation. | |
1689 | |
1690 This function takes arguments in a different order than in CLOS. | |
1691 @end defun | |
1692 | |
1693 @defun slot-unbound object class slot-name fn | |
1694 @anchor{slot-unbound} | |
1695 Slot unbound is invoked during an attempt to reference an unbound slot. | |
1696 @var{object} is the instance of the object being reference. @var{class} is the | |
1697 class of @var{object}, and @var{slot-name} is the offending slot. This function | |
1698 throws the signal @code{unbound-slot}. You can overload this function and | |
1699 return the value to use in place of the unbound value. | |
1700 Argument @var{fn} is the function signaling this error. | |
1701 Use @dfn{slot-boundp} to determine if a slot is bound or not. | |
1702 | |
1703 In @var{clos}, the argument list is (@var{class} @var{object} @var{slot-name}), but | |
1704 @var{eieio} can only dispatch on the first argument, so the first two are swapped. | |
1705 @end defun | |
1706 | |
1707 @defun no-applicable-method object method &rest args | |
1708 @anchor{no-applicable-method} | |
1709 Called if there are no implementations for @var{object} in @var{method}. | |
1710 @var{object} is the object which has no method implementation. | |
1711 @var{args} are the arguments that were passed to @var{method}. | |
1712 | |
1713 Implement this for a class to block this signal. The return | |
1714 value becomes the return value of the original method call. | |
1715 @end defun | |
1716 | |
1717 @defun no-next-method object &rest args | |
1718 @anchor{no-next-method} | |
1719 Called from @dfn{call-next-method} when no additional methods are available. | |
1720 @var{object} is othe object being called on @dfn{call-next-method}. | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
1721 @var{args} are the arguments it is called by. |
105494 | 1722 This method signals @dfn{no-next-method} by default. Override this |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
1723 method to not throw an error, and its return value becomes the |
105494 | 1724 return value of @dfn{call-next-method}. |
1725 @end defun | |
1726 | |
1727 @node Signals | |
1728 @comment node-name, next, previous, up | |
1729 @chapter Signals | |
1730 | |
1731 There are new condition names (signals) that can be caught when using | |
1732 @eieio{}. | |
1733 | |
1734 @deffn Signal invalid-slot-name obj-or-class slot | |
1735 This signal is called when an attempt to reference a slot in an | |
1736 @var{obj-or-class} is made, and the @var{slot} is not defined for | |
1737 it. | |
1738 @end deffn | |
1739 | |
1740 @deffn Signal no-method-definition method arguments | |
1741 This signal is called when @var{method} is called, with @var{arguments} | |
1742 and nothing is resolved. This occurs when @var{method} has been | |
1743 defined, but the arguments make it impossible for @eieio{} to determine | |
1744 which method body to run. | |
1745 | |
1746 To prevent this signal from occurring in your class, implement the | |
1747 method @code{no-applicable-method} for your class. This method is | |
1748 called when to throw this signal, so implementing this for your class | |
1749 allows you block the signal, and perform some work. | |
1750 @end deffn | |
1751 | |
1752 @deffn Signal no-next-method class arguments | |
1753 This signal is called if the function @code{call-next-method} is called | |
1754 and there is no next method to be called. | |
1755 | |
1756 Overload the method @code{no-next-method} to protect against this signal. | |
1757 @end deffn | |
1758 | |
1759 @deffn Signal invalid-slot-type slot spec value | |
1760 This signal is called when an attempt to set @var{slot} is made, and | |
1761 @var{value} doesn't match the specified type @var{spec}. | |
1762 | |
1763 In @eieio{}, this is also used if a slot specifier has an invalid value | |
1764 during a @code{defclass}. | |
1765 @end deffn | |
1766 | |
1767 @deffn Signal unbound-slot object class slot | |
1768 This signal is called when an attempt to reference @var{slot} in | |
1769 @var{object} is made, and that instance is currently unbound. | |
1770 @end deffn | |
1771 | |
1772 @node Naming Conventions | |
1773 @comment node-name, next, previous, up | |
1774 @chapter Naming Conventions | |
1775 | |
106719
b7f28f66e31e
eieio.texi (Naming Conventions): Correction to xref on elisp
Eli Zaretskii <eliz@gnu.org>
parents:
105754
diff
changeset
|
1776 @xref{Tips,,Tips and Conventions,elisp,GNU Emacs Lisp Reference |
b7f28f66e31e
eieio.texi (Naming Conventions): Correction to xref on elisp
Eli Zaretskii <eliz@gnu.org>
parents:
105754
diff
changeset
|
1777 Manual}, for a description of Emacs Lisp programming conventions. |
b7f28f66e31e
eieio.texi (Naming Conventions): Correction to xref on elisp
Eli Zaretskii <eliz@gnu.org>
parents:
105754
diff
changeset
|
1778 These conventions help ensure that Emacs packages work nicely one |
b7f28f66e31e
eieio.texi (Naming Conventions): Correction to xref on elisp
Eli Zaretskii <eliz@gnu.org>
parents:
105754
diff
changeset
|
1779 another, so an @eieio{}-based program should follow them. Here are |
b7f28f66e31e
eieio.texi (Naming Conventions): Correction to xref on elisp
Eli Zaretskii <eliz@gnu.org>
parents:
105754
diff
changeset
|
1780 some conventions that apply specifically to @eieio{}-based programs: |
105494 | 1781 |
1782 @itemize | |
1783 | |
1784 @item Come up with a package prefix that is relatively short. Prefix | |
1785 all classes, and methods with your prefix. This is a standard | |
1786 convention for functions and variables in Emacs. | |
1787 | |
1788 @item Do not prefix method names with the class name. All methods in | |
1789 @eieio{} are ``virtual'', and are dynamically dispatched. Anyone can | |
1790 override your methods at any time. Your methods should be prefixed | |
1791 with your package name. | |
1792 | |
1793 @item Do not prefix slots in your class. The slots are always locally | |
1794 scoped to your class, and need no prefixing. | |
1795 | |
1796 @item If your library inherits from other libraries of classes, you | |
1797 must ``require'' that library with the @code{require} command. | |
1798 | |
1799 @end itemize | |
1800 | |
1801 @node CLOS compatibility | |
1802 @comment node-name, next, previous, up | |
1803 @chapter CLOS compatibility | |
1804 | |
1805 Currently, the following functions should behave almost as expected from | |
1806 CLOS. | |
1807 | |
1808 @table @code | |
1809 | |
1810 @item defclass | |
1811 All slot keywords are available but not all work correctly. | |
1812 Slot keyword differences are: | |
1813 | |
1814 @table @asis | |
1815 | |
1816 @item :reader, and :writer tags | |
1817 Create methods that signal errors instead of creating an unqualified | |
1818 method. You can still create new ones to do its business. | |
1819 | |
1820 @item :accessor | |
1821 This should create an unqualified method to access a slot, but | |
1822 instead pre-builds a method that gets the slot's value. | |
1823 | |
1824 @item :type | |
1825 Specifier uses the @code{typep} function from the @file{cl} | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
1826 package. @xref{(cl)Type Predicates}. It therefore has the same issues as |
105494 | 1827 that package. Extensions include the ability to provide object names. |
1828 @end table | |
1829 | |
1830 Defclass also supports class options, but does not currently use values | |
1831 of @code{:metaclass}, and @code{:default-initargs}. | |
1832 | |
1833 @item make-instance | |
1834 Make instance works as expected, however it just uses the @eieio{} instance | |
1835 creator automatically generated when a new class is created. | |
1836 @xref{Making New Objects}. | |
1837 | |
1838 @item defgeneric | |
1839 Creates the desired symbol, and accepts all of the expected arguments | |
1840 except @code{:around}. | |
1841 | |
1842 @item defmethod | |
1843 Calls defgeneric, and accepts most of the expected arguments. Only | |
1844 the first argument to the created method may have a type specifier. | |
1845 To type cast against a class, the class must exist before defmethod is | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
1846 called. In addition, the @code{:around} tag is not supported. |
105494 | 1847 |
1848 @item call-next-method | |
1849 Inside a method, calls the next available method up the inheritance tree | |
1850 for the given object. This is different than that found in CLOS because | |
1851 in @eieio{} this function accepts replacement arguments. This permits | |
1852 subclasses to modify arguments as they are passed up the tree. If no | |
1853 arguments are given, the expected CLOS behavior is used. | |
1854 @item setf | |
1855 If the common-lisp subsystem is loaded, the setf parameters are also | |
1856 loaded so the form @code{(setf (slot-value object slot) t)} should | |
1857 work. | |
1858 @end table | |
1859 | |
1860 CLOS supports the @code{describe} command, but @eieio{} only provides | |
1861 @code{eieio-describe-class}, and @code{eieio-describe-generic}. These | |
1862 functions are adviced into @code{describe-variable}, and | |
1863 @code{describe-function}. | |
1864 | |
1865 When creating a new class (@pxref{Building Classes}) there are several | |
1866 new keywords supported by @eieio{}. | |
1867 | |
1868 In @eieio{} tags are in lower case, not mixed case. | |
1869 | |
1870 @node Wish List | |
1871 @chapter Wish List | |
1872 | |
1873 @eieio{} is an incomplete implementation of CLOS. Finding ways to | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
1874 improve the compatibility would help make CLOS style programs run |
105494 | 1875 better in Emacs. |
1876 | |
105528
6d711c116f28
* eieio.texi: Fix typos.
Juanma Barranquero <lekktu@gmail.com>
parents:
105494
diff
changeset
|
1877 Some important compatibility features that would be good to add are: |
105494 | 1878 |
1879 @enumerate | |
1880 @item | |
1881 @code{:around} method key. | |
1882 | |
1883 @item | |
1884 Method dispatch for built-in types. | |
1885 @item | |
1886 Method dispatch for multiple argument typing. | |
1887 @item | |
1888 Improve integration with the @file{cl} package. | |
1889 @end enumerate | |
1890 | |
1891 There are also improvements to be made to allow @eieio{} to operate | |
1892 better in the Emacs environment. | |
1893 | |
1894 @enumerate | |
1895 @item | |
1896 Allow subclasing of Emacs built-in types, such as faces, markers, and | |
1897 buffers. | |
1898 @item | |
1899 Allow method overloading of method-like functions in Emacs. | |
1900 @end enumerate | |
1901 | |
1902 @node Function Index | |
1903 @unnumbered Function Index | |
1904 | |
1905 @printindex fn | |
1906 | |
1907 @contents | |
1908 @bye | |
105754 | 1909 |
1910 @ignore | |
1911 arch-tag: 7225b7c7-2462-4563-99e7-836a20172178 | |
1912 @end ignore |