105494
|
1 \input texinfo
|
|
2 @setfilename ../../info/eieio
|
|
3 @set TITLE Enhanced Implementation of Emacs Interpreted Objects
|
|
4 @set AUTHOR Eric M. Ludlam
|
|
5 @settitle @value{TITLE}
|
|
6
|
|
7 @c *************************************************************************
|
|
8 @c @ Header
|
|
9 @c *************************************************************************
|
|
10
|
|
11 @copying
|
|
12 This manual documents EIEIO, an object framework for Emacs Lisp.
|
|
13
|
|
14 Copyright @copyright{} 2007, 2008, 2009 Free Software Foundation, Inc.
|
|
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}
|
|
175 error. @ref{Signals}.
|
|
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
|
|
472 that default value with @code{oset-default}. @ref{Accessing Slots}.
|
|
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
|
|
545 should accept one argument. The a rgument is the value from the slot
|
|
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
|
|
549 The output format MUST be something that could in turn be interpreted
|
|
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
|
|
648 Suppose we have defined a simple class is defined, such as:
|
|
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
|
|
685 To create an object from a class symbol, use use @code{make-instance}.
|
|
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
|
|
703 Compatability note:
|
|
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
|
|
733 class has been constructed, and provides a way to to configure the
|
|
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
|
|
820 @var{slot}. A Slot specified without a variable name is given a
|
|
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
|
|
1073 @var{CLASS}. This function provides a way to make an object of a class
|
|
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}.
|
|
1079 This should look like Lisp symbols from other parts of emacs such as
|
|
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}.
|
|
1158 @var{list} is a list of objects who's slots are searched.
|
|
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
|
|
1312 @code{slot-unbound} will signal an an error named @code{slot-unbound}.
|
|
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.
|
|
1345 The paramter @var{list-symbol} is the variable symbol which contains the
|
|
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
|
|
1429 to cause your classes to be displayable in Speedbar. @xref{Top,,,speedbar}.
|
|
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
|
|
1522 currently loaded classes in emacs. The classes are listed in an
|
|
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
|
|
1545 @code{eieio-describe-class} function. Interactively, type in the name of
|
|
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
|
|
1550 Additionally, all methods defined to have functionality on this class is
|
|
1551 displayed.
|
|
1552
|
|
1553 @node Default Superclass
|
|
1554 @comment node-name, next, previous, up
|
|
1555 @chapter Default Superclass
|
|
1556
|
|
1557 All defined classes, if created with no specified parent class) will
|
|
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
|
|
1618 Additional useful methods defined on the base sublcass are:
|
|
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
|
|
1653 here is what some output could look like:
|
|
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
|
|
1677 @defun slot-missing ab &rest foo
|
|
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}.
|
|
1724 @var{args} are the arguments it is called by.
|
|
1725 This method signals @dfn{no-next-method} by default. Override this
|
|
1726 method to not throw an error, and it's return value becomes the
|
|
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
|
|
1779 @pxref{Standards,,,elisp,GNU Emacs Lisp Reference Manual}, for a
|
|
1780 description of Emacs Lisp programming conventions. These conventions
|
|
1781 help ensure that Emacs packages work nicely one another, so an
|
|
1782 @eieio{}-based program should follow them. Here are some conventions
|
|
1783 that apply specifically to @eieio{}-based programs:
|
|
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}
|
|
1829 package. @xref{(cl)Type Predicates}. It therefore has the same issues as
|
|
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
|
|
1849 called. In addition, the @code{:around} tag is not supported.
|
|
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
|
|
1877 improve the compatability would help make CLOS style programs run
|
|
1878 better in Emacs.
|
|
1879
|
|
1880 Some important compatability features that would be good to add are:
|
|
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
|