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, 2008, 2009, 2010 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. Buying copies from the FSF supports it in
26 developing GNU and promoting software freedom.''
33 * eieio: (eieio). Objects for Emacs
39 @center @titlefont{@value{TITLE}}
41 @center by @value{AUTHOR}
49 @node Top, Quick Start, (dir), (dir)
50 @comment node-name, next, previous, up
53 @eieio{} (``Enhanced Implementation of Emacs Interpreted Objects'') is
54 a CLOS (Common Lisp Object System) compatibility layer for Emacs Lisp.
55 It provides a framework for writing object-oriented applications in
63 * Quick Start:: Quick start for EIEIO.
64 * Introduction:: Why use @eieio{}? Basic overview, samples list.
65 * Building Classes:: How to write new class structures.
66 * Making New Objects:: How to construct new objects.
67 * Accessing Slots:: How to access a slot.
68 * Writing Methods:: How to write a method.
69 @c * Method Invocation:: How methods are invoked.
70 * Predicates:: Class-p, Object-p, etc-p.
71 * Association Lists:: List of objects as association lists.
72 * Customizing:: Customizing objects.
73 * Introspection:: Looking inside a class.
74 * Base Classes:: Additional classes you can inherit from.
75 * Browsing:: Browsing your class lists.
76 * Class Values:: Displaying information about a class or object.
77 * Default Superclass:: The root superclasses.
78 * Signals:: When you make errors
79 * Naming Conventions:: Name your objects in an Emacs friendly way.
80 * CLOS compatibility:: What are the differences?
81 * Wish List:: Things about EIEIO that could be improved.
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 Automatic texinfo documentation generator.
208 Several base classes for interesting tasks.
212 Public and private classifications for slots (extensions to CLOS)
214 Customization support in a class (extension to CLOS)
217 Here are some CLOS features that @eieio{} presently lacks:
220 @item Complete @code{defclass} tag support
221 All CLOS tags are currently supported, but the following are not
222 currently implemented correctly:
226 There is only one base superclass for all @eieio{} classes, which is
227 the @code{eieio-default-superclass}.
228 @item :default-initargs
229 Each slot has an @code{:initarg} tag, so this is not really necessary.
232 @item Mock object initializers
233 Each class contains a mock object used for fast initialization of
234 instantiated objects. Using functions with side effects on object slot
235 values can potentially cause modifications in the mock object. @eieio{}
236 should use a deep copy but currently does not.
238 @item @code{:around} method tag
239 This CLOS method tag is non-functional.
243 @node Building Classes
244 @comment node-name, next, previous, up
245 @chapter Building Classes
247 A @dfn{class} is a definition for organizing data and methods
248 together. An @eieio{} class has structures similar to the classes
249 found in other object-oriented (OO) languages.
251 To create a new class, use the @code{defclass} macro:
253 @defmac defclass class-name superclass-list slot-list &rest options-and-doc
255 Create a new class named @var{class-name}. The class is represented
256 by a self-referential symbol with the name @var{class-name}. @eieio{}
257 stores the structure of the class as a symbol property of
258 @var{class-name} (@pxref{Symbol Components,,,elisp,GNU Emacs Lisp
261 The @var{class-name} symbol's variable documentation string is a
262 modified version of the doc string found in @var{options-and-doc}.
263 Each time a method is defined, the symbol's documentation string is
264 updated to include the methods documentation as well.
266 The parent classes for @var{class-name} is @var{superclass-list}.
267 Each element of @var{superclass-list} must be a class. These classes
268 are the parents of the class being created. Every slot that appears
269 in each parent class is replicated in the new class.
271 If two parents share the same slot name, the parent which appears in
272 the @var{superclass-list} first sets the tags for that slot. If the
273 new class has a slot with the same name as the parent, the new slot
274 overrides the parent's slot.
278 Whenever defclass is used to create a new class, two predicates are
279 created for it, named @code{@var{CLASS-NAME}-p} and
280 @code{@var{CLASS-NAME}-child-p}:
282 @defun CLASS-NAME-p object
283 Return @code{t} if @var{OBJECT} is of the class @var{CLASS-NAME}.
286 @defun CLASS-NAME-child-p object
287 Return @code{t} if @var{OBJECT} is of the class @var{CLASS-NAME},
288 or is of a subclass of @var{CLASS-NAME}.
291 @defvar eieio-error-unsupported-class-tags
292 If non-nil, @code{defclass} signals an error if a tag in a slot
293 specifier is unsupported.
295 This option is here to support programs written with older versions of
296 @eieio{}, which did not produce such errors.
300 * Inheritance:: How to specify parents classes
301 * Slot Options:: How to specify features of a slot.
302 * Class Options:: How to specify features for this class.
308 @dfn{Inheritance} is a basic feature of an object-oriented language.
309 In @eieio{}, a defined class specifies the super classes from which it
310 inherits by using the second argument to @code{defclass}. Here is an
314 (defclass my-baseclass ()
315 ((slot-A :initarg :slot-A)
316 (slot-B :initarg :slot-B))
321 To subclass from @code{my-baseclass}, we specify it in the superclass
325 (defclass my-subclass (my-baseclass)
326 ((specific-slot-A :initarg specific-slot-A)
328 "My subclass of my-baseclass")
332 Instances of @code{my-subclass} will inherit @code{slot-A} and
333 @code{slot-B}, in addition to having @code{specific-slot-A} from the
334 declaration of @code{my-subclass}.
336 @eieio{} also supports multiple inheritance. Suppose we define a
337 second baseclass, perhaps an ``interface'' class, like this:
340 (defclass my-interface ()
341 ((interface-slot :initarg :interface-slot))
342 "An interface to special behavior."
347 The interface class defines a special @code{interface-slot}, and also
348 specifies itself as abstract. Abstract classes cannot be
349 instantiated. It is not required to make interfaces abstract, but it
350 is a good programming practice.
352 We can now modify our definition of @code{my-subclass} to use this
353 interface class, together with our original base class:
356 (defclass my-subclass (my-baseclass my-interface)
357 ((specific-slot-A :initarg specific-slot-A)
359 "My subclass of my-baseclass")
363 With this, @code{my-subclass} also has @code{interface-slot}.
365 If @code{my-baseclass} and @code{my-interface} had slots with the same
366 name, then the superclass showing up in the list first defines the
369 Inheritance in @eieio{} is more than just combining different slots.
370 It is also important in method invocation. @ref{Methods}.
372 If a method is called on an instance of @code{my-subclass}, and that
373 method only has an implementation on @code{my-baseclass}, or perhaps
374 @code{my-interface}, then the implementation for the baseclass is
377 If there is a method implementation for @code{my-subclass}, and
378 another in @code{my-baseclass}, the implementation for
379 @code{my-subclass} can call up to the superclass as well.
382 @section Slot Options
384 The @var{slot-list} argument to @code{defclass} is a list of elements
385 where each element defines one slot. Each slot is a list of the form
388 (SLOT-NAME :TAG1 ATTRIB-VALUE1
394 where @var{SLOT-NAME} is a symbol that will be used to refer to the
395 slot. @var{:TAG} is a symbol that describes a feature to be set
396 on the slot. @var{ATTRIB-VALUE} is a lisp expression that will be
403 A symbol that can be used in the argument list of the constructor to
404 specify a value for the new instance being created.
406 A good symbol to use for initarg is one that starts with a colon @code{:}.
408 The slot specified like this:
410 (myslot :initarg :myslot)
412 could then be initialized to the number 1 like this:
414 (myobject "name" :myslot 1)
417 @xref{Making New Objects}.
420 A expression used as the default value for this slot.
422 If @code{:initform} is left out, that slot defaults to being unbound.
423 It is an error to reference an unbound slot, so if you need
424 slots to always be in a bound state, you should always use an
425 @code{:initform} specifier.
427 Use @code{slot-boundp} to test if a slot is unbound
428 (@pxref{Predicates}). Use @code{slot-makeunbound} to set a slot to
429 being unbound after giving it a value (@pxref{Accessing Slots}).
431 The value passed to initform is automatically quoted. Thus,
435 appears as the specified list in the default object.
436 A symbol that is a function like this:
440 will set the initial value as that symbol.
441 A function that is a lambda expression, like this:
443 :initform (lambda () some-variablename)
446 will be evaluated at instantiation time to the value of
447 @code{some-variablename}.
448 @c This feature was more annoying than useful. Use the
449 @c `initialize-instance' function to do this.
451 @c On the other hand, if you need code to be
452 @c executed at instantiation time as the initform, code like this:
454 @c :initform (lambda () (+ 1 some-global-var))
456 @c will be identified as a function call, and be executed in place.
458 @cindex lambda-default
461 Lastly, using the function @code{lambda-default} instead of
462 @code{lambda} will let you specify a lambda expression to use as the
463 value, without evaluation, thus:
465 :initform (lambda-default () some-variablename)
467 @c @@TODO - This will be deleted after fair warning.
468 will not be evaluated at instantiation time, and the value in this
469 slot will instead be @code{(lambda () some-variablename)}.
471 After a class has been created with @code{defclass}, you can change
472 that default value with @code{oset-default}. @ref{Accessing Slots}.
475 An unquoted type specifier used to validate data set into this slot.
476 @xref{(cl)Type Predicates}.
477 Here are some examples:
484 An object of your class type.
485 @item (or null symbol)
488 A function symbol, or a @code{lambda-default} expression.
493 Either :class or :instance (defaults to :instance) used to
494 specify how data is stored. Slots stored per instance have unique
495 values for each object. Slots stored per class have shared values for
496 each object. If one object changes a :class allocated slot, then all
497 objects for that class gain the new value.
500 Documentation detailing the use of this slot. This documentation is
501 exposed when the user describes a class, and during customization of an
505 Name of a generic function which can be used to fetch the value of this slot.
506 You can call this function later on your object and retrieve the value
509 This options is in the CLOS spec, but is not fully compliant in @eieio{}.
512 Name of a generic function which will write this slot.
514 This options is in the CLOS spec, but is not fully compliant in @eieio{}.
517 Name of a generic function which will read this slot.
519 This options is in the CLOS spec, but is not fully compliant in @eieio{}.
522 A custom :type specifier used when editing an object of this type.
523 See documentation for @code{defcustom} for details. This specifier is
524 equivalent to the :type spec of a @code{defcustom} call.
526 This options is specific to Emacs, and is not in the CLOS spec.
529 When customizing an object, the value of :label will be used instead
530 of the slot name. This enables better descriptions of the data than
531 would usually be afforded.
533 This options is specific to Emacs, and is not in the CLOS spec.
536 Similar to @code{defcustom}'s :group command, this organizes different
537 slots in an object into groups. When customizing an object, only the
538 slots belonging to a specific group need be worked with, simplifying the
541 This options is specific to Emacs, and is not in the CLOS spec.
544 This routine takes a symbol which is a function name. The function
545 should accept one argument. The argument is the value from the slot
546 to be printed. The function in @code{object-write} will write the
547 slot value out to a printable form on @code{standard-output}.
549 The output format MUST be something that could in turn be interpreted
550 with @code{read} such that the object can be brought back in from the
551 output stream. Thus, if you wanted to output a symbol, you would need
552 to quote the symbol. If you wanted to run a function on load, you
553 can output the code to do the construction of the value.
556 When using a slot referencing function such as @code{slot-value}, and
557 the value behind @var{slot} is private or protected, then the current
558 scope of operation must be within a method of the calling object.
564 Access this slot from any scope.
566 Access this slot only from methods of the same class or a child class.
568 Access this slot only from methods of the same class.
571 This options is specific to Emacs, and is not in the CLOS spec.
576 @section Class Options
578 In the @var{options-and-doc} arguments to @code{defclass}, the
579 following class options may be specified:
583 A documentation string for this class.
585 If an Emacs-style documentation string is also provided, then this
586 option is ignored. An Emacs-style documentation string is not
587 prefixed by the @code{:documentation} tag, and appears after the list
588 of slots, and before the options.
590 @item :allow-nil-initform
591 If this option is non-nil, and the @code{:initform} is @code{nil}, but
592 the @code{:type} is specifies something such as @code{string} then allow
593 this to pass. The default is to have this option be off. This is
594 implemented as an alternative to unbound slots.
596 This options is specific to Emacs, and is not in the CLOS spec.
599 A class which is @code{:abstract} cannot be instantiated, and instead
600 is used to define an interface which subclasses should implement.
602 This option is specific to Emacs, and is not in the CLOS spec.
605 This is a list of groups that can be customized within this class. This
606 slot is auto-generated when a class is created and need not be
607 specified. It can be retrieved with the @code{class-option} command,
608 however, to see what groups are available.
610 This option is specific to Emacs, and is not in the CLOS spec.
612 @item :method-invocation-order
613 This controls the order in which method resolution occurs for
614 @code{:primary} methods in cases of multiple inheritance. The order
615 affects which method is called first in a tree, and if
616 @code{call-next-method} is used, it controls the order in which the
617 stack of methods are run.
623 Search for methods in the class hierarchy in breadth first order.
626 Search for methods in the class hierarchy in a depth first order.
629 @c @xref{Method Invocation}, for more on method invocation order.
632 Unsupported CLOS option. Enables the use of a different base class other
633 than @code{standard-class}.
635 @item :default-initargs
636 Unsupported CLOS option. Specifies a list of initargs to be used when
637 creating new objects. As far as I can tell, this duplicates the
638 function of @code{:initform}.
641 @xref{CLOS compatibility}, for more details on CLOS tags versus
642 @eieio{}-specific tags.
644 @node Making New Objects
645 @comment node-name, next, previous, up
646 @chapter Making New Objects
648 Suppose we have a simple class is defined, such as:
656 It is now possible to create objects of that class type.
658 Calling @code{defclass} has defined two new functions. One is the
659 constructor @var{record}, and the other is the predicate,
662 @defun record object-name &rest slots
664 This creates and returns a new object. This object is not assigned to
665 anything, and will be garbage collected if not saved. This object
666 will be given the string name @var{object-name}. There can be
667 multiple objects of the same name, but the name slot provides a handy
668 way to keep track of your objects. @var{slots} is just all the slots
669 you wish to preset. Any slot set as such @emph{will not} get its
670 default value, and any side effects from a slot's @code{:initform}
671 that may be a function will not occur.
673 An example pair would appear simply as @code{:value 1}. Of course you
674 can do any valid Lispy thing you want with it, such as
675 @code{:value (if (boundp 'special-symbol) special-symbol nil)}
677 Example of creating an object from a class:
680 (record "test" :value 3 :reference nil)
685 To create an object from a class symbol, use @code{make-instance}.
687 @defun make-instance class &rest initargs
688 @anchor{make-instance}
689 Make a new instance of @var{class} based on @var{initargs}.
690 @var{class} is a class symbol. For example:
696 @var{initargs} is a property list with keywords based on the @code{:initarg}
697 for each slot. For example:
700 (make-instance @code{'foo} @code{:slot1} value1 @code{:slotN} valueN)
705 If the first element of @var{initargs} is a string, it is used as the
708 In @eieio{}, the class' constructor requires a name for use when printing.
709 @dfn{make-instance} in CLOS doesn't use names the way Emacs does, so the
710 class is used as the name slot instead when @var{initargs} doesn't start with
714 @node Accessing Slots
715 @comment node-name, next, previous, up
716 @chapter Accessing Slots
718 There are several ways to access slot values in an object. The naming
719 and argument-order conventions are similar to those used for
720 referencing vectors (@pxref{Vectors,,,elisp,GNU Emacs Lisp Reference
723 @defmac oset object slot value
724 This macro sets the value behind @var{slot} to @var{value} in
725 @var{object}. It returns @var{value}.
728 @defmac oset-default class slot value
729 This macro sets the @code{:initform} for @var{slot} in @var{class} to
732 This allows the user to set both public and private defaults after the
733 class has been constructed, and provides a way to configure the
734 default behavior of packages built with classes (the same way
735 @code{setq-default} does for buffer-local variables).
737 For example, if a user wanted all @code{data-objects} (@pxref{Building
738 Classes}) to inform a special object of his own devising when they
739 changed, this can be arranged by simply executing this bit of code:
742 (oset-default data-object reference (list my-special-object))
746 @defmac oref obj slot
748 Retrieve the value stored in @var{obj} in the slot named by @var{slot}.
749 Slot is the name of the slot when created by @dfn{defclass} or the label
750 created by the @code{:initarg} tag.
753 @defmac oref-default obj slot
754 @anchor{oref-default}
755 Gets the default value of @var{obj} (maybe a class) for @var{slot}.
756 The default value is the value installed in a class with the @code{:initform}
757 tag. @var{slot} can be the slot name, or the tag specified by the @code{:initarg}
758 tag in the @dfn{defclass} call.
761 The following accessors are defined by CLOS to reference or modify
762 slot values, and use the previously mentioned set/ref routines.
764 @defun slot-value object slot
766 This function retrieves the value of @var{slot} from @var{object}.
767 Unlike @code{oref}, the symbol for @var{slot} must be quoted.
770 @defun set-slot-value object slot value
771 @anchor{set-slot-value}
772 This is not a CLOS function, but is meant to mirror @code{slot-value} if
773 you don't want to use the cl package's @code{setf} function. This
774 function sets the value of @var{slot} from @var{object}. Unlike
775 @code{oset}, the symbol for @var{slot} must be quoted.
778 @defun slot-makeunbound object slot
779 This function unbinds @var{slot} in @var{object}. Referencing an
780 unbound slot can signal an error.
783 @defun object-add-to-list object slot item &optional append
784 @anchor{object-add-to-list}
785 In OBJECT's @var{slot}, add @var{item} to the list of elements.
786 Optional argument @var{append} indicates we need to append to the list.
787 If @var{item} already exists in the list in @var{slot}, then it is not added.
788 Comparison is done with @dfn{equal} through the @dfn{member} function call.
789 If @var{slot} is unbound, bind it to the list containing @var{item}.
792 @defun object-remove-from-list object slot item
793 @anchor{object-remove-from-list}
794 In OBJECT's @var{slot}, remove occurrences of @var{item}.
795 Deletion is done with @dfn{delete}, which deletes by side effect
796 and comparisons are done with @dfn{equal}.
797 If @var{slot} is unbound, do nothing.
800 @defun with-slots spec-list object &rest body
802 Bind @var{spec-list} lexically to slot values in @var{object}, and execute @var{body}.
803 This establishes a lexical environment for referring to the slots in
804 the instance named by the given slot-names as though they were
805 variables. Within such a context the value of the slot can be
806 specified by using its slot name, as if it were a lexically bound
807 variable. Both setf and setq can be used to set the value of the
810 @var{spec-list} is of a form similar to @dfn{let}. For example:
819 Where each @var{var} is the local variable given to the associated
820 @var{slot}. A slot specified without a variable name is given a
821 variable name of the same name as the slot.
824 (defclass myclass () (x :initarg 1))
825 (setq mc (make-instance 'myclass))
826 (with-slots (x) mc x) => 1
827 (with-slots ((something x)) mc something) => 1
831 @node Writing Methods
832 @comment node-name, next, previous, up
833 @chapter Writing Methods
835 Writing a method in @eieio{} is similar to writing a function. The
836 differences are that there are some extra options and there can be
837 multiple definitions under the same function symbol.
839 Where a method defines an implementation for a particular data type, a
840 @dfn{generic method} accepts any argument, but contains no code. It
841 is used to provide the dispatching to the defined methods. A generic
842 method has no body, and is merely a symbol upon which methods are
843 attached. It also provides the base documentation for what methods
855 Each @eieio{} method has one corresponding generic. This generic
856 provides a function binding and the base documentation for the method
857 symbol (@pxref{Symbol Components,,,elisp,GNU Emacs Lisp Reference
860 @defmac defgeneric method arglist [doc-string]
861 This macro turns the (unquoted) symbol @var{method} into a function.
862 @var{arglist} is the default list of arguments to use (not implemented
863 yet). @var{doc-string} is the documentation used for this symbol.
865 A generic function acts as a placeholder for methods. There is no
866 need to call @code{defgeneric} yourself, as @code{defmethod} will call
867 it if necessary. Currently the argument list is unused.
869 @code{defgeneric} signals an error if you attempt to turn an existing
870 Emacs Lisp function into a generic function.
872 You can also create a generic method with @code{defmethod}
873 (@pxref{Methods}). When a method is created and there is no generic
874 method in place with that name, then a new generic will be created,
875 and the new method will use it.
878 In CLOS, a generic call also be used to provide an argument list and
879 dispatch precedence for all the arguments. In @eieio{}, dispatching
880 only occurs for the first argument, so the @var{arglist} is not used.
885 A method is a function that is executed if the first argument passed
886 to it matches the method's class. Different @eieio{} classes may
887 share the same method names.
889 Methods are created with the @code{defmethod} macro, which is similar
892 @defmac defmethod method [:before | :primary | :after | :static ] arglist [doc-string] forms
894 @var{method} is the name of the function to create.
896 @code{:before} and @code{:after} specify execution order (i.e., when
897 this form is called). If neither of these symbols are present, the
898 default priority is used (before @code{:after} and after
899 @code{:before}); this default priority is represented in CLOS as
902 @b{Note:} The @code{:BEFORE}, @code{:PRIMARY}, @code{:AFTER}, and
903 @code{:STATIC} method tags were in all capital letters in previous
904 versions of @eieio{}.
906 @var{arglist} is the list of arguments to this method. The first
907 argument in this list---and @emph{only} the first argument---may have
908 a type specifier (see the example below). If no type specifier is
909 supplied, the method applies to any object.
911 @var{doc-string} is the documentation attached to the implementation.
912 All method doc-strings are incorporated into the generic method's
913 function documentation.
915 @var{forms} is the body of the function.
920 In the following example, we create a method @code{mymethod} for the
921 @code{classname} class:
924 (defmethod mymethod ((obj classname) secondarg)
929 This method only executes if the @var{obj} argument passed to it is an
930 @eieio{} object of class @code{classname}.
932 A method with no type specifier is a @dfn{default method}. If a given
933 class has no implementation, then the default method is called when
934 that method is used on a given object of that class.
936 Only one default method per execution specifier (@code{:before},
937 @code{:primary}, or @code{:after}) is allowed. If two
938 @code{defmethod}s appear with @var{arglist}s lacking a type specifier,
939 and having the same execution specifier, then the first implementation
942 When a method is called on an object, but there is no method specified
943 for that object, but there is a method specified for object's parent
944 class, the parent class' method is called. If there is a method
945 defined for both, only the child's method is called. A child method
946 may call a parent's method using @code{call-next-method}, described
949 If multiple methods and default methods are defined for the same
950 method and class, they are executed in this order:
954 @item default :before
955 @item method :primary
956 @item default :primary
961 If no methods exist, Emacs signals a @code{no-method-definition}
962 error. @xref{Signals}.
964 @defun call-next-method &rest replacement-args
965 @anchor{call-next-method}
967 This function calls the superclass method from a subclass method.
968 This is the ``next method'' specified in the current method list.
970 If @var{replacement-args} is non-@code{nil}, then use them instead of
971 @code{eieio-generic-call-arglst}. At the top level, the generic
972 argument list is passed in.
974 Use @code{next-method-p} to find out if there is a next method to
979 @anchor{next-method-p}
980 Non-@code{nil} if there is a next method.
981 Returns a list of lambda expressions which is the @code{next-method}
985 At present, @eieio{} does not implement all the features of CLOS:
989 There is currently no @code{:around} tag.
991 CLOS allows multiple sets of type-cast arguments, but @eieio{} only
992 allows the first argument to be cast.
996 @section Static Methods
998 Static methods do not depend on an object instance, but instead
999 operate on an object's class. You can create a static method by using
1000 the @code{:static} key with @code{defmethod}.
1002 Do not treat the first argument of a @code{:static} method as an
1003 object unless you test it first. Use the functions
1004 @code{oref-default} or @code{oset-default} which will work on a class,
1005 or on the class of an object.
1007 A Class' @code{constructor} method is defined as a @code{:static}
1010 @b{Note:} The @code{:static} keyword is unique to @eieio{}.
1012 @c TODO - Write some more about static methods here
1014 @c @node Method Invocation
1015 @c @chapter Method Invocation
1020 @comment node-name, next, previous, up
1021 @chapter Predicates and Utilities
1023 Now that we know how to create classes, access slots, and define
1024 methods, it might be useful to verify that everything is doing ok. To
1025 help with this a plethora of predicates have been created.
1027 @defun find-class symbol &optional errorp
1029 Return the class that @var{symbol} represents.
1030 If there is no class, @code{nil} is returned if @var{errorp} is @code{nil}.
1031 If @var{errorp} is non-@code{nil}, @code{wrong-argument-type} is signaled.
1034 @defun class-p class
1036 Return @code{t} if @var{class} is a valid class vector.
1037 @var{class} is a symbol.
1040 @defun slot-exists-p object-or-class slot
1041 @anchor{slot-exists-p}
1042 Non-@code{nil} if @var{object-or-class} has @var{slot}.
1045 @defun slot-boundp object slot
1046 @anchor{slot-boundp}
1047 Non-@code{nil} if OBJECT's @var{slot} is bound.
1048 Setting a slot's value makes it bound. Calling @dfn{slot-makeunbound} will
1049 make a slot unbound.
1050 @var{object} can be an instance or a class.
1053 @defun class-name class
1054 Return a string of the form @samp{#<class myclassname>} which should look
1055 similar to other Lisp objects like buffers and processes. Printing a
1056 class results only in a symbol.
1059 @defun class-option class option
1060 Return the value in @var{CLASS} of a given @var{OPTION}.
1064 (class-option eieio-default-superclass :documentation)
1067 Will fetch the documentation string for @code{eieio-default-superclass}.
1070 @defun class-constructor class
1071 Return a symbol used as a constructor for @var{class}. The
1072 constructor is a function used to create new instances of
1073 @var{CLASS}. This function provides a way to make an object of a class
1074 without knowing what it is. This is not a part of CLOS.
1077 @defun object-name obj
1078 Return a string of the form @samp{#<object-class myobjname>} for @var{obj}.
1079 This should look like Lisp symbols from other parts of Emacs such as
1080 buffers and processes, and is shorter and cleaner than printing the
1081 object's vector. It is more useful to use @code{object-print} to get
1082 and object's print form, as this allows the object to add extra display
1083 information into the symbol.
1086 @defun object-class obj
1087 Returns the class symbol from @var{obj}.
1091 CLOS symbol which does the same thing as @code{object-class}
1094 @defun object-class-fast obj
1095 Same as @code{object-class} except this is a macro, and no
1096 type-checking is performed.
1099 @defun object-class-name obj
1100 Returns the symbol of @var{obj}'s class.
1103 @defun class-parents class
1104 Returns the direct parents class of @var{class}. Returns @code{nil} if
1108 @defun class-parents-fast class
1109 Just like @code{class-parent} except it is a macro and no type checking
1113 @defun class-parent class
1114 Deprecated function which returns the first parent of @var{class}.
1117 @defun class-children class
1118 Return the list of classes inheriting from @var{class}.
1121 @defun class-children-fast class
1122 Just like @code{class-children}, but with no checks.
1125 @defun same-class-p obj class
1126 Returns @code{t} if @var{obj}'s class is the same as @var{class}.
1129 @defun same-class-fast-p obj class
1130 Same as @code{same-class-p} except this is a macro and no type checking
1134 @defun object-of-class-p obj class
1135 Returns @code{t} if @var{obj} inherits anything from @var{class}. This
1136 is different from @code{same-class-p} because it checks for inheritance.
1139 @defun child-of-class-p child class
1140 Returns @code{t} if @var{child} is a subclass of @var{class}.
1143 @defun generic-p method-symbol
1144 Returns @code{t} if @code{method-symbol} is a generic function, as
1145 opposed to a regular Emacs Lisp function.
1148 @node Association Lists
1149 @chapter Association Lists
1151 Lisp offers the concept of association lists, with primitives such as
1152 @code{assoc} used to access them. The following functions can be used
1153 to manage association lists of @eieio{} objects:
1155 @defun object-assoc key slot list
1156 @anchor{object-assoc}
1157 Return an object if @var{key} is @dfn{equal} to SLOT's value of an object in @var{list}.
1158 @var{list} is a list of objects whose slots are searched.
1159 Objects in @var{list} do not need to have a slot named @var{slot}, nor does
1160 @var{slot} need to be bound. If these errors occur, those objects will
1165 @defun object-assoc-list slot list
1166 Return an association list generated by extracting @var{slot} from all
1167 objects in @var{list}. For each element of @var{list} the @code{car} is
1168 the value of @var{slot}, and the @code{cdr} is the object it was
1169 extracted from. This is useful for generating completion tables.
1172 @defun eieio-build-class-alist &optional base-class
1173 Returns an alist of all currently defined classes. This alist is
1174 suitable for completion lists used by interactive functions to select a
1175 class. The optional argument @var{base-class} allows the programmer to
1176 select only a subset of classes which includes @var{base-class} and
1181 @comment node-name, next, previous, up
1182 @chapter Customizing Objects
1184 @eieio{} supports the Custom facility through two new widget types.
1185 If a variable is declared as type @code{object}, then full editing of
1186 slots via the widgets is made possible. This should be used
1187 carefully, however, because modified objects are cloned, so if there
1188 are other references to these objects, they will no longer be linked
1191 If you want in place editing of objects, use the following methods:
1193 @defun eieio-customize-object object
1194 Create a custom buffer and insert a widget for editing @var{object}. At
1195 the end, an @code{Apply} and @code{Reset} button are available. This
1196 will edit the object "in place" so references to it are also changed.
1197 There is no effort to prevent multiple edits of a singular object, so
1198 care must be taken by the user of this function.
1201 @defun eieio-custom-widget-insert object flags
1202 This method inserts an edit object into the current buffer in place.
1203 It is implemented as @code{(widget-create 'object-edit :value object)}.
1204 This method is provided as a locale for adding tracking, or
1205 specializing the widget insert procedure for any object.
1208 To define a slot with an object in it, use the @code{object} tag. This
1209 widget type will be automatically converted to @code{object-edit} if you
1210 do in place editing of you object.
1212 If you want to have additional actions taken when a user clicks on the
1213 @code{Apply} button, then overload the method @code{eieio-done-customizing}.
1214 This method does nothing by default, but that may change in the future.
1215 This would be the best way to make your objects persistent when using
1218 @section Widget extention
1220 When widgets are being created, one new widget extention has been added,
1221 called the @code{:slotofchoices}. When this occurs in a widget
1222 definition, all elements after it are removed, and the slot is specifies
1223 is queried and converted into a series of constants.
1226 (choice (const :tag "None" nil)
1227 :slotofchoices morestuff)
1230 and if the slot @code{morestuff} contains @code{(sym1 sym2 sym3)}, the
1231 above example is converted into:
1234 (choice (const :tag "None" nil)
1240 This is useful when a given item needs to be selected from a list of
1241 items defined in this second slot.
1244 @chapter Introspection
1246 Introspection permits a programmer to peek at the contents of a class
1247 without any previous knowledge of that class. While @eieio{} implements
1248 objects on top of vectors, and thus everything is technically visible,
1249 some functions have been provided. None of these functions are a part
1252 @defun object-slots obj
1253 Return the list of public slots for @var{obj}.
1256 @defun class-slot-initarg class slot
1257 For the given @var{class} return the :initarg associated with
1258 @var{slot}. Not all slots have initargs, so the return value can be
1263 @comment node-name, next, previous, up
1264 @chapter Base Classes
1266 All defined classes, if created with no specified parent class,
1267 inherit from a special class called @code{eieio-default-superclass}.
1268 @xref{Default Superclass}.
1270 Often, it is more convenient to inherit from one of the other base
1271 classes provided by @eieio{}, which have useful pre-defined
1272 properties. (Since @eieio{} supports multiple inheritance, you can
1273 even inherit from more than one of these classes at once.)
1276 * eieio-instance-inheritor:: Enable value inheritance between instances.
1277 * eieio-instance-tracker:: Enable self tracking instances.
1278 * eieio-singleton:: Only one instance of a given class.
1279 * eieio-persistent:: Enable persistence for a class.
1280 * eieio-named:: Use the object name as a :name slot.
1281 * eieio-speedbar:: Enable speedbar support in your objects.
1284 @node eieio-instance-inheritor
1285 @comment node-name, next, previous, up
1286 @section @code{eieio-instance-inheritor}
1288 This class is defined in the package @file{eieio-base}.
1290 Instance inheritance is a mechanism whereby the value of a slot in
1291 object instance can reference the parent instance. If the parent's slot
1292 value is changed, then the child instance is also changed. If the
1293 child's slot is set, then the parent's slot is not modified.
1295 @deftp {Class} eieio-instance-inheritor parent-instance
1296 A class whose instances are enabled with instance inheritance.
1297 The @var{parent-instance} slot indicates the instance which is
1298 considered the parent of the current instance. Default is @code{nil}.
1302 To use this class, inherit from it with your own class.
1303 To make a new instance that inherits from and existing instance of your
1304 class, use the @code{clone} method with additional parameters
1305 to specify local values.
1307 @cindex slot-unbound
1308 The @code{eieio-instance-inheritor} class works by causing cloned
1309 objects to have all slots unbound. This class' @code{slot-unbound}
1310 method will cause references to unbound slots to be redirected to the
1311 parent instance. If the parent slot is also unbound, then
1312 @code{slot-unbound} will signal an error named @code{slot-unbound}.
1314 @node eieio-instance-tracker
1315 @section @code{eieio-instance-tracker}
1317 This class is defined in the package @file{eieio-base}.
1319 Sometimes it is useful to keep a master list of all instances of a given
1320 class. The class @code{eieio-instance-tracker} performs this task.
1322 @deftp {Class} eieio-instance-tracker tracker-symbol
1323 Enable instance tracking for this class.
1324 The slot @var{tracker-symbol} should be initialized in inheritors of
1325 this class to a symbol created with @code{defvar}. This symbol will
1326 serve as the variable used as a master list of all objects of the given
1330 @defmethod eieio-instance-tracker initialize-instance obj slot
1331 This method is defined as an @code{:after} method.
1332 It adds new instances to the master list. Do not overload this method
1333 unless you use @code{call-next-method.}
1336 @defmethod eieio-instance-tracker delete-instance obj
1337 Remove @var{obj} from the master list of instances of this class.
1338 This may let the garbage collector nab this instance.
1341 @deffn eieio-instance-tracker-find key slot list-symbol
1342 This convenience function lets you find instances. @var{key} is the
1343 value to search for. @var{slot} is the slot to compare @var{KEY}
1344 against. The function @code{equal} is used for comparison.
1345 The parameter @var{list-symbol} is the variable symbol which contains the
1346 list of objects to be searched.
1349 @node eieio-singleton
1350 @comment node-name, next, previous, up
1351 @section @code{eieio-singleton}
1353 This class is defined in the package @file{eieio-base}.
1355 @deftp {Class} eieio-singleton
1356 Inheriting from the singleton class will guarantee that there will
1357 only ever be one instance of this class. Multiple calls to
1358 @code{make-instance} will always return the same object.
1361 @node eieio-persistent
1362 @comment node-name, next, previous, up
1363 @section @code{eieio-persistent}
1365 This class is defined in the package @file{eieio-base}.
1367 If you want an object, or set of objects to be persistent, meaning the
1368 slot values are important to keep saved between sessions, then you will
1369 want your top level object to inherit from @code{eieio-persistent}.
1371 To make sure your persistent object can be moved, make sure all file
1372 names stored to disk are made relative with
1373 @code{eieio-persistent-path-relative}.
1375 @deftp {Class} eieio-persistent file file-header-line
1376 Enables persistence for instances of this class.
1377 Slot @var{file} with initarg @code{:file} is the file name in which this
1378 object will be saved.
1379 Class allocated slot @var{file-header-line} is used with method
1380 @code{object-write} as a header comment.
1383 All objects can write themselves to a file, but persistent objects have
1384 several additional methods that aid in maintaining them.
1386 @defmethod eieio-persistent eieio-persistent-save obj &optional file
1387 Write the object @var{obj} to its file.
1388 If optional argument @var{file} is specified, use that file name
1392 @defmethod eieio-persistent eieio-persistent-path-relative obj file
1393 Return a file name derived from @var{file} which is relative to the
1394 stored location of @var{OBJ}. This method should be used to convert
1395 file names so that they are relative to the save file, making any system
1396 of files movable from one location to another.
1399 @defmethod eieio-persistent object-write obj &optional comment
1400 Like @code{object-write} for @code{standard-object}, but will derive
1401 a header line comment from the class allocated slot if one is not
1405 @defun eieio-persistent-read filename
1406 Read @var{filename} which contains an @code{eieio-persistent} object
1407 previously written with @code{eieio-persistent-save}.
1411 @comment node-name, next, previous, up
1412 @section @code{eieio-named}
1414 This class is defined in the package @file{eieio-base}.
1416 @deftp {Class} eieio-named
1418 Name storage already occurs in an object. This object provides get/set
1422 @node eieio-speedbar
1423 @comment node-name, next, previous, up
1424 @section @code{eieio-speedbar}
1426 This class is in package @file{eieio-speedbar}.
1428 If a series of class instances map to a tree structure, it is possible
1429 to cause your classes to be displayable in Speedbar. @xref{Top,,,speedbar}.
1430 Inheriting from these classes will enable a speedbar major display mode
1431 with a minimum of effort.
1433 @deftp {Class} eieio-speedbar buttontype buttonface
1434 Enables base speedbar display for a class.
1435 @cindex speedbar-make-tag-line
1436 The slot @var{buttontype} is any of the symbols allowed by the
1437 function @code{speedbar-make-tag-line} for the @var{exp-button-type}
1438 argument @xref{Extending,,,speedbar}.
1439 The slot @var{buttonface} is the face to use for the text of the string
1440 displayed in speedbar.
1441 The slots @var{buttontype} and @var{buttonface} are class allocated
1442 slots, and do not take up space in your instances.
1445 @deftp {Class} eieio-speedbar-directory-button buttontype buttonface
1446 This class inherits from @code{eieio-speedbar} and initializes
1447 @var{buttontype} and @var{buttonface} to appear as directory level lines.
1450 @deftp {Class} eieio-speedbar-file-button buttontype buttonface
1451 This class inherits from @code{eieio-speedbar} and initializes
1452 @var{buttontype} and @var{buttonface} to appear as file level lines.
1455 To use these classes, inherit from one of them in you class. You can
1456 use multiple inheritance with them safely. To customize your class for
1457 speedbar display, override the default values for @var{buttontype} and
1458 @var{buttonface} to get the desired effects.
1460 Useful methods to define for your new class include:
1462 @defmethod eieio-speedbar eieio-speedbar-derive-line-path obj depth
1463 Return a string representing a directory associated with an instance
1464 of @var{obj}. @var{depth} can be used to indice how many levels of
1465 indentation have been opened by the user where @var{obj} is shown.
1469 @defmethod eieio-speedbar eieio-speedbar-description obj
1470 Return a string description of @var{OBJ}.
1471 This is shown in the minibuffer or tooltip when the mouse hovers over
1472 this instance in speedbar.
1475 @defmethod eieio-speedbar eieio-speedbar-child-description obj
1476 Return a string representing a description of a child node of @var{obj}
1477 when that child is not an object. It is often useful to just use
1478 item info helper functions such as @code{speedbar-item-info-file-helper}.
1481 @defmethod eieio-speedbar eieio-speedbar-object-buttonname obj
1482 Return a string which is the text displayed in speedbar for @var{obj}.
1485 @defmethod eieio-speedbar eieio-speedbar-object-children obj
1486 Return a list of children of @var{obj}.
1489 @defmethod eieio-speedbar eieio-speedbar-child-make-tag-lines obj depth
1490 This method inserts a list of speedbar tag lines for @var{obj} to
1491 represent its children. Implement this method for your class
1492 if your children are not objects themselves. You still need to
1493 implement @code{eieio-speedbar-object-children}.
1495 In this method, use techniques specified in the Speedbar manual.
1496 @xref{Extending,,,speedbar}.
1499 Some other functions you will need to learn to use are:
1501 @deffn eieio-speedbar-create make-map key-map menu name toplevelfn
1502 Register your object display mode with speedbar.
1503 @var{make-map} is a function which initialized you keymap.
1504 @var{key-map} is a symbol you keymap is installed into.
1505 @var{menu} is an easy menu vector representing menu items specific to your
1507 @var{name} is a short string to use as a name identifying you mode.
1508 @var{toplevelfn} is a function called which must return a list of
1509 objects representing those in the instance system you wish to browse in
1512 Read the Extending chapter in the speedbar manual for more information
1513 on how speedbar modes work
1514 @xref{Extending,,,speedbar}.
1518 @comment node-name, next, previous, up
1519 @chapter Browsing class trees
1521 The command @kbd{M-x eieio-browse} displays a buffer listing all the
1522 currently loaded classes in Emacs. The classes are listed in an
1523 indented tree structure, starting from @code{eieio-default-superclass}
1524 (@pxref{Default Superclass}).
1526 With a prefix argument, this command prompts for a class name; it then
1527 lists only that class and its subclasses.
1529 Here is a sample tree from our current example:
1532 eieio-default-superclass
1534 +--data-object-symbol
1537 Note: new classes are consed into the inheritance lists, so the tree
1538 comes out upside-down.
1541 @comment node-name, next, previous, up
1542 @chapter Class Values
1544 Details about any class or object can be retrieved using the function
1545 @code{eieio-describe-class}. Interactively, type in the name of
1546 a class. In a program, pass it a string with the name of a class, a
1547 class symbol, or an object. The resulting buffer will display all slot
1550 Additionally, all methods defined to have functionality on this class
1553 @node Default Superclass
1554 @comment node-name, next, previous, up
1555 @chapter Default Superclass
1557 All defined classes, if created with no specified parent class, will
1558 inherit from a special class stored in
1559 @code{eieio-default-superclass}. This superclass is quite simple, but
1560 with it, certain default methods or attributes can be added to all
1561 objects. In CLOS, this would be named @code{STANDARD-CLASS}, and that
1562 symbol is an alias to @code{eieio-default-superclass}.
1565 Currently, the default superclass is defined as follows:
1568 (defclass eieio-default-superclass nil
1570 "Default parent class for classes with no specified parent class.
1571 Its slots are automatically adopted by classes with no specified
1572 parents. This class is not stored in the `parent' slot of a class vector."
1576 The default superclass implements several methods providing a default
1577 behavior for all objects created by @eieio{}.
1580 * Initialization:: How objects are initialized
1581 * Basic Methods:: Clone, print, and write
1582 * Signal Handling:: Methods for managing signals.
1585 @node Initialization
1586 @section Initialization
1588 When creating an object of any type, you can use its constructor, or
1589 @code{make-instance}. This, in turns calls the method
1590 @code{initialize-instance}, which then calls the method
1591 @code{shared-initialize}.
1593 These methods are all implemented on the default superclass so you do
1594 not need to write them yourself, unless you need to override one of
1597 Users should not need to call @code{initialize-instance} or
1598 @code{shared-initialize}, as these are used by @code{make-instance} to
1599 initialize the object. They are instead provided so that users can
1600 augment these behaviors.
1602 @defun initialize-instance obj &rest slots
1603 Initialize @var{obj}. Sets slots of @var{obj} with @var{slots} which
1604 is a list of name/value pairs. These are actually just passed to
1605 @code{shared-initialize}.
1608 @defun shared-initialize obj &rest slots
1609 Sets slots of @var{obj} with @var{slots} which is a list of name/value
1612 This is called from the default @code{constructor}.
1616 @section Basic Methods
1618 Additional useful methods defined on the base subclass are:
1620 @defun clone obj &rest params
1622 Make a copy of @var{obj}, and then apply @var{params}.
1623 @var{params} is a parameter list of the same form as @var{initialize-instance}
1624 which are applied to change the object. When overloading @dfn{clone}, be
1625 sure to call @dfn{call-next-method} first and modify the returned object.
1628 @defun object-print this &rest strings
1629 @anchor{object-print}
1630 Pretty printer for object @var{this}. Call function @dfn{object-name} with @var{strings}.
1631 The default method for printing object @var{this} is to use the
1632 function @dfn{object-name}.
1634 It is sometimes useful to put a summary of the object into the
1635 default #<notation> string when using eieio browsing tools.
1637 Implement this function and specify @var{strings} in a call to
1638 @dfn{call-next-method} to provide additional summary information.
1639 When passing in extra strings from child classes, always remember
1643 (defclass data-object ()
1645 "Object containing one data slot.")
1647 (defmethod object-print ((this data-object) &optional strings)
1648 "Return a string with a summary of the data object as part of the name."
1649 (apply 'call-next-method this
1650 (cons (format " value: %s" (render this)) strings)))
1653 Here is what some output could look like:
1655 (object-print test-object)
1656 => #<data-object test-object value: 3>
1660 @defun object-write obj &optional comment
1661 Write @var{obj} onto a stream in a readable fashion. The resulting
1662 output will be Lisp code which can be used with @code{read} and
1663 @code{eval} to recover the object. Only slots with @code{:initarg}s
1664 are written to the stream.
1667 @node Signal Handling
1668 @section Signal Handling
1670 The default superclass defines methods for managing error conditions.
1671 These methods all throw a signal for a particular error condition.
1673 By implementing one of these methods for a class, you can change the
1674 behavior that occurs during one of these error cases, or even ignore
1675 the error by providing some behavior.
1677 @defun slot-missing object slot-name operation &optional new-value
1678 @anchor{slot-missing}
1679 Method invoked when an attempt to access a slot in @var{object} fails.
1680 @var{slot-name} is the name of the failed slot, @var{operation} is the type of access
1681 that was requested, and optional @var{new-value} is the value that was desired
1684 This method is called from @code{oref}, @code{oset}, and other functions which
1685 directly reference slots in EIEIO objects.
1687 The default method signals an error of type @code{invalid-slot-name}.
1690 You may override this behavior, but it is not expected to return in the
1691 current implementation.
1693 This function takes arguments in a different order than in CLOS.
1696 @defun slot-unbound object class slot-name fn
1697 @anchor{slot-unbound}
1698 Slot unbound is invoked during an attempt to reference an unbound slot.
1699 @var{object} is the instance of the object being reference. @var{class} is the
1700 class of @var{object}, and @var{slot-name} is the offending slot. This function
1701 throws the signal @code{unbound-slot}. You can overload this function and
1702 return the value to use in place of the unbound value.
1703 Argument @var{fn} is the function signaling this error.
1704 Use @dfn{slot-boundp} to determine if a slot is bound or not.
1706 In @var{clos}, the argument list is (@var{class} @var{object} @var{slot-name}), but
1707 @var{eieio} can only dispatch on the first argument, so the first two are swapped.
1710 @defun no-applicable-method object method &rest args
1711 @anchor{no-applicable-method}
1712 Called if there are no implementations for @var{object} in @var{method}.
1713 @var{object} is the object which has no method implementation.
1714 @var{args} are the arguments that were passed to @var{method}.
1716 Implement this for a class to block this signal. The return
1717 value becomes the return value of the original method call.
1720 @defun no-next-method object &rest args
1721 @anchor{no-next-method}
1722 Called from @dfn{call-next-method} when no additional methods are available.
1723 @var{object} is othe object being called on @dfn{call-next-method}.
1724 @var{args} are the arguments it is called by.
1725 This method signals @dfn{no-next-method} by default. Override this
1726 method to not throw an error, and its return value becomes the
1727 return value of @dfn{call-next-method}.
1731 @comment node-name, next, previous, up
1734 There are new condition names (signals) that can be caught when using
1737 @deffn Signal invalid-slot-name obj-or-class slot
1738 This signal is called when an attempt to reference a slot in an
1739 @var{obj-or-class} is made, and the @var{slot} is not defined for
1743 @deffn Signal no-method-definition method arguments
1744 This signal is called when @var{method} is called, with @var{arguments}
1745 and nothing is resolved. This occurs when @var{method} has been
1746 defined, but the arguments make it impossible for @eieio{} to determine
1747 which method body to run.
1749 To prevent this signal from occurring in your class, implement the
1750 method @code{no-applicable-method} for your class. This method is
1751 called when to throw this signal, so implementing this for your class
1752 allows you block the signal, and perform some work.
1755 @deffn Signal no-next-method class arguments
1756 This signal is called if the function @code{call-next-method} is called
1757 and there is no next method to be called.
1759 Overload the method @code{no-next-method} to protect against this signal.
1762 @deffn Signal invalid-slot-type slot spec value
1763 This signal is called when an attempt to set @var{slot} is made, and
1764 @var{value} doesn't match the specified type @var{spec}.
1766 In @eieio{}, this is also used if a slot specifier has an invalid value
1767 during a @code{defclass}.
1770 @deffn Signal unbound-slot object class slot
1771 This signal is called when an attempt to reference @var{slot} in
1772 @var{object} is made, and that instance is currently unbound.
1775 @node Naming Conventions
1776 @comment node-name, next, previous, up
1777 @chapter Naming Conventions
1779 @xref{Tips,,Tips and Conventions,elisp,GNU Emacs Lisp Reference
1780 Manual}, for a description of Emacs Lisp programming conventions.
1781 These conventions help ensure that Emacs packages work nicely one
1782 another, so an @eieio{}-based program should follow them. Here are
1783 some conventions that apply specifically to @eieio{}-based programs:
1787 @item Come up with a package prefix that is relatively short. Prefix
1788 all classes, and methods with your prefix. This is a standard
1789 convention for functions and variables in Emacs.
1791 @item Do not prefix method names with the class name. All methods in
1792 @eieio{} are ``virtual'', and are dynamically dispatched. Anyone can
1793 override your methods at any time. Your methods should be prefixed
1794 with your package name.
1796 @item Do not prefix slots in your class. The slots are always locally
1797 scoped to your class, and need no prefixing.
1799 @item If your library inherits from other libraries of classes, you
1800 must ``require'' that library with the @code{require} command.
1804 @node CLOS compatibility
1805 @comment node-name, next, previous, up
1806 @chapter CLOS compatibility
1808 Currently, the following functions should behave almost as expected from
1814 All slot keywords are available but not all work correctly.
1815 Slot keyword differences are:
1819 @item :reader, and :writer tags
1820 Create methods that signal errors instead of creating an unqualified
1821 method. You can still create new ones to do its business.
1824 This should create an unqualified method to access a slot, but
1825 instead pre-builds a method that gets the slot's value.
1828 Specifier uses the @code{typep} function from the @file{cl}
1829 package. @xref{(cl)Type Predicates}. It therefore has the same issues as
1830 that package. Extensions include the ability to provide object names.
1833 Defclass also supports class options, but does not currently use values
1834 of @code{:metaclass}, and @code{:default-initargs}.
1837 Make instance works as expected, however it just uses the @eieio{} instance
1838 creator automatically generated when a new class is created.
1839 @xref{Making New Objects}.
1842 Creates the desired symbol, and accepts all of the expected arguments
1843 except @code{:around}.
1846 Calls defgeneric, and accepts most of the expected arguments. Only
1847 the first argument to the created method may have a type specifier.
1848 To type cast against a class, the class must exist before defmethod is
1849 called. In addition, the @code{:around} tag is not supported.
1851 @item call-next-method
1852 Inside a method, calls the next available method up the inheritance tree
1853 for the given object. This is different than that found in CLOS because
1854 in @eieio{} this function accepts replacement arguments. This permits
1855 subclasses to modify arguments as they are passed up the tree. If no
1856 arguments are given, the expected CLOS behavior is used.
1858 If the common-lisp subsystem is loaded, the setf parameters are also
1859 loaded so the form @code{(setf (slot-value object slot) t)} should
1863 CLOS supports the @code{describe} command, but @eieio{} only provides
1864 @code{eieio-describe-class}, and @code{eieio-describe-generic}. These
1865 functions are adviced into @code{describe-variable}, and
1866 @code{describe-function}.
1868 When creating a new class (@pxref{Building Classes}) there are several
1869 new keywords supported by @eieio{}.
1871 In @eieio{} tags are in lower case, not mixed case.
1876 @eieio{} is an incomplete implementation of CLOS. Finding ways to
1877 improve the compatibility would help make CLOS style programs run
1880 Some important compatibility features that would be good to add are:
1884 @code{:around} method key.
1887 Method dispatch for built-in types.
1889 Method dispatch for multiple argument typing.
1891 Improve integration with the @file{cl} package.
1894 There are also improvements to be made to allow @eieio{} to operate
1895 better in the Emacs environment.
1899 Allow subclasing of Emacs built-in types, such as faces, markers, and
1902 Allow method overloading of method-like functions in Emacs.
1905 @node Function Index
1906 @unnumbered Function Index
1914 arch-tag: 7225b7c7-2462-4563-99e7-836a20172178