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