2 @setfilename ../../info/eieio
3 @set TITLE Enhanced Implementation of Emacs Interpreted Objects
4 @set AUTHOR Eric M. Ludlam
5 @settitle @value{TITLE}
6 @documentencoding UTF-8
9 @c *************************************************************************
11 @c *************************************************************************
14 This manual documents EIEIO, an object framework for Emacs Lisp.
16 Copyright @copyright{} 2007--2013 Free Software Foundation, Inc.
19 Permission is granted to copy, distribute and/or modify this document
20 under the terms of the GNU Free Documentation License, Version 1.3 or
21 any later version published by the Free Software Foundation; with no
22 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
23 and with the Back-Cover Texts as in (a) below. A copy of the license
24 is included in the section entitled ``GNU Free Documentation License.''
26 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
27 modify this GNU manual.''
31 @dircategory Emacs misc features
33 * EIEIO: (eieio). An objects system for Emacs Lisp.
37 @center @titlefont{@value{TITLE}}
39 @center by @value{AUTHOR}
47 @node Top, Quick Start, (dir), (dir)
48 @comment node-name, next, previous, up
51 @eieio{} (``Enhanced Implementation of Emacs Interpreted Objects'')
52 provides an Object Oriented layer for Emacs Lisp, following the basic
53 concepts of the Common Lisp Object System (CLOS). It provides a
54 framework for writing object-oriented applications in Emacs.
61 * Quick Start:: Quick start for EIEIO.
62 * Introduction:: Why use @eieio{}? Basic overview, samples list.
63 * Building Classes:: How to write new class structures.
64 * Making New Objects:: How to construct new objects.
65 * Accessing Slots:: How to access a slot.
66 * Writing Methods:: How to write a method.
67 * Method Invocation:: How methods are invoked.
68 * Predicates:: Class-p, Object-p, etc-p.
69 * Association Lists:: List of objects as association lists.
70 * Customizing:: Customizing objects.
71 * Introspection:: Looking inside a class.
72 * Base Classes:: Additional classes you can inherit from.
73 * Browsing:: Browsing your class lists.
74 * Class Values:: Displaying information about a class or object.
75 * Documentation:: Automatically creating texinfo documentation.
76 * Default Superclass:: The root superclasses.
77 * Signals:: When you make errors.
78 * Naming Conventions:: Name your objects in an Emacs friendly way.
79 * CLOS compatibility:: What are the differences?
80 * Wish List:: Things about EIEIO that could be improved.
81 * GNU Free Documentation License:: The license for this documentation.
88 @eieio{} provides an Object Oriented layer for Emacs Lisp. You can
89 use @eieio{} to create classes, methods for those classes, and
92 Here is a simple example of a class named @code{record}, containing
93 three slots named @code{name}, @code{birthday}, and @code{phone}:
96 (defclass record () ; No superclasses
101 :documentation "The name of a person.")
102 (birthday :initarg :birthday
103 :initform "Jan 1, 1970"
106 :documentation "The person's birthday.")
107 (phone :initarg :phone
109 :documentation "Phone number."))
110 "A single record for tracking people I know.")
113 Each class can have methods, which are defined like this:
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")
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
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.
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:
144 (setq rec (record "Eric" :name "Eric" :birthday "June" :phone "555-5555"))
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
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}.
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:
168 (call-record rec "my-call-script")
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}.
178 @comment node-name, next, previous, up
179 @chapter Introduction
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
185 @eieio{} supports the following features:
189 A structured framework for the creation of basic classes with attributes
190 and methods using singular inheritance similar to CLOS.
192 Type checking, and slot unbinding.
194 Method definitions similar to CLOS.
196 Simple and complex class browsers.
198 Edebug support for methods.
202 Byte compilation support of methods.
204 Help system extensions for classes and methods.
206 Several base classes for interesting tasks.
210 Public and private classifications for slots (extensions to CLOS)
212 Customization support in a class (extension to CLOS)
215 Here are some important CLOS features that @eieio{} presently lacks:
219 @item Method dispatch
220 EIEO does not support method dispatch for built-in types and multiple
221 arguments types. In other words, method dispatch only looks at the
222 first argument, and this one must be an @eieio{} type.
224 @item Support for metaclasses
225 There is just one default metaclass, @code{eieio-default-superclass},
226 and you cannot define your own. The @code{:metaclass} tag in
227 @code{defclass} is ignored. Also, functions like `class-of' and
228 `find-class', which should return instances of the metaclass, behave
229 differently in @eieio{} in that they return symbols or plain structures
232 @item EQL specialization
233 EIEIO does not support it.
235 @item @code{:around} method tag
236 This CLOS method tag is non-functional.
238 @item :default-initargs in @code{defclass}
239 Each slot has an @code{:initarg} tag, so this is not really necessary.
241 @item Mock object initializers
242 Each class contains a mock object used for fast initialization of
243 instantiated objects. Using functions with side effects on object slot
244 values can potentially cause modifications in the mock object. @eieio{}
245 should use a deep copy but currently does not.
249 @node Building Classes
250 @comment node-name, next, previous, up
251 @chapter Building Classes
253 First off, please note that this manual cannot serve as a complete
254 introduction to object oriented programming and generic functions in
255 LISP. Although EIEIO is not a complete CLOS implementation and also
256 differs from CLOS in several aspects, it follows the same basic
257 concepts. Therefore, it is highly recommended to learn these from a
258 textbook or tutorial first, especially if you only know OOP from
259 languages like C++ or Java. If on the other hand you are already
260 familiar with CLOS, you should be aware that @eieio{} does not implement
261 the full CLOS specification and also differs in some other aspects
262 (@xref{Introduction}, and @ref{CLOS compatibility}).
264 A @dfn{class} is a definition for organizing data and methods
265 together. An @eieio{} class has structures similar to the classes
266 found in other object-oriented (OO) languages.
268 To create a new class, use the @code{defclass} macro:
270 @defmac defclass class-name superclass-list slot-list &rest options-and-doc
272 Create a new class named @var{class-name}. The class is represented
273 by a self-referential symbol with the name @var{class-name}. @eieio{}
274 stores the structure of the class as a symbol property of
275 @var{class-name} (@pxref{Symbol Components,,,elisp,GNU Emacs Lisp
278 The @var{class-name} symbol's variable documentation string is a
279 modified version of the doc string found in @var{options-and-doc}.
280 Each time a method is defined, the symbol's documentation string is
281 updated to include the methods documentation as well.
283 The parent classes for @var{class-name} is @var{superclass-list}.
284 Each element of @var{superclass-list} must be a class. These classes
285 are the parents of the class being created. Every slot that appears
286 in each parent class is replicated in the new class.
288 If two parents share the same slot name, the parent which appears in
289 the @var{superclass-list} first sets the tags for that slot. If the
290 new class has a slot with the same name as the parent, the new slot
291 overrides the parent's slot.
293 When overriding a slot, some slot attributes cannot be overridden
294 because they break basic OO rules. You cannot override @code{:type}
295 or @code{:protection}.
299 Whenever defclass is used to create a new class, two predicates are
300 created for it, named @code{@var{CLASS-NAME}-p} and
301 @code{@var{CLASS-NAME}-child-p}:
303 @defun CLASS-NAME-p object
304 Return @code{t} if @var{OBJECT} is of the class @var{CLASS-NAME}.
307 @defun CLASS-NAME-child-p object
308 Return @code{t} if @var{OBJECT} is of the class @var{CLASS-NAME},
309 or is of a subclass of @var{CLASS-NAME}.
312 @defvar eieio-error-unsupported-class-tags
313 If non-nil, @code{defclass} signals an error if a tag in a slot
314 specifier is unsupported.
316 This option is here to support programs written with older versions of
317 @eieio{}, which did not produce such errors.
321 * Inheritance:: How to specify parents classes.
322 * Slot Options:: How to specify features of a slot.
323 * Class Options:: How to specify features for this class.
329 @dfn{Inheritance} is a basic feature of an object-oriented language.
330 In @eieio{}, a defined class specifies the super classes from which it
331 inherits by using the second argument to @code{defclass}. Here is an
335 (defclass my-baseclass ()
336 ((slot-A :initarg :slot-A)
337 (slot-B :initarg :slot-B))
342 To subclass from @code{my-baseclass}, we specify it in the superclass
346 (defclass my-subclass (my-baseclass)
347 ((specific-slot-A :initarg specific-slot-A)
349 "My subclass of my-baseclass")
353 Instances of @code{my-subclass} will inherit @code{slot-A} and
354 @code{slot-B}, in addition to having @code{specific-slot-A} from the
355 declaration of @code{my-subclass}.
357 @eieio{} also supports multiple inheritance. Suppose we define a
358 second baseclass, perhaps an ``interface'' class, like this:
361 (defclass my-interface ()
362 ((interface-slot :initarg :interface-slot))
363 "An interface to special behavior."
368 The interface class defines a special @code{interface-slot}, and also
369 specifies itself as abstract. Abstract classes cannot be
370 instantiated. It is not required to make interfaces abstract, but it
371 is a good programming practice.
373 We can now modify our definition of @code{my-subclass} to use this
374 interface class, together with our original base class:
377 (defclass my-subclass (my-baseclass my-interface)
378 ((specific-slot-A :initarg specific-slot-A)
380 "My subclass of my-baseclass")
384 With this, @code{my-subclass} also has @code{interface-slot}.
386 If @code{my-baseclass} and @code{my-interface} had slots with the same
387 name, then the superclass showing up in the list first defines the
390 Inheritance in @eieio{} is more than just combining different slots.
391 It is also important in method invocation. @ref{Methods}.
393 If a method is called on an instance of @code{my-subclass}, and that
394 method only has an implementation on @code{my-baseclass}, or perhaps
395 @code{my-interface}, then the implementation for the baseclass is
398 If there is a method implementation for @code{my-subclass}, and
399 another in @code{my-baseclass}, the implementation for
400 @code{my-subclass} can call up to the superclass as well.
403 @section Slot Options
405 The @var{slot-list} argument to @code{defclass} is a list of elements
406 where each element defines one slot. Each slot is a list of the form
409 (SLOT-NAME :TAG1 ATTRIB-VALUE1
415 where @var{SLOT-NAME} is a symbol that will be used to refer to the
416 slot. @var{:TAG} is a symbol that describes a feature to be set
417 on the slot. @var{ATTRIB-VALUE} is a lisp expression that will be
424 A symbol that can be used in the argument list of the constructor to
425 specify a value for the new instance being created.
427 A good symbol to use for initarg is one that starts with a colon @code{:}.
429 The slot specified like this:
431 (myslot :initarg :myslot)
433 could then be initialized to the number 1 like this:
435 (myobject "name" :myslot 1)
438 @xref{Making New Objects}.
441 A expression used as the default value for this slot.
443 If @code{:initform} is left out, that slot defaults to being unbound.
444 It is an error to reference an unbound slot, so if you need
445 slots to always be in a bound state, you should always use an
446 @code{:initform} specifier.
448 Use @code{slot-boundp} to test if a slot is unbound
449 (@pxref{Predicates}). Use @code{slot-makeunbound} to set a slot to
450 being unbound after giving it a value (@pxref{Accessing Slots}).
452 The value passed to initform is automatically quoted. Thus,
456 appears as the specified list in the default object.
457 A symbol that is a function like this:
461 will set the initial value as that symbol.
463 After a class has been created with @code{defclass}, you can change
464 that default value with @code{oset-default}. @ref{Accessing Slots}.
467 An unquoted type specifier used to validate data set into this slot.
468 @xref{Type Predicates,,,cl,Common Lisp Extensions}.
469 Here are some examples:
476 An object of your class type.
477 @item (or null symbol)
482 Either :class or :instance (defaults to :instance) used to
483 specify how data is stored. Slots stored per instance have unique
484 values for each object. Slots stored per class have shared values for
485 each object. If one object changes a :class allocated slot, then all
486 objects for that class gain the new value.
489 Documentation detailing the use of this slot. This documentation is
490 exposed when the user describes a class, and during customization of an
494 Name of a generic function which can be used to fetch the value of this slot.
495 You can call this function later on your object and retrieve the value
498 This options is in the CLOS spec, but is not fully compliant in @eieio{}.
501 Name of a generic function which will write this slot.
503 This options is in the CLOS spec, but is not fully compliant in @eieio{}.
506 Name of a generic function which will read this slot.
508 This options is in the CLOS spec, but is not fully compliant in @eieio{}.
511 A custom :type specifier used when editing an object of this type.
512 See documentation for @code{defcustom} for details. This specifier is
513 equivalent to the :type spec of a @code{defcustom} call.
515 This options is specific to Emacs, and is not in the CLOS spec.
518 When customizing an object, the value of :label will be used instead
519 of the slot name. This enables better descriptions of the data than
520 would usually be afforded.
522 This options is specific to Emacs, and is not in the CLOS spec.
525 Similar to @code{defcustom}'s :group command, this organizes different
526 slots in an object into groups. When customizing an object, only the
527 slots belonging to a specific group need be worked with, simplifying the
530 This options is specific to Emacs, and is not in the CLOS spec.
533 This routine takes a symbol which is a function name. The function
534 should accept one argument. The argument is the value from the slot
535 to be printed. The function in @code{object-write} will write the
536 slot value out to a printable form on @code{standard-output}.
538 The output format MUST be something that could in turn be interpreted
539 with @code{read} such that the object can be brought back in from the
540 output stream. Thus, if you wanted to output a symbol, you would need
541 to quote the symbol. If you wanted to run a function on load, you
542 can output the code to do the construction of the value.
545 When using a slot referencing function such as @code{slot-value}, and
546 the value behind @var{slot} is private or protected, then the current
547 scope of operation must be within a method of the calling object.
553 Access this slot from any scope.
555 Access this slot only from methods of the same class or a child class.
557 Access this slot only from methods of the same class.
560 This options is specific to Emacs, and is not in the CLOS spec.
565 @section Class Options
567 In the @var{options-and-doc} arguments to @code{defclass}, the
568 following class options may be specified:
572 A documentation string for this class.
574 If an Emacs-style documentation string is also provided, then this
575 option is ignored. An Emacs-style documentation string is not
576 prefixed by the @code{:documentation} tag, and appears after the list
577 of slots, and before the options.
579 @item :allow-nil-initform
580 If this option is non-nil, and the @code{:initform} is @code{nil}, but
581 the @code{:type} is specifies something such as @code{string} then allow
582 this to pass. The default is to have this option be off. This is
583 implemented as an alternative to unbound slots.
585 This options is specific to Emacs, and is not in the CLOS spec.
588 A class which is @code{:abstract} cannot be instantiated, and instead
589 is used to define an interface which subclasses should implement.
591 This option is specific to Emacs, and is not in the CLOS spec.
594 This is a list of groups that can be customized within this class. This
595 slot is auto-generated when a class is created and need not be
596 specified. It can be retrieved with the @code{class-option} command,
597 however, to see what groups are available.
599 This option is specific to Emacs, and is not in the CLOS spec.
601 @item :method-invocation-order
602 This controls the order in which method resolution occurs for
603 @code{:primary} methods in cases of multiple inheritance. The order
604 affects which method is called first in a tree, and if
605 @code{call-next-method} is used, it controls the order in which the
606 stack of methods are run.
612 Search for methods in the class hierarchy in breadth first order.
615 Search for methods in the class hierarchy in a depth first order.
617 Searches for methods in in a linearized way that most closely matches
618 what CLOS does when a monotonic class structure is defined.
621 @xref{Method Invocation}, for more on method invocation order.
624 Unsupported CLOS option. Enables the use of a different base class other
625 than @code{standard-class}.
627 @item :default-initargs
628 Unsupported CLOS option. Specifies a list of initargs to be used when
629 creating new objects. As far as I can tell, this duplicates the
630 function of @code{:initform}.
633 @xref{CLOS compatibility}, for more details on CLOS tags versus
634 @eieio{}-specific tags.
636 @node Making New Objects
637 @comment node-name, next, previous, up
638 @chapter Making New Objects
640 Suppose we have a simple class is defined, such as:
648 It is now possible to create objects of that class type.
650 Calling @code{defclass} has defined two new functions. One is the
651 constructor @var{record}, and the other is the predicate,
654 @defun record object-name &rest slots
656 This creates and returns a new object. This object is not assigned to
657 anything, and will be garbage collected if not saved. This object
658 will be given the string name @var{object-name}. There can be
659 multiple objects of the same name, but the name slot provides a handy
660 way to keep track of your objects. @var{slots} is just all the slots
661 you wish to preset. Any slot set as such @emph{will not} get its
662 default value, and any side effects from a slot's @code{:initform}
663 that may be a function will not occur.
665 An example pair would appear simply as @code{:value 1}. Of course you
666 can do any valid Lispy thing you want with it, such as
667 @code{:value (if (boundp 'special-symbol) special-symbol nil)}
669 Example of creating an object from a class:
672 (record "test" :value 3 :reference nil)
677 To create an object from a class symbol, use @code{make-instance}.
679 @defun make-instance class &rest initargs
680 @anchor{make-instance}
681 Make a new instance of @var{class} based on @var{initargs}.
682 @var{class} is a class symbol. For example:
688 @var{initargs} is a property list with keywords based on the @code{:initarg}
689 for each slot. For example:
692 (make-instance @code{'foo} @code{:slot1} value1 @code{:slotN} valueN)
697 If the first element of @var{initargs} is a string, it is used as the
700 In @eieio{}, the class' constructor requires a name for use when printing.
701 @dfn{make-instance} in CLOS doesn't use names the way Emacs does, so the
702 class is used as the name slot instead when @var{initargs} doesn't start with
706 @node Accessing Slots
707 @comment node-name, next, previous, up
708 @chapter Accessing Slots
710 There are several ways to access slot values in an object. The naming
711 and argument-order conventions are similar to those used for
712 referencing vectors (@pxref{Vectors,,,elisp,GNU Emacs Lisp Reference
715 @defmac oset object slot value
716 This macro sets the value behind @var{slot} to @var{value} in
717 @var{object}. It returns @var{value}.
720 @defmac oset-default class slot value
721 This macro sets the @code{:initform} for @var{slot} in @var{class} to
724 This allows the user to set both public and private defaults after the
725 class has been constructed, and provides a way to configure the
726 default behavior of packages built with classes (the same way
727 @code{setq-default} does for buffer-local variables).
729 For example, if a user wanted all @code{data-objects} (@pxref{Building
730 Classes}) to inform a special object of his own devising when they
731 changed, this can be arranged by simply executing this bit of code:
734 (oset-default data-object reference (list my-special-object))
738 @defmac oref obj slot
740 Retrieve the value stored in @var{obj} in the slot named by @var{slot}.
741 Slot is the name of the slot when created by @dfn{defclass} or the label
742 created by the @code{:initarg} tag.
745 @defmac oref-default obj slot
746 @anchor{oref-default}
747 Gets the default value of @var{obj} (maybe a class) for @var{slot}.
748 The default value is the value installed in a class with the @code{:initform}
749 tag. @var{slot} can be the slot name, or the tag specified by the @code{:initarg}
750 tag in the @dfn{defclass} call.
753 The following accessors are defined by CLOS to reference or modify
754 slot values, and use the previously mentioned set/ref routines.
756 @defun slot-value object slot
758 This function retrieves the value of @var{slot} from @var{object}.
759 Unlike @code{oref}, the symbol for @var{slot} must be quoted.
762 @defun set-slot-value object slot value
763 @anchor{set-slot-value}
764 This is not a CLOS function, but is meant to mirror @code{slot-value} if
765 you don't want to use the cl package's @code{setf} function. This
766 function sets the value of @var{slot} from @var{object}. Unlike
767 @code{oset}, the symbol for @var{slot} must be quoted.
770 @defun slot-makeunbound object slot
771 This function unbinds @var{slot} in @var{object}. Referencing an
772 unbound slot can signal an error.
775 @defun object-add-to-list object slot item &optional append
776 @anchor{object-add-to-list}
777 In OBJECT's @var{slot}, add @var{item} to the list of elements.
778 Optional argument @var{append} indicates we need to append to the list.
779 If @var{item} already exists in the list in @var{slot}, then it is not added.
780 Comparison is done with @dfn{equal} through the @dfn{member} function call.
781 If @var{slot} is unbound, bind it to the list containing @var{item}.
784 @defun object-remove-from-list object slot item
785 @anchor{object-remove-from-list}
786 In OBJECT's @var{slot}, remove occurrences of @var{item}.
787 Deletion is done with @dfn{delete}, which deletes by side effect
788 and comparisons are done with @dfn{equal}.
789 If @var{slot} is unbound, do nothing.
792 @defun with-slots spec-list object &rest body
794 Bind @var{spec-list} lexically to slot values in @var{object}, and execute @var{body}.
795 This establishes a lexical environment for referring to the slots in
796 the instance named by the given slot-names as though they were
797 variables. Within such a context the value of the slot can be
798 specified by using its slot name, as if it were a lexically bound
799 variable. Both setf and setq can be used to set the value of the
802 @var{spec-list} is of a form similar to @dfn{let}. For example:
811 Where each @var{var} is the local variable given to the associated
812 @var{slot}. A slot specified without a variable name is given a
813 variable name of the same name as the slot.
816 (defclass myclass () (x :initarg 1))
817 (setq mc (make-instance 'myclass))
818 (with-slots (x) mc x) => 1
819 (with-slots ((something x)) mc something) => 1
823 @node Writing Methods
824 @comment node-name, next, previous, up
825 @chapter Writing Methods
827 Writing a method in @eieio{} is similar to writing a function. The
828 differences are that there are some extra options and there can be
829 multiple definitions under the same function symbol.
831 Where a method defines an implementation for a particular data type, a
832 @dfn{generic method} accepts any argument, but contains no code. It
833 is used to provide the dispatching to the defined methods. A generic
834 method has no body, and is merely a symbol upon which methods are
835 attached. It also provides the base documentation for what methods
847 Each @eieio{} method has one corresponding generic. This generic
848 provides a function binding and the base documentation for the method
849 symbol (@pxref{Symbol Components,,,elisp,GNU Emacs Lisp Reference
852 @defmac defgeneric method arglist [doc-string]
853 This macro turns the (unquoted) symbol @var{method} into a function.
854 @var{arglist} is the default list of arguments to use (not implemented
855 yet). @var{doc-string} is the documentation used for this symbol.
857 A generic function acts as a placeholder for methods. There is no
858 need to call @code{defgeneric} yourself, as @code{defmethod} will call
859 it if necessary. Currently the argument list is unused.
861 @code{defgeneric} signals an error if you attempt to turn an existing
862 Emacs Lisp function into a generic function.
864 You can also create a generic method with @code{defmethod}
865 (@pxref{Methods}). When a method is created and there is no generic
866 method in place with that name, then a new generic will be created,
867 and the new method will use it.
870 In CLOS, a generic call also be used to provide an argument list and
871 dispatch precedence for all the arguments. In @eieio{}, dispatching
872 only occurs for the first argument, so the @var{arglist} is not used.
877 A method is a function that is executed if the first argument passed
878 to it matches the method's class. Different @eieio{} classes may
879 share the same method names.
881 Methods are created with the @code{defmethod} macro, which is similar
884 @defmac defmethod method [:before | :primary | :after | :static ] arglist [doc-string] forms
886 @var{method} is the name of the function to create.
888 @code{:before} and @code{:after} specify execution order (i.e., when
889 this form is called). If neither of these symbols are present, the
890 default priority is used (before @code{:after} and after
891 @code{:before}); this default priority is represented in CLOS as
894 @b{Note:} The @code{:BEFORE}, @code{:PRIMARY}, @code{:AFTER}, and
895 @code{:STATIC} method tags were in all capital letters in previous
896 versions of @eieio{}.
898 @var{arglist} is the list of arguments to this method. The first
899 argument in this list---and @emph{only} the first argument---may have
900 a type specifier (see the example below). If no type specifier is
901 supplied, the method applies to any object.
903 @var{doc-string} is the documentation attached to the implementation.
904 All method doc-strings are incorporated into the generic method's
905 function documentation.
907 @var{forms} is the body of the function.
912 In the following example, we create a method @code{mymethod} for the
913 @code{classname} class:
916 (defmethod mymethod ((obj classname) secondarg)
921 This method only executes if the @var{obj} argument passed to it is an
922 @eieio{} object of class @code{classname}.
924 A method with no type specifier is a @dfn{default method}. If a given
925 class has no implementation, then the default method is called when
926 that method is used on a given object of that class.
928 Only one default method per execution specifier (@code{:before},
929 @code{:primary}, or @code{:after}) is allowed. If two
930 @code{defmethod}s appear with @var{arglist}s lacking a type specifier,
931 and having the same execution specifier, then the first implementation
934 When a method is called on an object, but there is no method specified
935 for that object, but there is a method specified for object's parent
936 class, the parent class' method is called. If there is a method
937 defined for both, only the child's method is called. A child method
938 may call a parent's method using @code{call-next-method}, described
941 If multiple methods and default methods are defined for the same
942 method and class, they are executed in this order:
946 @item default :before
947 @item method :primary
948 @item default :primary
953 If no methods exist, Emacs signals a @code{no-method-definition}
954 error. @xref{Signals}.
956 @defun call-next-method &rest replacement-args
957 @anchor{call-next-method}
959 This function calls the superclass method from a subclass method.
960 This is the ``next method'' specified in the current method list.
962 If @var{replacement-args} is non-@code{nil}, then use them instead of
963 @code{eieio-generic-call-arglst}. At the top level, the generic
964 argument list is passed in.
966 Use @code{next-method-p} to find out if there is a next method to
971 @anchor{next-method-p}
972 Non-@code{nil} if there is a next method.
973 Returns a list of lambda expressions which is the @code{next-method}
977 At present, @eieio{} does not implement all the features of CLOS:
981 There is currently no @code{:around} tag.
983 CLOS allows multiple sets of type-cast arguments, but @eieio{} only
984 allows the first argument to be cast.
988 @section Static Methods
990 Static methods do not depend on an object instance, but instead
991 operate on an object's class. You can create a static method by using
992 the @code{:static} key with @code{defmethod}.
994 Do not treat the first argument of a @code{:static} method as an
995 object unless you test it first. Use the functions
996 @code{oref-default} or @code{oset-default} which will work on a class,
997 or on the class of an object.
999 A Class' @code{constructor} method is defined as a @code{:static}
1002 @b{Note:} The @code{:static} keyword is unique to @eieio{}.
1004 @c TODO - Write some more about static methods here
1006 @node Method Invocation
1007 @chapter Method Invocation
1009 When classes are defined, you can specify the
1010 @code{:method-invocation-order}. This is a feature specific to EIEIO.
1012 This controls the order in which method resolution occurs for
1013 @code{:primary} methods in cases of multiple inheritance. The order
1014 affects which method is called first in a tree, and if
1015 @code{call-next-method} is used, it controls the order in which the
1016 stack of methods are run.
1018 The original EIEIO order turned out to be broken for multiple
1019 inheritance, but some programs depended on it. As such this option
1020 was added when the default invocation order was fixed to something
1021 that made more sense in that case.
1026 @item :breadth-first
1027 Search for methods in the class hierarchy in breadth first order.
1028 This is the default.
1030 Search for methods in the class hierarchy in a depth first order.
1032 Searches for methods in in a linearized way that most closely matches
1033 what CLOS does when CLOS when a monotonic class structure is defined.
1035 This is derived from the Dylan language documents by
1036 Kim Barrett et al.: A Monotonic Superclass Linearization for Dylan
1037 Retrieved from: http://192.220.96.201/dylan/linearization-oopsla96.html
1041 @comment node-name, next, previous, up
1042 @chapter Predicates and Utilities
1044 Now that we know how to create classes, access slots, and define
1045 methods, it might be useful to verify that everything is doing ok. To
1046 help with this a plethora of predicates have been created.
1048 @defun find-class symbol &optional errorp
1050 Return the class that @var{symbol} represents.
1051 If there is no class, @code{nil} is returned if @var{errorp} is @code{nil}.
1052 If @var{errorp} is non-@code{nil}, @code{wrong-argument-type} is signaled.
1055 @defun class-p class
1057 Return @code{t} if @var{class} is a valid class vector.
1058 @var{class} is a symbol.
1061 @defun slot-exists-p object-or-class slot
1062 @anchor{slot-exists-p}
1063 Non-@code{nil} if @var{object-or-class} has @var{slot}.
1066 @defun slot-boundp object slot
1067 @anchor{slot-boundp}
1068 Non-@code{nil} if OBJECT's @var{slot} is bound.
1069 Setting a slot's value makes it bound. Calling @dfn{slot-makeunbound} will
1070 make a slot unbound.
1071 @var{object} can be an instance or a class.
1074 @defun class-name class
1075 Return a string of the form @samp{#<class myclassname>} which should look
1076 similar to other Lisp objects like buffers and processes. Printing a
1077 class results only in a symbol.
1080 @defun class-option class option
1081 Return the value in @var{CLASS} of a given @var{OPTION}.
1085 (class-option eieio-default-superclass :documentation)
1088 Will fetch the documentation string for @code{eieio-default-superclass}.
1091 @defun class-constructor class
1092 Return a symbol used as a constructor for @var{class}. The
1093 constructor is a function used to create new instances of
1094 @var{CLASS}. This function provides a way to make an object of a class
1095 without knowing what it is. This is not a part of CLOS.
1098 @defun object-name obj
1099 Return a string of the form @samp{#<object-class myobjname>} for @var{obj}.
1100 This should look like Lisp symbols from other parts of Emacs such as
1101 buffers and processes, and is shorter and cleaner than printing the
1102 object's vector. It is more useful to use @code{object-print} to get
1103 and object's print form, as this allows the object to add extra display
1104 information into the symbol.
1107 @defun object-class obj
1108 Returns the class symbol from @var{obj}.
1112 CLOS symbol which does the same thing as @code{object-class}
1115 @defun object-class-fast obj
1116 Same as @code{object-class} except this is a macro, and no
1117 type-checking is performed.
1120 @defun object-class-name obj
1121 Returns the symbol of @var{obj}'s class.
1124 @defun class-parents class
1125 Returns the direct parents class of @var{class}. Returns @code{nil} if
1129 @defun class-parents-fast class
1130 Just like @code{class-parent} except it is a macro and no type checking
1134 @defun class-parent class
1135 Deprecated function which returns the first parent of @var{class}.
1138 @defun class-children class
1139 Return the list of classes inheriting from @var{class}.
1142 @defun class-children-fast class
1143 Just like @code{class-children}, but with no checks.
1146 @defun same-class-p obj class
1147 Returns @code{t} if @var{obj}'s class is the same as @var{class}.
1150 @defun same-class-fast-p obj class
1151 Same as @code{same-class-p} except this is a macro and no type checking
1155 @defun object-of-class-p obj class
1156 Returns @code{t} if @var{obj} inherits anything from @var{class}. This
1157 is different from @code{same-class-p} because it checks for inheritance.
1160 @defun child-of-class-p child class
1161 Returns @code{t} if @var{child} is a subclass of @var{class}.
1164 @defun generic-p method-symbol
1165 Returns @code{t} if @code{method-symbol} is a generic function, as
1166 opposed to a regular Emacs Lisp function.
1169 @node Association Lists
1170 @chapter Association Lists
1172 Lisp offers the concept of association lists, with primitives such as
1173 @code{assoc} used to access them. The following functions can be used
1174 to manage association lists of @eieio{} objects:
1176 @defun object-assoc key slot list
1177 @anchor{object-assoc}
1178 Return an object if @var{key} is @dfn{equal} to SLOT's value of an object in @var{list}.
1179 @var{list} is a list of objects whose slots are searched.
1180 Objects in @var{list} do not need to have a slot named @var{slot}, nor does
1181 @var{slot} need to be bound. If these errors occur, those objects will
1186 @defun object-assoc-list slot list
1187 Return an association list generated by extracting @var{slot} from all
1188 objects in @var{list}. For each element of @var{list} the @code{car} is
1189 the value of @var{slot}, and the @code{cdr} is the object it was
1190 extracted from. This is useful for generating completion tables.
1193 @defun eieio-build-class-alist &optional base-class
1194 Returns an alist of all currently defined classes. This alist is
1195 suitable for completion lists used by interactive functions to select a
1196 class. The optional argument @var{base-class} allows the programmer to
1197 select only a subset of classes which includes @var{base-class} and
1202 @comment node-name, next, previous, up
1203 @chapter Customizing Objects
1205 @eieio{} supports the Custom facility through two new widget types.
1206 If a variable is declared as type @code{object}, then full editing of
1207 slots via the widgets is made possible. This should be used
1208 carefully, however, because modified objects are cloned, so if there
1209 are other references to these objects, they will no longer be linked
1212 If you want in place editing of objects, use the following methods:
1214 @defun eieio-customize-object object
1215 Create a custom buffer and insert a widget for editing @var{object}. At
1216 the end, an @code{Apply} and @code{Reset} button are available. This
1217 will edit the object "in place" so references to it are also changed.
1218 There is no effort to prevent multiple edits of a singular object, so
1219 care must be taken by the user of this function.
1222 @defun eieio-custom-widget-insert object flags
1223 This method inserts an edit object into the current buffer in place.
1224 It is implemented as @code{(widget-create 'object-edit :value object)}.
1225 This method is provided as a locale for adding tracking, or
1226 specializing the widget insert procedure for any object.
1229 To define a slot with an object in it, use the @code{object} tag. This
1230 widget type will be automatically converted to @code{object-edit} if you
1231 do in place editing of you object.
1233 If you want to have additional actions taken when a user clicks on the
1234 @code{Apply} button, then overload the method @code{eieio-done-customizing}.
1235 This method does nothing by default, but that may change in the future.
1236 This would be the best way to make your objects persistent when using
1239 @section Widget extension
1241 When widgets are being created, one new widget extension has been added,
1242 called the @code{:slotofchoices}. When this occurs in a widget
1243 definition, all elements after it are removed, and the slot is specifies
1244 is queried and converted into a series of constants.
1247 (choice (const :tag "None" nil)
1248 :slotofchoices morestuff)
1251 and if the slot @code{morestuff} contains @code{(sym1 sym2 sym3)}, the
1252 above example is converted into:
1255 (choice (const :tag "None" nil)
1261 This is useful when a given item needs to be selected from a list of
1262 items defined in this second slot.
1265 @chapter Introspection
1267 Introspection permits a programmer to peek at the contents of a class
1268 without any previous knowledge of that class. While @eieio{} implements
1269 objects on top of vectors, and thus everything is technically visible,
1270 some functions have been provided. None of these functions are a part
1273 @defun object-slots obj
1274 Return the list of public slots for @var{obj}.
1277 @defun class-slot-initarg class slot
1278 For the given @var{class} return the :initarg associated with
1279 @var{slot}. Not all slots have initargs, so the return value can be
1284 @comment node-name, next, previous, up
1285 @chapter Base Classes
1287 All defined classes, if created with no specified parent class,
1288 inherit from a special class called @code{eieio-default-superclass}.
1289 @xref{Default Superclass}.
1291 Often, it is more convenient to inherit from one of the other base
1292 classes provided by @eieio{}, which have useful pre-defined
1293 properties. (Since @eieio{} supports multiple inheritance, you can
1294 even inherit from more than one of these classes at once.)
1297 * eieio-instance-inheritor:: Enable value inheritance between instances.
1298 * eieio-instance-tracker:: Enable self tracking instances.
1299 * eieio-singleton:: Only one instance of a given class.
1300 * eieio-persistent:: Enable persistence for a class.
1301 * eieio-named:: Use the object name as a :name slot.
1302 * eieio-speedbar:: Enable speedbar support in your objects.
1305 @node eieio-instance-inheritor
1306 @comment node-name, next, previous, up
1307 @section @code{eieio-instance-inheritor}
1309 This class is defined in the package @file{eieio-base}.
1311 Instance inheritance is a mechanism whereby the value of a slot in
1312 object instance can reference the parent instance. If the parent's slot
1313 value is changed, then the child instance is also changed. If the
1314 child's slot is set, then the parent's slot is not modified.
1316 @deftp {Class} eieio-instance-inheritor parent-instance
1317 A class whose instances are enabled with instance inheritance.
1318 The @var{parent-instance} slot indicates the instance which is
1319 considered the parent of the current instance. Default is @code{nil}.
1323 To use this class, inherit from it with your own class.
1324 To make a new instance that inherits from and existing instance of your
1325 class, use the @code{clone} method with additional parameters
1326 to specify local values.
1328 @cindex slot-unbound
1329 The @code{eieio-instance-inheritor} class works by causing cloned
1330 objects to have all slots unbound. This class' @code{slot-unbound}
1331 method will cause references to unbound slots to be redirected to the
1332 parent instance. If the parent slot is also unbound, then
1333 @code{slot-unbound} will signal an error named @code{slot-unbound}.
1335 @node eieio-instance-tracker
1336 @section @code{eieio-instance-tracker}
1338 This class is defined in the package @file{eieio-base}.
1340 Sometimes it is useful to keep a master list of all instances of a given
1341 class. The class @code{eieio-instance-tracker} performs this task.
1343 @deftp {Class} eieio-instance-tracker tracker-symbol
1344 Enable instance tracking for this class.
1345 The slot @var{tracker-symbol} should be initialized in inheritors of
1346 this class to a symbol created with @code{defvar}. This symbol will
1347 serve as the variable used as a master list of all objects of the given
1351 @defmethod eieio-instance-tracker initialize-instance obj slot
1352 This method is defined as an @code{:after} method.
1353 It adds new instances to the master list. Do not overload this method
1354 unless you use @code{call-next-method.}
1357 @defmethod eieio-instance-tracker delete-instance obj
1358 Remove @var{obj} from the master list of instances of this class.
1359 This may let the garbage collector nab this instance.
1362 @deffn eieio-instance-tracker-find key slot list-symbol
1363 This convenience function lets you find instances. @var{key} is the
1364 value to search for. @var{slot} is the slot to compare @var{KEY}
1365 against. The function @code{equal} is used for comparison.
1366 The parameter @var{list-symbol} is the variable symbol which contains the
1367 list of objects to be searched.
1370 @node eieio-singleton
1371 @comment node-name, next, previous, up
1372 @section @code{eieio-singleton}
1374 This class is defined in the package @file{eieio-base}.
1376 @deftp {Class} eieio-singleton
1377 Inheriting from the singleton class will guarantee that there will
1378 only ever be one instance of this class. Multiple calls to
1379 @code{make-instance} will always return the same object.
1382 @node eieio-persistent
1383 @comment node-name, next, previous, up
1384 @section @code{eieio-persistent}
1386 This class is defined in the package @file{eieio-base}.
1388 If you want an object, or set of objects to be persistent, meaning the
1389 slot values are important to keep saved between sessions, then you will
1390 want your top level object to inherit from @code{eieio-persistent}.
1392 To make sure your persistent object can be moved, make sure all file
1393 names stored to disk are made relative with
1394 @code{eieio-persistent-path-relative}.
1396 @deftp {Class} eieio-persistent file file-header-line
1397 Enables persistence for instances of this class.
1398 Slot @var{file} with initarg @code{:file} is the file name in which this
1399 object will be saved.
1400 Class allocated slot @var{file-header-line} is used with method
1401 @code{object-write} as a header comment.
1404 All objects can write themselves to a file, but persistent objects have
1405 several additional methods that aid in maintaining them.
1407 @defmethod eieio-persistent eieio-persistent-save obj &optional file
1408 Write the object @var{obj} to its file.
1409 If optional argument @var{file} is specified, use that file name
1413 @defmethod eieio-persistent eieio-persistent-path-relative obj file
1414 Return a file name derived from @var{file} which is relative to the
1415 stored location of @var{OBJ}. This method should be used to convert
1416 file names so that they are relative to the save file, making any system
1417 of files movable from one location to another.
1420 @defmethod eieio-persistent object-write obj &optional comment
1421 Like @code{object-write} for @code{standard-object}, but will derive
1422 a header line comment from the class allocated slot if one is not
1426 @defun eieio-persistent-read filename &optional class allow-subclass
1427 Read a persistent object from @var{filename}, and return it.
1428 Signal an error if the object in @var{FILENAME} is not a constructor
1429 for @var{CLASS}. Optional @var{allow-subclass} says that it is ok for
1430 @code{eieio-persistent-read} to load in subclasses of class instead of
1435 @comment node-name, next, previous, up
1436 @section @code{eieio-named}
1438 This class is defined in the package @file{eieio-base}.
1440 @deftp {Class} eieio-named
1442 Name storage already occurs in an object. This object provides get/set
1446 @node eieio-speedbar
1447 @comment node-name, next, previous, up
1448 @section @code{eieio-speedbar}
1450 This class is in package @file{eieio-speedbar}.
1452 If a series of class instances map to a tree structure, it is possible
1453 to cause your classes to be displayable in Speedbar. @xref{Top,,,speedbar}.
1454 Inheriting from these classes will enable a speedbar major display mode
1455 with a minimum of effort.
1457 @deftp {Class} eieio-speedbar buttontype buttonface
1458 Enables base speedbar display for a class.
1459 @cindex speedbar-make-tag-line
1460 The slot @var{buttontype} is any of the symbols allowed by the
1461 function @code{speedbar-make-tag-line} for the @var{exp-button-type}
1462 argument @xref{Extending,,,speedbar}.
1463 The slot @var{buttonface} is the face to use for the text of the string
1464 displayed in speedbar.
1465 The slots @var{buttontype} and @var{buttonface} are class allocated
1466 slots, and do not take up space in your instances.
1469 @deftp {Class} eieio-speedbar-directory-button buttontype buttonface
1470 This class inherits from @code{eieio-speedbar} and initializes
1471 @var{buttontype} and @var{buttonface} to appear as directory level lines.
1474 @deftp {Class} eieio-speedbar-file-button buttontype buttonface
1475 This class inherits from @code{eieio-speedbar} and initializes
1476 @var{buttontype} and @var{buttonface} to appear as file level lines.
1479 To use these classes, inherit from one of them in you class. You can
1480 use multiple inheritance with them safely. To customize your class for
1481 speedbar display, override the default values for @var{buttontype} and
1482 @var{buttonface} to get the desired effects.
1484 Useful methods to define for your new class include:
1486 @defmethod eieio-speedbar eieio-speedbar-derive-line-path obj depth
1487 Return a string representing a directory associated with an instance
1488 of @var{obj}. @var{depth} can be used to index how many levels of
1489 indentation have been opened by the user where @var{obj} is shown.
1493 @defmethod eieio-speedbar eieio-speedbar-description obj
1494 Return a string description of @var{OBJ}.
1495 This is shown in the minibuffer or tooltip when the mouse hovers over
1496 this instance in speedbar.
1499 @defmethod eieio-speedbar eieio-speedbar-child-description obj
1500 Return a string representing a description of a child node of @var{obj}
1501 when that child is not an object. It is often useful to just use
1502 item info helper functions such as @code{speedbar-item-info-file-helper}.
1505 @defmethod eieio-speedbar eieio-speedbar-object-buttonname obj
1506 Return a string which is the text displayed in speedbar for @var{obj}.
1509 @defmethod eieio-speedbar eieio-speedbar-object-children obj
1510 Return a list of children of @var{obj}.
1513 @defmethod eieio-speedbar eieio-speedbar-child-make-tag-lines obj depth
1514 This method inserts a list of speedbar tag lines for @var{obj} to
1515 represent its children. Implement this method for your class
1516 if your children are not objects themselves. You still need to
1517 implement @code{eieio-speedbar-object-children}.
1519 In this method, use techniques specified in the Speedbar manual.
1520 @xref{Extending,,,speedbar}.
1523 Some other functions you will need to learn to use are:
1525 @deffn eieio-speedbar-create make-map key-map menu name toplevelfn
1526 Register your object display mode with speedbar.
1527 @var{make-map} is a function which initialized you keymap.
1528 @var{key-map} is a symbol you keymap is installed into.
1529 @var{menu} is an easy menu vector representing menu items specific to your
1531 @var{name} is a short string to use as a name identifying you mode.
1532 @var{toplevelfn} is a function called which must return a list of
1533 objects representing those in the instance system you wish to browse in
1536 Read the Extending chapter in the speedbar manual for more information
1537 on how speedbar modes work
1538 @xref{Extending,,,speedbar}.
1542 @comment node-name, next, previous, up
1543 @chapter Browsing class trees
1545 The command @kbd{M-x eieio-browse} displays a buffer listing all the
1546 currently loaded classes in Emacs. The classes are listed in an
1547 indented tree structure, starting from @code{eieio-default-superclass}
1548 (@pxref{Default Superclass}).
1550 With a prefix argument, this command prompts for a class name; it then
1551 lists only that class and its subclasses.
1553 Here is a sample tree from our current example:
1556 eieio-default-superclass
1558 +--data-object-symbol
1561 Note: new classes are consed into the inheritance lists, so the tree
1562 comes out upside-down.
1565 @comment node-name, next, previous, up
1566 @chapter Class Values
1568 Details about any class or object can be retrieved using the function
1569 @code{eieio-describe-class}. Interactively, type in the name of
1570 a class. In a program, pass it a string with the name of a class, a
1571 class symbol, or an object. The resulting buffer will display all slot
1574 Additionally, all methods defined to have functionality on this class is
1578 @comment node-name, next, previous, up
1579 @chapter Documentation
1581 It is possible to automatically create documentation for your classes in
1582 texinfo format by using the tools in the file @file{eieio-doc.el}
1584 @deffn Command eieiodoc-class class indexstring &optional skiplist
1586 This will start at the current point, and create an indented menu of
1587 all the child classes of, and including @var{class}, but skipping any
1588 classes that might be in @var{skiplist}. It will then create nodes for
1589 all these classes, subsection headings, and indexes.
1591 Each class will be indexed using the texinfo labeled index
1592 @var{indexstring} which is a two letter description.
1593 @xref{New Indices,,,texinfo,Texinfo manual}.
1595 To use this command, the texinfo macro
1598 @@defindex @@var @{ indexstring @}
1602 where @var{indexstring} is replaced with the two letter code.
1604 Next, an inheritance tree will be created listing all parents of that
1607 Then, all the slots will be expanded in tables, and described
1608 using the documentation strings from the code. Default values will also
1609 be displayed. Only those slots with @code{:initarg} specified will be
1610 expanded, others will be hidden. If a slot is inherited from a parent,
1611 that slot will also be skipped unless the default value is different.
1612 If there is a change, then the documentation part of the slot will be
1613 replace with an @@xref back to the parent.
1615 This command can only display documentation for classes whose
1616 definitions have been loaded in this Emacs session.
1620 @node Default Superclass
1621 @comment node-name, next, previous, up
1622 @chapter Default Superclass
1624 All defined classes, if created with no specified parent class, will
1625 inherit from a special class stored in
1626 @code{eieio-default-superclass}. This superclass is quite simple, but
1627 with it, certain default methods or attributes can be added to all
1628 objects. In CLOS, this would be named @code{STANDARD-CLASS}, and that
1629 symbol is an alias to @code{eieio-default-superclass}.
1631 Currently, the default superclass is defined as follows:
1634 (defclass eieio-default-superclass nil
1636 "Default parent class for classes with no specified parent class.
1637 Its slots are automatically adopted by classes with no specified
1638 parents. This class is not stored in the `parent' slot of a class vector."
1642 The default superclass implements several methods providing a default
1643 behavior for all objects created by @eieio{}.
1646 * Initialization:: How objects are initialized
1647 * Basic Methods:: Clone, print, and write
1648 * Signal Handling:: Methods for managing signals.
1651 @node Initialization
1652 @section Initialization
1654 When creating an object of any type, you can use its constructor, or
1655 @code{make-instance}. This, in turns calls the method
1656 @code{initialize-instance}, which then calls the method
1657 @code{shared-initialize}.
1659 These methods are all implemented on the default superclass so you do
1660 not need to write them yourself, unless you need to override one of
1663 Users should not need to call @code{initialize-instance} or
1664 @code{shared-initialize}, as these are used by @code{make-instance} to
1665 initialize the object. They are instead provided so that users can
1666 augment these behaviors.
1668 @defun initialize-instance obj &rest slots
1669 Initialize @var{obj}. Sets slots of @var{obj} with @var{slots} which
1670 is a list of name/value pairs. These are actually just passed to
1671 @code{shared-initialize}.
1674 @defun shared-initialize obj &rest slots
1675 Sets slots of @var{obj} with @var{slots} which is a list of name/value
1678 This is called from the default @code{constructor}.
1682 @section Basic Methods
1684 Additional useful methods defined on the base subclass are:
1686 @defun clone obj &rest params
1688 Make a copy of @var{obj}, and then apply @var{params}.
1689 @var{params} is a parameter list of the same form as @var{initialize-instance}
1690 which are applied to change the object. When overloading @dfn{clone}, be
1691 sure to call @dfn{call-next-method} first and modify the returned object.
1694 @defun object-print this &rest strings
1695 @anchor{object-print}
1696 Pretty printer for object @var{this}. Call function @dfn{object-name} with @var{strings}.
1697 The default method for printing object @var{this} is to use the
1698 function @dfn{object-name}.
1700 It is sometimes useful to put a summary of the object into the
1701 default #<notation> string when using eieio browsing tools.
1703 Implement this function and specify @var{strings} in a call to
1704 @dfn{call-next-method} to provide additional summary information.
1705 When passing in extra strings from child classes, always remember
1709 (defclass data-object ()
1711 "Object containing one data slot.")
1713 (defmethod object-print ((this data-object) &optional strings)
1714 "Return a string with a summary of the data object as part of the name."
1715 (apply 'call-next-method this
1716 (cons (format " value: %s" (render this)) strings)))
1719 Here is what some output could look like:
1721 (object-print test-object)
1722 => #<data-object test-object value: 3>
1726 @defun object-write obj &optional comment
1727 Write @var{obj} onto a stream in a readable fashion. The resulting
1728 output will be Lisp code which can be used with @code{read} and
1729 @code{eval} to recover the object. Only slots with @code{:initarg}s
1730 are written to the stream.
1733 @node Signal Handling
1734 @section Signal Handling
1736 The default superclass defines methods for managing error conditions.
1737 These methods all throw a signal for a particular error condition.
1739 By implementing one of these methods for a class, you can change the
1740 behavior that occurs during one of these error cases, or even ignore
1741 the error by providing some behavior.
1743 @defun slot-missing object slot-name operation &optional new-value
1744 @anchor{slot-missing}
1745 Method invoked when an attempt to access a slot in @var{object} fails.
1746 @var{slot-name} is the name of the failed slot, @var{operation} is the type of access
1747 that was requested, and optional @var{new-value} is the value that was desired
1750 This method is called from @code{oref}, @code{oset}, and other functions which
1751 directly reference slots in EIEIO objects.
1753 The default method signals an error of type @code{invalid-slot-name}.
1756 You may override this behavior, but it is not expected to return in the
1757 current implementation.
1759 This function takes arguments in a different order than in CLOS.
1762 @defun slot-unbound object class slot-name fn
1763 @anchor{slot-unbound}
1764 Slot unbound is invoked during an attempt to reference an unbound slot.
1765 @var{object} is the instance of the object being reference. @var{class} is the
1766 class of @var{object}, and @var{slot-name} is the offending slot. This function
1767 throws the signal @code{unbound-slot}. You can overload this function and
1768 return the value to use in place of the unbound value.
1769 Argument @var{fn} is the function signaling this error.
1770 Use @dfn{slot-boundp} to determine if a slot is bound or not.
1772 In @var{clos}, the argument list is (@var{class} @var{object} @var{slot-name}), but
1773 @var{eieio} can only dispatch on the first argument, so the first two are swapped.
1776 @defun no-applicable-method object method &rest args
1777 @anchor{no-applicable-method}
1778 Called if there are no implementations for @var{object} in @var{method}.
1779 @var{object} is the object which has no method implementation.
1780 @var{args} are the arguments that were passed to @var{method}.
1782 Implement this for a class to block this signal. The return
1783 value becomes the return value of the original method call.
1786 @defun no-next-method object &rest args
1787 @anchor{no-next-method}
1788 Called from @dfn{call-next-method} when no additional methods are available.
1789 @var{object} is othe object being called on @dfn{call-next-method}.
1790 @var{args} are the arguments it is called by.
1791 This method signals @dfn{no-next-method} by default. Override this
1792 method to not throw an error, and its return value becomes the
1793 return value of @dfn{call-next-method}.
1797 @comment node-name, next, previous, up
1800 There are new condition names (signals) that can be caught when using
1803 @deffn Signal invalid-slot-name obj-or-class slot
1804 This signal is called when an attempt to reference a slot in an
1805 @var{obj-or-class} is made, and the @var{slot} is not defined for
1809 @deffn Signal no-method-definition method arguments
1810 This signal is called when @var{method} is called, with @var{arguments}
1811 and nothing is resolved. This occurs when @var{method} has been
1812 defined, but the arguments make it impossible for @eieio{} to determine
1813 which method body to run.
1815 To prevent this signal from occurring in your class, implement the
1816 method @code{no-applicable-method} for your class. This method is
1817 called when to throw this signal, so implementing this for your class
1818 allows you block the signal, and perform some work.
1821 @deffn Signal no-next-method class arguments
1822 This signal is called if the function @code{call-next-method} is called
1823 and there is no next method to be called.
1825 Overload the method @code{no-next-method} to protect against this signal.
1828 @deffn Signal invalid-slot-type slot spec value
1829 This signal is called when an attempt to set @var{slot} is made, and
1830 @var{value} doesn't match the specified type @var{spec}.
1832 In @eieio{}, this is also used if a slot specifier has an invalid value
1833 during a @code{defclass}.
1836 @deffn Signal unbound-slot object class slot
1837 This signal is called when an attempt to reference @var{slot} in
1838 @var{object} is made, and that instance is currently unbound.
1841 @node Naming Conventions
1842 @comment node-name, next, previous, up
1843 @chapter Naming Conventions
1845 @xref{Tips,,Tips and Conventions,elisp,GNU Emacs Lisp Reference
1846 Manual}, for a description of Emacs Lisp programming conventions.
1847 These conventions help ensure that Emacs packages work nicely one
1848 another, so an @eieio{}-based program should follow them. Here are
1849 some conventions that apply specifically to @eieio{}-based programs:
1853 @item Come up with a package prefix that is relatively short. Prefix
1854 all classes, and methods with your prefix. This is a standard
1855 convention for functions and variables in Emacs.
1857 @item Do not prefix method names with the class name. All methods in
1858 @eieio{} are ``virtual'', and are dynamically dispatched. Anyone can
1859 override your methods at any time. Your methods should be prefixed
1860 with your package name.
1862 @item Do not prefix slots in your class. The slots are always locally
1863 scoped to your class, and need no prefixing.
1865 @item If your library inherits from other libraries of classes, you
1866 must ``require'' that library with the @code{require} command.
1870 @node CLOS compatibility
1871 @comment node-name, next, previous, up
1872 @chapter CLOS compatibility
1874 Currently, the following functions should behave almost as expected from
1880 All slot keywords are available but not all work correctly.
1881 Slot keyword differences are:
1885 @item :reader, and :writer tags
1886 Create methods that signal errors instead of creating an unqualified
1887 method. You can still create new ones to do its business.
1890 This should create an unqualified method to access a slot, but
1891 instead pre-builds a method that gets the slot's value.
1894 Specifier uses the @code{typep} function from the @file{cl}
1895 package. @xref{Type Predicates,,,cl,Common Lisp Extensions}.
1896 It therefore has the same issues as that package. Extensions include
1897 the ability to provide object names.
1900 Defclass also supports class options, but does not currently use values
1901 of @code{:metaclass}, and @code{:default-initargs}.
1904 Make instance works as expected, however it just uses the @eieio{} instance
1905 creator automatically generated when a new class is created.
1906 @xref{Making New Objects}.
1909 Creates the desired symbol, and accepts all of the expected arguments
1910 except @code{:around}.
1913 Calls defgeneric, and accepts most of the expected arguments. Only
1914 the first argument to the created method may have a type specifier.
1915 To type cast against a class, the class must exist before defmethod is
1916 called. In addition, the @code{:around} tag is not supported.
1918 @item call-next-method
1919 Inside a method, calls the next available method up the inheritance tree
1920 for the given object. This is different than that found in CLOS because
1921 in @eieio{} this function accepts replacement arguments. This permits
1922 subclasses to modify arguments as they are passed up the tree. If no
1923 arguments are given, the expected CLOS behavior is used.
1925 If the common-lisp subsystem is loaded, the setf parameters are also
1926 loaded so the form @code{(setf (slot-value object slot) t)} should
1930 CLOS supports the @code{describe} command, but @eieio{} only provides
1931 @code{eieio-describe-class}, and @code{eieio-describe-generic}. These
1932 functions are adviced into @code{describe-variable}, and
1933 @code{describe-function}.
1935 When creating a new class (@pxref{Building Classes}) there are several
1936 new keywords supported by @eieio{}.
1938 In @eieio{} tags are in lower case, not mixed case.
1943 @eieio{} is an incomplete implementation of CLOS@. Finding ways to
1944 improve the compatibility would help make CLOS style programs run
1947 Some important compatibility features that would be good to add are:
1951 Support for metaclasses and EQL specialization.
1953 @code{:around} method key.
1955 Method dispatch for built-in types.
1957 Method dispatch for multiple argument typing.
1959 Improve integration with the @file{cl} package.
1962 There are also improvements to be made to allow @eieio{} to operate
1963 better in the Emacs environment.
1967 Allow subclassing of Emacs built-in types, such as faces, markers, and
1970 Allow method overloading of method-like functions in Emacs.
1973 @node GNU Free Documentation License
1974 @appendix GNU Free Documentation License
1975 @include doclicense.texi
1977 @node Function Index
1978 @unnumbered Function Index