EIEIO

3.1 Inheritance

Inheritance is a basic feature of an object-oriented language. In EIEIO, a defined class specifies the super classes from which it inherits by using the second argument to defclass. Here is an example:

(defclass my-baseclass ()
   ((slot-A :initarg :slot-A)
    (slot-B :initarg :slot-B))
  "My Baseclass.")

To subclass from my-baseclass, we specify it in the superclass list:

(defclass my-subclass (my-baseclass)
   ((specific-slot-A :initarg specific-slot-A)
    )
   "My subclass of my-baseclass")

Instances of my-subclass will inherit slot-A and slot-B, in addition to having specific-slot-A from the declaration of my-subclass.

EIEIO also supports multiple inheritance. Suppose we define a second baseclass, perhaps an “interface” class, like this:

(defclass my-interface ()
   ((interface-slot :initarg :interface-slot))
   "An interface to special behavior."
   :abstract t)

The interface class defines a special interface-slot, and also specifies itself as abstract. Abstract classes cannot be instantiated. It is not required to make interfaces abstract, but it is a good programming practice.

We can now modify our definition of my-subclass to use this interface class, together with our original base class:

(defclass my-subclass (my-baseclass my-interface)
   ((specific-slot-A :initarg specific-slot-A)
    )
   "My subclass of my-baseclass")

With this, my-subclass also has interface-slot.

If my-baseclass and my-interface had slots with the same name, then the superclass showing up in the list first defines the slot attributes.

Inheritance in EIEIO is more than just combining different slots. It is also important in method invocation. Methods.

If a method is called on an instance of my-subclass, and that method only has an implementation on my-baseclass, or perhaps my-interface, then the implementation for the baseclass is called.

If there is a method implementation for my-subclass, and another in my-baseclass, the implementation for my-subclass can call up to the superclass as well.

3.2 Slot Options

The slot-list argument to defclass is a list of elements where each element defines one slot. Each slot is a list of the form

  (SLOT-NAME :TAG1 ATTRIB-VALUE1
             :TAG2 ATTRIB-VALUE2
             :TAGN ATTRIB-VALUEN)

where SLOT-NAME is a symbol that will be used to refer to the slot. :TAG is a symbol that describes a feature to be set on the slot. ATTRIB-VALUE is a lisp expression that will be used for :TAG.

Valid tags are:

:initarg

A symbol that can be used in the argument list of the constructor to specify a value for this slot of the new instance being created.

A good symbol to use for initarg is one that starts with a colon :.

The slot specified like this:

  (myslot :initarg :myslot)

could then be initialized to the number 1 like this:

  (myobject :myslot 1)

See Making New Objects.

:initform

An expression used as the default value for this slot.

If :initform is left out, that slot defaults to being unbound. It is an error to reference an unbound slot, so if you need slots to always be in a bound state, you should always use an :initform specifier.

Use slot-boundp to test if a slot is unbound (see Predicates and Utilities). Use slot-makeunbound to set a slot to being unbound after giving it a value (see Accessing Slots).

The value passed to initform used to be automatically quoted. Thus,

:initform (1 2 3)

will use the list as a value. This is incompatible with CLOS (which would signal an error since 1 is not a valid function) and will likely change in the future, so better quote your initforms if they’re just values.

:type

An unquoted type specifier used to validate data set into this slot. See Type Predicates in Common Lisp Extensions. Here are some examples:

symbol

A symbol.

number

A number type

my-class-name

An object of your class type.

(or null symbol)

A symbol, or nil.

:allocation

Either :class or :instance (defaults to :instance) used to specify how data is stored. Slots stored per instance have unique values for each object. Slots stored per class have shared values for each object. If one object changes a :class allocated slot, then all objects for that class gain the new value.

:documentation

Documentation detailing the use of this slot. This documentation is exposed when the user describes a class, and during customization of an object.

:accessor

Name of a generic function which can be used to fetch the value of this slot. You can call this function later on your object and retrieve the value of the slot.

This option is in the CLOS spec, but is not fully compliant in EIEIO.

:writer

Name of a generic function which will write this slot.

This option is in the CLOS spec, but is not fully compliant in EIEIO.

:reader

Name of a generic function which will read this slot.

This option is in the CLOS spec, but is not fully compliant in EIEIO.

:custom

A custom :type specifier used when editing an object of this type. See documentation for defcustom for details. This specifier is equivalent to the :type spec of a defcustom call.

This option is specific to Emacs, and is not in the CLOS spec.

