EIEIO is a framework for writing object oriented applications in emacs
lisp, and is a result of my taking various object oriented classes at
work and my attempt to understand some of it better by implementing it.
The real reason I started eieio is because someone in one of my classes
said "I bet emacs can't do that!".  Well then, I just had to prove them
wrong!

1 Introduction
**************

EIEIO is a CLOS (Common Lisp Object System) compatibility layer.  Due to
restrictions in the Emacs Lisp language, CLOS cannot be completely
supported, and a few functions have been added in place of setf.

1.1 What EIEIO supports
=======================

  1. A structured framework for the creation of basic classes with
     attributes and methods using singular 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 extentions for classes and methods.
  9. Automatic texinfo documentation generator.
  10. Several base classes for interesting tasks.
  11. Simple test suite.
  12. Public and private classifications for slots (extensions to CLOS)
  13. Customization support in a class (extension to CLOS)

1.2 Issues using EIEIO
======================

Complete 'defclass' tag support
     All CLOS tags are currently supported, but some are not currently
     implemented correctly.
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.
:AROUND method tag
     This CLOS method tag is non-functional.

1.3 EIEIO example programs that are almost useful.
==================================================

linemark
     Manage line highlighting, where individual lines are given a
     background color, or some other graphic feature.  Lines can be
     highlighted in files not currently loaded in Emacs.  When they are
     read in, the lines are given the graphic properties.

     Includes an MS Visual Studio like bookmark facility.
lmcompile
     Using linemark, highlight all lines where the latest compilation
     has valid hits.
tree
     Draw a structured tree by building a series of embedded lists of
     'tree-node' class objects.  Includes the functions
     'eieio-class-tree' to browse your current eieio inheritance
     structure
call-tree
     Pass it an Emacs Lisp function (not byte compiled) to generate a
     call tree using the tree tool
chart
     Uses eieio to manage charts/axis/sequences, and allows display of
     simple bar-charts.  Example programs are available displaying emacs
     memory usage and list occupation, in addition to file counts and
     size charts.  There's even a sample that will display a chart of
     who sends you the most email!  See doc-string for
     'chart-bar-quickie' to make your own bar charts easily.
eieio-speedbar
     Classes for implementing a speedbar display.  If you write a
     program that uses a system of objects, and your classes inherit
     from those in 'eieio-speedbar', then you can write a speedbar
     display for your objects in very little time.
     eieio-speedbar

1.4 EIEIO wish list
===================

  1. More CLOS compatibility.
  2. Integrate the desired built-in methods into the object browser.
  3. Create some objects over pre-existing emacs-lisp stuff for fun,
     like faces, processes, buffers, frames and windows as examples.

2 CLOS compatibility
********************

As you read this, it is important to know that I have just recently
learned some of the CLOS syntax, but have never used it myself outside
of the EIEIO framework.  I'm primarily and Emacs Lisp hacker who wrote
EIEIO to help myself learn some of the mechanics of Object Oriented
programming.

   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 throw 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.
'defgeneric'
     Creates the desired symbol, and accepts all of the expected
     arguments except ':AROUND'.
'defmethod'
     Calls defgeneric, and accepts most of the expected arguments.  Only
     the first argument to the created method may be type cast, though
     any argument can be syntactically type cast.  (And promptly
     ignored) To type cast against a class, the class must exist before
     defmethod is called.  In addition, the ':AROUND' tag is not
     supported.
'call-next-method'
     Inside a method, calls the next available method up the inheritance
     tree for the given object.  This is different than that found in
     CLOS because in EIEIO this function accepts replacement arguments.
     This permits subclasses to modify arguments as they are passed up
     the tree.  If no arguments are given, the expected CLOS behavior is
     used.
'setf'
     If the common-lisp subsystem is loaded, the setf parameters are
     also loaded so the form '(setf (slot-value object slot) t)' should
     work.

   CLOS supports the 'describe' command, but eieio only provides
