EIEIO
*****

EIEIO (“Enhanced Implementation of Emacs Interpreted Objects”) provides
an Object Oriented layer for Emacs Lisp, following the basic concepts of
the Common Lisp Object System (CLOS). It provides a framework for
writing object-oriented applications in Emacs.

   This manual documents EIEIO, an object framework for Emacs Lisp.

   Copyright © 2007–2025 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.3 or any later version published by the Free Software
     Foundation; with no Invariant Sections, with the Front-Cover Texts
     being “A GNU Manual,” and with the Back-Cover Texts as in (a)
     below.  A copy of the license is included in the section entitled
     “GNU Free Documentation License.”

     (a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
     modify this GNU manual.”

1 Quick Start
*************

EIEIO provides an Object Oriented layer for Emacs Lisp.  You can use
EIEIO to create classes, methods for those classes, and instances of
classes.

   Here is a simple example of a class named ‘person’, containing three
slots named ‘name’, ‘birthday’, and ‘phone’:

     (defclass person () ; No superclasses
       ((name :initarg :name
              :initform ""
              :type string
              :custom string
              :documentation "The name of a person.")
        (birthday :initarg :birthday
                  :initform "Jan 1, 1970"
                  :custom string
                  :type string
                  :documentation "The person's birthday.")
        (phone :initarg :phone
               :initform ""
               :documentation "Phone number."))
       "A class for tracking people I know.")

   Each class can have methods, which are defined like this:

     (cl-defmethod call-person ((pers person) &optional scriptname)
       "Dial the phone for the person PERS.
     Execute the program SCRIPTNAME to dial the phone."
       (message "Dialing the phone for %s"  (slot-value pers 'name))
       (shell-command (concat (or scriptname "dialphone.sh")
                              " "
                              (slot-value pers 'phone))))

In this example, the first argument to ‘call-person’ is a list, of the
form (VARNAME CLASSNAME).  VARNAME is the name of the variable used for
the first argument; CLASSNAME is the name of the class that is expected
as the first argument for this method.

   EIEIO dispatches methods based on the type of the first argument.
You can have multiple methods with the same name for different classes
of object.  When the ‘call-person’ method is called, the first argument
is examined to determine the class of that argument, and the method
matching the input type is then executed.

   Once the behavior of a class is defined, you can create a new object
of type ‘person’.  Objects are created by calling the constructor.  The
constructor is a function with the same name as your class which returns
a new instance of that class.  Here is an example:

     (setq pers (person :name "Eric" :birthday "June" :phone "555-5555"))

For backward compatibility reasons, the first argument can be a string
(a name given to this instance).  Each instance used to be given a name,
so different instances could be easily distinguished when debugging.

   It can be a bit repetitive to also have a :name slot.  To avoid doing
this, it is sometimes handy to use the base class ‘eieio-named’.  See
eieio-named.

   Calling methods on an object is a lot like calling any function.  The
first argument should be an object of a class which has had this method
defined for it.  In this example it would look like this:

     (call-person pers)

or

     (call-person pers "my-call-script")

   In these examples, EIEIO automatically examines the class of ‘pers’,
and ensures that the method defined above is called.  If ‘pers’ is some
other class lacking a ‘call-person’ method, or some other data type,
Emacs signals a ‘cl-no-applicable-method’ error.  See Signals.

2 Introduction
**************

First off, please note that this manual cannot serve as a complete
introduction to object oriented programming and generic functions in
LISP.  Although EIEIO is not a complete implementation of the Common
Lisp Object System (CLOS) and also differs from it in several aspects,
it follows the same basic concepts.  Therefore, it is highly recommended
to learn those from a textbook or tutorial first, especially if you only
know OOP from languages like C++ or Java.  If on the other hand you are
already familiar with CLOS, you should be aware that EIEIO does not
implement the full CLOS specification and also differs in some other
aspects which are mentioned below (also CLOS compatibility).

   EIEIO supports the following features:

  1. A structured framework for the creation of basic classes with
     attributes and methods using inheritance similar to CLOS.
  2. Type checking, and slot unbinding.
  3. Method definitions similar to CLOS.
  4. Simple and complex class browsers.
  5. Edebug support for methods.
  6. Imenu updates.
  7. Byte compilation support of methods.
  8. Help system extensions for classes and methods.
  9. Several base classes for interesting tasks.
  10. Simple test suite.
  11. Public and private classifications for slots (extensions to CLOS)
  12. Customization support in a class (extension to CLOS)

   Due to restrictions in the Emacs Lisp language, CLOS cannot be
completely supported, and a few functions have been added in place of
setf.  Here are some important CLOS features that EIEIO presently lacks:

Support for metaclasses
     There is just one default metaclass, ‘eieio-default-superclass’,
     and you cannot define your own.  The ‘:metaclass’ tag in ‘defclass’
     is ignored.  Also, functions like ‘find-class’, which should return
     instances of the metaclass, behave differently in EIEIO in that
     they return symbols or plain structures instead.

:default-initargs in ‘defclass’
     Each slot can have an ‘:initform’ tag, so this is not really
     necessary.

Mock object initializers
     Each class contains a mock object used for fast initialization of
     instantiated objects.  Using functions with side effects on object
     slot values can potentially cause modifications in the mock object.
     EIEIO should use a deep copy but currently does not.

3 Building Classes
******************

A “class” is a definition for organizing data and methods together.  An
EIEIO class has structures similar to the classes found in other
object-oriented (OO) languages.

   To create a new class, use the ‘defclass’ macro:

 -- Macro: defclass class-name superclass-list slot-list &rest
          options-and-doc

     Create a new class named CLASS-NAME.  The class is represented by a
     symbol with the name CLASS-NAME.  EIEIO stores the structure of the
     class as a symbol property of CLASS-NAME (see Symbol Components (elisp)).

     When defining a class, EIEIO overwrites any preexisting variable or
     function bindings for the symbol CLASS-NAME, which may lead to
     undesired consequences.  Before naming a new class, you should
     check for name conflicts.  To help avoid cross-package conflicts
     you should choose a name with the same prefix you chose for the
     rest of your package’s functions and variables (see Coding Conventions (elisp)).

     The CLASS-NAME symbol’s variable documentation string is a modified
     version of the doc string found in OPTIONS-AND-DOC.  Each time a
     method is defined, the symbol’s documentation string is updated to
     include the method’s documentation as well.

     The parent classes for CLASS-NAME is SUPERCLASS-LIST.  Each element
     of SUPERCLASS-LIST must be a class.  These classes are the parents
     of the class being created.  Every slot that appears in each parent
     class is replicated in the new class.

     If two parents share the same slot name, the parent which appears
     in the SUPERCLASS-LIST first sets the tags for that slot.  If the
     new class has a slot with the same name as the parent, the new slot
     overrides the parent’s slot.

     When overriding a slot, some slot attributes cannot be overridden
     because they break basic OO rules.  You cannot override ‘:type’ or
     ‘:protection’.

Whenever defclass is used to create a new class, a predicate is created
for it, named ‘CLASS-NAME-p’:

 -- Function: CLASS-NAME-p object
     Return non-‘nil’ if and only if OBJECT is of the class CLASS-NAME.

 -- Variable: eieio-error-unsupported-class-tags
     If non-‘nil’, ‘defclass’ signals an error if a tag in a slot
     specifier is unsupported.

     This option is here to support programs written with older versions
     of EIEIO, which did not produce such errors.

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.  See Writing 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).  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 (cl).  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.

4 Making New Objects
********************

Suppose we have defined a simple class, such as:

     (defclass my-class ()
        ( ) "Doc String")

It is now possible to create objects of that class type.

   Calling ‘defclass’ has defined two new functions.  One is the
constructor MY-CLASS, and the other is the predicate, MY-CLASS-p.

 -- Function: my-class object-name &rest slots

     This creates and returns a new object.  This object is not assigned
     to anything, and will be garbage collected if not saved.  This
     object will be given the string name OBJECT-NAME.  There can be
     multiple objects of the same name, but the name slot provides a
     handy way to keep track of your objects.  SLOTS is just all the
     slots you wish to preset.  Any slot set as such _will not_ get its
     default value, and any side effects from a slot’s ‘:initform’ that
     may be a function will not occur.

     An example pair would appear simply as ‘:value 1’.  Of course you
     can do any valid Lispy thing you want with it, such as ‘:value (if
     (boundp 'special-symbol) special-symbol nil)’

     Example of creating an object from a class:

          (my-class :value 3 :reference nil)

   To create an object from a class symbol, use ‘make-instance’.

 -- Function: make-instance class &rest initargs
     Make a new instance of CLASS based on INITARGS.  CLASS is a class
     symbol.  For example:

            (make-instance 'foo)

     INITARGS is a property list with keywords based on the ‘:initarg’
     for each slot.  For example:

            (make-instance 'foo :slot1 value1 :slotN valueN)

5 Accessing Slots
*****************

There are several ways to access slot values in an object.  The
following accessors are defined by CLOS to reference or modify slot
values, and use the previously mentioned set/ref routines.

 -- Function: slot-value object slot
     This function retrieves the value of SLOT from OBJECT.  It can also
     be used on objects defined by ‘cl-defstruct’.

     This is a generalized variable that can be used with ‘setf’ to
     modify the value stored in SLOT.  See Generalized Variables (elisp).

 -- Function: set-slot-value object slot value
     This function sets the value of SLOT from OBJECT.

     This is not a CLOS function.  It is therefore recommended to use
     ‘(setf (slot-value OBJECT SLOT) VALUE)’ instead.

 -- Function: slot-makeunbound object slot
     This function unbinds SLOT in OBJECT.  Referencing an unbound slot
     can signal an error.

   The following accessors follow a naming and argument-order
conventions are similar to those used for referencing vectors (see
Vectors (elisp)).

 -- Macro: oref obj slot
     This macro retrieves the value stored in OBJ in the named SLOT.
     Unlike ‘slot-value’, the symbol for SLOT must not be quoted.

     This is a generalized variable that can be used with ‘setf’ to
     modify the value stored in SLOT.  See Generalized Variables (elisp).

 -- Macro: oref-default class slot
     This macro returns the value of the class-allocated SLOT from
     CLASS.

     This is a generalized variable that can be used with ‘setf’ to
     modify the value stored in SLOT.  See Generalized Variables (elisp).

 -- Macro: oset object slot value
     This macro sets the value behind SLOT to VALUE in OBJECT.  It
     returns VALUE.

 -- Macro: oset-default class slot value
     This macro sets the value for the class-allocated SLOT in CLASS to
     VALUE.

     For example, if a user wanted all ‘data-objects’ (see Building Classes)
     to inform a special object of his own devising when they
     changed, this can be arranged by simply executing this bit of code:

          (oset-default data-object reference (list my-special-object))

 -- Function: object-add-to-list object slot item &optional append
     In OBJECT’s SLOT, add ITEM to the list of elements.  Optional
     argument APPEND indicates we need to append to the list.  If ITEM
     already exists in the list in SLOT, then it is not added.
     Comparison is done with “equal” through the “member” function call.
     If SLOT is unbound, bind it to the list containing ITEM.

 -- Function: object-remove-from-list object slot item
     In OBJECT’s SLOT, remove occurrences of ITEM.  Deletion is done
     with “delete”, which deletes by side effect and comparisons are
     done with “equal”.  If SLOT is unbound, do nothing.

 -- Function: with-slots spec-list object &rest body
     Bind SPEC-LIST lexically to slot values in OBJECT, and execute
     BODY.  This establishes a lexical environment for referring to the
     slots in the instance named by the given slot-names as though they
     were variables.  Within such a context the value of the slot can be
     specified by using its slot name, as if it were a lexically bound
     variable.  Both ‘setf’ and ‘setq’ can be used to set the value of
     the slot.

     SPEC-LIST is of a form similar to “let”.  For example:

            ((VAR1 SLOT1)
              SLOT2
              SLOTN
             (VARN+1 SLOTN+1))

     Where each VAR is the local variable given to the associated SLOT.
     A slot specified without a variable name is given a variable name
     of the same name as the slot.

          (defclass myclass () ((x :initform 1)))
          (setq mc (make-instance 'myclass))
          (with-slots (x) mc x)                      => 1
          (with-slots ((something x)) mc something)  => 1

6 Writing Methods
*****************

Writing a method in EIEIO is similar to writing a function.  The
differences are that there are some extra options and there can be
multiple definitions under the same function symbol.

   You do it using Emacs Lisp’s built-in support for CLOS-style generic
functions via the ‘cl-defgeneric’ and ‘cl-defmethod’ macros (see
Generic Functions (elisp)).

   EIEIO provides one extension to ‘cl-defmethod’ to allow methods to
dispatch on a class argument: so-called “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.

7 Method Invocation
*******************

When classes are defined, you can specify the
‘:method-invocation-order’.  This is a feature specific to EIEIO.

   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.

   The original EIEIO order turned out to be broken for multiple
inheritance, but some programs depended on it.  As such this option was
added when the default invocation order was fixed to something that made
more sense in that case.

   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.

     This is derived from the Dylan language documents by Kim Barrett et
     al.: A Monotonic Superclass Linearization for Dylan Retrieved from:
     https://doi.org/10.1145/236338.236343

8 Predicates and Utilities
**************************

Now that we know how to create classes, access slots, and define
methods, it might be useful to verify that everything is doing ok.  To
help with this a plethora of predicates have been created.

 -- Function: find-class symbol &optional errorp
     Return the class that SYMBOL represents.  If there is no class,
     ‘nil’ is returned if ERRORP is ‘nil’.  If ERRORP is non-‘nil’,
     ‘wrong-argument-type’ is signaled.

 -- Function: class-p class
     Return ‘t’ if CLASS is a valid class object.  CLASS is a symbol.

 -- Function: slot-exists-p object-or-class slot
     Non-‘nil’ if OBJECT-OR-CLASS has SLOT.

 -- Function: slot-boundp object slot
     Non-‘nil’ if OBJECT’s SLOT is bound.  Setting a slot’s value makes
     it bound.  Calling “slot-makeunbound” will make a slot unbound.
     OBJECT can be an instance or a class.

 -- Function: eieio-class-name class
     Return the class name as a symbol.

 -- Function: class-option class option
     Return the value in CLASS of a given OPTION.  For example:

          (class-option eieio-default-superclass :documentation)

     Will fetch the documentation string for ‘eieio-default-superclass’.

 -- Function: eieio-object-name obj
     Return a string of the form ‘#<object-class myobjname>’ for OBJ.
     This should look like Lisp symbols from other parts of Emacs such
     as buffers and processes, and is shorter and cleaner than printing
     the object’s record.  It is more useful to use ‘object-print’ to
     get an object’s print form, as this allows the object to add extra
     display information into the symbol.

 -- Function: eieio-object-class obj
     Returns the class symbol from OBJ.

 -- Function: eieio-object-class-name obj
     Returns the symbol of OBJ’s class.

 -- Function: eieio-class-parents class
     Returns the direct parents class of CLASS.  Returns ‘nil’ if it is
     a superclass.

 -- Function: eieio-class-parents-fast class
     Just like ‘eieio-class-parents’ except it is a macro and no type
     checking is performed.

 -- Function: eieio-class-parent class
     Deprecated function which returns the first parent of CLASS.

 -- Function: eieio-class-children class
     Return the list of classes inheriting from CLASS.

 -- Function: eieio-class-children-fast class
     Just like ‘eieio-class-children’, but with no checks.

 -- Function: same-class-p obj class
     Returns ‘t’ if OBJ’s class is the same as CLASS.

 -- Function: object-of-class-p obj class
     Returns ‘t’ if OBJ inherits anything from CLASS.  This is different
     from ‘same-class-p’ because it checks for inheritance.

 -- Function: child-of-class-p child class
     Returns ‘t’ if CHILD is a subclass of CLASS.

 -- Function: generic-p method-symbol
     Returns ‘t’ if ‘method-symbol’ is a generic function, as opposed to
     a regular Emacs Lisp function.

9 Association Lists
*******************

Lisp offers the concept of association lists, with primitives such as
‘assoc’ used to access them.  The following functions can be used to
manage association lists of EIEIO objects:

 -- Function: object-assoc key slot list
     Return an object if KEY is “equal” to SLOT’s value of an object in
     LIST.  LIST is a list of objects whose slots are searched.  Objects
     in LIST do not need to have a slot named SLOT, nor does SLOT need
     to be bound.  If these errors occur, those objects will be ignored.

 -- Function: object-assoc-list slot list
     Return an association list generated by extracting SLOT from all
     objects in LIST.  For each element of LIST the ‘car’ is the value
     of SLOT, and the ‘cdr’ is the object it was extracted from.  This
     is useful for generating completion tables.

 -- Function: eieio-build-class-alist &optional base-class
     Returns an alist of all currently defined classes.  This alist is
     suitable for completion lists used by interactive functions to
     select a class.  The optional argument BASE-CLASS allows the
     programmer to select only a subset of classes which includes
     BASE-CLASS and all its subclasses.

10 Customizing Objects
**********************

EIEIO supports the Custom facility through two new widget types.  If a
variable is declared as type ‘object’, then full editing of slots via
the widgets is made possible.  This should be used carefully, however,
because modified objects are cloned, so if there are other references to
these objects, they will no longer be linked together.

   If you want in place editing of objects, use the following methods:

 -- Function: eieio-customize-object object
     Create a custom buffer and insert a widget for editing OBJECT.  At
     the end, an ‘Apply’ and ‘Reset’ button are available.  This will
     edit the object "in place" so references to it are also changed.
     There is no effort to prevent multiple edits of a singular object,
     so care must be taken by the user of this function.

 -- Function: eieio-custom-widget-insert object flags
     This method inserts an edit object into the current buffer in
     place.  It is implemented as ‘(widget-create 'object-edit :value
     object)’.  This method is provided as a locale for adding tracking,
     or specializing the widget insert procedure for any object.

   To define a slot with an object in it, use the ‘object’ tag.  This
widget type will be automatically converted to ‘object-edit’ if you do
in place editing of you object.

   If you want to have additional actions taken when a user clicks on
the ‘Apply’ button, then overload the method ‘eieio-done-customizing’.
This method does nothing by default, but that may change in the future.
This would be the best way to make your objects persistent when using
in-place editing.

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.

11 Introspection
****************

Introspection permits a programmer to peek at the contents of a class
without any previous knowledge of that class.  While EIEIO implements
objects on top of records, and thus everything is technically visible,
some functions have been provided.  None of these functions are a part
of CLOS.

 -- Function: eieio-class-slots obj
     Return the list of public slots for OBJ.

12 Base Classes
***************

All defined classes, if created with no specified parent class, inherit
from a special class called ‘eieio-default-superclass’.  See Default Superclass.

   Often, it is more convenient to inherit from one of the other base
classes provided by EIEIO, which have useful pre-defined properties.
(Since EIEIO supports multiple inheritance, you can even inherit from
more than one of these classes at once.)

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.  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 Extending (speedbar).  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 Extending (speedbar).

   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 Extending (speedbar).

13 Browsing class trees
***********************

The command ‘M-x eieio-browse’ displays a buffer listing all the
currently loaded classes in Emacs.  The classes are listed in an
indented tree structure, starting from ‘eieio-default-superclass’ (see
Default Superclass).

   With a prefix argument, this command prompts for a class name; it
then lists only that class and its subclasses.

   Here is a sample tree from our current example:

     eieio-default-superclass
       +--data-object
            +--data-object-symbol

   Note: new classes are consed into the inheritance lists, so the tree
comes out upside-down.

14 Class Values
***************

You can use the normal ‘describe-function’ command to retrieve
information about a class.  Running it on constructors will show a full
description of the generated class.  If you call it on a generic
function, all implementations of that generic function will be listed,
together with links through which you can directly jump to the source.

15 Default Superclass
*********************

All defined classes, if created with no specified parent class, will
inherit from a special class stored in ‘eieio-default-superclass’.  This
superclass is quite simple, but with it, certain default methods or
attributes can be added to all objects.  In CLOS, this would be named
‘STANDARD-CLASS’, and that symbol is an alias to
‘eieio-default-superclass’.

   Currently, the default superclass is defined as follows:

     (defclass eieio-default-superclass nil
       nil
       "Default parent class for classes with no specified parent class.
     Its slots are automatically adopted by classes with no specified
     parents.  This class is not stored in the `parent' slot of a class object."
       :abstract t)

   The default superclass implements several methods providing a default
behavior for all objects created by EIEIO.

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 ‘:initarg’s 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”.

16 Signals
**********

There are new condition names (signals) that can be caught when using
EIEIO.

 -- Signal: invalid-slot-name obj-or-class slot
     This signal is called when an attempt to reference a slot in an
     OBJ-OR-CLASS is made, and the SLOT is not defined for it.

 -- Signal: cl-no-applicable-method generic arguments
     This signal is called when GENERIC is called, with ARGUMENTS and
     nothing is resolved.  This occurs when GENERIC has been defined,
     but the arguments make it impossible for EIEIO to determine which
     method body to run.

     To prevent this signal from occurring in your class, implement the
     method ‘cl-no-applicable-method’ for your class.  This method is
     called when to throw this signal, so implementing this for your
     class allows you block the signal, and perform some work.

 -- Signal: cl-no-primary-method generic arguments
     Like ‘cl-no-applicable-method’ but applies when there are some
     applicable methods, but none of them are primary.  You can
     similarly block it by implementing a ‘cl-no-primary-method’ method.

 -- Signal: cl-no-next-method class arguments
     This signal is called if the function ‘cl-call-next-method’ is
     called and there is no next method to be called.

     Overload the method ‘cl-no-next-method’ to protect against this
     signal.

 -- Signal: invalid-slot-type slot spec value
     This signal is called when an attempt to set SLOT is made, and
     VALUE doesn’t match the specified type SPEC.

     In EIEIO, this is also used if a slot specifier has an invalid
     value during a ‘defclass’.

 -- Signal: unbound-slot object class slot
     This signal is called when an attempt to reference SLOT in OBJECT
     is made, and that instance is currently unbound.

17 Naming Conventions
*********************

See Tips and Conventions (elisp), for a description of Emacs Lisp
programming conventions.  These conventions help ensure that Emacs
packages work nicely one another, so an EIEIO-based program should
follow them.  Here are some conventions that apply specifically to
EIEIO-based programs:

   • Come up with a package prefix that is relatively short.  Prefix all
     classes, and methods with your prefix.  This is a standard
     convention for functions and variables in Emacs.

   • Do not prefix method names with the class name.  All methods in
     EIEIO are “virtual”, and are dynamically dispatched.  Anyone can
     override your methods at any time.  Your methods should be prefixed
     with your package name.

   • Do not prefix slots in your class.  The slots are always locally
     scoped to your class, and need no prefixing.

   • If your library inherits from other libraries of classes, you must
     “require” that library with the ‘require’ command.

18 CLOS compatibility
*********************

Currently, the following functions should behave almost as expected from
CLOS.

‘defclass’
     All slot keywords are available but not all work correctly.  Slot
     keyword differences are:

     :reader, and :writer tags
          Create methods that signal errors instead of creating an
          unqualified method.  You can still create new ones to do its
          business.

     :accessor
          This should create an unqualified method to access a slot, but
          instead pre-builds a method that gets the slot’s value.

     :type
          Specifier uses the ‘typep’ function from the ‘cl’ package.
          See Type Predicates (cl).  It therefore has the same issues
          as that package.  Extensions include the ability to provide
          object names.

     defclass also supports class options, but does not currently use
     values of ‘:metaclass’, and ‘:default-initargs’.

‘make-instance’
     Make instance works as expected, however it just uses the EIEIO
     instance creator automatically generated when a new class is
     created.  See Making New Objects.

‘cl-defgeneric’
     Creates the desired symbol, and accepts most of the expected
     arguments of CLOS’s ‘defgeneric’.

‘cl-defmethod’
     Accepts most of the expected arguments of CLOS’s ‘defmethod’.  To
     type cast against a class, the class must exist before
     ‘cl-defmethod’ is called.

‘cl-call-next-method’
     Works just like CLOS’s ‘call-next-method’.

   CLOS supports the ‘describe’ command, but EIEIO provides support for
using the standard ‘describe-function’ command on a constructor or
generic function.

   When creating a new class (see Building Classes) there are
several new keywords supported by EIEIO.

   In EIEIO tags are in lower case, not mixed case.

19 Wish List
************

EIEIO is an incomplete implementation of CLOS.  Finding ways to improve
the compatibility would help make CLOS style programs run better in
Emacs.

   Some important compatibility features that would be good to add are:

  1. Support for metaclasses.
  2. Improve integration with the ‘cl’ package.

   There are also improvements to be made to allow EIEIO to operate
better in the Emacs environment.

  1. Allow subclassing of Emacs built-in types, such as faces, markers,
     and buffers.
  2. Allow method overloading of method-like functions in Emacs.

Appendix A GNU Free Documentation License
*****************************************

                     Version 1.3, 3 November 2008

     Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
     <https://fsf.org/>

     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

  0. PREAMBLE

     The purpose of this License is to make a manual, textbook, or other
     functional and useful document “free” in the sense of freedom: to
     assure everyone the effective freedom to copy and redistribute it,
     with or without modifying it, either commercially or
     noncommercially.  Secondarily, this License preserves for the
     author and publisher a way to get credit for their work, while not
     being considered responsible for modifications made by others.

     This License is a kind of “copyleft”, which means that derivative
     works of the document must themselves be free in the same sense.
     It complements the GNU General Public License, which is a copyleft
     license designed for free software.

     We have designed this License in order to use it for manuals for
     free software, because free software needs free documentation: a
     free program should come with manuals providing the same freedoms
     that the software does.  But this License is not limited to
     software manuals; it can be used for any textual work, regardless
     of subject matter or whether it is published as a printed book.  We
     recommend this License principally for works whose purpose is
     instruction or reference.

  1. APPLICABILITY AND DEFINITIONS

     This License applies to any manual or other work, in any medium,
     that contains a notice placed by the copyright holder saying it can
     be distributed under the terms of this License.  Such a notice
     grants a world-wide, royalty-free license, unlimited in duration,
     to use that work under the conditions stated herein.  The
     “Document”, below, refers to any such manual or work.  Any member
     of the public is a licensee, and is addressed as “you”.  You accept
     the license if you copy, modify or distribute the work in a way
     requiring permission under copyright law.

     A “Modified Version” of the Document means any work containing the
     Document or a portion of it, either copied verbatim, or with
     modifications and/or translated into another language.

     A “Secondary Section” is a named appendix or a front-matter section
     of the Document that deals exclusively with the relationship of the
     publishers or authors of the Document to the Document’s overall
     subject (or to related matters) and contains nothing that could
     fall directly within that overall subject.  (Thus, if the Document
     is in part a textbook of mathematics, a Secondary Section may not
     explain any mathematics.)  The relationship could be a matter of
     historical connection with the subject or with related matters, or
     of legal, commercial, philosophical, ethical or political position
     regarding them.

     The “Invariant Sections” are certain Secondary Sections whose
     titles are designated, as being those of Invariant Sections, in the
     notice that says that the Document is released under this License.
     If a section does not fit the above definition of Secondary then it
     is not allowed to be designated as Invariant.  The Document may
     contain zero Invariant Sections.  If the Document does not identify
     any Invariant Sections then there are none.

     The “Cover Texts” are certain short passages of text that are
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
     that says that the Document is released under this License.  A
     Front-Cover Text may be at most 5 words, and a Back-Cover Text may
     be at most 25 words.

     A “Transparent” copy of the Document means a machine-readable copy,
     represented in a format whose specification is available to the
     general public, that is suitable for revising the document
     straightforwardly with generic text editors or (for images composed
     of pixels) generic paint programs or (for drawings) some widely
     available drawing editor, and that is suitable for input to text
     formatters or for automatic translation to a variety of formats
     suitable for input to text formatters.  A copy made in an otherwise
     Transparent file format whose markup, or absence of markup, has
     been arranged to thwart or discourage subsequent modification by
     readers is not Transparent.  An image format is not Transparent if
     used for any substantial amount of text.  A copy that is not
     “Transparent” is called “Opaque”.

     Examples of suitable formats for Transparent copies include plain
     ASCII without markup, Texinfo input format, LaTeX input format,
     SGML or XML using a publicly available DTD, and standard-conforming
     simple HTML, PostScript or PDF designed for human modification.
     Examples of transparent image formats include PNG, XCF and JPG.
     Opaque formats include proprietary formats that can be read and
     edited only by proprietary word processors, SGML or XML for which
     the DTD and/or processing tools are not generally available, and
     the machine-generated HTML, PostScript or PDF produced by some word
     processors for output purposes only.

     The “Title Page” means, for a printed book, the title page itself,
     plus such following pages as are needed to hold, legibly, the
     material this License requires to appear in the title page.  For
     works in formats which do not have any title page as such, “Title
     Page” means the text near the most prominent appearance of the
     work’s title, preceding the beginning of the body of the text.

     The “publisher” means any person or entity that distributes copies
     of the Document to the public.

     A section “Entitled XYZ” means a named subunit of the Document
     whose title either is precisely XYZ or contains XYZ in parentheses
     following text that translates XYZ in another language.  (Here XYZ
     stands for a specific section name mentioned below, such as
     “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.)
     To “Preserve the Title” of such a section when you modify the
     Document means that it remains a section “Entitled XYZ” according
     to this definition.

     The Document may include Warranty Disclaimers next to the notice
     which states that this License applies to the Document.  These
     Warranty Disclaimers are considered to be included by reference in
     this License, but only as regards disclaiming warranties: any other
     implication that these Warranty Disclaimers may have is void and
     has no effect on the meaning of this License.

  2. VERBATIM COPYING

     You may copy and distribute the Document in any medium, either
     commercially or noncommercially, provided that this License, the
     copyright notices, and the license notice saying this License
     applies to the Document are reproduced in all copies, and that you
     add no other conditions whatsoever to those of this License.  You
     may not use technical measures to obstruct or control the reading
     or further copying of the copies you make or distribute.  However,
     you may accept compensation in exchange for copies.  If you
     distribute a large enough number of copies you must also follow the
     conditions in section 3.

     You may also lend copies, under the same conditions stated above,
     and you may publicly display copies.

  3. COPYING IN QUANTITY

     If you publish printed copies (or copies in media that commonly
     have printed covers) of the Document, numbering more than 100, and
     the Document’s license notice requires Cover Texts, you must
     enclose the copies in covers that carry, clearly and legibly, all
     these Cover Texts: Front-Cover Texts on the front cover, and
     Back-Cover Texts on the back cover.  Both covers must also clearly
     and legibly identify you as the publisher of these copies.  The
     front cover must present the full title with all words of the title
     equally prominent and visible.  You may add other material on the
     covers in addition.  Copying with changes limited to the covers, as
     long as they preserve the title of the Document and satisfy these
     conditions, can be treated as verbatim copying in other respects.

     If the required texts for either cover are too voluminous to fit
     legibly, you should put the first ones listed (as many as fit
     reasonably) on the actual cover, and continue the rest onto
     adjacent pages.

     If you publish or distribute Opaque copies of the Document
     numbering more than 100, you must either include a machine-readable
     Transparent copy along with each Opaque copy, or state in or with
     each Opaque copy a computer-network location from which the general
     network-using public has access to download using public-standard
     network protocols a complete Transparent copy of the Document, free
     of added material.  If you use the latter option, you must take
     reasonably prudent steps, when you begin distribution of Opaque
     copies in quantity, to ensure that this Transparent copy will
     remain thus accessible at the stated location until at least one
     year after the last time you distribute an Opaque copy (directly or
     through your agents or retailers) of that edition to the public.

     It is requested, but not required, that you contact the authors of
     the Document well before redistributing any large number of copies,
     to give them a chance to provide you with an updated version of the
     Document.

  4. MODIFICATIONS

     You may copy and distribute a Modified Version of the Document
     under the conditions of sections 2 and 3 above, provided that you
     release the Modified Version under precisely this License, with the
     Modified Version filling the role of the Document, thus licensing
     distribution and modification of the Modified Version to whoever
     possesses a copy of it.  In addition, you must do these things in
     the Modified Version:

       A. Use in the Title Page (and on the covers, if any) a title
          distinct from that of the Document, and from those of previous
          versions (which should, if there were any, be listed in the
          History section of the Document).  You may use the same title
          as a previous version if the original publisher of that
          version gives permission.

       B. List on the Title Page, as authors, one or more persons or
          entities responsible for authorship of the modifications in
          the Modified Version, together with at least five of the
          principal authors of the Document (all of its principal
          authors, if it has fewer than five), unless they release you
          from this requirement.

       C. State on the Title page the name of the publisher of the
          Modified Version, as the publisher.

       D. Preserve all the copyright notices of the Document.

       E. Add an appropriate copyright notice for your modifications
          adjacent to the other copyright notices.

       F. Include, immediately after the copyright notices, a license
          notice giving the public permission to use the Modified
          Version under the terms of this License, in the form shown in
          the Addendum below.

       G. Preserve in that license notice the full lists of Invariant
          Sections and required Cover Texts given in the Document’s
          license notice.

       H. Include an unaltered copy of this License.

       I. Preserve the section Entitled “History”, Preserve its Title,
          and add to it an item stating at least the title, year, new
          authors, and publisher of the Modified Version as given on the
          Title Page.  If there is no section Entitled “History” in the
          Document, create one stating the title, year, authors, and
          publisher of the Document as given on its Title Page, then add
          an item describing the Modified Version as stated in the
          previous sentence.

       J. Preserve the network location, if any, given in the Document
          for public access to a Transparent copy of the Document, and
          likewise the network locations given in the Document for
          previous versions it was based on.  These may be placed in the
          “History” section.  You may omit a network location for a work
          that was published at least four years before the Document
          itself, or if the original publisher of the version it refers
          to gives permission.

       K. For any section Entitled “Acknowledgements” or “Dedications”,
          Preserve the Title of the section, and preserve in the section
          all the substance and tone of each of the contributor
          acknowledgements and/or dedications given therein.

       L. Preserve all the Invariant Sections of the Document, unaltered
          in their text and in their titles.  Section numbers or the
          equivalent are not considered part of the section titles.

       M. Delete any section Entitled “Endorsements”.  Such a section
          may not be included in the Modified Version.

       N. Do not retitle any existing section to be Entitled
          “Endorsements” or to conflict in title with any Invariant
          Section.

       O. Preserve any Warranty Disclaimers.

     If the Modified Version includes new front-matter sections or
     appendices that qualify as Secondary Sections and contain no
     material copied from the Document, you may at your option designate
     some or all of these sections as invariant.  To do this, add their
     titles to the list of Invariant Sections in the Modified Version’s
     license notice.  These titles must be distinct from any other
     section titles.

     You may add a section Entitled “Endorsements”, provided it contains
     nothing but endorsements of your Modified Version by various
     parties—for example, statements of peer review or that the text has
     been approved by an organization as the authoritative definition of
     a standard.

     You may add a passage of up to five words as a Front-Cover Text,
     and a passage of up to 25 words as a Back-Cover Text, to the end of
     the list of Cover Texts in the Modified Version.  Only one passage
     of Front-Cover Text and one of Back-Cover Text may be added by (or
     through arrangements made by) any one entity.  If the Document
     already includes a cover text for the same cover, previously added
     by you or by arrangement made by the same entity you are acting on
     behalf of, you may not add another; but you may replace the old
     one, on explicit permission from the previous publisher that added
     the old one.

     The author(s) and publisher(s) of the Document do not by this
     License give permission to use their names for publicity for or to
     assert or imply endorsement of any Modified Version.

  5. COMBINING DOCUMENTS

     You may combine the Document with other documents released under
     this License, under the terms defined in section 4 above for
     modified versions, provided that you include in the combination all
     of the Invariant Sections of all of the original documents,
     unmodified, and list them all as Invariant Sections of your
     combined work in its license notice, and that you preserve all
     their Warranty Disclaimers.

     The combined work need only contain one copy of this License, and
     multiple identical Invariant Sections may be replaced with a single
     copy.  If there are multiple Invariant Sections with the same name
     but different contents, make the title of each such section unique
     by adding at the end of it, in parentheses, the name of the
     original author or publisher of that section if known, or else a
     unique number.  Make the same adjustment to the section titles in
     the list of Invariant Sections in the license notice of the
     combined work.

     In the combination, you must combine any sections Entitled
     “History” in the various original documents, forming one section
     Entitled “History”; likewise combine any sections Entitled
     “Acknowledgements”, and any sections Entitled “Dedications”.  You
     must delete all sections Entitled “Endorsements.”

  6. COLLECTIONS OF DOCUMENTS

     You may make a collection consisting of the Document and other
     documents released under this License, and replace the individual
     copies of this License in the various documents with a single copy
     that is included in the collection, provided that you follow the
     rules of this License for verbatim copying of each of the documents
     in all other respects.

     You may extract a single document from such a collection, and
     distribute it individually under this License, provided you insert
     a copy of this License into the extracted document, and follow this
     License in all other respects regarding verbatim copying of that
     document.

  7. AGGREGATION WITH INDEPENDENT WORKS

     A compilation of the Document or its derivatives with other
     separate and independent documents or works, in or on a volume of a
     storage or distribution medium, is called an “aggregate” if the
     copyright resulting from the compilation is not used to limit the
     legal rights of the compilation’s users beyond what the individual
     works permit.  When the Document is included in an aggregate, this
     License does not apply to the other works in the aggregate which
     are not themselves derivative works of the Document.

     If the Cover Text requirement of section 3 is applicable to these
     copies of the Document, then if the Document is less than one half
     of the entire aggregate, the Document’s Cover Texts may be placed
     on covers that bracket the Document within the aggregate, or the
     electronic equivalent of covers if the Document is in electronic
     form.  Otherwise they must appear on printed covers that bracket
     the whole aggregate.

  8. TRANSLATION

     Translation is considered a kind of modification, so you may
     distribute translations of the Document under the terms of section
     4.  Replacing Invariant Sections with translations requires special
     permission from their copyright holders, but you may include
     translations of some or all Invariant Sections in addition to the
     original versions of these Invariant Sections.  You may include a
     translation of this License, and all the license notices in the
     Document, and any Warranty Disclaimers, provided that you also
     include the original English version of this License and the
     original versions of those notices and disclaimers.  In case of a
     disagreement between the translation and the original version of
     this License or a notice or disclaimer, the original version will
     prevail.

     If a section in the Document is Entitled “Acknowledgements”,
     “Dedications”, or “History”, the requirement (section 4) to
     Preserve its Title (section 1) will typically require changing the
     actual title.

  9. TERMINATION

     You may not copy, modify, sublicense, or distribute the Document
     except as expressly provided under this License.  Any attempt
     otherwise to copy, modify, sublicense, or distribute it is void,
     and will automatically terminate your rights under this License.

     However, if you cease all violation of this License, then your
     license from a particular copyright holder is reinstated (a)
     provisionally, unless and until the copyright holder explicitly and
     finally terminates your license, and (b) permanently, if the
     copyright holder fails to notify you of the violation by some
     reasonable means prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
     reinstated permanently if the copyright holder notifies you of the
     violation by some reasonable means, this is the first time you have
     received notice of violation of this License (for any work) from
     that copyright holder, and you cure the violation prior to 30 days
     after your receipt of the notice.

     Termination of your rights under this section does not terminate
     the licenses of parties who have received copies or rights from you
     under this License.  If your rights have been terminated and not
     permanently reinstated, receipt of a copy of some or all of the
     same material does not give you any rights to use it.

  10. FUTURE REVISIONS OF THIS LICENSE

     The Free Software Foundation may publish new, revised versions of
     the GNU Free Documentation License from time to time.  Such new
     versions will be similar in spirit to the present version, but may
     differ in detail to address new problems or concerns.  See
     <https://www.gnu.org/licenses/>.

     Each version of the License is given a distinguishing version
     number.  If the Document specifies that a particular numbered
     version of this License “or any later version” applies to it, you
     have the option of following the terms and conditions either of
     that specified version or of any later version that has been
     published (not as a draft) by the Free Software Foundation.  If the
     Document does not specify a version number of this License, you may
     choose any version ever published (not as a draft) by the Free
     Software Foundation.  If the Document specifies that a proxy can
     decide which future versions of this License can be used, that
     proxy’s public statement of acceptance of a version permanently
     authorizes you to choose that version for the Document.

  11. RELICENSING

     “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any
     World Wide Web server that publishes copyrightable works and also
     provides prominent facilities for anybody to edit those works.  A
     public wiki that anybody can edit is an example of such a server.
     A “Massive Multiauthor Collaboration” (or “MMC”) contained in the
     site means any set of copyrightable works thus published on the MMC
     site.

     “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0
     license published by Creative Commons Corporation, a not-for-profit
     corporation with a principal place of business in San Francisco,
     California, as well as future copyleft versions of that license
     published by that same organization.

     “Incorporate” means to publish or republish a Document, in whole or
     in part, as part of another Document.

     An MMC is “eligible for relicensing” if it is licensed under this
     License, and if all works that were first published under this
     License somewhere other than this MMC, and subsequently
     incorporated in whole or in part into the MMC, (1) had no cover
     texts or invariant sections, and (2) were thus incorporated prior
     to November 1, 2008.

     The operator of an MMC Site may republish an MMC contained in the
     site under CC-BY-SA on the same site at any time before August 1,
     2009, provided the MMC is eligible for relicensing.

ADDENDUM: How to use this License for your documents
====================================================

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

       Copyright (C)  YEAR  YOUR NAME.
       Permission is granted to copy, distribute and/or modify this document
       under the terms of the GNU Free Documentation License, Version 1.3
       or any later version published by the Free Software Foundation;
       with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
       Texts.  A copy of the license is included in the section entitled ``GNU
       Free Documentation License''.

   If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the “with...Texts.” line with this:

         with the Invariant Sections being LIST THEIR TITLES, with
         the Front-Cover Texts being LIST, and with the Back-Cover Texts
         being LIST.

   If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.

   If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of free
software license, such as the GNU General Public License, to permit
their use in free software.