1 \input texinfo @c -*-texinfo-*-
3 @c $Id: eieio.texi,v 1.4 2007-11-26 15:01:06 michaels Exp $
7 @c THIS MANUAL NEEDS WORK:
9 @c See the comments at the end of this document.
10 @c they need to be integrated into the text of this manual.
12 @setfilename eieio.info
13 @settitle Enhanced Implementation of Emacs Interpreted Objects
18 * eieio: (eieio). Objects for Emacs
25 @center @titlefont{eieio}
26 @vskip 0pt plus 1 fill
27 Copyright @copyright{} 1995,1996,1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Eric M. Ludlam
31 @node Top, , , (dir)Top
32 @comment node-name, next, previous, up
34 EIEIO is a framework for writing object oriented applications in emacs
35 lisp, and is a result of my taking various object oriented classes at
36 work and my attempt to understand some of it better by implementing it.
37 The real reason I started eieio is because someone in one of my classes
38 said "I bet emacs can't do that!". Well then, I just had to prove them
42 * Introduction:: Why use eieio? Basic overview, samples list.
43 * CLOS compatibility:: What are the differences?
44 * Building Classes:: How to write new class structures.
45 * Default Superclass:: The root superclasses.
46 * Making New Objects:: How to construct new objects.
47 * Accessing Slots:: How to access a slot.
48 * Writing Methods:: How to write a CLOS style method.
49 * Predicates:: Class-p, Object-p, etc-p.
50 * Association Lists:: List of objects as association lists.
51 * Introspection:: Looking inside a class.
52 * Signals:: When you make errors
53 * Base Classes:: Additional classes you can inherit from.
54 * Browsing:: Browsing your class lists.
55 * Class Values:: Displaying information about a class or object.
56 * Customizing:: Customizing objects.
57 * Documentation:: Automatically creating texinfo documentation
58 * Naming Conventions:: Name your objects in an Emacs friendly way.
59 * Demo Programs:: Some examples using eieio.
63 @node Introduction, CLOS compatibility, Top, Top
64 @comment node-name, next, previous, up
68 EIEIO is a CLOS (Common Lisp Object System) compatibility layer. Due
69 to restrictions in the Emacs Lisp language, CLOS cannot be completely
70 supported, and a few functions have been added in place of setf.
72 @section What EIEIO supports
76 A structured framework for the creation of basic classes with attributes
77 and methods using singular inheritance similar to CLOS.
79 Type checking, and slot unbinding.
81 Method definitions similar to CLOS.
83 Simple and complex class browsers.
85 Edebug support for methods.
89 Byte compilation support of methods.
91 Help system extentions for classes and methods.
93 Automatic texinfo documentation generator.
95 Several base classes for interesting tasks.
99 Public and private classifications for slots (extensions to CLOS)
101 Customization support in a class (extension to CLOS)
104 @section Issues using EIEIO
107 @item Complete @code{defclass} tag support
108 All CLOS tags are currently supported, but some are not currently
109 implemented correctly.
110 @item Mock object initializers
111 Each class contains a mock object used for fast initialization of
112 instantiated objects. Using functions with side effects on object slot
113 values can potentially cause modifications in the mock object. EIEIO
114 should use a deep copy but currently does not.
115 @item :AROUND method tag
116 This CLOS method tag is non-functional.
119 @section EIEIO example programs that are almost useful.
123 Manage line highlighting, where individual lines are given a
124 background color, or some other graphic feature. Lines can be
125 highlighted in files not currently loaded in Emacs. When they are
126 read in, the lines are given the graphic properties.
128 Includes an MS Visual Studio like bookmark facility.
130 Using linemark, highlight all lines where the latest compilation
133 Draw a structured tree by building a series of embedded lists of
134 `tree-node' class objects. Includes the functions `eieio-class-tree' to
135 browse your current eieio inheritance structure
137 Pass it an Emacs Lisp function (not byte compiled) to generate a call tree
140 Uses eieio to manage charts/axis/sequences, and allows display of simple
141 bar-charts. Example programs are available displaying emacs memory
142 usage and list occupation, in addition to file counts and size charts.
143 There's even a sample that will display a chart of who sends you the most
144 email! See doc-string for `chart-bar-quickie' to make your own bar
147 Classes for implementing a speedbar display. If you write a program
148 that uses a system of objects, and your classes inherit from those in
149 @file{eieio-speedbar}, then you can write a speedbar display for your
150 objects in very little time. @ref{eieio-speedbar}
153 @section EIEIO wish list
157 More CLOS compatibility.
159 Integrate the desired built-in methods into the object browser.
161 Create some objects over pre-existing emacs-lisp stuff for fun, like
162 faces, processes, buffers, frames and windows as examples.
165 @node CLOS compatibility, Building Classes, Introduction, Top
166 @comment node-name, next, previous, up
167 @chapter CLOS compatibility
169 As you read this, it is important to know that I have just recently
170 learned some of the CLOS syntax, but have never used it myself outside
171 of the EIEIO framework. I'm primarily and Emacs Lisp hacker who wrote
172 EIEIO to help myself learn some of the mechanics of Object Oriented
175 Currently, the following functions should behave almost as expected from
180 All slot keywords are available but not all work correctly.
181 Slot keyword differences are:
184 @item :reader, and :writer tags
185 Create methods that throw errors instead of creating an unqualified
186 method. You can still create new ones to do its business.
188 This should create an unqualified method to access a slot, but
189 instead pre-builds a method that gets the slot's value.
191 Specifier uses the @code{typep} function from the @file{cl}
192 package. @xref{(cl)Type Predicates}. It therefore has the same issues as
193 that package. Extensions include the ability to provide object names.
196 Defclass also supports class options, but does not currently use values
197 of @code{:metaclass}, and @code{:default-initargs}.
200 Make instance works as expected, however it just uses the EIEIO instance
201 creator automatically generated when a new class is created.
202 @xref{Making New Objects}.
204 Creates the desired symbol, and accepts all of the expected arguments
205 except @code{:AROUND}.
207 Calls defgeneric, and accepts most of the expected arguments. Only the
208 first argument to the created method may be type cast, though any
209 argument can be syntactically type cast. (And promptly ignored) To
210 type cast against a class, the class must exist before defmethod is
211 called. In addition, the @code{:AROUND} tag is not supported.
212 @item call-next-method
213 Inside a method, calls the next available method up the inheritance tree
214 for the given object. This is different than that found in CLOS because
215 in EIEIO this function accepts replacement arguments. This permits
216 subclasses to modify arguments as they are passed up the tree. If no
217 arguments are given, the expected CLOS behavior is used.
219 If the common-lisp subsystem is loaded, the setf parameters are also
220 loaded so the form @code{(setf (slot-value object slot) t)} should
224 CLOS supports the @code{describe} command, but eieio only provides
225 @code{eieio-describe-class}, and @code{eieio-describe-generic}. These
226 functions are adviced into @code{describe-variable}, and
227 @code{describe-function}.
229 When creating a new class (@pxref{Building Classes}) there are several
230 new keywords supported by EIEIO.
232 In EIEIO tags are in lower case, not mixed case.
234 @node Building Classes, Default Superclass, CLOS compatibility, Top
235 @comment node-name, next, previous, up
236 @chapter Building Classes
238 A class in EIEIO has a similar structure to that found in other
239 languages. A new class is created with @code{defclass}
241 @defun defclass class-name superclass-list slot-list options-or-doc
243 This function is specified by CLOS, and EIEIO conforms in structure.
245 Creates a new class called @code{class-name}. The created variable's
246 documentation string is set to a modified version of the doc string
247 found in @var{options-or-doc}. Each time a slot is defined the
248 variables documentation string is updated to include the methods
249 documentation as well.
251 The parent class for @code{class-name} is @var{superclass-list} which
252 must be a list. Each element of this list must be a class. These
253 classes form the parents of the class being created. Every slot in
254 parent is replicated in the new class. If two parents share the same
255 slot name, the parent which appears in the list first sets the attributes
256 for that slot. If a slot in the new class' slot list matches a parent,
257 then the new specifications for the child class override that of the
260 @var{slot-list} is a list of lists. Each sublist defines an attribute.
261 These lists are of the form @code{(name :tag1 value1 :tag2 value2 :tagn
262 valuen)}. Some valid CLOS tags are:
266 The argument used during initialization. @xref{Making New Objects}.
267 A good symbol to use for initarg is one that starts with a colon @code{:}.
269 A lisp expression used to generate the default value for this slot.
270 If :initform is left out, that slot defaults to being unbound.
271 The value passed to initform is automatically quoted. Thus,
275 appears as the specified list in the default object.
276 A function like this:
280 is quoted in as a symbol.
282 @c This feature was more annoying than useful. Use the
283 @c `initialize-instance' function to do this.
285 @c On the other hand, if you need code to be
286 @c executed at instantiation time as the initform, code like this:
288 @c :initform (lambda () (+ 1 some-global-var))
290 @c will be identified as a function call, and be executed in place.
292 @cindex lambda-default
293 Lastly, using the function @code{lambda-default} instead of
294 @code{lambda} will let you specify a lambda expression to use as the
295 value, without evaluation.
297 An unquoted type specifier used to validate data set into this slot.
298 @xref{(cl)Type Predicates}.
299 Here are some examples:
306 An object of your class type.
307 @item (or null symbol)
310 A function symbol, or a @code{lambda-default} expression.
313 Either :class or :instance (defaults to :instance) used to
314 specify how data is stored. Slots stored per instance have unique
315 values for each object. Slots stored per class have shared values for
316 each object. If one object changes a :class allocated slot, then all
317 objects for that class gain the new value.
319 Documentation detailing the use of this slot. This documentation is
320 exposed when the user describes a class, and during customization of an
324 Some tags whose behaviors do not yet match CLOS are:
328 Name of a generic function which can be used to fetch the value of this slot.
329 You can call this function later on your object and retrieve the value
332 Name of a generic function which will write this slot.
334 Name of a generic function which will read this slot.
337 Some tags which are unique to EIEIO are:
341 A custom :type specifier used when editing an object of this type.
342 See documentation for @code{defcustom} for details. This specifier is
343 equivalent to the :type field of a @code{defcustom} call.
345 When customizing an object, the value of :label will be used instead
346 of the slot name. This enables better descriptions of the data than
347 would usually be afforded.
349 Similar to @code{defcustom}'s :group command, this organizes different
350 slots in an object into groups. When customizing an object, only the
351 slots belonging to a specific group need be worked with, simplifying the
354 A CLOS unsupported specifier which indicates that only methods of this
355 class may access this slot.
357 When using a slot referencing function, if the value behind @var{slot}
358 is private or protected, then the current scope of operation must be
359 within a method of the calling object.
365 Anyone may access this slot from any scope.
367 Only methods of the same class, or of a child class may access this
370 Only methods of the same class as this slot's definition may access
376 Additionally, CLOS style class options are available. These are various
377 options attached to a class. These options can occur in place or in
378 addition to a documentation string. If both occur, then the options
379 appear before the documentation string. In CLOS, documentation is one
380 of the options available to a class, so the ability to have a standalone
381 documentation string is specific to Emacs.
383 Possible class options are:
386 Doc string to use for this class. If an Emacs style documentation
387 string is also provided, then this option is ignored.
388 @item :allow-nil-initform
389 This is not a CLOS option.
391 If this option is non-nil, and the @code{:initform} is @code{nil}, but
392 the @code{:type} is specifies something such as @code{string} then allow
393 this to pass. The default is to have this option be off. This is
394 implemented as an alternative to unbound slots.
396 This is not a CLOS option.
398 Tags a class as being abstract, or uninstantiable.
400 This is a list of groups that can be customized within this class. This
401 slot is auto-generated when a class is created and need not be
402 specified. It can be retrieved with the @code{class-option} command,
403 however, to see what groups are available.
405 Unsupported CLOS option. Enables the use of a different base class other
406 than @code{standard-class}.
407 @item :default-initargs
408 Unsupported CLOS option. Specifies a list of initargs to be used when
409 creating new objects. As far as I can tell, this duplicates the
410 function of @code{:initform}.
413 @xref{CLOS compatibility}, for more details on CLOS tags versus EIEIO
416 The whole definition may look like this:
418 (defclass data-object ()
419 ((value :initarg :value
423 "Lisp object which represents the data this object maintains."
424 :protection :protected)
425 (reference :initarg :reference
428 :custom (repeat object)
430 "List of objects looking at this object.
431 The method `update-symbol' is called for each member of `reference' whenever
432 `value' is modified."
433 :protection :protected)
435 "Data object which tracks referencers.")
440 @defvar eieio-error-unsupported-class-tags
441 If Non-nil, then @code{defclass} will throw an error if a tag
442 in a slot specifier is unsupported.
445 @node Default Superclass, Making New Objects, Building Classes, Top
446 @comment node-name, next, previous, up
447 @chapter Default Superclass
449 All defined classes, if created as a superclass (With no specified
450 parent class) will actually inherit from a special superclass stored in
451 @code{eieio-default-superclass}. This superclass is actually quite
452 simple, but with it, certain default methods or attributes can be added
453 to all objects at any time, without updating their code in the future
454 (If there is a change). In CLOS, this would be named
455 @code{STANDARD-CLASS} and is aliased.
457 Currently, the default superclass is defined as follows:
460 (defclass eieio-default-superclass nil
463 "Default class used as parent class for superclasses. It's
464 slots are automatically adopted by such superclasses but not stored
465 in the `parent' slot. When searching for attributes or methods, when
466 the last parent is found, the search will recurse to this class.")
469 When creating an object of any type, you can use it's constructor, or
470 @code{make-instance}. This, in turns calls the method
471 @code{initialize-instance}, which then calls the method
472 @code{shared-initialize}.
474 @defun initialize-instance obj &rest slots
475 Initialize @var{obj}. Sets slots of @var{obj} with @var{slots} which
476 is a list of name/value pairs. These are actually just passed to
477 @code{shared-initialize}.
480 @defun shared-initialize obj &rest slots
481 Sets slots of @var{obj} with @var{slots} which is a list of name/value
485 These methods are used to override errors:
487 @defun slot-missing object slot operation &optional new-value
488 This method is called when there is an attempt to access a slot that
489 does not exist for a given object. The default method signals an error
490 of type @code{invalid-slot-name}. @xref{Signals}.
492 You may override this behavior, but it is not expected to return in the
493 current implementation.
495 This function takes arguments in a different order than in CLOS.
498 @defun slot-unbound object class slot-name fn
499 This method is called when there is an attempt to access a slot that is
500 not bound. This will throw an @code{unbound-slot} signal. If
501 overridden it's return value will be returned from the function
502 attempting to reference its value.
505 @defun no-applicable-method object method
506 This method is called when there is an attempt to call a method on
507 @var{object} when there is no method to call. The default method throws
508 a @code{no-method-definition} signal. The return value of this function
509 becomes the return value of the non-existent method.
512 @defun no-next-method object args
513 This method is called when an attempt to call @code{call-next-method} is
514 made, and there is no next method that can be called. The return
515 value becomes the return value of @code{call-next-method}.
518 Additional useful methods are:
520 @defun clone obj &rest params
521 Make a deep copy of @var{obj}. Once this copy is made, make
522 modifications specified by @var{params}. @var{params} uses the same
523 format as the @var{slots} of @code{initialize-instance}. The only
524 other change is to modify the name with an incrementing numeric.
527 @defun object-print obj &rest strings
528 Construct a printing lisp symbol for @var{OBJ}. This would look like:
530 #<class-name "objname">
532 STRINGS are additional parameters passed in by overloading functions to
533 add more data into the printing abbreviation.
536 (defclass data-object ()
538 "Object containing one data slot.")
540 (defmethod object-print ((this data-object) &optional strings)
541 "Return a string with a summary of the data object as part of the name."
542 (apply 'call-next-method this
543 (cons (format " value: %s" (render this)) strings)))
546 here is what some output could look like:
548 (object-print test-object)
549 => #<data-object test-object value: 3>
553 @defun object-write obj &optional comment
554 Write @var{obj} onto a stream in a readable fashion. The resulting
555 output will be lisp code which can be used with @code{read} and
556 @code{eval} to recover the object. Only slots with @code{:initarg}s
557 are written to the stream.
560 @node Making New Objects, Accessing Slots, Default Superclass, Top
561 @comment node-name, next, previous, up
562 @chapter Making New Objects
564 Once we have defined our classes, it's time to create objects with the
565 specified structure. After we call @code{defclass} two new functions
566 are created, one of which is @code{classname}. Thus, from the example at
567 the end of the previous chapter @xref{Building Classes}, we would have
568 the functions @code{data-object} and @code{data-object-p}.
570 @defun classname object-name &rest slots
572 This creates and returns a new object. This object is not assigned to
573 anything, and will be garbage collected if not saved. This object will
574 be given the string name @var{object-name}. There can be multiple
575 objects of the same name, but the name slot provides a handy way to
576 keep track of your objects. @var{slots} is just all the slots you
577 wish to preset. Any slot set as such WILL NOT get it's default value,
578 and any side effects from an attributes default function will not occur.
579 An example pair would appear simply as @code{:value 1}. Of course you
580 can do any valid lispy thing you want with it, such as
581 @code{:value (if (boundp 'special-symbol) special-symbol nil)}
583 Example of creating an object from a class, @ref{Building Classes}:
586 (data-object "test" :value 3 :reference nil)
591 @node Accessing Slots, Writing Methods, Making New Objects, Top
592 @comment node-name, next, previous, up
593 @chapter Accessing Slots
595 There are several ways to access slot values in an object. The naming
596 convention and argument order is similar to that found in Emacs Lisp for
597 referencing vectors. The basics for referencing, setting, and calling
598 methods are all accounted for.
600 @defun oset object slot value
602 This sets the value behind @var{slot} to @var{value} in @var{object}.
603 @code{oset} returns @var{value}.
606 @defun oset-default class slot value
608 This sets the slot @var{slot} in @var{class} which is initialized with
609 the @code{:initform} tag to @var{value}. This will allow a user to set
610 both public and private defaults after the class has been constructed.
611 This function is intrusive, and is offered as a way to allow users to
612 configure the default behavior of packages built with classes the same
613 way @code{setq-default} is used for buffer-local variables.
615 For example, if a user wanted all @code{data-objects} (@pxref{Building
616 Classes}) to inform a special object of his own devising when they
617 changed, this can be arranged by simply executing this bit of code:
620 (oset-default data-object reference (list my-special-object))
625 @defun oref object slot
627 This recalls the value in slot @var{slot} in @var{object} and returns
628 it. If @var{object} is a class, and @var{slot} is a class allocated
629 slot, then oref will return that value. If @var{object} is a class, and
630 @var{slot} is not class allocated, a signal will be thrown.
633 @defun oref-default object slot
634 This gets the default value in @var{object}'s class definition for
635 @code{slot}. This can be different from the value returned by
636 @code{oref}. @var{object} can also be a class symbol or an instantiated
640 These next accessors are defined by CLOS to reference or modify slot
641 values, and use the previously mentioned set/ref routines.
643 @defun slot-value object slot
644 This function retrieves the value of @var{slot} from @var{object}.
645 Unlike @code{oref}, the symbol for @var{slot} must be quoted in.
648 @defun set-slot-value object slot value
649 This is not a CLOS function, but is meant to mirror @code{slot-value} if
650 you don't want to use the cl package's @code{setf} function. This
651 function sets the value of @var{slot} from @var{object}. Unlike
652 @code{oset}, the symbol for @var{slot} must be quoted in.
655 @defun slot-makeunbound object slot
656 This function unbinds @var{slot} in @var{object}. Referencing an
657 unbound slot can throw an error.
660 @defun object-add-to-list object slot &optional append
661 In @var{OBJECT}'s @var{SLOT}, add @var{ITEM} to the pre-existing list of elements.
662 Optional argument @var{APPEND} indicates we need to append to the list.
663 If @var{ITEM} already exists in the list in @var{SLOT}, then it is not added.
664 Comparison is done with @dfn{equal} through the @dfn{member} function call.
665 If @var{SLOT} is unbound, bind it to the list containing @var{ITEM}.
668 @defun with-slots entries object forms
669 Bind @var{entries} lexically to the specified slot values in
670 @var{object}, and execute @var{forms}. In CLOS, it would be possible to
671 set values in OBJECT by using @code{setf} to assign to these values, but
672 in Emacs, you may only read the values, or set the local variable to a
676 (defclass myclass () (x :initarg 1))
677 (setq mc (make-instance 'myclass))
678 (with-slots (x) mc x) => 1
679 (with-slots ((something x)) mc something) => 1
683 @node Writing Methods, Predicates, Accessing Slots, Top
684 @comment node-name, next, previous, up
685 @chapter Writing Methods
687 Writing a CLOS style method is similar to writing a function. The
688 differences are that there are some extra options and there can be
689 multiple implementations of a single method which interact interestingly
692 Each method created verifies that there is a @dfn{generic method}
693 available to attach to. A generic method has no body, and is merely a
694 symbol upon which methods are attached.
696 @defun defgeneric method arglist [doc-string]
698 @var{method} is the unquoted symbol to turn into a function.
699 @var{arglist} is the default list of arguments to use (not implemented yet).
700 @var{doc-string} is the documentation used for this symbol.
702 A generic function acts as a place holder for methods. There is no need
703 to call @code{defgeneric} yourself, as @code{defmethod} will call it if
704 necessary. Currently the argument list is unused.
706 @code{defgeneric} will prevent you from turning an existing emacs lisp
707 function into a generic function.
710 @defun defmethod method [:BEFORE | :PRIMARY | :AFTER | :STATIC ] arglist [doc-string] forms
712 @var{method} is the name of the function to be created.
714 @var{:BEFORE | :AFTER} represent when this form is to be called. If
715 neither of these symbols are present, then the default priority is,
716 before @var{:AFTER}, after @var{:BEFORE}, and is represented in CLOS as
719 If @var{:STATIC} is used, then the first argument when calling this
720 function can be a class or an object. Never treat the first argument
721 of a STATIC method as an object, always used @code{oref-default} or
722 @code{oset-default}. A Class' construction is defined as a static
725 @code{arglist} is the argument list. Unlike CLOS, only the FIRST
726 argument may be type-cast, and it may only be type-cast to an EIEIO
727 object. An arglist such as @code{(a b)} would classify the function
728 as generic call, which has no object it can talk to (none is passed
729 in) and merely allows the creation of side-effects. If the arglist
730 appears as @code{((this data-object) b)} then the form is stored as
731 belonging to the class @code{data-object}.
733 The first argument does not need to be typecast. A method with no
734 typecast is a @code{generic}. If a given class has no implementation,
735 then the generic will be called when that method is used on a given
736 object of that class.
738 If two @code{defmethod}s appear with arglists such as @code{(a b)}
739 and @code{(c d)} then one of the implementations will be overwritten,
740 but generic and multiple type cast arglists can co-exist.
742 When called, if there is a method cast against the object's parent
743 class, but not for that object's class, the parent class' method will be
744 called. If there is a method defined for both, only the child's method
747 @var{doc-string} is the documentation attached to the implementation.
748 All method doc-strings are concatenated into the generic method's
749 function documentation.
751 @var{forms} is the body of the function.
753 If multiple methods and generics are defined for the same method name,
754 they are executed in this order:
758 @item generic :BEFORE
759 @item method :PRIMARY
760 @item generic :PRIMARY
766 If in any situation a method does not exist, but a generic does, then
767 the generic is called in place of the method.
769 If no methods exist, then the signal @code{no-method-definition} is
770 thrown. @ref{Signals}
772 See the file @file{eieio-test.el} for an example testing these
773 differently tagged methods.
775 @defun call-next-method &rest replacement-args
777 While running inside a CLOS method, calling this function will call the
778 method associated with the parent of the class of the currently running
779 method with the same parameters.
781 If no next method is available, but a generic is implemented for the
782 given key (Such as @code{:BEFORE}), then the generic will be called.
784 OPTIONAL arguments @var{replacement-args} can be used to replace the
785 arguments the next method would be called with. Useful if a child class
786 wishes to add additional behaviors through the modification of the
787 parameters. This is not a feature of CLOS.
789 For example code @xref{Default Superclass}.
793 @defun call-next-method-p
795 Return t if there is a next method we can call.
799 In this implementation, not all features of CLOS exist.
803 There is currently no :AROUND tag.
805 CLOS allows multiple sets of type-cast arguments, where eieio only
806 allows the first argument to be cast.
809 @node Predicates, Association Lists, Writing Methods, Top
810 @comment node-name, next, previous, up
811 @chapter Predicates and Utilities
813 Now that we know how to create classes, access slots, and define
814 methods, it might be useful to verify that everything is doing ok. To
815 help with this a plethora of predicates have been created.
818 Return a vector with all the class's important parts in it. This vector
819 is not a copy. Changing this vector changes the class. The CLOS method
820 @code{find-class} will have the same effect.
823 @defun find-class symbol &optional errorp
824 CLOS function. In EIEIO it returns the vector definition of the class.
825 If there is no class, @code{nil} is returned if @var{errorp} is
830 Return non-@code{nil} if @var{class} is a class type.
834 Return non-@code{nil} if @var{obj} is an object.
837 @defun slot-exists-p obj-or-class slot
838 Return Non-@code{nil} if @var{obj-or-class} contains @var{slot} in its class.
841 @defun slot-boundp object slot
842 Non-@code{nil} if OBJECT's @var{SLOT} is bound.
843 Setting a slot's value makes it bound. Calling @dfn{slot-makeunbound} will
845 @var{OBJECT} can be an instance or a class.
848 @defun class-name class
849 Return a string of the form #<class myclassname> which should look
850 similar to other lisp objects like buffers and processes. Printing a
851 class results only in a symbol.
854 @defun class-option class option
855 Return the value in @var{CLASS} of a given @var{OPTION}.
859 (class-option eieio-default-superclass :documentation)
862 Will fetch the documentation string for @code{eieio-default-superclass}.
865 @defun class-constructor class
866 Return a symbol used as a constructor for @var{class}. This way you can
867 make an object of a passed in class without knowing what it is. This is
871 @defun object-name obj
872 Return a string of the form #<object-class myobjname> for @var{obj}.
873 This should look like lisp symbols from other parts of emacs such as
874 buffers and processes, and is shorter and cleaner than printing the
875 object's vector. It is more useful to use @code{object-print} to get
876 and object's print form, as this allows the object to add extra display
877 information into the symbol.
880 @defun object-class obj
881 Returns the class symbol from @var{obj}.
885 CLOS symbol which does the same thing as @code{object-class}
888 @defun object-class-fast obj
889 Same as @code{object-class} except this is a macro, and no
890 type-checking is performed.
893 @defun object-class-name obj
894 Returns the symbol of @var{obj}'s class.
897 @defun class-parents class
898 Returns the direct parents class of @var{class}. Returns @code{nil} if
902 @defun class-parents-fast class
903 Just like @code{class-parent} except it is a macro and no type checking
907 @defun class-parent class
908 Deprecated function which returns the first parent of @var{class}.
911 @defun class-children class
912 Return the list of classes inheriting from @var{class}.
915 @defun class-children-fast class
916 Just like @code{class-children}, but with no checks.
919 @defun same-class-p obj class
920 Returns @code{t} if @var{obj}'s class is the same as @var{class}.
923 @defun same-class-fast-p obj class
924 Same as @code{same-class-p} except this is a macro and no type checking
928 @defun object-of-class-p obj class
929 Returns @code{t} if @var{obj} inherits anything from @var{class}. This
930 is different from @code{same-class-p} because it checks for inheritance.
933 @defun child-of-class-p child class
934 Returns @code{t} if @var{child} is a subclass of @var{class}.
937 @defun generic-p method-symbol
938 Returns @code{t} if @code{method-symbol} is a generic function, as
939 opposed to a regular emacs list function.
942 It is also important to note, that for every created class, a two
943 predicates are created for it. Thus in our example, the function
944 @code{data-object-p} is created, and return @code{t} if passed an object
945 of the appropriate type. Also, the function @code{data-object-child-p}
946 is created which returns @code{t} if the object passed to it is of a
947 type which inherits from @code{data-object}.
949 @node Association Lists, Introspection, Predicates, Top
950 @chapter Association Lists
952 Lisp offers the concept of association lists, with primitives such as
953 @code{assoc} used to access them. Eieio provides a few such functions
954 to help with using lists of objects easily.
956 @defun object-assoc key slot list
957 Returns the first object in @var{list} for which @var{key} is in
961 @defun object-assoc-list slot list
962 Return an association list generated by extracting @var{slot} from all
963 objects in @var{list}. For each element of @var{list} the @code{car} is
964 the value of @var{slot}, and the @code{cdr} is the object it was
965 extracted from. This is useful for generating completion tables.
968 @defun eieio-build-class-alist &optional base-class
969 Returns an alist of all currently defined classes. This alist is
970 suitable for completion lists used by interactive functions to select a
971 class. The optional argument @var{base-class} allows the programmer to
972 select only a subset of classes to choose from should it prove
976 @node Introspection, Signals, Association Lists, Top
977 @chapter Introspection
979 Introspection permits a programmer to peek at the contents of a class
980 without any previous knowledge of that class. While EIEIO implements
981 objects on top of vectors, and thus everything is technically visible,
982 some functions have been provided. None of these functions are a part
985 @defun object-slots obj
986 Return the list of public slots for @var{obj}.
989 @defun class-slot-initarg class slot
990 For the given @var{class} return the :initarg associated with
991 @var{slot}. Not all slots have initargs, so the return value can be
995 @node Signals, Base Classes, Introspection, Top
996 @comment node-name, next, previous, up
999 There are new signal types that can be caught when using eieio.
1001 @deffn Signal invalid-slot-name obj-or-class slot
1002 This signal is called when an attempt to reference a slot in an
1003 @var{obj-or-class} is made, and the @var{slot} is not defined for
1007 @deffn Signal no-method-definition method arguments
1008 This signal is called when @var{method} is called, with @var{arguments}
1009 and nothing is resolved. This occurs when @var{method} has been
1010 defined, but the arguments make it impossible for eieio to determine
1011 which method body to run.
1013 Overload the method @code{no-method-definition} to protect against this
1017 @deffn Signal no-next-method class arguments
1018 This signal is called if the function @code{call-next-method} is called
1019 and there is no next method to be called.
1021 Overload the method @code{no-next-method} to protect against this signal.
1024 @deffn Signal invalid-slot-type slot spec value
1025 This signal is called when an attempt to set @var{slot} is made, and
1026 @var{var} doesn't match the specified type @var{spec}.
1028 In EIEIO, this is also used of a slot specifier has an invalid value
1029 during a @code{defclass}.
1032 @deffn Signal unbound-slot object class slot
1033 This signal is called when an attempt to reference @var{slot} in
1034 @var{object} is made, and that instance is currently unbound.
1037 @node Base Classes, Browsing, Signals, Top
1038 @comment node-name, next, previous, up
1039 @chapter Base Classes
1041 Asside from @code{eieio-default-superclass}, EIEIO comes with some
1042 additional classes that you can use. By using multiple inheritance, it
1043 is possible to use several features at the same time.
1046 * eieio-instance-inheritor:: Enable value inheritance between instances.
1047 * eieio-instance-tracker:: Enable self tracking instances.
1048 * eieio-singleton:: Only one instance of a given class.
1049 * eieio-persistent:: Enable persistence for a class.
1050 * eieio-named:: Use the object name as a :name field.
1051 * eieio-speedbar:: Enable speedbar support in your objects.
1054 @node eieio-instance-inheritor, eieio-instance-tracker, Base Classes, Base Classes
1055 @comment node-name, next, previous, up
1056 @section @code{eieio-instance-inheritor}
1058 This class is in package @file{eieio-base}.
1060 Instance inheritance is a mechanism whereby the value of a slot in
1061 object instance can reference the parent instance. If the parent's slot
1062 value is changed, then the child instance is also changed. If the
1063 child's slot is set, then the parent's slot is not modified.
1065 @deftp {Class} eieio-instance-inheritor parent-instance
1066 A class whose instances are enabled with instance inheritance.
1067 The @var{parent-instance} slot indicates the instance which is
1068 considered the parent of the current instance. Default is @code{nil}.
1072 To use this class, inherit from it with your own class.
1073 To make a new instance that inherits from and existing instance of your
1074 class, use the @code{clone} method with additional parameters
1075 to specify local values.
1077 @cindex slot-unbound
1078 The @code{eieio-instance-inheritor} class works by causing cloned
1079 objects to have all slots unbound. This class' @code{slot-unbound}
1080 method will cause references to unbound slots to be redirected to the
1081 parent instance. If the parent slot is also unbound, then
1082 @code{slot-unbound} will throw an @code{slot-unbound} signal.
1084 @node eieio-instance-tracker, eieio-singleton, eieio-instance-inheritor, Base Classes
1085 @comment node-name, next, previous, up
1087 This class is in package @file{eieio-base}.
1089 Sometimes it is useful to keep a master list of all instances of a given
1090 class. The class @code{eieio-instance-tracker} performs this task.
1092 @deftp {Class} eieio-instance-tracker tracker-symbol
1093 Enable instance tracking for this class.
1094 The field @var{tracker-symbol} should be initialized in inheritors of
1095 this class to a symbol created with @code{defvar}. This symbol will
1096 serve as the variable used as a master list of all objects of the given
1100 @defmethod eieio-instance-tracker initialize-instance obj fields
1101 This method is defined as an @code{:AFTER} method.
1102 It adds new instances to the master list. Do not overload this method
1103 unless you use @code{call-next-method.}
1106 @defmethod eieio-instance-tracker delete-instance obj
1107 Remove @var{obj} from the master list of instances of this class.
1108 This may let the garbage collector nab this instance.
1111 @deffn eieio-instance-tracker-find key field list-symbol
1112 This convenience function lets you find instances. @var{key} is the
1113 value to search for. @var{FIELD} is the field to compare @var{KEY}
1114 against. The function @code{equal} is used for comparison.
1115 The paramter @var{list-symbol} is the variable symbol which contains the
1116 list of objects to be searched.
1119 @node eieio-singleton, eieio-persistent, eieio-instance-tracker, Base Classes
1120 @comment node-name, next, previous, up
1121 @section @code{eieio-singleton}
1123 This class is in package @file{eieio-base}.
1125 @deftp {Class} eieio-singleton
1126 Inheriting from the singleton class will guarantee that there will
1127 only ever be one instance of this class. Multiple calls to
1128 @code{make-instance} will always return the same object.
1131 @node eieio-persistent, eieio-named, eieio-singleton, Base Classes
1132 @comment node-name, next, previous, up
1133 @section @code{eieio-persistent}
1135 This class is in package @file{eieio-base}.
1137 If you want an object, or set of objects to be persistent, meaning the
1138 slot values are important to keep saved between sessions, then you will
1139 want your top level object to inherit from @code{eieio-persistent}.
1141 To make sure your persistent object can be moved, make sure all file
1142 names stored to disk are made relative with
1143 @code{eieio-persistent-path-relative}.
1145 @deftp {Class} eieio-persistent file file-header-line
1146 Enables persistence for instances of this class.
1147 Slot @var{file} with initarg @code{:file} is the file name in which this
1148 object will be saved.
1149 Class allocated slot @var{file-header-line} is used with method
1150 @code{object-write} as a header comment.
1153 All objects can write themselves to a file, but persistent objects have
1154 several additional methods that aid in maintaining them.
1156 @defmethod eieio-persistent eieio-persistent-save obj &optional file
1157 Write the object @var{obj} to its file.
1158 If optional argument @var{file} is specified, use that file name
1162 @defmethod eieio-persistent eieio-persistent-path-relative obj file
1163 Return a file name derived from @var{file} which is relative to the
1164 stored location of @var{OBJ}. This method should be used to convert
1165 file names so that they are relative to the save file, making any system
1166 of files movable from one location to another.
1169 @defmethod eieio-persistent object-write obj &optional comment
1170 Like @code{object-write} for @code{standard-object}, but will derive
1171 a header line comment from the class allocated slot if one is not
1175 @defun eieio-persistent-read filename
1176 Read @var{filename} which contains an @code{eieio-persistent} object
1177 previously written with @code{eieio-persistent-save}.
1180 @node eieio-named, eieio-speedbar, eieio-persistent, Base Classes
1181 @comment node-name, next, previous, up
1182 @section @code{eieio-named}
1184 This class is in package @file{eieio-base}.
1186 @deftp {Class} eieio-named
1188 Name storage already occurs in an object. This object provides get/set
1192 @node eieio-speedbar, , eieio-named, Base Classes
1193 @comment node-name, next, previous, up
1194 @section @code{eieio-speedbar}
1196 This class is in package @file{eieio-speedbar}.
1198 If a series of class instances map to a tree structure, it is possible
1199 to cause your classes to be displayable in Speedbar. @xref{Top,,,speedbar}.
1200 Inheriting from these classes will enable a speedbar major display mode
1201 with a minimum of effort.
1203 @deftp {Class} eieio-speedbar buttontype buttonface
1204 Enables base speedbar display for a class.
1205 @cindex speedbar-make-tag-line
1206 The slot @var{buttontype} is any of the symbols allowed by the
1207 function @code{speedbar-make-tag-line} for the @var{exp-button-type}
1208 argument @xref{Extending,,,speedbar}.
1209 The slot @var{buttonface} is the face to use for the text of the string
1210 displayed in speedbar.
1211 The slots @var{buttontype} and @var{buttonface} are class allocated
1212 slots, and do not take up space in your instances.
1215 @deftp {Class} eieio-speedbar-directory-button buttontype buttonface
1216 This class inherits from @code{eieio-speedbar} and initializes
1217 @var{buttontype} and @var{buttonface} to appear as directory level lines.
1220 @deftp {Class} eieio-speedbar-file-button buttontype buttonface
1221 This class inherits from @code{eieio-speedbar} and initializes
1222 @var{buttontype} and @var{buttonface} to appear as file level lines.
1225 To use these classes, inherit from one of them in you class. You can
1226 use multiple inheritance with them safely. To customize your class for
1227 speedbar display, override the default values for @var{buttontype} and
1228 @var{buttonface} to get the desired effects.
1230 Useful methods to define for your new class include:
1232 @defmethod eieio-speedbar eieio-speedbar-derive-line-path obj depth
1233 Return a string representing a directory associated with an instance
1234 of @var{obj}. @var{depth} can be used to indice how many levels of
1235 indentation have been opened by the user where @var{obj} is shown.
1239 @defmethod eieio-speedbar eieio-speedbar-description obj
1240 Return a string description of @var{OBJ}.
1241 This is shown in the minibuffer or tooltip when the mouse hovers over
1242 this instance in speedbar.
1245 @defmethod eieio-speedbar eieio-speedbar-child-description obj
1246 Return a string representing a description of a child node of @var{obj}
1247 when that child is not an object. It is often useful to just use
1248 item info helper functions such as @code{speedbar-item-info-file-helper}.
1251 @defmethod eieio-speedbar eieio-speedbar-object-buttonname obj
1252 Return a string which is the text displayed in speedbar for @var{obj}.
1255 @defmethod eieio-speedbar eieio-speedbar-object-children obj
1256 Return a list of children of @var{obj}.
1259 @defmethod eieio-speedbar eieio-speedbar-child-make-tag-lines obj depth
1260 This method inserts a list of speedbar tag lines for @var{obj} to
1261 represent its children. Implement this method for your class
1262 if your children are not objects themselves. You still need to
1263 implement @code{eieio-speedbar-object-children}.
1265 In this method, use techniques specified in the Speedbar manual.
1266 @xref{Extending,,,speedbar}.
1269 Some other functions you will need to learn to use are:
1271 @deffn eieio-speedbar-create make-map key-map menu name toplevelfn
1272 Register your object display mode with speedbar.
1273 @var{make-map} is a function which initialized you keymap.
1274 @var{key-map} is a symbol you keymap is installed into.
1275 @var{menu} is an easy menu vector representing menu items specific to your
1277 @var{name} is a short string to use as a name identifying you mode.
1278 @var{toplevelfn} is a function called which must return a list of
1279 objects representing those in the instance system you wish to browse in
1282 Read the Extending chapter in the speedbar manual for more information
1283 on how speedbar modes work
1284 @xref{Extending,,,speedbar}.
1287 @node Browsing, Class Values, Base Classes, Top
1288 @comment node-name, next, previous, up
1289 @chapter Browsing class trees
1291 To browse all the currently loaded classes in emacs, simply run the
1292 EIEIO browser. @kbd{M-x eieio-browse}. This browses all the way from
1293 the default super-duper class eieio-default-superclass, and lists all
1294 children in an indented tree structure.
1296 To browse only from a specific class, pass it in as an alternate
1299 Here is a sample tree from our current example:
1302 eieio-default-superclass
1304 +--data-object-symbol
1307 Note that we start with eieio-default-superclass. @xref{Default Superclass}.
1309 Note: new classes are consed into the inheritance lists, so the tree
1310 comes out upside-down.
1312 It is also possible to use the function @code{eieio-class-tree} in the
1313 @file{tree.el} package. This will create an interactive tree. Clicking
1314 on nodes will allow expansion/contraction of branches, or editing of a
1315 class. @xref{Class Values}.
1317 @node Class Values, Customizing, Browsing, Top
1318 @comment node-name, next, previous, up
1319 @chapter Class Values
1321 Details about any class or object can be retrieved using the function
1322 @code{eieio-describe-class} function. Interactively, type in the name of
1323 a class. In a program, pass it a string with the name of a class, a
1324 class symbol, or an object. The resulting buffer will display all slot
1327 Additionally, all methods defined to have functionality on this class is
1330 @node Customizing, Documentation, Class Values, Top
1331 @comment node-name, next, previous, up
1332 @chapter Customizing Objects
1334 In Emacs 20 a useful customization utility became available called
1335 `custom'. EIEIO supports custom through two new widget types. If a
1336 variable is declared as type @code{'object}, then full editing of slots
1337 via the widgets is made possible. This should be used carefully,
1338 however, because objects modified are cloned, so if there are other
1339 references to these objects, they will no longer be linked together.
1341 If you want in place editing of objects, use the following methods:
1343 @defun eieio-customize-object object
1344 Create a custom buffer and insert a widget for editing @var{object}. At
1345 the end, an @code{Apply} and @code{Reset} button are available. This
1346 will edit the object "in place" so references to it are also changed.
1347 There is no effort to prevent multiple edits of a singular object, so
1348 care must be taken by the user of this function.
1351 @defun eieio-custom-widget-insert object flags
1352 This method inserts an edit object into the current buffer in place.
1353 It's sole code is @code{(widget-create 'object-edit :value object)} and
1354 is provided as a locale for adding tracking, or specializing the widget
1355 insert procedure for any object.
1358 To define a slot with an object in it, use the @code{object} tag. This
1359 widget type will be automatically converted to @code{object-edit} if you
1360 do in place editing of you object.
1362 If you want to have additional actions taken when a user clicks on the
1363 @code{Apply} button, then overload the method @code{eieio-done-customizing}.
1364 This method does nothing by default, but that may change in the future.
1365 This would be the best way to make your objects persistent when using
1368 @section Widget extention
1370 When widgets are being created, one new widget extention has been added,
1371 called the @code{:slotofchoices}. When this occurs in a widget
1372 definition, all elements after it are removed, and the slot is specifies
1373 is queried and converted into a series of constants.
1376 (choice (const :tag "None" nil)
1377 :slotofchoices morestuff)
1380 and if the slot @code{morestuff} contains @code{(sym1 sym2 sym3)}, the
1381 above example is converted into:
1384 (choice (const :tag "None" nil)
1390 This is useful when a given item needs to be selected from a list of
1391 items defined in this second slot.
1393 @node Documentation, Naming Conventions, Customizing, Top
1394 @comment node-name, next, previous, up
1395 @chapter Documentation
1397 It is possible to automatically create documentation for your classes in
1398 texinfo format by using the tools in the file @file{eieio-doc.el}
1400 @deffn Command eieiodoc-class class indexstring &optional skiplist
1402 This will start at the current point, and created an indented menu of
1403 all the child classes of, and including @var{class}, but skipping any
1404 classes that might be in @var{skiplist} It will then create nodes for
1405 all these classes, subsection headings, and indexes.
1407 Each class will be indexed using the texinfo labeled index
1408 @var{indexstring} which is a two letter description.
1409 @xref{(texinfo) New Indices}.
1411 To use this command, the texinfo macro
1414 @@defindex @@var @{ indexstring @}
1418 where @var{indexstring} is replaced with the two letter code.
1420 Next, an inheritance tree will be created listing all parents of that
1423 Then,all the slots will be expanded in tables, and described
1424 using the documentation strings from the code. Default values will also
1425 be displayed. Only those slots with @code{:initarg} specified will be
1426 expanded, others will be hidden. If a slot is inherited from a parent,
1427 that slot will also be skipped unless the default value is different.
1428 If there is a change, then the documentation part of the slot will be
1429 replace with an @@xref back to the parent.
1431 Only classes loaded into emacs' memory can be documented.
1435 @node Naming Conventions, Demo Programs, Documentation, Top
1436 @comment node-name, next, previous, up
1437 @chapter Naming Conventions
1439 The Emacs Lisp programming manual has a great chapter programming
1440 conventions that help keep each Emacs package working nicely with the
1441 entire system. @ref{(elisp)Standards} An EIEIO based program needs to
1442 follow these conventions, while simultaneously taking advantage of the
1443 Object Oriented features.
1445 The below tips are things that I do when I program an EIEIO based
1449 @item Come up with a package prefix that is relatively short. Prefix
1450 all classes, and methods with your prefix. This is a standard
1451 convention for functions and variables in Emacs.
1452 @item Do not prefix method names with the class name. All methods in
1453 EIEIO are ``virtual'', and are dynamically dispatched. Anyone can
1454 override your methods at any time. Your methods should be prefixed
1455 with your package name.
1456 @item Do not prefix slots in your class. The slots are always locally
1457 scoped to your class, and need no prefixing.
1458 @item If your library inherits from other libraries of classes, you
1459 must ``require'' that library with the @code{require} command.
1462 @node Demo Programs, Function Index, Naming Conventions, Top
1463 @comment node-name, next, previous, up
1464 @chapter Demo Programs
1466 There are many sample programs I have written for eieio which could
1467 become useful components of other applications, or are good stand alone
1468 programs providing some useful functionality. The file, and
1469 functionality of these appear below:
1473 Maintains and displays a tree structure in a buffer. Nodes in the tree
1474 can be clicked on for editing, node expansion, and simple information.
1475 Includes a sample program for showing directory trees, and to draw trees
1476 of the eieio class structures.
1478 Parses a non-byte-compiled function, and generates a call tree from it,
1479 and all sub-non-byte-compiled functions. Provides protection from
1480 recursive functions.
1482 Draw bar charts from data. Examples include displaying sizes of emacs
1483 values, file distribution, and rmail distributions.
1486 @node Function Index, , Demo Programs, Top
1487 @unnumbered Function Index
1495 From: Richard Stallman <rms@gnu.org>
1497 Subject: eieio manual
1498 Reply-to: rms@gnu.org
1499 Date: Mon, 26 Jul 2004 10:30:19 -0400
1501 I read the eieio manual, and while it was complete enough that
1502 I could mostly understand it, it needs a lot of work.
1504 The general problem is that parts are still to some extent written for
1505 people who know CLOS. It should be written entirely for a person who
1506 has never seen CLOS. It is ok to include compatibility notes
1507 describing differences from CLOS, as in the Emacs Lisp Reference
1508 Manual. These should come after, not before, the material
1509 described (consider section 1.2).
1511 It needs a lot of proofreading. Words are capitalized in
1512 mid-sentence. Symbols appear without @code. Variable names
1513 are in all caps, sometimes with @var and sometimes without.
1514 The name "Lisp" is written in lower case.
1516 The text uses nonstandard terminology such as "throw an error" and
1517 "must be quoted in". I can understand them, but this manual should
1518 use the normal Emacs terminology found in the Emacs Lisp Reference
1521 The topics should be ordered from most conceptually essential to
1522 least. For instance, the default ancestor class is a comparatively
1523 unimportant topic. Most users don't need to know about it. So put it
1524 near the end. Constructors are essential basic, so they should come
1527 The functions initialize-instance are rather unimportant details and
1528 should go near the end; however, I don't see that they relate to the
1529 default ancestor class, so grouping them under that heading does not seem
1532 The methods used in case of errors are also rather minor side
1533 issues, so they should go late in the manual. They belong with
1534 the new condition names. (The correct term is "condition names",
1535 not "signal types".)
1537 In general, the examples are not indented right, perhaps because they
1538 use tabs. You must not have tab characters in Texinfo.
1539 eieio-default-superclass has unmatched parens.
1541 Some specific points:
1543 There are two mysterious references to something called
1544 `lambda-default' that is not explained. I can't understand it.
1546 I am not sure how initializing slots with :initform relates to
1547 initializing slots with oset-default. That needs to be better explained.
1549 There seems to be a fundamental difference in usage between slots
1550 initialized using :initform and slots that are not initialized.
1551 This needs to be stated loud and clear in the explanation of defclass,
1552 before you get into the specific slot list attributes.
1554 The term "superclass" seems to be used in two inconsistent meanings.
1555 In defclass it is synonymous with "parent class" (this is the
1556 traditional meaning), but section 4 gives it a different meaning.
1557 Please choose another term for the latter meaning, such as "orphan
1558 class". This would mean renaming eieio-default-superclass.
1560 Creates a new class called @code{class-name}. The created
1561 variable's documentation string is set to a modified version of
1562 the doc string found in @var{options-or-doc}.
1564 What is "the created variable"?
1567 parent is replicated in the new class.
1569 Do you mean, "Every slot that appears in any parent class
1570 is replicated in the new class"?
1572 The parent class for @code{class-name} is
1574 Shouldn't that be @var? That is not the only place.
1575 Also, it seems strange to speak of "the" parent class
1576 given that there can be more than one.
1578 @var{slot-list} is a list of lists. Each sublist defines an attribute.
1579 These lists are of the form @code{(name :tag1 value1 :tag2 value2 :tagn
1582 All those parts that can vary need @var.
1585 The argument used during initialization. @xref{Making New Objects}.
1587 The node Making New Objects does not explain :initarg.
1589 A lisp expression used to generate the default value for this slot.
1590 If :initform is left out, that slot defaults to being unbound.
1591 The value passed to initform is automatically quoted. Thus,
1595 (1 2 3) is not a valid Lisp expression: evaluating it would get an
1596 error. Do you mean "a Lisp object"?
1598 A function like this:
1602 is quoted in as a symbol.
1604 That is really confusing. What does "a function like this" refer to?
1606 "Default class used as parent class for superclasses. It's
1607 slots are automatically adopted by such superclasses but not stored
1609 The possessive of "it" is "its". In English, the possessive pronouns
1610 have no apostrophe. My, our, your, his, her, their, its.
1612 When creating an object of any type, you can use it's constructor, or
1613 @code{make-instance}.
1615 Same problem. Please check every occurrence of "it's".
1617 Also, you need to explain what a constructor is. Otherwise, this is
1618 completely confusing to a reader who does not know. The manual does
1619 not explain "constructor" anywhere. When it describes how to use
1620 constructors, it does not use that term.
1622 @defun initialize-instance obj &rest slots
1623 Initialize @var{obj}. Sets slots of @var{obj} with @var{slots} which
1624 is a list of name/value pairs. These are actually just passed to
1625 @code{shared-initialize}.
1628 @defun shared-initialize obj &rest slots
1629 Sets slots of @var{obj} with @var{slots} which is a list of name/value
1633 It needs to say when the programmer should call initialize-instance
1634 and when person should call shared-initialize.
1636 @defun clone obj &rest params
1637 Make a deep copy of @var{obj}.
1639 "Deep copy" is not defined Emacs terminology, so it needs a precise
1640 definition. I have a general idea what you probably mean, but I
1641 cannot be sure of details. Does this copy cons cells? Does it copy
1642 vectors? Does it copy hash tables? Does it copy symbols? The manual
1645 @defun object-print obj &rest strings
1646 Construct a printing lisp symbol for @var{OBJ}.
1648 Should that be @var{obj}?
1650 Once we have defined our classes, it's time to create objects with the
1651 specified structure. After we call @code{defclass} two new functions
1652 are created, one of which is @code{classname}.
1654 I don't think there is a function named `classname'. The eieio sources
1655 do not define one. Do you mean its name is the name of the class?
1656 If so, use @var{classname}.
1658 @defun classname object-name &rest slots
1660 The symbol after @defun is the literal name of a function
1661 you are describing. You can't use @defun for this.
1663 wish to preset. Any slot set as such WILL NOT get it's default value,
1665 That should be @emph{will not}. Also, "its" is misspelled here too.
1667 and any side effects from an attributes default function will not occur.
1669 I am not sure what an "attributes default function" is, and I cannot
1670 find anything in the manual that explains it. There should be a
1671 cross-reference here to an explanation elsewhere.
1673 @defun defmethod method [:BEFORE | :PRIMARY | :AFTER | :STATIC ] arglist [doc-string] forms
1675 This needs to be @defmac. Also, you may need to use @code inside it.
1677 It is really confusing that names such as :BEFORE are upper-case.
1678 Is that what CL does?
1680 @var{:BEFORE | :AFTER} represent when this form is to be called. If
1681 neither of these symbols are present, then the default priority is,
1682 before @var{:AFTER}, after @var{:BEFORE}, and is represented in CLOS as
1685 These names are keywords, not variables; @var is wrong for them.
1686 They should be in @code.
1688 Never treat the first argument
1689 of a STATIC method as an object, always used @code{oref-default} or
1690 @code{oset-default}.
1692 I can't understand that. However, I am sure that "a STATIC method"
1693 needs some style change.
1695 @code{arglist} is the argument list. Unlike CLOS, only the FIRST
1696 argument may be type-cast,
1698 I have no idea what that means. "Type-cast" is not standard Emacs
1699 terminology, so you need to define it. The manual must explain this
1700 type-cast feature, assuming that the reader has never heard of it
1703 If two @code{defmethod}s appear with arglists such as @code{(a b)}
1704 and @code{(c d)} then one of the implementations will be overwritten,
1706 "will be overwritten" is not clear; I don't understand it.
1708 When called, if there is a method cast against the object's parent
1709 class, but not for that object's class, the parent class' method will be
1712 I am not sure what a "method cast" is, or what it means for that to
1713 be "against" some class. The text has to explain this.
1715 If multiple methods and generics are defined for the same method name,
1716 they are executed in this order:
1719 @item method :BEFORE
1720 @item generic :BEFORE
1722 I can't understand that. What are these "generics", and how does one
1723 define them? Apparently not with defmethod, which defines methods.
1724 Apparently not with defgeneric, which defines a placeholder, not
1725 something that may need to be run.
1727 If in any situation a method does not exist, but a generic does, then
1728 the generic is called in place of the method.
1730 I can't make sense of that. According to the previous text it would
1731 run both of them, the method first. So if there's no method, it would
1732 naturally run just the generic, if the absence of a method isn't an
1733 error. So what information is this sentence meant to convey?
1734 I can't figure it out.
1736 @defun call-next-method &rest replacement-args
1738 While running inside a CLOS method, calling this function will call the
1739 method associated with the parent of the class of the currently running
1740 method with the same parameters.
1742 When would a program do this? Should methods normally do this?
1744 @defun class-name class
1745 Return a string of the form #<class myclassname>
1747 That needs @samp. Other places too.
1749 opposed to a regular emacs list function.
1751 I think that should say "a regular Emacs Lisp function".
1753 @defun object-assoc key slot list
1754 Returns the first object in @var{list} for which @var{key} is in
1757 Is this as trivial as it sounds? If so, please include equivalent
1758 code not using the function, as an explanatory example. In the
1759 absence of that, I wonder "Is this doing something that I could not
1760 easily code for myself"?
1762 In Emacs 20 a useful customization utility became available called
1765 If we install this in Emacs 21, we should take for granted that Emacs
1766 includes Custom, and not refer to the time when it was absent.
1768 The below tips are things that I do when I program an EIEIO based
1771 These are important, so they belong earlier, with defclass.