:label

When customizing an object, the value of :label will be used instead of the slot name. This enables better descriptions of the data than would usually be afforded.

This option is specific to Emacs, and is not in the CLOS spec.

:group

Similar to defcustom’s :group command, this organizes different slots in an object into groups. When customizing an object, only the slots belonging to a specific group need be worked with, simplifying the size of the display.

This option is specific to Emacs, and is not in the CLOS spec.

:printer

This routine takes a symbol which is a function name. The function should accept one argument. The argument is the value from the slot to be printed. The function in object-write will write the slot value out to a printable form on standard-output.

The output format MUST be something that could in turn be interpreted with read such that the object can be brought back in from the output stream. Thus, if you wanted to output a symbol, you would need to quote the symbol. If you wanted to run a function on load, you can output the code to do the construction of the value.

:protection

This is an old option that is not supported any more.

When using a slot referencing function such as slot-value, and the value behind slot is private or protected, then the current scope of operation must be within a method of the calling object.

This protection is not enforced by the code any more, so it’s only useful as documentation.

Valid values are:

:public

Access this slot from any scope.

:protected

Access this slot only from methods of the same class or a child class.

:private

Access this slot only from methods of the same class.

This option is specific to Emacs, and is not in the CLOS spec.

3.3 Class Options

In the options-and-doc arguments to defclass, the following class options may be specified:

:documentation

A documentation string for this class.

If an Emacs-style documentation string is also provided, then this option is ignored. An Emacs-style documentation string is not prefixed by the :documentation tag, and appears after the list of slots, and before the options.

:allow-nil-initform

If this option is non-nil, and the :initform is nil, but the :type is specifies something such as string then allow this to pass. The default is to have this option be off. This is implemented as an alternative to unbound slots.

This option is specific to Emacs, and is not in the CLOS spec.

:abstract

A class which is :abstract cannot be instantiated, and instead is used to define an interface which subclasses should implement.

This option is specific to Emacs, and is not in the CLOS spec.

:custom-groups

This is a list of groups that can be customized within this class. This slot is auto-generated when a class is created and need not be specified. It can be retrieved with the class-option command, however, to see what groups are available.

This option is specific to Emacs, and is not in the CLOS spec.

:method-invocation-order

This controls the order in which method resolution occurs for methods in cases of multiple inheritance. The order affects which method is called first in a tree, and if cl-call-next-method is used, it controls the order in which the stack of methods are run.

Valid values are:

:breadth-first

Search for methods in the class hierarchy in breadth first order. This is the default.

:depth-first

Search for methods in the class hierarchy in a depth first order.

:c3

Searches for methods in a linearized way that most closely matches what CLOS does when a monotonic class structure is defined.

See Method Invocation, for more on method invocation order.

:metaclass

Unsupported CLOS option. Enables the use of a different base class other than standard-class.

:default-initargs

Unsupported CLOS option. Specifies a list of initargs to be used when creating new objects. As far as I can tell, this duplicates the function of :initform.

See CLOS compatibility, for more details on CLOS tags versus EIEIO-specific tags.

6.1 Generics

Each EIEIO method has one corresponding generic. This generic provides a function binding and the base documentation for the method symbol (see Symbol Components in GNU Emacs Lisp Reference Manual).

Macro: cl-defgeneric method arglist [doc-string] ¶

This macro turns the (unquoted) symbol method into a function. arglist is the default list of arguments to use (not implemented yet). doc-string is the documentation used for this symbol.

A generic function acts as a placeholder for methods. There is no need to call cl-defgeneric yourself, as cl-defmethod will call it if necessary. Currently the argument list is unused.

cl-defgeneric signals an error if you attempt to turn an existing Emacs Lisp function into a generic function.

You can also create a generic method with cl-defmethod (see Methods). When a method is created and there is no generic method in place with that name, then a new generic will be created, and the new method will use it.

6.2 Methods

A method is a function that is executed if the arguments passed to it matches the method’s specializers. Different EIEIO classes may share the same method names.

Methods are created with the cl-defmethod macro, which is similar to defun.

Macro: cl-defmethod method [:before | :around | :after ] arglist [doc-string] forms ¶

method is the name of the function to create.

:before, :around, and :after specify execution order (i.e., when this form is called). If none of these symbols are present, the method is said to be a primary.

arglist is the list of arguments to this method. The mandatory arguments in this list may have a type specializer (see the example below) which means that the method will only apply when those arguments match the given type specializer. An argument with no type specializer means that the method applies regardless of its value.

