X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/f619ad4ca2ce943d53589469c010e451afab97dd..24a6b65e905fe25355fd65a1cf1fff501ba28352:/doc/misc/eieio.texi diff --git a/doc/misc/eieio.texi b/doc/misc/eieio.texi index 8ee40288fe..5b9f3a8e00 100644 --- a/doc/misc/eieio.texi +++ b/doc/misc/eieio.texi @@ -11,7 +11,7 @@ @copying This manual documents EIEIO, an object framework for Emacs Lisp. -Copyright @copyright{} 2007-2011 Free Software Foundation, Inc. +Copyright @copyright{} 2007--2013 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -22,8 +22,7 @@ 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.'' (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 @@ -47,10 +46,10 @@ developing GNU and promoting software freedom.'' @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 @@ -63,7 +62,7 @@ Emacs. * 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. @@ -71,11 +70,13 @@ Emacs. * 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 @@ -200,8 +201,6 @@ Byte compilation support of methods. @item Help system extensions for classes and methods. @item -Automatic texinfo documentation generator. -@item Several base classes for interesting tasks. @item Simple test suite. @@ -211,20 +210,31 @@ Public and private classifications for slots (extensions to CLOS) 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 @@ -232,15 +242,23 @@ instantiated objects. Using functions with side effects on object slot 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. @@ -269,6 +287,10 @@ If two parents share the same slot name, the parent which appears in 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 @@ -294,7 +316,7 @@ This option is here to support programs written with older versions of @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 @@ -435,42 +457,13 @@ A symbol that is a function like this: :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 @@ -481,9 +474,6 @@ Here are some examples: 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 @@ -621,9 +611,12 @@ 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 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 @@ -1008,10 +1001,39 @@ method. @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 @@ -1212,9 +1234,9 @@ This method does nothing by default, but that may change in the future. 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. @@ -1399,9 +1421,12 @@ a header line comment from the class allocated slot if one is not 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 @@ -1458,7 +1483,7 @@ Useful methods to define for your new class include: @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 @@ -1544,8 +1569,51 @@ 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. +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 @@ -1557,7 +1625,6 @@ inherit from a special class stored in 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: @@ -1823,8 +1890,9 @@ instead pre-builds a method that gets the slot's value. @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 @@ -1870,7 +1938,7 @@ In @eieio{} tags are in lower case, not mixed case. @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. @@ -1878,8 +1946,9 @@ Some important compatibility features that would be good to add are: @enumerate @item +Support for metaclasses and EQL specialization. +@item @code{:around} method key. - @item Method dispatch for built-in types. @item @@ -1893,12 +1962,16 @@ better in the Emacs environment. @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