comparison doc/misc/eieio.texi @ 105494:6104e7688824

* eieio.texi: * ede.texi: New files. * Makefile.in: Build EIEIO and EDE manuals.
author Chong Yidong <cyd@stupidchicken.com>
date Wed, 07 Oct 2009 01:10:52 +0000
parents
children 6d711c116f28
comparison
equal deleted inserted replaced
105493:c8d4e5f3f0c8 105494:6104e7688824
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