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