@set AUTHOR Eric M. Ludlam
@settitle @value{TITLE}
@documentencoding UTF-8
-@documentlanguage en
@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
@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 (@xref{Introduction}, and @ref{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.
@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
@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.
@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
+@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
@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
@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{}.