@set TITLE Enhanced Implementation of Emacs Interpreted Objects
@set AUTHOR Eric M. Ludlam
@settitle @value{TITLE}
+@documentencoding UTF-8
@c *************************************************************************
@c @ Header
@copying
This manual documents EIEIO, an object framework for Emacs Lisp.
-Copyright @copyright{} 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc.
+Copyright @copyright{} 2007--2014 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
@dircategory Emacs misc features
@direntry
-* EIEIO: (eieio). Objects for Emacs.
+* EIEIO: (eieio). An objects system for Emacs Lisp.
@end direntry
@titlepage
@center @titlefont{@value{TITLE}}
@sp 4
@center by @value{AUTHOR}
-@end titlepage
@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
@macro eieio{}
@i{EIEIO}
@end macro
-@node Top, Quick Start, (dir), (dir)
-@comment node-name, next, previous, up
+@node Top
@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.
* Browsing:: Browsing your class lists.
* Class Values:: Displaying information about a class or object.
* 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
error. @ref{Signals}.
@node Introduction
-@comment node-name, next, previous, up
@chapter Introduction
-Due to restrictions in the Emacs Lisp language, CLOS cannot be
-completely supported, and a few functions have been added in place of
-setf.
+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 (@xref{Introduction}, and @ref{CLOS
+compatibility}).
@eieio{} supports the following features:
@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:
+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:
@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 `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
A @dfn{class} is a definition for organizing data and methods
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
@eieio{}-specific tags.
@node Making New Objects
-@comment node-name, next, previous, up
@chapter Making New Objects
Suppose we have a simple class is defined, such as:
@end defun
@node Accessing Slots
-@comment node-name, next, previous, up
@chapter Accessing Slots
There are several ways to access slot values in an object. The naming
@end defun
@node Writing Methods
-@comment node-name, next, previous, up
@chapter Writing Methods
Writing a method in @eieio{} is similar to writing a function. The
@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.
+
+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.
-@c TODO - writeme
+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
@chapter Predicates and Utilities
Now that we know how to create classes, access slots, and define
@var{object} can be an instance or a class.
@end defun
-@defun class-name class
+@defun eieio-class-name class
Return a string of the form @samp{#<class myclassname>} which should look
similar to other Lisp objects like buffers and processes. Printing a
class results only in a symbol.
without knowing what it is. This is not a part of CLOS.
@end defun
-@defun object-name obj
+@defun eieio-object-name obj
Return a string of the form @samp{#<object-class myobjname>} for @var{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
information into the symbol.
@end defun
-@defun object-class obj
+@defun eieio-object-class obj
Returns the class symbol from @var{obj}.
@end defun
-@defun class-of obj
-CLOS symbol which does the same thing as @code{object-class}
-@end defun
-
-@defun object-class-fast obj
-Same as @code{object-class} except this is a macro, and no
+@defun eieio--object-class obj
+Same as @code{eieio-object-class} except this is a macro, and no
type-checking is performed.
@end defun
-@defun object-class-name obj
+@defun eieio-object-class-name obj
Returns the symbol of @var{obj}'s class.
@end defun
-@defun class-parents class
+@defun eieio-class-parents class
Returns the direct parents class of @var{class}. Returns @code{nil} if
it is a superclass.
@end defun
-@defun class-parents-fast class
-Just like @code{class-parent} except it is a macro and no type checking
+@defun eieio-class-parents-fast class
+Just like @code{eieio-class-parents} except it is a macro and no type checking
is performed.
@end defun
-@defun class-parent class
+@defun eieio-class-parent class
Deprecated function which returns the first parent of @var{class}.
@end defun
-@defun class-children class
+@defun eieio-class-children class
Return the list of classes inheriting from @var{class}.
@end defun
-@defun class-children-fast class
-Just like @code{class-children}, but with no checks.
+@defun eieio-class-children-fast class
+Just like @code{eieio-class-children}, but with no checks.
@end defun
@defun same-class-p obj class
@end defun
@node Customizing
-@comment node-name, next, previous, up
@chapter Customizing Objects
@eieio{} supports the Custom facility through two new widget types.
This would be the best way to make your objects persistent when using
in-place editing.
-@section Widget extention
+@section Widget extension
-When widgets are being created, one new widget extention has been added,
+When widgets are being created, one new widget extension has been added,
called the @code{: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.
@end defun
@node Base Classes
-@comment node-name, next, previous, up
@chapter Base Classes
All defined classes, if created with no specified parent class,
@end menu
@node eieio-instance-inheritor
-@comment node-name, next, previous, up
@section @code{eieio-instance-inheritor}
This class is defined in the package @file{eieio-base}.
@end deffn
@node eieio-singleton
-@comment node-name, next, previous, up
@section @code{eieio-singleton}
This class is defined in the package @file{eieio-base}.
@end deftp
@node eieio-persistent
-@comment node-name, next, previous, up
@section @code{eieio-persistent}
This class is defined in the package @file{eieio-base}.
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
-@comment node-name, next, previous, up
@section @code{eieio-named}
This class is defined in the package @file{eieio-base}.
@end deftp
@node eieio-speedbar
-@comment node-name, next, previous, up
@section @code{eieio-speedbar}
This class is in package @file{eieio-speedbar}.
@defmethod eieio-speedbar eieio-speedbar-derive-line-path obj depth
Return a string representing a directory associated with an instance
-of @var{obj}. @var{depth} can be used to indice how many levels of
+of @var{obj}. @var{depth} can be used to index how many levels of
indentation have been opened by the user where @var{obj} is shown.
@end defmethod
@end deffn
@node Browsing
-@comment node-name, next, previous, up
@chapter Browsing class trees
The command @kbd{M-x eieio-browse} displays a buffer listing all the
comes out upside-down.
@node Class Values
-@comment node-name, next, previous, up
@chapter Class Values
Details about any class or object can be retrieved using the function
-@code{eieio-describe-class}. 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
-are displayed.
+@code{eieio-describe-class}. 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.
+
+You can also use the normal @code{describe-function} to retrieve
+information about a class. If you call it on a constructor function,
+it will also display the class information. If you call it on a
+generic function, all implementations of that generic function will be
+listet, together with links through which you can directly jump to the
+source.
@node Default Superclass
-@comment node-name, next, previous, up
@chapter Default Superclass
All defined classes, if created with no specified parent class, will
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:
@defun object-print this &rest strings
@anchor{object-print}
-Pretty printer for object @var{this}. Call function @dfn{object-name} with @var{strings}.
+Pretty printer for object @var{this}. Call function @dfn{eieio-object-name} with @var{strings}.
The default method for printing object @var{this} is to use the
-function @dfn{object-name}.
+function @dfn{eieio-object-name}.
It is sometimes useful to put a summary of the object into the
default #<notation> string when using eieio browsing tools.
@end defun
@node Signals
-@comment node-name, next, previous, up
@chapter Signals
There are new condition names (signals) that can be caught when using
@end deffn
@node Naming Conventions
-@comment node-name, next, previous, up
@chapter Naming Conventions
@xref{Tips,,Tips and Conventions,elisp,GNU Emacs Lisp Reference
@end itemize
@node CLOS compatibility
-@comment node-name, next, previous, up
@chapter CLOS compatibility
Currently, the following functions should behave almost as expected from
@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
@end table
CLOS supports the @code{describe} command, but @eieio{} only provides
-@code{eieio-describe-class}, and @code{eieio-describe-generic}. These
-functions are adviced into @code{describe-variable}, and
-@code{describe-function}.
+@code{eieio-describe-class}, and @code{eieio-describe-generic}. Those
+are automatically called by @code{describe-function} when called on a
+constructor or generic function.
When creating a new class (@pxref{Building Classes}) there are several
new keywords supported by @eieio{}.
@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
@enumerate
@item
-Allow subclasing of Emacs built-in types, such as faces, markers, and
+Allow subclassing of Emacs built-in types, such as faces, markers, and
buffers.
@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
@contents
@bye
-
-@ignore
- arch-tag: 7225b7c7-2462-4563-99e7-836a20172178
-@end ignore
HCoop / bpt / emacs.git / blobdiff