2 @setfilename ../../info/eieio
3 @set TITLE Enhanced Implementation of Emacs Interpreted Objects
4 @set AUTHOR Eric M. Ludlam
5 @settitle @value{TITLE}
7 @c *************************************************************************
9 @c *************************************************************************
12 This manual documents EIEIO, an object framework for Emacs Lisp.
14 Copyright @copyright{} 2007-2012 Free Software Foundation, Inc.
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.''
24 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
25 modify this GNU manual.''
29 @dircategory Emacs misc features
31 * EIEIO: (eieio). An objects system for Emacs Lisp.
35 @center @titlefont{@value{TITLE}}
37 @center by @value{AUTHOR}
45 @node Top, Quick Start, (dir), (dir)
46 @comment node-name, next, previous, up
49 @eieio{} (``Enhanced Implementation of Emacs Interpreted Objects'') is
50 a CLOS (Common Lisp Object System) compatibility layer for Emacs Lisp.
51 It provides a framework for writing object-oriented applications in
59 * Quick Start:: Quick start for EIEIO.
60 * Introduction:: Why use @eieio{}? Basic overview, samples list.
61 * Building Classes:: How to write new class structures.
62 * Making New Objects:: How to construct new objects.
63 * Accessing Slots:: How to access a slot.
64 * Writing Methods:: How to write a method.
65 * Method Invocation:: How methods are invoked.
66 * Predicates:: Class-p, Object-p, etc-p.
67 * Association Lists:: List of objects as association lists.
68 * Customizing:: Customizing objects.
69 * Introspection:: Looking inside a class.
70 * Base Classes:: Additional classes you can inherit from.
71 * Browsing:: Browsing your class lists.
72 * Class Values:: Displaying information about a class or object.
73 * Documentation:: Automatically creating texinfo documentation.
74 * Default Superclass:: The root superclasses.
75 * Signals:: When you make errors.
76 * Naming Conventions:: Name your objects in an Emacs friendly way.
77 * CLOS compatibility:: What are the differences?
78 * Wish List:: Things about EIEIO that could be improved.
85 @eieio{} provides an Object Oriented layer for Emacs Lisp. You can
86 use @eieio{} to create classes, methods for those classes, and
89 Here is a simple example of a class named @code{record}, containing
90 three slots named @code{name}, @code{birthday}, and @code{phone}:
93 (defclass record () ; No superclasses
98 :documentation "The name of a person.")
99 (birthday :initarg :birthday
100 :initform "Jan 1, 1970"
103 :documentation "The person's birthday.")
104 (phone :initarg :phone
106 :documentation "Phone number."))
107 "A single record for tracking people I know.")
110 Each class can have methods, which are defined like this:
113 (defmethod call-record ((rec record) &optional scriptname)
114 "Dial the phone for the record REC.
115 Execute the program SCRIPTNAME to dial the phone."
116 (message "Dialing the phone for %s" (oref rec name))
117 (shell-command (concat (or scriptname "dialphone.sh")
123 In this example, the first argument to @code{call-record} is a list,
124 of the form (@var{varname} @var{classname}). @var{varname} is the
125 name of the variable used for the first argument; @var{classname} is
126 the name of the class that is expected as the first argument for this
129 @eieio{} dispatches methods based on the type of the first argument.
130 You can have multiple methods with the same name for different classes
131 of object. When the @code{call-record} method is called, the first
132 argument is examined to determine the class of that argument, and the
133 method matching the input type is then executed.
135 Once the behavior of a class is defined, you can create a new
136 object of type @code{record}. Objects are created by calling the
137 constructor. The constructor is a function with the same name as your
138 class which returns a new instance of that class. Here is an example:
141 (setq rec (record "Eric" :name "Eric" :birthday "June" :phone "555-5555"))
145 The first argument is the name given to this instance. Each instance
146 is given a name, so different instances can be easily distinguished
149 It can be a bit repetitive to also have a :name slot. To avoid doing
150 this, it is sometimes handy to use the base class @code{eieio-named}.
153 Calling methods on an object is a lot like calling any function. The
154 first argument should be an object of a class which has had this
155 method defined for it. In this example it would look like this:
165 (call-record rec "my-call-script")
168 In these examples, @eieio{} automatically examines the class of
169 @code{rec}, and ensures that the method defined above is called. If
170 @code{rec} is some other class lacking a @code{call-record} method, or
171 some other data type, Emacs signals a @code{no-method-definition}
172 error. @ref{Signals}.
175 @comment node-name, next, previous, up
176 @chapter Introduction
178 Due to restrictions in the Emacs Lisp language, CLOS cannot be
179 completely supported, and a few functions have been added in place of
182 @eieio{} supports the following features:
186 A structured framework for the creation of basic classes with attributes
187 and methods using singular inheritance similar to CLOS.
189 Type checking, and slot unbinding.
191 Method definitions similar to CLOS.
193 Simple and complex class browsers.
195 Edebug support for methods.
199 Byte compilation support of methods.
201 Help system extensions for classes and methods.
203 Automatic texinfo documentation generator.
205 Several base classes for interesting tasks.
209 Public and private classifications for slots (extensions to CLOS)
211 Customization support in a class (extension to CLOS)
214 Here are some CLOS features that @eieio{} presently lacks:
217 @item Complete @code{defclass} tag support
218 All CLOS tags are currently supported, but the following are not
219 currently implemented correctly:
223 There is only one base superclass for all @eieio{} classes, which is
224 the @code{eieio-default-superclass}.
225 @item :default-initargs
226 Each slot has an @code{:initarg} tag, so this is not really necessary.
229 @item Mock object initializers
230 Each class contains a mock object used for fast initialization of
231 instantiated objects. Using functions with side effects on object slot
232 values can potentially cause modifications in the mock object. @eieio{}
233 should use a deep copy but currently does not.
235 @item @code{:around} method tag
236 This CLOS method tag is non-functional.
240 @node Building Classes
241 @comment node-name, next, previous, up
242 @chapter Building Classes
244 A @dfn{class} is a definition for organizing data and methods
245 together. An @eieio{} class has structures similar to the classes
246 found in other object-oriented (OO) languages.
248 To create a new class, use the @code{defclass} macro:
250 @defmac defclass class-name superclass-list slot-list &rest options-and-doc
252 Create a new class named @var{class-name}. The class is represented
253 by a self-referential symbol with the name @var{class-name}. @eieio{}
254 stores the structure of the class as a symbol property of
255 @var{class-name} (@pxref{Symbol Components,,,elisp,GNU Emacs Lisp
258 The @var{class-name} symbol's variable documentation string is a
259 modified version of the doc string found in @var{options-and-doc}.
260 Each time a method is defined, the symbol's documentation string is
261 updated to include the methods documentation as well.
263 The parent classes for @var{class-name} is @var{superclass-list}.
264 Each element of @var{superclass-list} must be a class. These classes
265 are the parents of the class being created. Every slot that appears
266 in each parent class is replicated in the new class.
268 If two parents share the same slot name, the parent which appears in
269 the @var{superclass-list} first sets the tags for that slot. If the
270 new class has a slot with the same name as the parent, the new slot
271 overrides the parent's slot.
273 When overriding a slot, some slot attributes cannot be overridden
274 because they break basic OO rules. You cannot override @code{:type}
275 or @code{:protection}.
279 Whenever defclass is used to create a new class, two predicates are
280 created for it, named @code{@var{CLASS-NAME}-p} and
281 @code{@var{CLASS-NAME}-child-p}:
283 @defun CLASS-NAME-p object
284 Return @code{t} if @var{OBJECT} is of the class @var{CLASS-NAME}.
287 @defun CLASS-NAME-child-p object
288 Return @code{t} if @var{OBJECT} is of the class @var{CLASS-NAME},
289 or is of a subclass of @var{CLASS-NAME}.
292 @defvar eieio-error-unsupported-class-tags
293 If non-nil, @code{defclass} signals an error if a tag in a slot
294 specifier is unsupported.
296 This option is here to support programs written with older versions of
297 @eieio{}, which did not produce such errors.
301 * Inheritance:: How to specify parents classes.
302 * Slot Options:: How to specify features of a slot.
303 * Class Options:: How to specify features for this class.
309 @dfn{Inheritance} is a basic feature of an object-oriented language.
310 In @eieio{}, a defined class specifies the super classes from which it
311 inherits by using the second argument to @code{defclass}. Here is an
315 (defclass my-baseclass ()
316 ((slot-A :initarg :slot-A)
317 (slot-B :initarg :slot-B))
322 To subclass from @code{my-baseclass}, we specify it in the superclass
326 (defclass my-subclass (my-baseclass)
327 ((specific-slot-A :initarg specific-slot-A)
329 "My subclass of my-baseclass")
333 Instances of @code{my-subclass} will inherit @code{slot-A} and
334 @code{slot-B}, in addition to having @code{specific-slot-A} from the
335 declaration of @code{my-subclass}.
337 @eieio{} also supports multiple inheritance. Suppose we define a
338 second baseclass, perhaps an ``interface'' class, like this:
341 (defclass my-interface ()
342 ((interface-slot :initarg :interface-slot))
343 "An interface to special behavior."
348 The interface class defines a special @code{interface-slot}, and also
349 specifies itself as abstract. Abstract classes cannot be
350 instantiated. It is not required to make interfaces abstract, but it
351 is a good programming practice.
353 We can now modify our definition of @code{my-subclass} to use this
354 interface class, together with our original base class:
357 (defclass my-subclass (my-baseclass my-interface)
358 ((specific-slot-A :initarg specific-slot-A)
360 "My subclass of my-baseclass")
364 With this, @code{my-subclass} also has @code{interface-slot}.
366 If @code{my-baseclass} and @code{my-interface} had slots with the same
367 name, then the superclass showing up in the list first defines the
370 Inheritance in @eieio{} is more than just combining different slots.
371 It is also important in method invocation. @ref{Methods}.
373 If a method is called on an instance of @code{my-subclass}, and that
374 method only has an implementation on @code{my-baseclass}, or perhaps
375 @code{my-interface}, then the implementation for the baseclass is
378 If there is a method implementation for @code{my-subclass}, and
379 another in @code{my-baseclass}, the implementation for
380 @code{my-subclass} can call up to the superclass as well.
383 @section Slot Options
385 The @var{slot-list} argument to @code{defclass} is a list of elements
386 where each element defines one slot. Each slot is a list of the form
389 (SLOT-NAME :TAG1 ATTRIB-VALUE1
395 where @var{SLOT-NAME} is a symbol that will be used to refer to the
396 slot. @var{:TAG} is a symbol that describes a feature to be set
397 on the slot. @var{ATTRIB-VALUE} is a lisp expression that will be
404 A symbol that can be used in the argument list of the constructor to
405 specify a value for the new instance being created.
407 A good symbol to use for initarg is one that starts with a colon @code{:}.
409 The slot specified like this:
411 (myslot :initarg :myslot)
413 could then be initialized to the number 1 like this:
415 (myobject "name" :myslot 1)
418 @xref{Making New Objects}.
421 A expression used as the default value for this slot.
423 If @code{:initform} is left out, that slot defaults to being unbound.
424 It is an error to reference an unbound slot, so if you need
425 slots to always be in a bound state, you should always use an
426 @code{:initform} specifier.
428 Use @code{slot-boundp} to test if a slot is unbound
429 (@pxref{Predicates}). Use @code{slot-makeunbound} to set a slot to
430 being unbound after giving it a value (@pxref{Accessing Slots}).
432 The value passed to initform is automatically quoted. Thus,
436 appears as the specified list in the default object.
437 A symbol that is a function like this:
441 will set the initial value as that symbol.
443 After a class has been created with @code{defclass}, you can change
444 that default value with @code{oset-default}. @ref{Accessing Slots}.
447 An unquoted type specifier used to validate data set into this slot.
448 @xref{(cl)Type Predicates}.
449 Here are some examples:
456 An object of your class type.
457 @item (or null symbol)
462 Either :class or :instance (defaults to :instance) used to
463 specify how data is stored. Slots stored per instance have unique
464 values for each object. Slots stored per class have shared values for
465 each object. If one object changes a :class allocated slot, then all
466 objects for that class gain the new value.
469 Documentation detailing the use of this slot. This documentation is
470 exposed when the user describes a class, and during customization of an
474 Name of a generic function which can be used to fetch the value of this slot.
475 You can call this function later on your object and retrieve the value
478 This options is in the CLOS spec, but is not fully compliant in @eieio{}.
481 Name of a generic function which will write this slot.
483 This options is in the CLOS spec, but is not fully compliant in @eieio{}.
486 Name of a generic function which will read this slot.
488 This options is in the CLOS spec, but is not fully compliant in @eieio{}.
491 A custom :type specifier used when editing an object of this type.
492 See documentation for @code{defcustom} for details. This specifier is
493 equivalent to the :type spec of a @code{defcustom} call.
495 This options is specific to Emacs, and is not in the CLOS spec.
498 When customizing an object, the value of :label will be used instead
499 of the slot name. This enables better descriptions of the data than
500 would usually be afforded.
502 This options is specific to Emacs, and is not in the CLOS spec.
505 Similar to @code{defcustom}'s :group command, this organizes different
506 slots in an object into groups. When customizing an object, only the
507 slots belonging to a specific group need be worked with, simplifying the
510 This options is specific to Emacs, and is not in the CLOS spec.
513 This routine takes a symbol which is a function name. The function
514 should accept one argument. The argument is the value from the slot
515 to be printed. The function in @code{object-write} will write the
516 slot value out to a printable form on @code{standard-output}.
518 The output format MUST be something that could in turn be interpreted
519 with @code{read} such that the object can be brought back in from the
520 output stream. Thus, if you wanted to output a symbol, you would need
521 to quote the symbol. If you wanted to run a function on load, you
522 can output the code to do the construction of the value.
525 When using a slot referencing function such as @code{slot-value}, and
526 the value behind @var{slot} is private or protected, then the current
527 scope of operation must be within a method of the calling object.
533 Access this slot from any scope.
535 Access this slot only from methods of the same class or a child class.
537 Access this slot only from methods of the same class.
540 This options is specific to Emacs, and is not in the CLOS spec.
545 @section Class Options
547 In the @var{options-and-doc} arguments to @code{defclass}, the
548 following class options may be specified:
552 A documentation string for this class.
554 If an Emacs-style documentation string is also provided, then this
555 option is ignored. An Emacs-style documentation string is not
556 prefixed by the @code{:documentation} tag, and appears after the list
557 of slots, and before the options.
559 @item :allow-nil-initform
560 If this option is non-nil, and the @code{:initform} is @code{nil}, but
561 the @code{:type} is specifies something such as @code{string} then allow
562 this to pass. The default is to have this option be off. This is
563 implemented as an alternative to unbound slots.
565 This options is specific to Emacs, and is not in the CLOS spec.
568 A class which is @code{:abstract} cannot be instantiated, and instead
569 is used to define an interface which subclasses should implement.
571 This option is specific to Emacs, and is not in the CLOS spec.
574 This is a list of groups that can be customized within this class. This
575 slot is auto-generated when a class is created and need not be
576 specified. It can be retrieved with the @code{class-option} command,
577 however, to see what groups are available.
579 This option is specific to Emacs, and is not in the CLOS spec.
581 @item :method-invocation-order
582 This controls the order in which method resolution occurs for
583 @code{:primary} methods in cases of multiple inheritance. The order
584 affects which method is called first in a tree, and if
585 @code{call-next-method} is used, it controls the order in which the
586 stack of methods are run.
592 Search for methods in the class hierarchy in breadth first order.
595 Search for methods in the class hierarchy in a depth first order.
597 Searches for methods in in a linearized way that most closely matches
598 what CLOS does when a monotonic class structure is defined.
601 @xref{Method Invocation}, for more on method invocation order.
604 Unsupported CLOS option. Enables the use of a different base class other
605 than @code{standard-class}.
607 @item :default-initargs
608 Unsupported CLOS option. Specifies a list of initargs to be used when
609 creating new objects. As far as I can tell, this duplicates the
610 function of @code{:initform}.
613 @xref{CLOS compatibility}, for more details on CLOS tags versus
614 @eieio{}-specific tags.
616 @node Making New Objects
617 @comment node-name, next, previous, up
618 @chapter Making New Objects
620 Suppose we have a simple class is defined, such as:
628 It is now possible to create objects of that class type.
630 Calling @code{defclass} has defined two new functions. One is the
631 constructor @var{record}, and the other is the predicate,
634 @defun record object-name &rest slots
636 This creates and returns a new object. This object is not assigned to
637 anything, and will be garbage collected if not saved. This object
638 will be given the string name @var{object-name}. There can be
639 multiple objects of the same name, but the name slot provides a handy
640 way to keep track of your objects. @var{slots} is just all the slots
641 you wish to preset. Any slot set as such @emph{will not} get its
642 default value, and any side effects from a slot's @code{:initform}
643 that may be a function will not occur.
645 An example pair would appear simply as @code{:value 1}. Of course you
646 can do any valid Lispy thing you want with it, such as
647 @code{:value (if (boundp 'special-symbol) special-symbol nil)}
649 Example of creating an object from a class:
652 (record "test" :value 3 :reference nil)
657 To create an object from a class symbol, use @code{make-instance}.
659 @defun make-instance class &rest initargs
660 @anchor{make-instance}
661 Make a new instance of @var{class} based on @var{initargs}.
662 @var{class} is a class symbol. For example:
668 @var{initargs} is a property list with keywords based on the @code{:initarg}
669 for each slot. For example:
672 (make-instance @code{'foo} @code{:slot1} value1 @code{:slotN} valueN)
677 If the first element of @var{initargs} is a string, it is used as the
680 In @eieio{}, the class' constructor requires a name for use when printing.
681 @dfn{make-instance} in CLOS doesn't use names the way Emacs does, so the
682 class is used as the name slot instead when @var{initargs} doesn't start with
686 @node Accessing Slots
687 @comment node-name, next, previous, up
688 @chapter Accessing Slots
690 There are several ways to access slot values in an object. The naming
691 and argument-order conventions are similar to those used for
692 referencing vectors (@pxref{Vectors,,,elisp,GNU Emacs Lisp Reference
695 @defmac oset object slot value
696 This macro sets the value behind @var{slot} to @var{value} in
697 @var{object}. It returns @var{value}.
700 @defmac oset-default class slot value
701 This macro sets the @code{:initform} for @var{slot} in @var{class} to
704 This allows the user to set both public and private defaults after the
705 class has been constructed, and provides a way to configure the
706 default behavior of packages built with classes (the same way
707 @code{setq-default} does for buffer-local variables).
709 For example, if a user wanted all @code{data-objects} (@pxref{Building
710 Classes}) to inform a special object of his own devising when they
711 changed, this can be arranged by simply executing this bit of code:
714 (oset-default data-object reference (list my-special-object))
718 @defmac oref obj slot
720 Retrieve the value stored in @var{obj} in the slot named by @var{slot}.
721 Slot is the name of the slot when created by @dfn{defclass} or the label
722 created by the @code{:initarg} tag.
725 @defmac oref-default obj slot
726 @anchor{oref-default}
727 Gets the default value of @var{obj} (maybe a class) for @var{slot}.
728 The default value is the value installed in a class with the @code{:initform}
729 tag. @var{slot} can be the slot name, or the tag specified by the @code{:initarg}
730 tag in the @dfn{defclass} call.
733 The following accessors are defined by CLOS to reference or modify
734 slot values, and use the previously mentioned set/ref routines.
736 @defun slot-value object slot
738 This function retrieves the value of @var{slot} from @var{object}.
739 Unlike @code{oref}, the symbol for @var{slot} must be quoted.
742 @defun set-slot-value object slot value
743 @anchor{set-slot-value}
744 This is not a CLOS function, but is meant to mirror @code{slot-value} if
745 you don't want to use the cl package's @code{setf} function. This
746 function sets the value of @var{slot} from @var{object}. Unlike
747 @code{oset}, the symbol for @var{slot} must be quoted.
750 @defun slot-makeunbound object slot
751 This function unbinds @var{slot} in @var{object}. Referencing an
752 unbound slot can signal an error.
755 @defun object-add-to-list object slot item &optional append
756 @anchor{object-add-to-list}
757 In OBJECT's @var{slot}, add @var{item} to the list of elements.
758 Optional argument @var{append} indicates we need to append to the list.
759 If @var{item} already exists in the list in @var{slot}, then it is not added.
760 Comparison is done with @dfn{equal} through the @dfn{member} function call.
761 If @var{slot} is unbound, bind it to the list containing @var{item}.
764 @defun object-remove-from-list object slot item
765 @anchor{object-remove-from-list}
766 In OBJECT's @var{slot}, remove occurrences of @var{item}.
767 Deletion is done with @dfn{delete}, which deletes by side effect
768 and comparisons are done with @dfn{equal}.
769 If @var{slot} is unbound, do nothing.
772 @defun with-slots spec-list object &rest body
774 Bind @var{spec-list} lexically to slot values in @var{object}, and execute @var{body}.
775 This establishes a lexical environment for referring to the slots in
776 the instance named by the given slot-names as though they were
777 variables. Within such a context the value of the slot can be
778 specified by using its slot name, as if it were a lexically bound
779 variable. Both setf and setq can be used to set the value of the
782 @var{spec-list} is of a form similar to @dfn{let}. For example:
791 Where each @var{var} is the local variable given to the associated
792 @var{slot}. A slot specified without a variable name is given a
793 variable name of the same name as the slot.
796 (defclass myclass () (x :initarg 1))
797 (setq mc (make-instance 'myclass))
798 (with-slots (x) mc x) => 1
799 (with-slots ((something x)) mc something) => 1
803 @node Writing Methods
804 @comment node-name, next, previous, up
805 @chapter Writing Methods
807 Writing a method in @eieio{} is similar to writing a function. The
808 differences are that there are some extra options and there can be
809 multiple definitions under the same function symbol.
811 Where a method defines an implementation for a particular data type, a
812 @dfn{generic method} accepts any argument, but contains no code. It
813 is used to provide the dispatching to the defined methods. A generic
814 method has no body, and is merely a symbol upon which methods are
815 attached. It also provides the base documentation for what methods
827 Each @eieio{} method has one corresponding generic. This generic
828 provides a function binding and the base documentation for the method
829 symbol (@pxref{Symbol Components,,,elisp,GNU Emacs Lisp Reference
832 @defmac defgeneric method arglist [doc-string]
833 This macro turns the (unquoted) symbol @var{method} into a function.
834 @var{arglist} is the default list of arguments to use (not implemented
835 yet). @var{doc-string} is the documentation used for this symbol.
837 A generic function acts as a placeholder for methods. There is no
838 need to call @code{defgeneric} yourself, as @code{defmethod} will call
839 it if necessary. Currently the argument list is unused.
841 @code{defgeneric} signals an error if you attempt to turn an existing
842 Emacs Lisp function into a generic function.
844 You can also create a generic method with @code{defmethod}
845 (@pxref{Methods}). When a method is created and there is no generic
846 method in place with that name, then a new generic will be created,
847 and the new method will use it.
850 In CLOS, a generic call also be used to provide an argument list and
851 dispatch precedence for all the arguments. In @eieio{}, dispatching
852 only occurs for the first argument, so the @var{arglist} is not used.
857 A method is a function that is executed if the first argument passed
858 to it matches the method's class. Different @eieio{} classes may
859 share the same method names.
861 Methods are created with the @code{defmethod} macro, which is similar
864 @defmac defmethod method [:before | :primary | :after | :static ] arglist [doc-string] forms
866 @var{method} is the name of the function to create.
868 @code{:before} and @code{:after} specify execution order (i.e., when
869 this form is called). If neither of these symbols are present, the
870 default priority is used (before @code{:after} and after
871 @code{:before}); this default priority is represented in CLOS as
874 @b{Note:} The @code{:BEFORE}, @code{:PRIMARY}, @code{:AFTER}, and
875 @code{:STATIC} method tags were in all capital letters in previous
876 versions of @eieio{}.
878 @var{arglist} is the list of arguments to this method. The first
879 argument in this list---and @emph{only} the first argument---may have
880 a type specifier (see the example below). If no type specifier is
881 supplied, the method applies to any object.
883 @var{doc-string} is the documentation attached to the implementation.
884 All method doc-strings are incorporated into the generic method's
885 function documentation.
887 @var{forms} is the body of the function.
892 In the following example, we create a method @code{mymethod} for the
893 @code{classname} class:
896 (defmethod mymethod ((obj classname) secondarg)
901 This method only executes if the @var{obj} argument passed to it is an
902 @eieio{} object of class @code{classname}.
904 A method with no type specifier is a @dfn{default method}. If a given
905 class has no implementation, then the default method is called when
906 that method is used on a given object of that class.
908 Only one default method per execution specifier (@code{:before},
909 @code{:primary}, or @code{:after}) is allowed. If two
910 @code{defmethod}s appear with @var{arglist}s lacking a type specifier,
911 and having the same execution specifier, then the first implementation
914 When a method is called on an object, but there is no method specified
915 for that object, but there is a method specified for object's parent
916 class, the parent class' method is called. If there is a method
917 defined for both, only the child's method is called. A child method
918 may call a parent's method using @code{call-next-method}, described
921 If multiple methods and default methods are defined for the same
922 method and class, they are executed in this order:
926 @item default :before
927 @item method :primary
928 @item default :primary
933 If no methods exist, Emacs signals a @code{no-method-definition}
934 error. @xref{Signals}.
936 @defun call-next-method &rest replacement-args
937 @anchor{call-next-method}
939 This function calls the superclass method from a subclass method.
940 This is the ``next method'' specified in the current method list.
942 If @var{replacement-args} is non-@code{nil}, then use them instead of
943 @code{eieio-generic-call-arglst}. At the top level, the generic
944 argument list is passed in.
946 Use @code{next-method-p} to find out if there is a next method to
951 @anchor{next-method-p}
952 Non-@code{nil} if there is a next method.
953 Returns a list of lambda expressions which is the @code{next-method}
957 At present, @eieio{} does not implement all the features of CLOS:
961 There is currently no @code{:around} tag.
963 CLOS allows multiple sets of type-cast arguments, but @eieio{} only
964 allows the first argument to be cast.
968 @section Static Methods
970 Static methods do not depend on an object instance, but instead
971 operate on an object's class. You can create a static method by using
972 the @code{:static} key with @code{defmethod}.
974 Do not treat the first argument of a @code{:static} method as an
975 object unless you test it first. Use the functions
976 @code{oref-default} or @code{oset-default} which will work on a class,
977 or on the class of an object.
979 A Class' @code{constructor} method is defined as a @code{:static}
982 @b{Note:} The @code{:static} keyword is unique to @eieio{}.
984 @c TODO - Write some more about static methods here
986 @node Method Invocation
987 @chapter Method Invocation
989 When classes are defined, you can specify the
990 @code{:method-invocation-order}. This is a feature specific to EIEIO.
992 This controls the order in which method resolution occurs for
993 @code{:primary} methods in cases of multiple inheritance. The order
994 affects which method is called first in a tree, and if
995 @code{call-next-method} is used, it controls the order in which the
996 stack of methods are run.
998 The original EIEIO order turned out to be broken for multiple
999 inheritance, but some programs depended on it. As such this option
1000 was added when the default invocation order was fixed to something
1001 that made more sense in that case.
1006 @item :breadth-first
1007 Search for methods in the class hierarchy in breadth first order.
1008 This is the default.
1010 Search for methods in the class hierarchy in a depth first order.
1012 Searches for methods in in a linearized way that most closely matches
1013 what CLOS does when CLOS when a monotonic class structure is defined.
1015 This is derived from the Dylan language documents by
1016 Kim Barrett et al.: A Monotonic Superclass Linearization for Dylan
1017 Retrieved from: http://192.220.96.201/dylan/linearization-oopsla96.html
1021 @comment node-name, next, previous, up
1022 @chapter Predicates and Utilities
1024 Now that we know how to create classes, access slots, and define
1025 methods, it might be useful to verify that everything is doing ok. To
1026 help with this a plethora of predicates have been created.
1028 @defun find-class symbol &optional errorp
1030 Return the class that @var{symbol} represents.
1031 If there is no class, @code{nil} is returned if @var{errorp} is @code{nil}.
1032 If @var{errorp} is non-@code{nil}, @code{wrong-argument-type} is signaled.
1035 @defun class-p class
1037 Return @code{t} if @var{class} is a valid class vector.
1038 @var{class} is a symbol.
1041 @defun slot-exists-p object-or-class slot
1042 @anchor{slot-exists-p}
1043 Non-@code{nil} if @var{object-or-class} has @var{slot}.
1046 @defun slot-boundp object slot
1047 @anchor{slot-boundp}
1048 Non-@code{nil} if OBJECT's @var{slot} is bound.
1049 Setting a slot's value makes it bound. Calling @dfn{slot-makeunbound} will
1050 make a slot unbound.
1051 @var{object} can be an instance or a class.
1054 @defun class-name class
1055 Return a string of the form @samp{#<class myclassname>} which should look
1056 similar to other Lisp objects like buffers and processes. Printing a
1057 class results only in a symbol.
1060 @defun class-option class option
1061 Return the value in @var{CLASS} of a given @var{OPTION}.
1065 (class-option eieio-default-superclass :documentation)
1068 Will fetch the documentation string for @code{eieio-default-superclass}.
1071 @defun class-constructor class
1072 Return a symbol used as a constructor for @var{class}. The
1073 constructor is a function used to create new instances of
1074 @var{CLASS}. This function provides a way to make an object of a class
1075 without knowing what it is. This is not a part of CLOS.
1078 @defun object-name obj
1079 Return a string of the form @samp{#<object-class myobjname>} for @var{obj}.
1080 This should look like Lisp symbols from other parts of Emacs such as
1081 buffers and processes, and is shorter and cleaner than printing the
1082 object's vector. It is more useful to use @code{object-print} to get
1083 and object's print form, as this allows the object to add extra display
1084 information into the symbol.
1087 @defun object-class obj
1088 Returns the class symbol from @var{obj}.
1092 CLOS symbol which does the same thing as @code{object-class}
1095 @defun object-class-fast obj
1096 Same as @code{object-class} except this is a macro, and no
1097 type-checking is performed.
1100 @defun object-class-name obj
1101 Returns the symbol of @var{obj}'s class.
1104 @defun class-parents class
1105 Returns the direct parents class of @var{class}. Returns @code{nil} if
1109 @defun class-parents-fast class
1110 Just like @code{class-parent} except it is a macro and no type checking
1114 @defun class-parent class
1115 Deprecated function which returns the first parent of @var{class}.
1118 @defun class-children class
1119 Return the list of classes inheriting from @var{class}.
1122 @defun class-children-fast class
1123 Just like @code{class-children}, but with no checks.
1126 @defun same-class-p obj class
1127 Returns @code{t} if @var{obj}'s class is the same as @var{class}.
1130 @defun same-class-fast-p obj class
1131 Same as @code{same-class-p} except this is a macro and no type checking
1135 @defun object-of-class-p obj class
1136 Returns @code{t} if @var{obj} inherits anything from @var{class}. This
1137 is different from @code{same-class-p} because it checks for inheritance.
1140 @defun child-of-class-p child class
1141 Returns @code{t} if @var{child} is a subclass of @var{class}.
1144 @defun generic-p method-symbol
1145 Returns @code{t} if @code{method-symbol} is a generic function, as
1146 opposed to a regular Emacs Lisp function.
1149 @node Association Lists
1150 @chapter Association Lists
1152 Lisp offers the concept of association lists, with primitives such as
1153 @code{assoc} used to access them. The following functions can be used
1154 to manage association lists of @eieio{} objects:
1156 @defun object-assoc key slot list
1157 @anchor{object-assoc}
1158 Return an object if @var{key} is @dfn{equal} to SLOT's value of an object in @var{list}.
1159 @var{list} is a list of objects whose slots are searched.
1160 Objects in @var{list} do not need to have a slot named @var{slot}, nor does
1161 @var{slot} need to be bound. If these errors occur, those objects will
1166 @defun object-assoc-list slot list
1167 Return an association list generated by extracting @var{slot} from all
1168 objects in @var{list}. For each element of @var{list} the @code{car} is
1169 the value of @var{slot}, and the @code{cdr} is the object it was
1170 extracted from. This is useful for generating completion tables.
1173 @defun eieio-build-class-alist &optional base-class
1174 Returns an alist of all currently defined classes. This alist is
1175 suitable for completion lists used by interactive functions to select a
1176 class. The optional argument @var{base-class} allows the programmer to
1177 select only a subset of classes which includes @var{base-class} and
1182 @comment node-name, next, previous, up
1183 @chapter Customizing Objects
1185 @eieio{} supports the Custom facility through two new widget types.
1186 If a variable is declared as type @code{object}, then full editing of
1187 slots via the widgets is made possible. This should be used
1188 carefully, however, because modified objects are cloned, so if there
1189 are other references to these objects, they will no longer be linked
1192 If you want in place editing of objects, use the following methods:
1194 @defun eieio-customize-object object
1195 Create a custom buffer and insert a widget for editing @var{object}. At
1196 the end, an @code{Apply} and @code{Reset} button are available. This
1197 will edit the object "in place" so references to it are also changed.
1198 There is no effort to prevent multiple edits of a singular object, so
1199 care must be taken by the user of this function.
1202 @defun eieio-custom-widget-insert object flags
1203 This method inserts an edit object into the current buffer in place.
1204 It is implemented as @code{(widget-create 'object-edit :value object)}.
1205 This method is provided as a locale for adding tracking, or
1206 specializing the widget insert procedure for any object.
1209 To define a slot with an object in it, use the @code{object} tag. This
1210 widget type will be automatically converted to @code{object-edit} if you
1211 do in place editing of you object.
1213 If you want to have additional actions taken when a user clicks on the
1214 @code{Apply} button, then overload the method @code{eieio-done-customizing}.
1215 This method does nothing by default, but that may change in the future.
1216 This would be the best way to make your objects persistent when using
1219 @section Widget extension
1221 When widgets are being created, one new widget extension has been added,
1222 called the @code{:slotofchoices}. When this occurs in a widget
1223 definition, all elements after it are removed, and the slot is specifies
1224 is queried and converted into a series of constants.
1227 (choice (const :tag "None" nil)
1228 :slotofchoices morestuff)
1231 and if the slot @code{morestuff} contains @code{(sym1 sym2 sym3)}, the
1232 above example is converted into:
1235 (choice (const :tag "None" nil)
1241 This is useful when a given item needs to be selected from a list of
1242 items defined in this second slot.
1245 @chapter Introspection
1247 Introspection permits a programmer to peek at the contents of a class
1248 without any previous knowledge of that class. While @eieio{} implements
1249 objects on top of vectors, and thus everything is technically visible,
1250 some functions have been provided. None of these functions are a part
1253 @defun object-slots obj
1254 Return the list of public slots for @var{obj}.
1257 @defun class-slot-initarg class slot
1258 For the given @var{class} return the :initarg associated with
1259 @var{slot}. Not all slots have initargs, so the return value can be
1264 @comment node-name, next, previous, up
1265 @chapter Base Classes
1267 All defined classes, if created with no specified parent class,
1268 inherit from a special class called @code{eieio-default-superclass}.
1269 @xref{Default Superclass}.
1271 Often, it is more convenient to inherit from one of the other base
1272 classes provided by @eieio{}, which have useful pre-defined
1273 properties. (Since @eieio{} supports multiple inheritance, you can
1274 even inherit from more than one of these classes at once.)
1277 * eieio-instance-inheritor:: Enable value inheritance between instances.
1278 * eieio-instance-tracker:: Enable self tracking instances.
1279 * eieio-singleton:: Only one instance of a given class.
1280 * eieio-persistent:: Enable persistence for a class.
1281 * eieio-named:: Use the object name as a :name slot.
1282 * eieio-speedbar:: Enable speedbar support in your objects.
1285 @node eieio-instance-inheritor
1286 @comment node-name, next, previous, up
1287 @section @code{eieio-instance-inheritor}
1289 This class is defined in the package @file{eieio-base}.
1291 Instance inheritance is a mechanism whereby the value of a slot in
1292 object instance can reference the parent instance. If the parent's slot
1293 value is changed, then the child instance is also changed. If the
1294 child's slot is set, then the parent's slot is not modified.
1296 @deftp {Class} eieio-instance-inheritor parent-instance
1297 A class whose instances are enabled with instance inheritance.
1298 The @var{parent-instance} slot indicates the instance which is
1299 considered the parent of the current instance. Default is @code{nil}.
1303 To use this class, inherit from it with your own class.
1304 To make a new instance that inherits from and existing instance of your
1305 class, use the @code{clone} method with additional parameters
1306 to specify local values.
1308 @cindex slot-unbound
1309 The @code{eieio-instance-inheritor} class works by causing cloned
1310 objects to have all slots unbound. This class' @code{slot-unbound}
1311 method will cause references to unbound slots to be redirected to the
1312 parent instance. If the parent slot is also unbound, then
1313 @code{slot-unbound} will signal an error named @code{slot-unbound}.
1315 @node eieio-instance-tracker
1316 @section @code{eieio-instance-tracker}
1318 This class is defined in the package @file{eieio-base}.
1320 Sometimes it is useful to keep a master list of all instances of a given
1321 class. The class @code{eieio-instance-tracker} performs this task.
1323 @deftp {Class} eieio-instance-tracker tracker-symbol
1324 Enable instance tracking for this class.
1325 The slot @var{tracker-symbol} should be initialized in inheritors of
1326 this class to a symbol created with @code{defvar}. This symbol will
1327 serve as the variable used as a master list of all objects of the given
1331 @defmethod eieio-instance-tracker initialize-instance obj slot
1332 This method is defined as an @code{:after} method.
1333 It adds new instances to the master list. Do not overload this method
1334 unless you use @code{call-next-method.}
1337 @defmethod eieio-instance-tracker delete-instance obj
1338 Remove @var{obj} from the master list of instances of this class.
1339 This may let the garbage collector nab this instance.
1342 @deffn eieio-instance-tracker-find key slot list-symbol
1343 This convenience function lets you find instances. @var{key} is the
1344 value to search for. @var{slot} is the slot to compare @var{KEY}
1345 against. The function @code{equal} is used for comparison.
1346 The parameter @var{list-symbol} is the variable symbol which contains the
1347 list of objects to be searched.
1350 @node eieio-singleton
1351 @comment node-name, next, previous, up
1352 @section @code{eieio-singleton}
1354 This class is defined in the package @file{eieio-base}.
1356 @deftp {Class} eieio-singleton
1357 Inheriting from the singleton class will guarantee that there will
1358 only ever be one instance of this class. Multiple calls to
1359 @code{make-instance} will always return the same object.
1362 @node eieio-persistent
1363 @comment node-name, next, previous, up
1364 @section @code{eieio-persistent}
1366 This class is defined in the package @file{eieio-base}.
1368 If you want an object, or set of objects to be persistent, meaning the
1369 slot values are important to keep saved between sessions, then you will
1370 want your top level object to inherit from @code{eieio-persistent}.
1372 To make sure your persistent object can be moved, make sure all file
1373 names stored to disk are made relative with
1374 @code{eieio-persistent-path-relative}.
1376 @deftp {Class} eieio-persistent file file-header-line
1377 Enables persistence for instances of this class.
1378 Slot @var{file} with initarg @code{:file} is the file name in which this
1379 object will be saved.
1380 Class allocated slot @var{file-header-line} is used with method
1381 @code{object-write} as a header comment.
1384 All objects can write themselves to a file, but persistent objects have
1385 several additional methods that aid in maintaining them.
1387 @defmethod eieio-persistent eieio-persistent-save obj &optional file
1388 Write the object @var{obj} to its file.
1389 If optional argument @var{file} is specified, use that file name
1393 @defmethod eieio-persistent eieio-persistent-path-relative obj file
1394 Return a file name derived from @var{file} which is relative to the
1395 stored location of @var{OBJ}. This method should be used to convert
1396 file names so that they are relative to the save file, making any system
1397 of files movable from one location to another.
1400 @defmethod eieio-persistent object-write obj &optional comment
1401 Like @code{object-write} for @code{standard-object}, but will derive
1402 a header line comment from the class allocated slot if one is not
1406 @defun eieio-persistent-read filename &optional class allow-subclass
1407 Read a persistent object from @var{filename}, and return it.
1408 Signal an error if the object in @var{FILENAME} is not a constructor
1409 for @var{CLASS}. Optional @var{allow-subclass} says that it is ok for
1410 @code{eieio-persistent-read} to load in subclasses of class instead of
1415 @comment node-name, next, previous, up
1416 @section @code{eieio-named}
1418 This class is defined in the package @file{eieio-base}.
1420 @deftp {Class} eieio-named
1422 Name storage already occurs in an object. This object provides get/set
1426 @node eieio-speedbar
1427 @comment node-name, next, previous, up
1428 @section @code{eieio-speedbar}
1430 This class is in package @file{eieio-speedbar}.
1432 If a series of class instances map to a tree structure, it is possible
1433 to cause your classes to be displayable in Speedbar. @xref{Top,,,speedbar}.
1434 Inheriting from these classes will enable a speedbar major display mode
1435 with a minimum of effort.
1437 @deftp {Class} eieio-speedbar buttontype buttonface
1438 Enables base speedbar display for a class.
1439 @cindex speedbar-make-tag-line
1440 The slot @var{buttontype} is any of the symbols allowed by the
1441 function @code{speedbar-make-tag-line} for the @var{exp-button-type}
1442 argument @xref{Extending,,,speedbar}.
1443 The slot @var{buttonface} is the face to use for the text of the string
1444 displayed in speedbar.
1445 The slots @var{buttontype} and @var{buttonface} are class allocated
1446 slots, and do not take up space in your instances.
1449 @deftp {Class} eieio-speedbar-directory-button buttontype buttonface
1450 This class inherits from @code{eieio-speedbar} and initializes
1451 @var{buttontype} and @var{buttonface} to appear as directory level lines.
1454 @deftp {Class} eieio-speedbar-file-button buttontype buttonface
1455 This class inherits from @code{eieio-speedbar} and initializes
1456 @var{buttontype} and @var{buttonface} to appear as file level lines.
1459 To use these classes, inherit from one of them in you class. You can
1460 use multiple inheritance with them safely. To customize your class for
1461 speedbar display, override the default values for @var{buttontype} and
1462 @var{buttonface} to get the desired effects.
1464 Useful methods to define for your new class include:
1466 @defmethod eieio-speedbar eieio-speedbar-derive-line-path obj depth
1467 Return a string representing a directory associated with an instance
1468 of @var{obj}. @var{depth} can be used to index how many levels of
1469 indentation have been opened by the user where @var{obj} is shown.
1473 @defmethod eieio-speedbar eieio-speedbar-description obj
1474 Return a string description of @var{OBJ}.
1475 This is shown in the minibuffer or tooltip when the mouse hovers over
1476 this instance in speedbar.
1479 @defmethod eieio-speedbar eieio-speedbar-child-description obj
1480 Return a string representing a description of a child node of @var{obj}
1481 when that child is not an object. It is often useful to just use
1482 item info helper functions such as @code{speedbar-item-info-file-helper}.
1485 @defmethod eieio-speedbar eieio-speedbar-object-buttonname obj
1486 Return a string which is the text displayed in speedbar for @var{obj}.
1489 @defmethod eieio-speedbar eieio-speedbar-object-children obj
1490 Return a list of children of @var{obj}.
1493 @defmethod eieio-speedbar eieio-speedbar-child-make-tag-lines obj depth
1494 This method inserts a list of speedbar tag lines for @var{obj} to
1495 represent its children. Implement this method for your class
1496 if your children are not objects themselves. You still need to
1497 implement @code{eieio-speedbar-object-children}.
1499 In this method, use techniques specified in the Speedbar manual.
1500 @xref{Extending,,,speedbar}.
1503 Some other functions you will need to learn to use are:
1505 @deffn eieio-speedbar-create make-map key-map menu name toplevelfn
1506 Register your object display mode with speedbar.
1507 @var{make-map} is a function which initialized you keymap.
1508 @var{key-map} is a symbol you keymap is installed into.
1509 @var{menu} is an easy menu vector representing menu items specific to your
1511 @var{name} is a short string to use as a name identifying you mode.
1512 @var{toplevelfn} is a function called which must return a list of
1513 objects representing those in the instance system you wish to browse in
1516 Read the Extending chapter in the speedbar manual for more information
1517 on how speedbar modes work
1518 @xref{Extending,,,speedbar}.
1522 @comment node-name, next, previous, up
1523 @chapter Browsing class trees
1525 The command @kbd{M-x eieio-browse} displays a buffer listing all the
1526 currently loaded classes in Emacs. The classes are listed in an
1527 indented tree structure, starting from @code{eieio-default-superclass}
1528 (@pxref{Default Superclass}).
1530 With a prefix argument, this command prompts for a class name; it then
1531 lists only that class and its subclasses.
1533 Here is a sample tree from our current example:
1536 eieio-default-superclass
1538 +--data-object-symbol
1541 Note: new classes are consed into the inheritance lists, so the tree
1542 comes out upside-down.
1545 @comment node-name, next, previous, up
1546 @chapter Class Values
1548 Details about any class or object can be retrieved using the function
1549 @code{eieio-describe-class}. Interactively, type in the name of
1550 a class. In a program, pass it a string with the name of a class, a
1551 class symbol, or an object. The resulting buffer will display all slot
1554 Additionally, all methods defined to have functionality on this class is
1558 @comment node-name, next, previous, up
1559 @chapter Documentation
1561 It is possible to automatically create documentation for your classes in
1562 texinfo format by using the tools in the file @file{eieio-doc.el}
1564 @deffn Command eieiodoc-class class indexstring &optional skiplist
1566 This will start at the current point, and create an indented menu of
1567 all the child classes of, and including @var{class}, but skipping any
1568 classes that might be in @var{skiplist}. It will then create nodes for
1569 all these classes, subsection headings, and indexes.
1571 Each class will be indexed using the texinfo labeled index
1572 @var{indexstring} which is a two letter description.
1573 @xref{(texinfo) New Indices}.
1575 To use this command, the texinfo macro
1578 @@defindex @@var @{ indexstring @}
1582 where @var{indexstring} is replaced with the two letter code.
1584 Next, an inheritance tree will be created listing all parents of that
1587 Then, all the slots will be expanded in tables, and described
1588 using the documentation strings from the code. Default values will also
1589 be displayed. Only those slots with @code{:initarg} specified will be
1590 expanded, others will be hidden. If a slot is inherited from a parent,
1591 that slot will also be skipped unless the default value is different.
1592 If there is a change, then the documentation part of the slot will be
1593 replace with an @@xref back to the parent.
1595 This command can only display documentation for classes whose
1596 definitions have been loaded in this Emacs session.
1600 @node Default Superclass
1601 @comment node-name, next, previous, up
1602 @chapter Default Superclass
1604 All defined classes, if created with no specified parent class, will
1605 inherit from a special class stored in
1606 @code{eieio-default-superclass}. This superclass is quite simple, but
1607 with it, certain default methods or attributes can be added to all
1608 objects. In CLOS, this would be named @code{STANDARD-CLASS}, and that
1609 symbol is an alias to @code{eieio-default-superclass}.
1612 Currently, the default superclass is defined as follows:
1615 (defclass eieio-default-superclass nil
1617 "Default parent class for classes with no specified parent class.
1618 Its slots are automatically adopted by classes with no specified
1619 parents. This class is not stored in the `parent' slot of a class vector."
1623 The default superclass implements several methods providing a default
1624 behavior for all objects created by @eieio{}.
1627 * Initialization:: How objects are initialized
1628 * Basic Methods:: Clone, print, and write
1629 * Signal Handling:: Methods for managing signals.
1632 @node Initialization
1633 @section Initialization
1635 When creating an object of any type, you can use its constructor, or
1636 @code{make-instance}. This, in turns calls the method
1637 @code{initialize-instance}, which then calls the method
1638 @code{shared-initialize}.
1640 These methods are all implemented on the default superclass so you do
1641 not need to write them yourself, unless you need to override one of
1644 Users should not need to call @code{initialize-instance} or
1645 @code{shared-initialize}, as these are used by @code{make-instance} to
1646 initialize the object. They are instead provided so that users can
1647 augment these behaviors.
1649 @defun initialize-instance obj &rest slots
1650 Initialize @var{obj}. Sets slots of @var{obj} with @var{slots} which
1651 is a list of name/value pairs. These are actually just passed to
1652 @code{shared-initialize}.
1655 @defun shared-initialize obj &rest slots
1656 Sets slots of @var{obj} with @var{slots} which is a list of name/value
1659 This is called from the default @code{constructor}.
1663 @section Basic Methods
1665 Additional useful methods defined on the base subclass are:
1667 @defun clone obj &rest params
1669 Make a copy of @var{obj}, and then apply @var{params}.
1670 @var{params} is a parameter list of the same form as @var{initialize-instance}
1671 which are applied to change the object. When overloading @dfn{clone}, be
1672 sure to call @dfn{call-next-method} first and modify the returned object.
1675 @defun object-print this &rest strings
1676 @anchor{object-print}
1677 Pretty printer for object @var{this}. Call function @dfn{object-name} with @var{strings}.
1678 The default method for printing object @var{this} is to use the
1679 function @dfn{object-name}.
1681 It is sometimes useful to put a summary of the object into the
1682 default #<notation> string when using eieio browsing tools.
1684 Implement this function and specify @var{strings} in a call to
1685 @dfn{call-next-method} to provide additional summary information.
1686 When passing in extra strings from child classes, always remember
1690 (defclass data-object ()
1692 "Object containing one data slot.")
1694 (defmethod object-print ((this data-object) &optional strings)
1695 "Return a string with a summary of the data object as part of the name."
1696 (apply 'call-next-method this
1697 (cons (format " value: %s" (render this)) strings)))
1700 Here is what some output could look like:
1702 (object-print test-object)
1703 => #<data-object test-object value: 3>
1707 @defun object-write obj &optional comment
1708 Write @var{obj} onto a stream in a readable fashion. The resulting
1709 output will be Lisp code which can be used with @code{read} and
1710 @code{eval} to recover the object. Only slots with @code{:initarg}s
1711 are written to the stream.
1714 @node Signal Handling
1715 @section Signal Handling
1717 The default superclass defines methods for managing error conditions.
1718 These methods all throw a signal for a particular error condition.
1720 By implementing one of these methods for a class, you can change the
1721 behavior that occurs during one of these error cases, or even ignore
1722 the error by providing some behavior.
1724 @defun slot-missing object slot-name operation &optional new-value
1725 @anchor{slot-missing}
1726 Method invoked when an attempt to access a slot in @var{object} fails.
1727 @var{slot-name} is the name of the failed slot, @var{operation} is the type of access
1728 that was requested, and optional @var{new-value} is the value that was desired
1731 This method is called from @code{oref}, @code{oset}, and other functions which
1732 directly reference slots in EIEIO objects.
1734 The default method signals an error of type @code{invalid-slot-name}.
1737 You may override this behavior, but it is not expected to return in the
1738 current implementation.
1740 This function takes arguments in a different order than in CLOS.
1743 @defun slot-unbound object class slot-name fn
1744 @anchor{slot-unbound}
1745 Slot unbound is invoked during an attempt to reference an unbound slot.
1746 @var{object} is the instance of the object being reference. @var{class} is the
1747 class of @var{object}, and @var{slot-name} is the offending slot. This function
1748 throws the signal @code{unbound-slot}. You can overload this function and
1749 return the value to use in place of the unbound value.
1750 Argument @var{fn} is the function signaling this error.
1751 Use @dfn{slot-boundp} to determine if a slot is bound or not.
1753 In @var{clos}, the argument list is (@var{class} @var{object} @var{slot-name}), but
1754 @var{eieio} can only dispatch on the first argument, so the first two are swapped.
1757 @defun no-applicable-method object method &rest args
1758 @anchor{no-applicable-method}
1759 Called if there are no implementations for @var{object} in @var{method}.
1760 @var{object} is the object which has no method implementation.
1761 @var{args} are the arguments that were passed to @var{method}.
1763 Implement this for a class to block this signal. The return
1764 value becomes the return value of the original method call.
1767 @defun no-next-method object &rest args
1768 @anchor{no-next-method}
1769 Called from @dfn{call-next-method} when no additional methods are available.
1770 @var{object} is othe object being called on @dfn{call-next-method}.
1771 @var{args} are the arguments it is called by.
1772 This method signals @dfn{no-next-method} by default. Override this
1773 method to not throw an error, and its return value becomes the
1774 return value of @dfn{call-next-method}.
1778 @comment node-name, next, previous, up
1781 There are new condition names (signals) that can be caught when using
1784 @deffn Signal invalid-slot-name obj-or-class slot
1785 This signal is called when an attempt to reference a slot in an
1786 @var{obj-or-class} is made, and the @var{slot} is not defined for
1790 @deffn Signal no-method-definition method arguments
1791 This signal is called when @var{method} is called, with @var{arguments}
1792 and nothing is resolved. This occurs when @var{method} has been
1793 defined, but the arguments make it impossible for @eieio{} to determine
1794 which method body to run.
1796 To prevent this signal from occurring in your class, implement the
1797 method @code{no-applicable-method} for your class. This method is
1798 called when to throw this signal, so implementing this for your class
1799 allows you block the signal, and perform some work.
1802 @deffn Signal no-next-method class arguments
1803 This signal is called if the function @code{call-next-method} is called
1804 and there is no next method to be called.
1806 Overload the method @code{no-next-method} to protect against this signal.
1809 @deffn Signal invalid-slot-type slot spec value
1810 This signal is called when an attempt to set @var{slot} is made, and
1811 @var{value} doesn't match the specified type @var{spec}.
1813 In @eieio{}, this is also used if a slot specifier has an invalid value
1814 during a @code{defclass}.
1817 @deffn Signal unbound-slot object class slot
1818 This signal is called when an attempt to reference @var{slot} in
1819 @var{object} is made, and that instance is currently unbound.
1822 @node Naming Conventions
1823 @comment node-name, next, previous, up
1824 @chapter Naming Conventions
1826 @xref{Tips,,Tips and Conventions,elisp,GNU Emacs Lisp Reference
1827 Manual}, for a description of Emacs Lisp programming conventions.
1828 These conventions help ensure that Emacs packages work nicely one
1829 another, so an @eieio{}-based program should follow them. Here are
1830 some conventions that apply specifically to @eieio{}-based programs:
1834 @item Come up with a package prefix that is relatively short. Prefix
1835 all classes, and methods with your prefix. This is a standard
1836 convention for functions and variables in Emacs.
1838 @item Do not prefix method names with the class name. All methods in
1839 @eieio{} are ``virtual'', and are dynamically dispatched. Anyone can
1840 override your methods at any time. Your methods should be prefixed
1841 with your package name.
1843 @item Do not prefix slots in your class. The slots are always locally
1844 scoped to your class, and need no prefixing.
1846 @item If your library inherits from other libraries of classes, you
1847 must ``require'' that library with the @code{require} command.
1851 @node CLOS compatibility
1852 @comment node-name, next, previous, up
1853 @chapter CLOS compatibility
1855 Currently, the following functions should behave almost as expected from
1861 All slot keywords are available but not all work correctly.
1862 Slot keyword differences are:
1866 @item :reader, and :writer tags
1867 Create methods that signal errors instead of creating an unqualified
1868 method. You can still create new ones to do its business.
1871 This should create an unqualified method to access a slot, but
1872 instead pre-builds a method that gets the slot's value.
1875 Specifier uses the @code{typep} function from the @file{cl}
1876 package. @xref{(cl)Type Predicates}. It therefore has the same issues as
1877 that package. Extensions include the ability to provide object names.
1880 Defclass also supports class options, but does not currently use values
1881 of @code{:metaclass}, and @code{:default-initargs}.
1884 Make instance works as expected, however it just uses the @eieio{} instance
1885 creator automatically generated when a new class is created.
1886 @xref{Making New Objects}.
1889 Creates the desired symbol, and accepts all of the expected arguments
1890 except @code{:around}.
1893 Calls defgeneric, and accepts most of the expected arguments. Only
1894 the first argument to the created method may have a type specifier.
1895 To type cast against a class, the class must exist before defmethod is
1896 called. In addition, the @code{:around} tag is not supported.
1898 @item call-next-method
1899 Inside a method, calls the next available method up the inheritance tree
1900 for the given object. This is different than that found in CLOS because
1901 in @eieio{} this function accepts replacement arguments. This permits
1902 subclasses to modify arguments as they are passed up the tree. If no
1903 arguments are given, the expected CLOS behavior is used.
1905 If the common-lisp subsystem is loaded, the setf parameters are also
1906 loaded so the form @code{(setf (slot-value object slot) t)} should
1910 CLOS supports the @code{describe} command, but @eieio{} only provides
1911 @code{eieio-describe-class}, and @code{eieio-describe-generic}. These
1912 functions are adviced into @code{describe-variable}, and
1913 @code{describe-function}.
1915 When creating a new class (@pxref{Building Classes}) there are several
1916 new keywords supported by @eieio{}.
1918 In @eieio{} tags are in lower case, not mixed case.
1923 @eieio{} is an incomplete implementation of CLOS@. Finding ways to
1924 improve the compatibility would help make CLOS style programs run
1927 Some important compatibility features that would be good to add are:
1931 @code{:around} method key.
1934 Method dispatch for built-in types.
1936 Method dispatch for multiple argument typing.
1938 Improve integration with the @file{cl} package.
1941 There are also improvements to be made to allow @eieio{} to operate
1942 better in the Emacs environment.
1946 Allow subclassing of Emacs built-in types, such as faces, markers, and
1949 Allow method overloading of method-like functions in Emacs.
1952 @node Function Index
1953 @unnumbered Function Index