'eieio-describe-class', and 'eieio-describe-generic'.  These functions
are adviced into 'describe-variable', and 'describe-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.

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

A class in EIEIO has a similar structure to that found in other
languages.  A new class is created with 'defclass'

 -- Function: defclass class-name superclass-list slot-list
          options-or-doc

     This function is specified by CLOS, and EIEIO conforms in
     structure.

     Creates a new class called 'class-name'.  The created variable's
     documentation string is set to a modified version of the doc string
     found in OPTIONS-OR-DOC.  Each time a slot is defined the variables
     documentation string is updated to include the methods
     documentation as well.

     The parent class for 'class-name' is SUPERCLASS-LIST which must be
     a list.  Each element of this list must be a class.  These classes
     form the parents of the class being created.  Every slot in parent
     is replicated in the new class.  If two parents share the same slot
     name, the parent which appears in the list first sets the
     attributes for that slot.  If a slot in the new class' slot list
     matches a parent, then the new specifications for the child class
     override that of the parent.

     SLOT-LIST is a list of lists.  Each sublist defines an attribute.
     These lists are of the form '(name :tag1 value1 :tag2 value2 :tagn
     valuen)'.  Some valid CLOS tags are:

     ':initarg'
          The argument used during initialization.  See Making New Objects.
          A good symbol to use for initarg is one that
          starts with a colon ':'.
     ':initform'
          A lisp expression used to generate the default value for this
          slot.  If :initform is left out, that slot defaults to being
          unbound.  The value passed to initform is automatically
          quoted.  Thus,
               :initform (1 2 3)
          appears as the specified list in the default object.  A
          function like this:
               :initform +
          is quoted in as a symbol.

          Lastly, using the function 'lambda-default' instead of
          'lambda' will let you specify a lambda expression to use as
          the value, without evaluation.
     ':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.
          'function'
               A function symbol, or a 'lambda-default' expression.
     ':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.

     Some tags whose behaviors do not yet match CLOS are:

     ':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.
     ':writer'
          Name of a generic function which will write this slot.
     ':reader'
          Name of a generic function which will read this slot.

     Some tags which are unique to EIEIO are:

     ':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 field of a 'defcustom'
          call.
     ':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.
     ':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.
     ':protection'
          A CLOS unsupported specifier which indicates that only methods
          of this class may access this slot.

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

          Valid values are:

          ':public'
               Anyone may access this slot from any scope.
          ':protected'
               Only methods of the same class, or of a child class may
               access this slot.
          ':private'
               Only methods of the same class as this slot's definition
               may access this slot.

     Additionally, CLOS style class options are available.  These are
     various options attached to a class.  These options can occur in
     place or in addition to a documentation string.  If both occur,
     then the options appear before the documentation string.  In CLOS,
     documentation is one of the options available to a class, so the
     ability to have a standalone documentation string is specific to
     Emacs.

     Possible class options are:
     ':documentation'
          Doc string to use for this class.  If an Emacs style
          documentation string is also provided, then this option is
          ignored.
     ':allow-nil-initform'
          This is not a CLOS option.

          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.
     ':abstract'
          This is not a CLOS option.

          Tags a class as being abstract, or uninstantiable.
     ':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.
     ':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.

     The whole definition may look like this:
          (defclass data-object ()
            ((value :initarg :value
          	  :initform nil
          	  :accessor get-value
          	  :documentation
                    "Lisp object which represents the data this object maintains."
          	  :protection :protected)
             (reference :initarg :reference
          	      :initform nil
                        :type list
                        :custom (repeat object)
          	      :documentation
                        "List of objects looking at this object.
          The method `update-symbol' is called for each member of `reference' whenever
          `value' is modified."
          	      :protection :protected)
             )
            "Data object which tracks referencers.")

 -- Variable: eieio-error-unsupported-class-tags
     If Non-nil, then 'defclass' will throw an error if a tag in a slot
     specifier is unsupported.

4 Default Superclass
********************

All defined classes, if created as a superclass (With no specified
parent class) will actually inherit from a special superclass stored in
'eieio-default-superclass'.  This superclass is actually quite simple,
but with it, certain default methods or attributes can be added to all
objects at any time, without updating their code in the future (If there
is a change).  In CLOS, this would be named 'STANDARD-CLASS' and is
aliased.

   Currently, the default superclass is defined as follows:

     (defclass eieio-default-superclass nil
       nil
       )
      "Default class used as parent class for superclasses.  It's
     slots are automatically adopted by such superclasses but not stored
     in the `parent' slot.  When searching for attributes or methods, when
     the last parent is found, the search will recurse to this class.")

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

 -- 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.

   These methods are used to override errors:

 -- Function: slot-missing object slot operation &optional new-value
     This method is called when there is an attempt to access a slot
     that does not exist for a given object.  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
     This method is called when there is an attempt to access a slot
     that is not bound.  This will throw an 'unbound-slot' signal.  If
     overridden it's return value will be returned from the function
     attempting to reference its value.

 -- Function: no-applicable-method object method
     This method is called when there is an attempt to call a method on
     OBJECT when there is no method to call.  The default method throws
     a 'no-method-definition' signal.  The return value of this function
     becomes the return value of the non-existent method.

 -- Function: no-next-method object args
     This method is called when an attempt to call 'call-next-method' is
     made, and there is no next method that can be called.  The return
     value becomes the return value of 'call-next-method'.

   Additional useful methods are:

 -- Function: clone obj &rest params
     Make a deep copy of OBJ.  Once this copy is made, make
     modifications specified by PARAMS.  PARAMS uses the same format as
     the SLOTS of 'initialize-instance'.  The only other change is to
     modify the name with an incrementing numeric.

 -- Function: object-print obj &rest strings
     Construct a printing lisp symbol for OBJ.  This would look like:
           #<class-name "objname">
     STRINGS are additional parameters passed in by overloading
     functions to add more data into the printing abbreviation.

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

          (defmethod object-print ((this data-object) &optional strings)
            "Return a string with a summary of the data object as part of the name."
            (apply 'call-next-method this
          	 (cons (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.

5 Making New Objects
********************

Once we have defined our classes, it's time to create objects with the
specified structure.  After we call 'defclass' two new functions are
created, one of which is 'classname'.  Thus, from the example at the end
of the previous chapter Building Classes, we would have the
functions 'data-object' and 'data-object-p'.

 -- Function: classname 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 it's
     default value, and any side effects from an attributes default
     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, see Building Classes:

          (data-object "test" :value 3 :reference nil)

6 Accessing Slots
*****************

There are several ways to access slot values in an object.  The naming
convention and argument order is similar to that found in Emacs Lisp for
referencing vectors.  The basics for referencing, setting, and calling
methods are all accounted for.

 -- Function: oset object slot value

     This sets the value behind SLOT to VALUE in OBJECT.  'oset' returns
     VALUE.

 -- Function: oset-default class slot value

     This sets the slot SLOT in CLASS which is initialized with the
     ':initform' tag to VALUE.  This will allow a user to set both
     public and private defaults after the class has been constructed.
     This function is intrusive, and is offered as a way to allow users
     to configure the default behavior of packages built with classes
     the same way 'setq-default' is used for buffer-local variables.

     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: oref object slot

     This recalls the value in slot SLOT in OBJECT and returns it.  If
     OBJECT is a class, and SLOT is a class allocated slot, then oref
     will return that value.  If OBJECT is a class, and SLOT is not
     class allocated, a signal will be thrown.

 -- Function: oref-default object slot
     This gets the default value in OBJECT's class definition for
     'slot'.  This can be different from the value returned by 'oref'.
     OBJECT can also be a class symbol or an instantiated object.

   These next 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.  Unlike
     'oref', the symbol for SLOT must be quoted in.

 -- Function: set-slot-value object slot value
     This is not a CLOS function, but is meant to mirror 'slot-value' if
     you don't want to use the cl package's 'setf' function.  This
     function sets the value of SLOT from OBJECT.  Unlike 'oset', the
     symbol for SLOT must be quoted in.

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

 -- Function: object-add-to-list object slot &optional append
     In OBJECT's SLOT, add ITEM to the pre-existing 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: with-slots entries object forms
     Bind ENTRIES lexically to the specified slot values in OBJECT, and
     execute FORMS.  In CLOS, it would be possible to set values in
     OBJECT by using 'setf' to assign to these values, but in Emacs, you
     may only read the values, or set the local variable to a new value.

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

7 Writing Methods
*****************

Writing a CLOS style method is similar to writing a function.  The
differences are that there are some extra options and there can be
multiple implementations of a single method which interact interestingly
with each other.

   Each method created verifies that there is a "generic method"
available to attach to.  A generic method has no body, and is merely a
symbol upon which methods are attached.

 -- Function: defgeneric method arglist [doc-string]

     METHOD is the unquoted symbol to turn 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 place holder for methods.  There is no
     need to call 'defgeneric' yourself, as 'defmethod' will call it if
     necessary.  Currently the argument list is unused.

     'defgeneric' will prevent you from turning an existing emacs lisp
     function into a generic function.

 -- Function: defmethod method [:BEFORE | :PRIMARY | :AFTER | :STATIC ]
          arglist [doc-string] forms

     METHOD is the name of the function to be created.

     :BEFORE | :AFTER represent when this form is to be called.  If
     neither of these symbols are present, then the default priority is,
     before :AFTER, after :BEFORE, and is represented in CLOS as
     PRIMARY.

     If :STATIC is used, then the first argument when calling this
     function can be a class or an object.  Never treat the first
     argument of a STATIC method as an object, always used
     'oref-default' or 'oset-default'.  A Class' construction is defined
     as a static method.

     'arglist' is the argument list.  Unlike CLOS, only the FIRST
     argument may be type-cast, and it may only be type-cast to an EIEIO
     object.  An arglist such as '(a b)' would classify the function as
     generic call, which has no object it can talk to (none is passed
     in) and merely allows the creation of side-effects.  If the arglist
     appears as '((this data-object) b)' then the form is stored as
     belonging to the class 'data-object'.

     The first argument does not need to be typecast.  A method with no
     typecast is a 'generic'.  If a given class has no implementation,
     then the generic will be called when that method is used on a given
     object of that class.

     If two 'defmethod's appear with arglists such as '(a b)' and '(c
     d)' then one of the implementations will be overwritten, but
     generic and multiple type cast arglists can co-exist.

     When called, if there is a method cast against the object's parent
     class, but not for that object's class, the parent class' method
     will be called.  If there is a method defined for both, only the
     child's method is called.

     DOC-STRING is the documentation attached to the implementation.
     All method doc-strings are concatenated into the generic method's
     function documentation.

     FORMS is the body of the function.

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

     method :BEFORE
     generic :BEFORE
     method :PRIMARY
     generic :PRIMARY
     method :AFTER
     generic :AFTER

   If in any situation a method does not exist, but a generic does, then
the generic is called in place of the method.

   If no methods exist, then the signal 'no-method-definition' is
thrown.  See Signals

   See the file 'eieio-test.el' for an example testing these differently
tagged methods.

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

     While running inside a CLOS method, calling this function will call
     the method associated with the parent of the class of the currently
     running method with the same parameters.

     If no next method is available, but a generic is implemented for
     the given key (Such as ':BEFORE'), then the generic will be called.

     OPTIONAL arguments REPLACEMENT-ARGS can be used to replace the
     arguments the next method would be called with.  Useful if a child
     class wishes to add additional behaviors through the modification
     of the parameters.  This is not a feature of CLOS.

     For example code Default Superclass.

 -- Function: call-next-method-p

     Return t if there is a next method we can call.

   In this implementation, not all features of CLOS exist.

  1. There is currently no :AROUND tag.
  2. CLOS allows multiple sets of type-cast arguments, where eieio only
     allows the first argument to be cast.

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: class-v class
     Return a vector with all the class's important parts in it.  This
     vector is not a copy.  Changing this vector changes the class.  The
     CLOS method 'find-class' will have the same effect.

 -- Function: find-class symbol &optional errorp
     CLOS function.  In EIEIO it returns the vector definition of the
     class.  If there is no class, 'nil' is returned if ERRORP is 'nil'.

 -- Function: class-p class
     Return non-'nil' if CLASS is a class type.

 -- Function: object-p obj
     Return non-'nil' if OBJ is an object.

 -- Function: slot-exists-p obj-or-class slot
     Return Non-'nil' if OBJ-OR-CLASS contains SLOT in its class.

 -- 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: class-name class
     Return a string of the form #<class myclassname> which should look
     similar to other lisp objects like buffers and processes.  Printing
     a class results only in 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: class-constructor class
     Return a symbol used as a constructor for CLASS.  This way you can
     make an object of a passed in class without knowing what it is.
     This is not a part of CLOS.

 -- Function: 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 vector.  It is more useful to use 'object-print' to
     get and object's print form, as this allows the object to add extra
     display information into the symbol.

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

 -- Function: class-of obj
     CLOS symbol which does the same thing as 'object-class'

 -- Function: object-class-fast obj
     Same as 'object-class' except this is a macro, and no type-checking
     is performed.

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

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

 -- Function: class-parents-fast class
     Just like 'class-parent' except it is a macro and no type checking
     is performed.

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

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

 -- Function: class-children-fast class
     Just like 'class-children', but with no checks.

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

 -- Function: same-class-fast-p obj class
     Same as 'same-class-p' except this is a macro and no type checking
     is performed.

 -- 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 list function.

   It is also important to note, that for every created class, a two
predicates are created for it.  Thus in our example, the function
'data-object-p' is created, and return 't' if passed an object of the
appropriate type.  Also, the function 'data-object-child-p' is created
which returns 't' if the object passed to it is of a type which inherits
from 'data-object'.

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

Lisp offers the concept of association lists, with primitives such as
'assoc' used to access them.  Eieio provides a few such functions to
help with using lists of objects easily.

 -- Function: object-assoc key slot list
     Returns the first object in LIST for which KEY is in SLOT.

 -- 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 to choose from should
     it prove necessary.

10 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 vectors, and thus everything is technically visible,
some functions have been provided.  None of these functions are a part
of CLOS.

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

 -- Function: class-slot-initarg class slot
     For the given CLASS return the :initarg associated with SLOT.  Not
     all slots have initargs, so the return value can be nil.

11 Signals
**********

There are new signal types 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: no-method-definition method arguments
     This signal is called when METHOD is called, with ARGUMENTS and
     nothing is resolved.  This occurs when METHOD has been defined, but
     the arguments make it impossible for eieio to determine which
     method body to run.

     Overload the method 'no-method-definition' to protect against this
     signal.

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

     Overload the method '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 VAR
     doesn't match the specified type SPEC.

     In EIEIO, this is also used of 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.

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

Asside from 'eieio-default-superclass', EIEIO comes with some additional
classes that you can use.  By using multiple inheritance, it is possible
to use several features at the same time.

12.1 'eieio-instance-inheritor'
===============================

This class is in 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 throw an
'slot-unbound' signal.

This class is in 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 tracker-symbol
     Enable instance tracking for this class.  The field TRACKER-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 fields
     This method is defined as an ':AFTER' method.  It adds new
     instances to the master list.  Do not overload this method unless
     you use 'call-next-method.'

 -- 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 field list-symbol
     This convenience function lets you find instances.  KEY is the
     value to search for.  FIELD is the field to compare KEY against.
     The function 'equal' is used for comparison.  The paramter
     LIST-SYMBOL is the variable symbol which contains the list of
     objects to be searched.

12.2 'eieio-singleton'
======================

This class is in 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.3 'eieio-persistent'
=======================

This class is in 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
     Read FILENAME which contains an 'eieio-persistent' object
     previously written with 'eieio-persistent-save'.

12.4 'eieio-named'
==================

This class is in 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.5 '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 indice 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
***********************

To browse all the currently loaded classes in emacs, simply run the
EIEIO browser.  'M-x eieio-browse'.  This browses all the way from the
default super-duper class eieio-default-superclass, and lists all
children in an indented tree structure.

   To browse only from a specific class, pass it in as an alternate
parameter.

   Here is a sample tree from our current example:

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

   Note that we start with eieio-default-superclass.  See Default Superclass.

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

   It is also possible to use the function 'eieio-class-tree' in the
'tree.el' package.  This will create an interactive tree.  Clicking on
nodes will allow expansion/contraction of branches, or editing of a
class.  See Class Values.

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

Details about any class or object can be retrieved using the function
'eieio-describe-class' function.  Interactively, type in the name of a
class.  In a program, pass it a string with the name of a class, a class
symbol, or an object.  The resulting buffer will display all slot names.

   Additionally, all methods defined to have functionality on this class
is displayed.

15 Customizing Objects
**********************

In Emacs 20 a useful customization utility became available called
'custom'.  EIEIO supports custom 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 objects modified 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's sole code is '(widget-create 'object-edit :value
     object)' and 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.

15.1 Widget extention
=====================

When widgets are being created, one new widget extention 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.

16 Documentation
****************

It is possible to automatically create documentation for your classes in
texinfo format by using the tools in the file 'eieio-doc.el'

 -- Command: eieiodoc-class class indexstring &optional skiplist

     This will start at the current point, and created an indented menu
     of all the child classes of, and including CLASS, but skipping any
     classes that might be in SKIPLIST It will then create nodes for all
     these classes, subsection headings, and indexes.

     Each class will be indexed using the texinfo labeled index
     INDEXSTRING which is a two letter description.  See New Indices (texinfo).

     To use this command, the texinfo macro

          @defindex @var { indexstring }

     where INDEXSTRING is replaced with the two letter code.

     Next, an inheritance tree will be created listing all parents of
     that section's class.

     Then,all the slots will be expanded in tables, and described using
     the documentation strings from the code.  Default values will also
     be displayed.  Only those slots with ':initarg' specified will be
     expanded, others will be hidden.  If a slot is inherited from a
     parent, that slot will also be skipped unless the default value is
     different.  If there is a change, then the documentation part of
     the slot will be replace with an @xref back to the parent.

     Only classes loaded into emacs' memory can be documented.

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

The Emacs Lisp programming manual has a great chapter programming
conventions that help keep each Emacs package working nicely with the
entire system.  Standards (elisp) An EIEIO based program needs to
follow these conventions, while simultaneously taking advantage of the
Object Oriented features.

   The below tips are things that I do when I program an EIEIO based
package.

   * 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 Demo Programs
****************

There are many sample programs I have written for eieio which could
become useful components of other applications, or are good stand alone
programs providing some useful functionality.  The file, and
functionality of these appear below:

'tree'
     Maintains and displays a tree structure in a buffer.  Nodes in the
     tree can be clicked on for editing, node expansion, and simple
     information.  Includes a sample program for showing directory
     trees, and to draw trees of the eieio class structures.
'call-tree'
     Parses a non-byte-compiled function, and generates a call tree from
     it, and all sub-non-byte-compiled functions.  Provides protection
     from recursive functions.
'chart'
     Draw bar charts from data.  Examples include displaying sizes of
     emacs values, file distribution, and rmail distributions.