@copying
This manual documents EIEIO, an object framework for Emacs Lisp.
-Copyright @copyright{} 2007-2012 Free Software Foundation, Inc.
+Copyright @copyright{} 2007--2013 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
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. Buying copies from the FSF supports it in
-developing GNU and promoting software freedom.''
+modify this GNU manual.''
@end quotation
@end copying
@comment node-name, next, previous, up
@top EIEIO
-@eieio{} (``Enhanced Implementation of Emacs Interpreted Objects'') is
-a CLOS (Common Lisp Object System) compatibility layer for Emacs Lisp.
-It provides a framework for writing object-oriented applications in
-Emacs.
+@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.
@ifnottex
@insertcopying
* Making New Objects:: How to construct new objects.
* Accessing Slots:: How to access a slot.
* Writing Methods:: How to write a method.
-@c * Method Invocation:: How methods are invoked.
+* Method Invocation:: How methods are invoked.
* Predicates:: Class-p, Object-p, etc-p.
* Association Lists:: List of objects as association lists.
* Customizing:: Customizing objects.
* Base Classes:: Additional classes you can inherit from.
* Browsing:: Browsing your class lists.
* Class Values:: Displaying information about a class or object.
+* Documentation:: Automatically creating texinfo documentation.
* Default Superclass:: The root superclasses.
-* Signals:: When you make errors
+* Signals:: When you make errors.
* Naming Conventions:: Name your objects in an Emacs friendly way.
* CLOS compatibility:: What are the differences?
* Wish List:: Things about EIEIO that could be improved.
+* GNU Free Documentation License:: The license for this documentation.
* Function Index::
@end menu
@item
Help system extensions for classes and methods.
@item
-Automatic texinfo documentation generator.
-@item
Several base classes for interesting tasks.
@item
Simple test suite.
Customization support in a class (extension to CLOS)
@end enumerate
-Here are some CLOS features that @eieio{} presently lacks:
+Here are some important CLOS features that @eieio{} presently lacks:
@table @asis
-@item Complete @code{defclass} tag support
-All CLOS tags are currently supported, but the following are not
-currently implemented correctly:
-@table @code
-@item :metaclass
-There is only one base superclass for all @eieio{} classes, which is
-the @code{eieio-default-superclass}.
-@item :default-initargs
+@item Method dispatch
+EIEO does not support method dispatch for built-in types and multiple
+arguments types. In other words, method dispatch only looks at the
+first argument, and this one must be an @eieio{} type.
+
+@item Support for metaclasses
+There is just one default metaclass, @code{eieio-default-superclass},
+and you cannot define your own. The @code{:metaclass} tag in
+@code{defclass} is ignored. Also, functions like `class-of' and
+`find-class', which should return instances of the metaclass, behave
+differently in @eieio{} in that they return symbols or plain structures
+instead.
+
+@item EQL specialization
+EIEIO does not support it.
+
+@item @code{:around} method tag
+This CLOS method tag is non-functional.
+
+@item :default-initargs in @code{defclass}
Each slot has an @code{:initarg} tag, so this is not really necessary.
-@end table
@item Mock object initializers
Each class contains a mock object used for fast initialization of
values can potentially cause modifications in the mock object. @eieio{}
should use a deep copy but currently does not.
-@item @code{:around} method tag
-This CLOS method tag is non-functional.
-
@end table
@node Building Classes
@comment node-name, next, previous, up
@chapter Building Classes
+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 CLOS implementation and also
+differs from CLOS in several aspects, it follows the same basic
+concepts. Therefore, it is highly recommended to learn these 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
+(@xref{Introduction}, and @ref{CLOS compatibility}).
+
A @dfn{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.
the @var{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 @code{:type}
+or @code{:protection}.
@end defmac
@noindent
@end defvar
@menu
-* Inheritance:: How to specify parents classes
+* Inheritance:: How to specify parents classes.
* Slot Options:: How to specify features of a slot.
* Class Options:: How to specify features for this class.
@end menu
:initform +
@end example
will set the initial value as that symbol.
-A function that is a lambda expression, like this:
-@example
-:initform (lambda () some-variablename)
-@end example
-
-will be evaluated at instantiation time to the value of
-@code{some-variablename}.
-@c This feature was more annoying than useful. Use the
-@c `initialize-instance' function to do this.
-@c
-@c On the other hand, if you need code to be
-@c executed at instantiation time as the initform, code like this:
-@c @example
-@c :initform (lambda () (+ 1 some-global-var))
-@c @end example
-@c will be identified as a function call, and be executed in place.
-
-@cindex lambda-default
-
-
-Lastly, using the function @code{lambda-default} instead of
-@code{lambda} will let you specify a lambda expression to use as the
-value, without evaluation, thus:
-@example
-:initform (lambda-default () some-variablename)
-@end example
-@c @@TODO - This will be deleted after fair warning.
-will not be evaluated at instantiation time, and the value in this
-slot will instead be @code{(lambda () some-variablename)}.
After a class has been created with @code{defclass}, you can change
that default value with @code{oset-default}. @ref{Accessing Slots}.
@item :type
An unquoted type specifier used to validate data set into this slot.
-@xref{(cl)Type Predicates}.
+@xref{Type Predicates,,,cl,Common Lisp Extensions}.
Here are some examples:
@table @code
@item symbol
An object of your class type.
@item (or null symbol)
A symbol, or nil.
- @item function
- A function symbol, or a @code{lambda-default} expression.
-
@end table
@item :allocation
This is the default.
@item :depth-first
Search for methods in the class hierarchy in a depth first order.
+@item :c3
+Searches for methods in in a linearized way that most closely matches
+what CLOS does when a monotonic class structure is defined.
@end table
-@c @xref{Method Invocation}, for more on method invocation order.
+@xref{Method Invocation}, for more on method invocation order.
@item :metaclass
Unsupported CLOS option. Enables the use of a different base class other
@c TODO - Write some more about static methods here
-@c @node Method Invocation
-@c @chapter Method Invocation
+@node Method Invocation
+@chapter Method Invocation
+
+When classes are defined, you can specify the
+@code{:method-invocation-order}. This is a feature specific to EIEIO.
+
+This controls the order in which method resolution occurs for
+@code{:primary} methods in cases of multiple inheritance. The order
+affects which method is called first in a tree, and if
+@code{call-next-method} is used, it controls the order in which the
+stack of methods are run.
-@c TODO - writeme
+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:
+
+@table @code
+@item :breadth-first
+Search for methods in the class hierarchy in breadth first order.
+This is the default.
+@item :depth-first
+Search for methods in the class hierarchy in a depth first order.
+@item :c3
+Searches for methods in in a linearized way that most closely matches
+what CLOS does when CLOS 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: http://192.220.96.201/dylan/linearization-oopsla96.html
+@end table
@node Predicates
@comment node-name, next, previous, up
provided.
@end defmethod
-@defun eieio-persistent-read filename
-Read @var{filename} which contains an @code{eieio-persistent} object
-previously written with @code{eieio-persistent-save}.
+@defun eieio-persistent-read filename &optional class allow-subclass
+Read a persistent object from @var{filename}, and return it.
+Signal an error if the object in @var{FILENAME} is not a constructor
+for @var{CLASS}. Optional @var{allow-subclass} says that it is ok for
+@code{eieio-persistent-read} to load in subclasses of class instead of
+being pedantic.
@end defun
@node eieio-named
class symbol, or an object. The resulting buffer will display all slot
names.
-Additionally, all methods defined to have functionality on this class
-are displayed.
+Additionally, all methods defined to have functionality on this class is
+displayed.
+
+@node Documentation
+@comment node-name, next, previous, up
+@chapter Documentation
+
+It is possible to automatically create documentation for your classes in
+texinfo format by using the tools in the file @file{eieio-doc.el}
+
+@deffn Command eieiodoc-class class indexstring &optional skiplist
+
+This will start at the current point, and create an indented menu of
+all the child classes of, and including @var{class}, but skipping any
+classes that might be in @var{skiplist}. It will then create nodes for
+all these classes, subsection headings, and indexes.
+
+Each class will be indexed using the texinfo labeled index
+@var{indexstring} which is a two letter description.
+@xref{New Indices,,,texinfo,Texinfo manual}.
+
+To use this command, the texinfo macro
+
+@example
+@@defindex @@var @{ indexstring @}
+@end example
+
+@noindent
+where @var{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 @code{: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.
+
+This command can only display documentation for classes whose
+definitions have been loaded in this Emacs session.
+
+@end deffn
@node Default Superclass
@comment node-name, next, previous, up
with it, certain default methods or attributes can be added to all
objects. In CLOS, this would be named @code{STANDARD-CLASS}, and that
symbol is an alias to @code{eieio-default-superclass}.
-@refill
Currently, the default superclass is defined as follows:
@item :type
Specifier uses the @code{typep} function from the @file{cl}
-package. @xref{(cl)Type Predicates}. It therefore has the same issues as
-that package. Extensions include the ability to provide object names.
+package. @xref{Type Predicates,,,cl,Common Lisp Extensions}.
+It therefore has the same issues as that package. Extensions include
+the ability to provide object names.
@end table
Defclass also supports class options, but does not currently use values
@node Wish List
@chapter Wish List
-@eieio{} is an incomplete implementation of CLOS. Finding ways to
+@eieio{} is an incomplete implementation of CLOS@. Finding ways to
improve the compatibility would help make CLOS style programs run
better in Emacs.
@enumerate
@item
+Support for metaclasses and EQL specialization.
+@item
@code{:around} method key.
-
@item
Method dispatch for built-in types.
@item
Allow method overloading of method-like functions in Emacs.
@end enumerate
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
@node Function Index
@unnumbered Function Index