@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
@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 specificiation 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
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
@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{}.
HCoop / bpt / emacs.git / blobdiff