@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--2013 Free Software Foundation, Inc.
+Copyright @copyright{} 2007--2014 Free Software Foundation, Inc.
@quotation
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,''
+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.''
@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'')
* 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.
* Naming Conventions:: Name your objects in an Emacs friendly way.
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 which are mentioned below (also
+@pxref{CLOS compatibility}).
@eieio{} supports the following features:
Customization support in a class (extension to CLOS)
@end enumerate
-Here are some important 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 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.
+@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.
@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.
@end defun
@defvar eieio-error-unsupported-class-tags
-If non-nil, @code{defclass} signals an error if a tag in a slot
+If non-@code{nil}, @code{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
@item my-class-name
An object of your class type.
@item (or null symbol)
- A symbol, or nil.
+ A symbol, or @code{nil}.
@end table
@item :allocation
of slots, and before the options.
@item :allow-nil-initform
-If this option is non-nil, and the @code{:initform} is @code{nil}, but
+If this option is non-@code{nil}, and the @code{:initform} is @code{nil}, but
the @code{:type} is specifies something such as @code{string} then allow
this to pass. The default is to have this option be off. This is
implemented as an alternative to unbound slots.
@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
+Searches for methods in a linearized way that most closely matches
what CLOS does when a monotonic class structure is defined.
@end table
@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:
Calling @code{defclass} has defined two new functions. One is the
constructor @var{record}, and the other is the predicate,
-@var{record-p}.
+@var{record}-p.
@defun record object-name &rest slots
@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
@defun set-slot-value object slot value
@anchor{set-slot-value}
-This is not a CLOS function, but is meant to mirror @code{slot-value} if
-you don't want to use the cl package's @code{setf} function. This
+This is not a CLOS function, but is the setter for @code{slot-value}
+used by the @code{setf} macro. This
function sets the value of @var{slot} from @var{object}. Unlike
@code{oset}, the symbol for @var{slot} must be quoted.
@end defun
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
+variable. Both @code{setf} and @code{setq} can be used to set the value of the
slot.
@var{spec-list} is of a form similar to @dfn{let}. For example:
@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
@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.
+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
@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.
@defun class-slot-initarg class slot
For the given @var{class} return the :initarg associated with
@var{slot}. Not all slots have initargs, so the return value can be
-nil.
+@code{nil}.
@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}.
@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}.
@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 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
+You can use the normal @code{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.
@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
the ability to provide object names.
@end table
-Defclass also supports class options, but does not currently use values
+defclass also supports class options, but does not currently use values
of @code{:metaclass}, and @code{:default-initargs}.
@item make-instance
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.
-@item setf
-If the common-lisp subsystem is loaded, the setf parameters are also
-loaded so the form @code{(setf (slot-value object slot) t)} should
-work.
@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}.
+CLOS supports the @code{describe} command, but @eieio{} provides
+support for using the standard @code{describe-function} command on a
+constructor or generic function.
When creating a new class (@pxref{Building Classes}) there are several
new keywords supported by @eieio{}.