doc-string is the documentation attached to the implementation. All method doc-strings are incorporated into the generic method’s function documentation.

forms is the body of the function.

In the following example, we create a method mymethod for the classname class:

(cl-defmethod mymethod ((obj classname) secondarg)
  "Doc string" )

This method only executes if the obj argument passed to it is an EIEIO object of class classname.

A method with no type specializer is a default method. If a given class has no implementation, then the default method is called when that method is used on a given object of that class.

Only one method per combination of specializers and qualifiers (:before, :around, or :after) is kept. If two cl-defmethods appear with the same specializers and the same qualifiers, then the second implementation replaces the first.

When a method is called on an object, but there is no method specified for that object, but there is a method specified for object’s parent class, the parent class’s method is called. If there is a method defined for both, only the child’s method is called. A child method may call a parent’s method using cl-call-next-method, described below.

If multiple methods and default methods are defined for the same method and class, they are executed in this order:

1. :around methods The most specific :around method is called first, which may invoke the less specific ones via cl-call-next-method. If it doesn’t invoke cl-call-next-method, then no other methods will be executed. When there are no more :around methods to call, falls through to run the other (non-:around) methods.
2. :before methods Called in sequence from most specific to least specific.
3. primary methods The most specific method is called, which may invoke the less specific ones via cl-call-next-method.
4. :after methods Called in sequence from least specific to most specific.

If no methods exist, Emacs signals a cl-no-applicable-method error. See Signals. If methods exist but none of them are primary, Emacs signals a cl-no-primary-method error. See Signals.

Function: cl-call-next-method &rest replacement-args ¶

This function calls the superclass method from a subclass method. This is the “next method” specified in the current method list.

If replacement-args is non-nil, then use them instead of the arguments originally provided to the method.

Can only be used from within the lexical body of a primary or around method.

Function: cl-next-method-p ¶

Non-nil if there is a next method.

Can only be used from within the lexical body of a primary or around method.

6.3 Static Methods

Static methods do not depend on an object instance, but instead operate on a class. You can create a static method by using the subclass specializer with cl-defmethod:

(cl-defmethod make-instance ((class (subclass mychild)) &rest args)
  (let ((new (cl-call-next-method)))
    (push new all-my-children)
    new))

The argument of a static method will be a class rather than an object. Use the functions oref-default or oset-default which will work on a class.

A class’s make-instance method is defined as a static method.

Note: The subclass specializer is unique to EIEIO.

10.1 Widget extension

When widgets are being created, one new widget extension has been added, called the :slotofchoices. When this occurs in a widget definition, all elements after it are removed, and the slot is specifies is queried and converted into a series of constants.

(choice (const :tag "None" nil)
        :slotofchoices morestuff)

and if the slot morestuff contains (sym1 sym2 sym3), the above example is converted into:

(choice (const :tag "None" nil)
        (const sym1)
        (const sym2)
        (const sym3))

This is useful when a given item needs to be selected from a list of items defined in this second slot.

12.1 eieio-instance-inheritor

This class is defined in the package eieio-base.

Instance inheritance is a mechanism whereby the value of a slot in object instance can reference the parent instance. If the parent’s slot value is changed, then the child instance is also changed. If the child’s slot is set, then the parent’s slot is not modified.

Class: eieio-instance-inheritor parent-instance ¶

A class whose instances are enabled with instance inheritance. The parent-instance slot indicates the instance which is considered the parent of the current instance. Default is nil.

To use this class, inherit from it with your own class. To make a new instance that inherits from and existing instance of your class, use the clone method with additional parameters to specify local values.

The eieio-instance-inheritor class works by causing cloned objects to have all slots unbound. This class’ slot-unbound method will cause references to unbound slots to be redirected to the parent instance. If the parent slot is also unbound, then slot-unbound will signal an error named slot-unbound.

12.2 eieio-instance-tracker

This class is defined in the package eieio-base.

Sometimes it is useful to keep a master list of all instances of a given class. The class eieio-instance-tracker performs this task.

Class: eieio-instance-tracker tracking-symbol ¶

Enable instance tracking for this class. The slot tracking-symbol should be initialized in inheritors of this class to a symbol created with defvar. This symbol will serve as the variable used as a master list of all objects of the given class.

Method on eieio-instance-tracker: initialize-instance obj slot ¶

This method is defined as an :after method. It adds new instances to the master list.

Method on eieio-instance-tracker: delete-instance obj ¶

