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