Remove obj from the master list of instances of this class. This may let the garbage collector nab this instance.

eieio-instance-tracker-find: key slot list-symbol ¶

This convenience function lets you find instances. key is the value to search for. slot is the slot to compare KEY against. The function equal is used for comparison. The parameter list-symbol is the variable symbol which contains the list of objects to be searched.

12.3 eieio-singleton

This class is defined in the package eieio-base.

Class: eieio-singleton ¶

Inheriting from the singleton class will guarantee that there will only ever be one instance of this class. Multiple calls to make-instance will always return the same object.

12.4 eieio-persistent

This class is defined in the package eieio-base.

If you want an object, or set of objects to be persistent, meaning the slot values are important to keep saved between sessions, then you will want your top level object to inherit from eieio-persistent.

To make sure your persistent object can be moved, make sure all file names stored to disk are made relative with eieio-persistent-path-relative.

Class: eieio-persistent file file-header-line ¶

Enables persistence for instances of this class. Slot file with initarg :file is the file name in which this object will be saved. Class allocated slot file-header-line is used with method object-write as a header comment.

All objects can write themselves to a file, but persistent objects have several additional methods that aid in maintaining them.

Method on eieio-persistent: eieio-persistent-save obj &optional file ¶

Write the object obj to its file. If optional argument file is specified, use that file name instead.

Method on eieio-persistent: eieio-persistent-path-relative obj file ¶

Return a file name derived from file which is relative to the stored location of OBJ. This method should be used to convert file names so that they are relative to the save file, making any system of files movable from one location to another.

Method on eieio-persistent: object-write obj &optional comment ¶

Like object-write for standard-object, but will derive a header line comment from the class allocated slot if one is not provided.

Function: eieio-persistent-read filename &optional class allow-subclass ¶

Read a persistent object from filename, and return it. Signal an error if the object in FILENAME is not a constructor for CLASS. Optional allow-subclass says that it is ok for eieio-persistent-read to load in subclasses of class instead of being pedantic.

12.5 eieio-named

This class is defined in the package eieio-base.

Class: eieio-named ¶

Object with a name. Name storage already occurs in an object. This object provides get/set access to it.

12.6 eieio-speedbar

This class is in package eieio-speedbar.

If a series of class instances map to a tree structure, it is possible to cause your classes to be displayable in Speedbar. See (speedbar)Top. Inheriting from these classes will enable a speedbar major display mode with a minimum of effort.

Class: eieio-speedbar buttontype buttonface ¶

Enables base speedbar display for a class. The slot buttontype is any of the symbols allowed by the function speedbar-make-tag-line for the exp-button-type argument See (speedbar)Extending. The slot buttonface is the face to use for the text of the string displayed in speedbar. The slots buttontype and buttonface are class allocated slots, and do not take up space in your instances.

Class: eieio-speedbar-directory-button buttontype buttonface ¶

This class inherits from eieio-speedbar and initializes buttontype and buttonface to appear as directory level lines.

Class: eieio-speedbar-file-button buttontype buttonface ¶

This class inherits from eieio-speedbar and initializes buttontype and buttonface to appear as file level lines.

To use these classes, inherit from one of them in you class. You can use multiple inheritance with them safely. To customize your class for speedbar display, override the default values for buttontype and buttonface to get the desired effects.

Useful methods to define for your new class include:

Method on eieio-speedbar: eieio-speedbar-derive-line-path obj depth ¶

Return a string representing a directory associated with an instance of obj. depth can be used to index how many levels of indentation have been opened by the user where obj is shown.

Method on eieio-speedbar: eieio-speedbar-description obj ¶

Return a string description of OBJ. This is shown in the minibuffer or tooltip when the mouse hovers over this instance in speedbar.

Method on eieio-speedbar: eieio-speedbar-child-description obj ¶

Return a string representing a description of a child node of obj when that child is not an object. It is often useful to just use item info helper functions such as speedbar-item-info-file-helper.

Method on eieio-speedbar: eieio-speedbar-object-buttonname obj ¶

Return a string which is the text displayed in speedbar for obj.

Method on eieio-speedbar: eieio-speedbar-object-children obj ¶

Return a list of children of obj.

Method on eieio-speedbar: eieio-speedbar-child-make-tag-lines obj depth ¶

This method inserts a list of speedbar tag lines for obj to represent its children. Implement this method for your class if your children are not objects themselves. You still need to implement eieio-speedbar-object-children.

In this method, use techniques specified in the Speedbar manual. See (speedbar)Extending.

Some other functions you will need to learn to use are:

eieio-speedbar-create: make-map key-map menu name toplevelfn ¶

Register your object display mode with speedbar. make-map is a function which initialized you keymap. key-map is a symbol you keymap is installed into. menu is an easy menu vector representing menu items specific to your object display. name is a short string to use as a name identifying you mode. toplevelfn is a function called which must return a list of objects representing those in the instance system you wish to browse in speedbar.

Read the Extending chapter in the speedbar manual for more information on how speedbar modes work See (speedbar)Extending.

15.1 Initialization

When creating an object of any type, you can use its constructor, or make-instance. This, in turns calls the method initialize-instance, which then calls the method shared-initialize.

These methods are all implemented on the default superclass so you do not need to write them yourself, unless you need to override one of their behaviors.

Users should not need to call initialize-instance or shared-initialize, as these are used by make-instance to initialize the object. They are instead provided so that users can augment these behaviors.

Function: initialize-instance obj &rest slots ¶

Initialize obj. Sets slots of obj with slots which is a list of name/value pairs. These are actually just passed to shared-initialize.

Function: shared-initialize obj &rest slots ¶

Sets slots of obj with slots which is a list of name/value pairs.

This is called from the default constructor.

15.2 Basic Methods

Additional useful methods defined on the base subclass are:

Function: clone obj &rest params ¶

Make a copy of obj, and then apply params. params is a parameter list of the same form as initialize-instance which are applied to change the object. When overloading clone, be sure to call cl-call-next-method first and modify the returned object.

Function: object-print this &rest strings ¶

Pretty printer for object this. Call function eieio-object-name with strings. The default method for printing object this is to use the function eieio-object-name.

It is sometimes useful to put a summary of the object into the default #<notation> string when using eieio browsing tools.

Implement this function and specify strings in a call to cl-call-next-method to provide additional summary information. When passing in extra strings from child classes, always remember to prepend a space.

(defclass data-object ()
   (value)
   "Object containing one data slot.")

(cl-defmethod object-print ((this data-object) &optional strings)
  "Return a string with a summary of the data object as part of the name."
  (apply #'cl-call-next-method this
         (format " value: %s" (render this))
         strings))

Here is what some output could look like:

(object-print test-object)
   => #<data-object test-object value: 3>

Function: object-write obj &optional comment ¶

Write obj onto a stream in a readable fashion. The resulting output will be Lisp code which can be used with read and eval to recover the object. Only slots with :initargs are written to the stream.

15.3 Signal Handling

The default superclass defines methods for managing error conditions. These methods all throw a signal for a particular error condition.

By implementing one of these methods for a class, you can change the behavior that occurs during one of these error cases, or even ignore the error by providing some behavior.

Function: slot-missing object slot-name operation &optional new-value ¶

Method invoked when an attempt to access a slot in object fails. slot-name is the name of the failed slot, operation is the type of access that was requested, and optional new-value is the value that was desired to be set.

This method is called from slot-value, set-slot-value, and other functions which directly reference slots in EIEIO objects.

The default method signals an error of type invalid-slot-name. See Signals.

You may override this behavior, but it is not expected to return in the current implementation.

This function takes arguments in a different order than in CLOS.

Function: slot-unbound object class slot-name fn ¶

Slot unbound is invoked during an attempt to reference an unbound slot. object is the instance of the object being reference. class is the class of object, and slot-name is the offending slot. This function throws the signal unbound-slot. You can overload this function and return the value to use in place of the unbound value. Argument fn is the function signaling this error. Use slot-boundp to determine if a slot is bound or not.

In clos, the argument list is (class object slot-name), but eieio can only dispatch on the first argument, so the first two are swapped.

Function: cl-no-applicable-method generic &rest args ¶

Called if there are no methods applicable for args in the generic function generic. args are the arguments that were passed to generic.

Implement this for a class to block this signal. The return value becomes the return value of the original method call.

Function: cl-no-primary-method generic &rest args ¶

Called if there are methods applicable for args in the generic function generic but they are all qualified. args are the arguments that were passed to generic.

Implement this for a class to block this signal. The return value becomes the return value of the original method call.

Function: cl-no-next-method generic method &rest args ¶

Called from cl-call-next-method when no additional methods are available. generic is the generic function being called on cl-call-next-method, method is the method where cl-call-next-method was called, and args are the arguments it is called by. This method signals cl-no-next-method by default. Override this method to not throw an error, and its return value becomes the return value of cl-call-next-method.