Deprecated: The each() function is deprecated. This message will be suppressed on further calls in /home/zhenxiangba/zhenxiangba.com/public_html/phproxy-improved-master/index.php on line 456
This is eieio.info, produced by makeinfo version 4.0 from eieio.texi. START-INFO-DIR-ENTRY * eieio: (eieio). Objects for Emacs END-INFO-DIR-ENTRY  File: eieio.info, Node: Top, Up: (dir)Top EIEIO is a framework for writing object oriented applications in emacs lisp, and is a result of my taking various object oriented classes at work and my attempt to understand some of it better by implementing it. The real reason I started eieio is because someone in one of my classes said "I bet emacs can't do that!". Well then, I just had to prove them wrong! * Menu: * Introduction:: Why use eieio? Basic overview, samples list. * CLOS compatibility:: What are the differences? * Building Classes:: How to write new class structures. * Default Superclass:: The root superclasses. * Making New Objects:: How to construct new objects. * Accessing Slots:: How to access a slot. * Writing Methods:: How to write a CLOS style method. * Predicates:: Class-p, Object-p, etc-p. * Association Lists:: List of objects as association lists. * Introspection:: Looking inside a class. * Signals:: When you make errors * Base Classes:: Additional classes you can inherit from. * Browsing:: Browsing your class lists. * Class Values:: Displaying information about a class or object. * Customizing:: Customizing objects. * Documentation:: Automatically creating texinfo documentation * Naming Conventions:: Name your objects in an Emacs friendly way. * Demo Programs:: Some examples using eieio. * Function Index:: As of this writing, updates can be found at: `ftp://ftp.ultranet.com/pub/zappo'.  File: eieio.info, Node: Introduction, Next: CLOS compatibility, Prev: Top, Up: Top Introduction ************ EIEIO is a CLOS (Common Lisp Object System) compatibility layer. Due to restrictions in the Emacs Lisp language, CLOS cannot be completely supported, and a few functions have been added in place of setf. What EIEIO supports =================== 1. A structured framework for the creation of basic classes with attributes and methods using singular inheritance similar to CLOS. 2. Type checking, and slot unbinding. 3. Method definitions similar to CLOS. 4. Simple and complex class browsers. 5. Edebug support for methods. 6. Imenu updates. 7. Byte compilation support of methods. 8. Help system extentions for classes and methods. 9. Automatic texinfo documentation generator. 10. Several base classes for interesting tasks. 11. Simple test suite. 12. Public and private classifications for slots (extensions to CLOS) 13. Customization support in a class (extension to CLOS) Issues using EIEIO ================== Complete `defclass' tag support All CLOS tags are currently supported, but some are not currently implemented correctly. Mock object initializers Each class contains a mock object used for fast initialization of 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. :AROUND method tag This CLOS method tag is non-functional. EIEIO example programs that are almost useful. ============================================== linemark Manage line highlighting, where individual lines are given a background color, or some other graphic feature. Lines can be highlighted in files not currently loaded in Emacs. When they are read in, the lines are given the graphic properties. Includes an MS Visual Studio like bookmark facility. tree Draw a structured tree by building a series of embedded lists of `tree-node' class objects. Includes the functions `eieio-class-tree' to browse your current eieio inheritance structure call-tree Pass it an Emacs Lisp function (not byte compiled) to generate a call tree using the tree tool chart Uses eieio to manage charts/axis/sequences, and allows display of simple bar-charts. Example programs are available displaying emacs memory usage and list occupation, in addition to file counts and size charts. There's even a sample that will display a chart of who sends you the most email! See doc-string for `chart-bar-quickie' to make your own bar charts easily. eieio-speedbar Classes for implementing a speedbar display. If you write a program that uses a system of objects, and your classes inherit from those in `eieio-speedbar', then you can write a speedbar display for your objects in very little time. *Note eieio-speedbar:: EIEIO wish list =============== 1. More CLOS compatibility. 2. Integrate the desired built-in methods into the object browser. 3. Create some objects over pre-existing emacs-lisp stuff for fun, like faces, processes, buffers, frames and windows as examples.  File: eieio.info, Node: CLOS compatibility, Next: Building Classes, Prev: Introduction, Up: Top CLOS compatibility ****************** As you read this, it is important to know that I have just recently learned some of the CLOS syntax, but have never used it myself outside of the EIEIO framework. I'm primarily and Emacs Lisp hacker who wrote EIEIO to help myself learn some of the mechanics of Object Oriented programming. Currently, the following functions should behave almost as expected from CLOS. `defclass' All slot keywords are available but not all work correctly. Slot keyword differences are: :reader, and :writer tags Create methods that throw errors instead of creating an unqualified method. You can still create new ones to do its business. :accessor This should create an unqualified method to access a slot, but instead pre-builds a method that gets the slot's value. :type Specifier uses the `typep' function from the `cl' package. *Note (cl)Type Predicates::. It therefore has the same issues as that package. Extensions include the ability to provide object names. Defclass also supports class options, but does not currently use values of `:metaclass', and `:default-initargs'. `make-instance' Make instance works as expected, however it just uses the EIEIO instance creator automatically generated when a new class is created. *Note Making New Objects::. `defgeneric' Creates the desired symbol, and accepts all of the expected arguments except `:AROUND'. `defmethod' Calls defgeneric, and accepts most of the expected arguments. Only the first argument to the created method may be type cast, though any argument can be syntactically type cast. (And promptly ignored) To type cast against a class, the class must exist before defmethod is called. In addition, the `:AROUND' tag is not supported. `call-next-method' Inside a method, calls the next available method up the inheritance tree for the given object. This is different than that found in CLOS because in EIEIO this function accepts replacement arguments. This permits subclasses to modify arguments as they are passed up the tree. If no arguments are given, the expected CLOS behavior is used. `setf' If the common-lisp subsystem is loaded, the setf parameters are also loaded so the form `(setf (slot-value object slot) t)' should work. CLOS supports the `describe' command, but eieio only provides `eieio-describe-class', and `eieio-describe-generic'. These functions are adviced into `describe-variable', and `describe-function'. When creating a new class (*note Building Classes::) there are several new keywords supported by EIEIO. In EIEIO tags are in lower case, not mixed case.  File: eieio.info, Node: Building Classes, Next: Default Superclass, Prev: CLOS compatibility, Up: Top Building Classes **************** A class in EIEIO has a similar structure to that found in other languages. A new class is created with `defclass' - Function: defclass class-name superclass-list slot-list options-or-doc This function is specified by CLOS, and EIEIO conforms in structure. Creates a new class called `class-name'. The created variable's documentation string is set to a modified version of the doc string found in OPTIONS-OR-DOC. Each time a slot is defined the variables documentation string is updated to include the methods documentation as well. The parent class for `class-name' is SUPERCLASS-LIST which must be a list. Each element of this list must be a class. These classes form the parents of the class being created. Every slot in parent is replicated in the new class. If two parents share the same slot name, the parent which appears in the list first sets the attributes for that slot. If a slot in the new class' slot list matches a parent, then the new specifications for the child class override that of the parent. SLOT-LIST is a list of lists. Each sublist defines an attribute. These lists are of the form `(name :tag1 value1 :tag2 value2 :tagn valuen)'. Some valid CLOS tags are: `:initarg' The argument used during initialization. *Note Making New Objects::. A good symbol to use for initarg is one that starts with a colon `:'. `:initform' A lisp expression used to generate the default value for this slot. If :initform is left out, that slot defaults to being unbound. The value passed to initform is automatically quoted. Thus, :initform (1 2 3) appears as the specified list in the default object. A function like this: :initform + is quoted in as a symbol. Lastly, using the function `lambda-default' instead of `lambda' will let you specify a lambda expression to use as the value, without evaluation. `:type' An unquoted type specifier used to validate data set into this slot. *Note (cl)Type Predicates::. Here are some examples: `symbol' A symbol. `number' A number type `my-class-name' An object of your class type. `(or null symbol)' A symbol, or nil. `function' A function symbol, or a `lambda-default' expression. `:allocation' Either :class or :instance (defaults to :instance) used to specify how data is stored. Slots stored per instance have unique values for each object. Slots stored per class have shared values for each object. If one object changes a :class allocated slot, then all objects for that class gain the new value. `:documentation' Documentation detailing the use of this slot. This documentation is exposed when the user describes a class, and during customization of an object. Some tags whose behaviors do not yet match CLOS are: `:accessor' Name of a generic function which can be used to fetch the value of this slot. You can call this function later on your object and retrieve the value of the slot. `:writer' Name of a generic function which will write this slot. `:reader' Name of a generic function which will read this slot. Some tags which are unique to EIEIO are: `:custom' A custom :type specifier used when editing an object of this type. See documentation for `defcustom' for details. This specifier is equivalent to the :type field of a `defcustom' call. `:label' When customizing an object, the value of :label will be used instead of the slot name. This enables better descriptions of the data than would usually be afforded. `:group' Similar to `defcustom''s :group command, this organizes different slots in an object into groups. When customizing an object, only the slots belonging to a specific group need be worked with, simplifying the size of the display. `:protection' A CLOS unsupported specifier which indicates that only methods of this class may access this slot. When using a slot referencing function, if the value behind SLOT is private or protected, then the current scope of operation must be within a method of the calling object. Valid values are: `:public' Anyone may access this slot from any scope. `:protected' Only methods of the same class, or of a child class may access this slot. `:private' Only methods of the same class as this slot's definition may access this slot. Additionally, CLOS style class options are available. These are various options attached to a class. These options can occur in place or in addition to a documentation string. If both occur, then the options appear before the documentation string. In CLOS, documentation is one of the options available to a class, so the ability to have a standalone documentation string is specific to Emacs. Possible class options are: `:documentation' Doc string to use for this class. If an Emacs style documentation string is also provided, then this option is ignored. `:allow-nil-initform' This is not a CLOS option. If this option is non-nil, and the `:initform' is `nil', but the `:type' is specifies something such as `string' then allow this to pass. The default is to have this option be off. This is implemented as an alternative to unbound slots. `:abstract' This is not a CLOS option. Tags a class as being abstract, or uninstantiable. `:custom-groups' This is a list of groups that can be customized within this class. This slot is auto-generated when a class is created and need not be specified. It can be retrieved with the `class-option' command, however, to see what groups are available. `:metaclass' Unsupported CLOS option. Enables the use of a different base class other than `standard-class'. `:default-initargs' Unsupported CLOS option. Specifies a list of initargs to be used when creating new objects. As far as I can tell, this duplicates the function of `:initform'. *Note CLOS compatibility::, for more details on CLOS tags versus EIEIO specific tags. The whole definition may look like this: (defclass data-object () ((value :initarg :value :initform nil :accessor get-value :documentation "Lisp object which represents the data this object maintains." :protection :protected) (reference :initarg :reference :initform nil :type list :custom (repeat object) :documentation "List of objects looking at this object. The method `update-symbol' is called for each member of `reference' whenever `value' is modified." :protection :protected) ) "Data object which tracks referencers.") - Variable: eieio-error-unsupported-class-tags If Non-nil, then `defclass' will throw an error if a tag in a slot specifier is unsupported.  File: eieio.info, Node: Default Superclass, Next: Making New Objects, Prev: Building Classes, Up: Top Default Superclass ****************** All defined classes, if created as a superclass (With no specified parent class) will actually inherit from a special superclass stored in `eieio-default-superclass'. This superclass is actually quite simple, but with it, certain default methods or attributes can be added to all objects at any time, without updating their code in the future (If there is a change). In CLOS, this would be named `STANDARD-CLASS' and is aliased. Currently, the default superclass is defined as follows: (defclass eieio-default-superclass nil nil ) "Default class used as parent class for superclasses. It's slots are automatically adopted by such superclasses but not stored in the `parent' slot. When searching for attributes or methods, when the last parent is found, the search will recurse to this class.") When creating an object of any type, you can use it's constructor, or `make-instance'. This, in turns calls the method `initialize-instance', which then calls the method `shared-initialize'. - Function: initialize-instance obj &rest slots Initialize OBJ. Sets slots of OBJ with SLOTS which is a list of name/value pairs. These are actually just passed to `shared-initialize'. - Function: shared-initialize obj &rest slots Sets slots of OBJ with SLOTS which is a list of name/value pairs. These methods are used to override errors: - Function: slot-missing object slot operation &optional new-value This method is called when there is an attempt to access a slot that does not exist for a given object. The default method signals an error of type `invalid-slot-name'. *Note Signals::. You may override this behavior, but it is not expected to return in the current implementation. This function takes arguments in a different order than in CLOS. - Function: slot-unbound object class slot-name fn This method is called when there is an attempt to access a slot that is not bound. This will throw an `unbound-slot' signal. If overridden it's return value will be returned from the function attempting to reference its value. - Function: no-applicable-method object method This method is called when there is an attempt to call a method on OBJECT when there is no method to call. The default method throws a `no-method-definition' signal. The return value of this function becomes the return value of the non-existent method. - Function: no-next-method object args This method is called when an attempt to call `call-next-method' is made, and there is no next method that can be called. The return value becomes the return value of `call-next-method'. Additional useful methods are: - Function: clone obj &rest params Make a deep copy of OBJ. Once this copy is made, make modifications specified by PARAMS. PARAMS uses the same format as the SLOTS of `initialize-instance'. The only other change is to modify the name with an incrementing numeric. - Function: object-print obj &rest strings Construct a printing lisp symbol for OBJ. This would look like: # STRINGS are additional parameters passed in by overloading functions to add more data into the printing abbreviation. (defclass data-object () (value) "Object containing one data slot.") (defmethod object-print ((this data-object) &optional strings) "Return a string with a summary of the data object as part of the name." (apply 'call-next-method this (cons (format " value: %s" (render this)) strings))) here is what some output could look like: (object-print test-object) => # - Function: object-write obj &optional comment Write OBJ onto a stream in a readable fashion. The resulting output will be lisp code which can be used with `read' and `eval' to recover the object. Only slots with `:initarg's are written to the stream.  File: eieio.info, Node: Making New Objects, Next: Accessing Slots, Prev: Default Superclass, Up: Top Making New Objects ****************** Once we have defined our classes, it's time to create objects with the specified structure. After we call `defclass' two new functions are created, one of which is `classname'. Thus, from the example at the end of the previous chapter *Note Building Classes::, we would have the functions `data-object' and `data-object-p'. - Function: classname object-name &rest slots This creates and returns a new object. This object is not assigned to anything, and will be garbage collected if not saved. This object will be given the string name OBJECT-NAME. There can be multiple objects of the same name, but the name slot provides a handy way to keep track of your objects. SLOTS is just all the slots you wish to preset. Any slot set as such WILL NOT get it's default value, and any side effects from an attributes default function will not occur. An example pair would appear simply as `:value 1'. Of course you can do any valid lispy thing you want with it, such as `:value (if (boundp 'special-symbol) special-symbol nil)' Example of creating an object from a class, *Note Building Classes::: (data-object "test" :value 3 :reference nil)  File: eieio.info, Node: Accessing Slots, Next: Writing Methods, Prev: Making New Objects, Up: Top Accessing Slots *************** There are several ways to access slot values in an object. The naming convention and argument order is similar to that found in Emacs Lisp for referencing vectors. The basics for referencing, setting, and calling methods are all accounted for. - Function: oset object slot value This sets the value behind SLOT to VALUE in OBJECT. `oset' returns VALUE. - Function: oset-default class slot value This sets the slot SLOT in CLASS which is initialized with the `:initform' tag to VALUE. This will allow a user to set both public and private defaults after the class has been constructed. This function is intrusive, and is offered as a way to allow users to configure the default behavior of packages built with classes the same way `setq-default' is used for buffer-local variables. For example, if a user wanted all `data-objects' (*note Building Classes::) to inform a special object of his own devising when they changed, this can be arranged by simply executing this bit of code: (oset-default data-object reference (list my-special-object)) - Function: oref object slot This recalls the value in slot SLOT in OBJECT and returns it. If OBJECT is a class, and SLOT is a class allocated slot, then oref will return that value. If OBJECT is a class, and SLOT is not class allocated, a signal will be thrown. - Function: oref-default object slot This gets the default value in OBJECT's class definition for `slot'. This can be different from the value returned by `oref'. OBJECT can also be a class symbol or an instantiated object. These next accessors are defined by CLOS to reference or modify slot values, and use the previously mentioned set/ref routines. - Function: slot-value object slot This function retrieves the value of SLOT from OBJECT. Unlike `oref', the symbol for SLOT must be quoted in. - Function: set-slot-value object slot value This is not a CLOS function, but is meant to mirror `slot-value' if you don't want to use the cl package's `setf' function. This function sets the value of SLOT from OBJECT. Unlike `oset', the symbol for SLOT must be quoted in. - Function: slot-makeunbound object slot This function unbinds SLOT in OBJECT. Referencing an unbound slot can throw an error. - Function: object-add-to-list object slot &optional append In OBJECT's SLOT, add ITEM to the pre-existing list of elements. Optional argument APPEND indicates we need to append to the list. If ITEM already exists in the list in SLOT, then it is not added. Comparison is done with "equal" through the "member" function call. If SLOT is unbound, bind it to the list containing ITEM. - Function: with-slots entries object forms Bind ENTRIES lexically to the specified slot values in OBJECT, and execute FORMS. In CLOS, it would be possible to set values in OBJECT by using `setf' to assign to these values, but in Emacs, you may only read the values, or set the local variable to a new value. (defclass myclass () (x :initarg 1)) (setq mc (make-instance 'myclass)) (with-slots (x) mc x) => 1 (with-slots ((something x)) mc something) => 1  File: eieio.info, Node: Writing Methods, Next: Predicates, Prev: Accessing Slots, Up: Top Writing Methods *************** Writing a CLOS style method is similar to writing a function. The differences are that there are some extra options and there can be multiple implementations of a single method which interact interestingly with each other. Each method created verifies that there is a "generic method" available to attach to. A generic method has no body, and is merely a symbol upon which methods are attached. - Function: defgeneric method arglist [doc-string] METHOD is the unquoted symbol to turn into a function. ARGLIST is the default list of arguments to use (not implemented yet). DOC-STRING is the documentation used for this symbol. A generic function acts as a place holder for methods. There is no need to call `defgeneric' yourself, as `defmethod' will call it if necessary. Currently the argument list is unused. `defgeneric' will prevent you from turning an existing emacs lisp function into a generic function. - Function: defmethod method [:BEFORE | :PRIMARY | :AFTER | :STATIC ] arglist [doc-string] forms METHOD is the name of the function to be created. :BEFORE | :AFTER represent when this form is to be called. If neither of these symbols are present, then the default priority is, before :AFTER, after :BEFORE, and is represented in CLOS as PRIMARY. If :STATIC is used, then the first argument when calling this function can be a class or an object. Never treat the first argument of a STATIC method as an object, always used `oref-default' or `oset-default'. A Class' construction is defined as a static method. `arglist' is the argument list. Unlike CLOS, only the FIRST argument may be type-cast, and it may only be type-cast to an EIEIO object. An arglist such as `(a b)' would classify the function as generic call, which has no object it can talk to (none is passed in) and merely allows the creation of side-effects. If the arglist appears as `((this data-object) b)' then the form is stored as belonging to the class `data-object'. The first argument does not need to be typecast. A method with no typecast is a `generic'. If a given class has no implementation, then the generic will be called when that method is used on a given object of that class. If two `defmethod's appear with arglists such as `(a b)' and `(c d)' then one of the implementations will be overwritten, but generic and multiple type cast arglists can co-exist. When called, if there is a method cast against the object's parent class, but not for that object's class, the parent class' method will be called. If there is a method defined for both, only the child's method is called. DOC-STRING is the documentation attached to the implementation. All method doc-strings are concatenated into the generic method's function documentation. FORMS is the body of the function. If multiple methods and generics are defined for the same method name, they are executed in this order: method :BEFORE generic :BEFORE method :PRIMARY generic :PRIMARY method :AFTER generic :AFTER If in any situation a method does not exist, but a generic does, then the generic is called in place of the method. If no methods exist, then the signal `no-method-definition' is thrown. *Note Signals:: See the file `eieio-test.el' for an example testing these differently tagged methods. - Function: call-next-method &rest replacement-args While running inside a CLOS method, calling this function will call the method associated with the parent of the class of the currently running method with the same parameters. If no next method is available, but a generic is implemented for the given key (Such as `:BEFORE'), then the generic will be called. OPTIONAL arguments REPLACEMENT-ARGS can be used to replace the arguments the next method would be called with. Useful if a child class wishes to add additional behaviors through the modification of the parameters. This is not a feature of CLOS. For example code *Note Default Superclass::. - Function: call-next-method-p Return t if there is a next method we can call. In this implementation, not all features of CLOS exist. 1. There is currently no :AROUND tag. 2. CLOS allows multiple sets of type-cast arguments, where eieio only allows the first argument to be cast.  File: eieio.info, Node: Predicates, Next: Association Lists, Prev: Writing Methods, Up: Top Predicates and Utilities ************************ Now that we know how to create classes, access slots, and define methods, it might be useful to verify that everything is doing ok. To help with this a plethora of predicates have been created. - Function: class-v class Return a vector with all the class's important parts in it. This vector is not a copy. Changing this vector changes the class. The CLOS method `find-class' will have the same effect. - Function: find-class symbol &optional errorp CLOS function. In EIEIO it returns the vector definition of the class. If there is no class, `nil' is returned if ERRORP is `nil'. - Function: class-p class Return non-`nil' if CLASS is a class type. - Function: object-p obj Return non-`nil' if OBJ is an object. - Function: slot-exists-p obj-or-class slot Return Non-`nil' if OBJ-OR-CLASS contains SLOT in its class. - Function: slot-boundp object slot Non-`nil' if OBJECT's SLOT is bound. Setting a slot's value makes it bound. Calling "slot-makeunbound" will make a slot unbound. OBJECT can be an instance or a class. - Function: class-name class Return a string of the form # which should look similar to other lisp objects like buffers and processes. Printing a class results only in a symbol. - Function: class-option class option Return the value in CLASS of a given OPTION. For example: (class-option eieio-default-superclass :documentation) Will fetch the documentation string for `eieio-default-superclass'. - Function: class-constructor class Return a symbol used as a constructor for CLASS. This way you can make an object of a passed in class without knowing what it is. This is not a part of CLOS. - Function: object-name obj Return a string of the form # for 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 object's vector. It is more useful to use `object-print' to get and object's print form, as this allows the object to add extra display information into the symbol. - Function: object-class obj Returns the class symbol from OBJ. - Function: class-of obj CLOS symbol which does the same thing as `object-class' - Function: object-class-fast obj Same as `object-class' except this is a macro, and no type-checking is performed. - Function: object-class-name obj Returns the symbol of OBJ's class. - Function: class-parents class Returns the direct parents class of CLASS. Returns `nil' if it is a superclass. - Function: class-parents-fast class Just like `class-parent' except it is a macro and no type checking is performed. - Function: class-parent class Deprecated function which returns the first parent of CLASS. - Function: class-children class Return the list of classes inheriting from CLASS. - Function: class-children-fast class Just like `class-children', but with no checks. - Function: same-class-p obj class Returns `t' if OBJ's class is the same as CLASS. - Function: same-class-fast-p obj class Same as `same-class-p' except this is a macro and no type checking is performed. - Function: object-of-class-p obj class Returns `t' if OBJ inherits anything from CLASS. This is different from `same-class-p' because it checks for inheritance. - Function: child-of-class-p child class Returns `t' if CHILD is a subclass of CLASS. - Function: generic-p method-symbol Returns `t' if `method-symbol' is a generic function, as opposed to a regular emacs list function. It is also important to note, that for every created class, a two predicates are created for it. Thus in our example, the function `data-object-p' is created, and return `t' if passed an object of the appropriate type. Also, the function `data-object-child-p' is created which returns `t' if the object passed to it is of a type which inherits from `data-object'.  File: eieio.info, Node: Association Lists, Next: Introspection, Prev: Predicates, Up: Top Association Lists ***************** Lisp offers the concept of association lists, with primitives such as `assoc' used to access them. Eieio provides a few such functions to help with using lists of objects easily. - Function: object-assoc key slot list Returns the first object in LIST for which KEY is in SLOT. - Function: object-assoc-list slot list Return an association list generated by extracting SLOT from all objects in LIST. For each element of LIST the `car' is the value of SLOT, and the `cdr' is the object it was extracted from. This is useful for generating completion tables. - Function: eieio-build-class-alist &optional base-class Returns an alist of all currently defined classes. This alist is suitable for completion lists used by interactive functions to select a class. The optional argument BASE-CLASS allows the programmer to select only a subset of classes to choose from should it prove necessary.  File: eieio.info, Node: Introspection, Next: Signals, Prev: Association Lists, Up: Top Introspection ************* Introspection permits a programmer to peek at the contents of a class without any previous knowledge of that class. While EIEIO implements objects on top of vectors, and thus everything is technically visible, some functions have been provided. None of these functions are a part of CLOS. - Function: object-slots obj Return the list of public slots for OBJ. - Function: class-slot-initarg class slot For the given CLASS return the :initarg associated with SLOT. Not all slots have initargs, so the return value can be nil.  File: eieio.info, Node: Signals, Next: Base Classes, Prev: Introspection, Up: Top Signals ******* There are new signal types that can be caught when using eieio. - Signal: invalid-slot-name obj-or-class slot This signal is called when an attempt to reference a slot in an OBJ-OR-CLASS is made, and the SLOT is not defined for it. - Signal: no-method-definition method arguments This signal is called when METHOD is called, with ARGUMENTS and nothing is resolved. This occurs when METHOD has been defined, but the arguments make it impossible for eieio to determine which method body to run. Overload the method `no-method-definition' to protect against this signal. - Signal: no-next-method class arguments This signal is called if the function `call-next-method' is called and there is no next method to be called. Overload the method `no-next-method' to protect against this signal. - Signal: invalid-slot-type slot spec value This signal is called when an attempt to set SLOT is made, and VAR doesn't match the specified type SPEC. In EIEIO, this is also used of a slot specifier has an invalid value during a `defclass'. - Signal: unbound-slot object class slot This signal is called when an attempt to reference SLOT in OBJECT is made, and that instance is currently unbound.  File: eieio.info, Node: Base Classes, Next: Browsing, Prev: Signals, Up: Top Base Classes ************ Asside from `eieio-default-superclass', EIEIO comes with some additional classes that you can use. By using multiple inheritance, it is possible to use several features at the same time. * Menu: * eieio-instance-inheritor:: Enable value inheritance between instances. * eieio-instance-tracker:: Enable self tracking instances. * eieio-singleton:: Only one instance of a given class. * eieio-persistent:: Enable persistence for a class. * eieio-named:: Use the object name as a :name field. * eieio-speedbar:: Enable speedbar support in your objects.  File: eieio.info, Node: eieio-instance-inheritor, Next: eieio-instance-tracker, Prev: Base Classes, Up: Base Classes `eieio-instance-inheritor' ========================== This class is in package `eieio-base'. Instance inheritance is a mechanism whereby the value of a slot in object instance can reference the parent instance. If the parent's slot value is changed, then the child instance is also changed. If the child's slot is set, then the parent's slot is not modified. - Class: eieio-instance-inheritor parent-instance A class whose instances are enabled with instance inheritance. The PARENT-INSTANCE slot indicates the instance which is considered the parent of the current instance. Default is `nil'. To use this class, inherit from it with your own class. To make a new instance that inherits from and existing instance of your class, use the `clone' method with additional parameters to specify local values. The `eieio-instance-inheritor' class works by causing cloned objects to have all slots unbound. This class' `slot-unbound' method will cause references to unbound slots to be redirected to the parent instance. If the parent slot is also unbound, then `slot-unbound' will throw an `slot-unbound' signal.  File: eieio.info, Node: eieio-instance-tracker, Next: eieio-singleton, Prev: eieio-instance-inheritor, Up: Base Classes This class is in package `eieio-base'. Sometimes it is useful to keep a master list of all instances of a given class. The class `eieio-instance-tracker' performs this task. - Class: eieio-instance-tracker tracker-symbol Enable instance tracking for this class. The field TRACKER-SYMBOL should be initialized in inheritors of this class to a symbol created with `defvar'. This symbol will serve as the variable used as a master list of all objects of the given class. - Method on eieio-instance-tracker: initialize-instance obj fields This method is defined as an `:AFTER' method. It adds new instances to the master list. Do not overload this method unless you use `call-next-method.' - Method on eieio-instance-tracker: delete-instance obj Remove OBJ from the master list of instances of this class. This may let the garbage collector nab this instance. - eieio-instance-tracker-find: key field list-symbol This convenience function lets you find instances. KEY is the value to search for. FIELD is the field to compare KEY against. The function `equal' is used for comparison. The paramter LIST-SYMBOL is the variable symbol which contains the list of objects to be searched.  File: eieio.info, Node: eieio-singleton, Next: eieio-persistent, Prev: eieio-instance-tracker, Up: Base Classes `eieio-singleton' ================= This class is in package `eieio-base'. - Class: eieio-singleton Inheriting from the singleton class will guarantee that there will only ever be one instance of this class. Multiple calls to `make-instance' will always return the same object.  File: eieio.info, Node: eieio-persistent, Next: eieio-named, Prev: eieio-singleton, Up: Base Classes `eieio-persistent' ================== This class is in package `eieio-base'. If you want an object, or set of objects to be persistent, meaning the slot values are important to keep saved between sessions, then you will want your top level object to inherit from `eieio-persistent'. To make sure your persistent object can be moved, make sure all file names stored to disk are made relative with `eieio-persistent-path-relative'. - Class: eieio-persistent file file-header-line Enables persistence for instances of this class. Slot FILE with initarg `:file' is the file name in which this object will be saved. Class allocated slot FILE-HEADER-LINE is used with method `object-write' as a header comment. All objects can write themselves to a file, bu persistent objects have several additional methods that aid in maintaining them. - Method on eieio-persistent: eieio-save obj &optional file Write the object OBJ to its file. If optional argument FILE is specified, use that file name instead. - Method on eieio-persistent: eieio-persistent-path-relative obj file Return a file name derived from FILE which is relative to the stored location of OBJ. This method should be used to convert file names so that they are relative to the save file, making any system of files movable from one location to another. - Method on eieio-persistent: object-write obj &optional comment Like `object-write' for `standard-object', but will derive a header line comment from the class allocated slot if one is not provided. - Function: eieio-persistent-read filename Read FILENAME which contains an `eieio-persistent' object previously written with `eieio-persistent-save'.  File: eieio.info, Node: eieio-named, Next: eieio-speedbar, Prev: eieio-persistent, Up: Base Classes `eieio-named' ============= This class is in package `eieio-base'. - Class: eieio-named Object with a name. Name storage already occurs in an object. This object provides get/set access to it.  File: eieio.info, Node: eieio-speedbar, Prev: eieio-named, Up: Base Classes `eieio-speedbar' ================ This class is in package `eieio-speedbar'. If a series of class instances map to a tree structure, it is possible to cause your classes to be displayable in Speedbar. *Note Top: (speedbar)Top. Inheriting from these classes will enable a speedbar major display mode with a minimum of effort. - Class: eieio-speedbar buttontype buttonface Enables base speedbar display for a class. The slot BUTTONTYPE is any of the symbols allowed by the function `speedbar-make-tag-line' for the EXP-BUTTON-TYPE argument *Note Extending: (speedbar)Extending. The slot BUTTONFACE is the face to use for the text of the string displayed in speedbar. The slots BUTTONTYPE and BUTTONFACE are class allocated slots, and do not take up space in your instances. - Class: eieio-speedbar-directory-button buttontype buttonface This class inherits from `eieio-speedbar' and initializes BUTTONTYPE and BUTTONFACE to appear as directory level lines. - Class: eieio-speedbar-file-button buttontype buttonface This class inherits from `eieio-speedbar' and initializes BUTTONTYPE and BUTTONFACE to appear as file level lines. To use these classes, inherit from one of them in you class. You can use multiple inheritance with them safely. To customize your class for speedbar display, override the default values for BUTTONTYPE and BUTTONFACE to get the desired effects. Useful methods to define for your new class include: - Method on eieio-speedbar: eieio-speedbar-derive-line-path obj depth Return a string representing a directory associated with an instance of OBJ. DEPTH can be used to indice how many levels of indentation have been opened by the user where OBJ is shown. - Method on eieio-speedbar: eieio-speedbar-description obj Return a string description of OBJ. This is shown in the minibuffer or tooltip when the mouse hovers over this instance in speedbar. - Method on eieio-speedbar: eieio-speedbar-child-description obj Return a string representing a description of a child node of OBJ when that child is not an object. It is often useful to just use item info helper functions such as `speedbar-item-info-file-helper'. - Method on eieio-speedbar: eieio-speedbar-object-buttonname obj Return a string which is the text displayed in speedbar for OBJ. - Method on eieio-speedbar: eieio-speedbar-object-children obj Return a list of children of OBJ. - Method on eieio-speedbar: eieio-speedbar-child-make-tag-lines obj depth This method inserts a list of speedbar tag lines for OBJ to represent its children. Implement this method for your class if your children are not objects themselves. You still need to implement `eieio-speedbar-object-children'. In this method, use techniques specified in the Speedbar manual. *Note Extending: (speedbar)Extending. Some other functions you will need to learn to use are: - eieio-speedbar-create: make-map key-map menu name toplevelfn Register your object display mode with speedbar. MAKE-MAP is a function which initialized you keymap. KEY-MAP is a symbol you keymap is installed into. MENU is an easy menu vector representing menu items specific to your object display. NAME is a short string to use as a name identifying you mode. TOPLEVELFN is a function called which must return a list of objects representing those in the instance system you wish to browse in speedbar. Read the Extending chapter in the speedbar manual for more information on how speedbar modes work *Note Extending: (speedbar)Extending.  File: eieio.info, Node: Browsing, Next: Class Values, Prev: Base Classes, Up: Top Browsing class trees ******************** To browse all the currently loaded classes in emacs, simply run the EIEIO browser. `M-x eieio-browse'. This browses all the way from the default super-duper class eieio-default-superclass, and lists all children in an indented tree structure. To browse only from a specific class, pass it in as an alternate parameter. Here is a sample tree from our current example: eieio-default-superclass +--data-object +--data-object-symbol Note that we start with eieio-default-superclass. *Note Default Superclass::. Note: new classes are consed into the inheritance lists, so the tree comes out upside-down. It is also possible to use the function `eieio-class-tree' in the `tree.el' package. This will create an interactive tree. Clicking on nodes will allow expansion/contraction of branches, or editing of a class. *Note Class Values::.  File: eieio.info, Node: Class Values, Next: Customizing, Prev: Browsing, Up: Top Class Values ************ Details about any class or object can be retrieved using the function `eieio-describe-class' function. 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.  File: eieio.info, Node: Customizing, Next: Documentation, Prev: Class Values, Up: Top Customizing Objects ******************* In Emacs 20 a useful customization utility became available called `custom'. EIEIO supports custom through two new widget types. If a variable is declared as type `'object', then full editing of slots via the widgets is made possible. This should be used carefully, however, because objects modified are cloned, so if there are other references to these objects, they will no longer be linked together. If you want in place editing of objects, use the following methods: - Function: eieio-customize-object object Create a custom buffer and insert a widget for editing OBJECT. At the end, an `Apply' and `Reset' button are available. This will edit the object "in place" so references to it are also changed. There is no effort to prevent multiple edits of a singular object, so care must be taken by the user of this function. - Function: eieio-custom-widget-insert object flags This method inserts an edit object into the current buffer in place. It's sole code is `(widget-create 'object-edit :value object)' and is provided as a locale for adding tracking, or specializing the widget insert procedure for any object. To define a slot with an object in it, use the `object' tag. This widget type will be automatically converted to `object-edit' if you do in place editing of you object. If you want to have additional actions taken when a user clicks on the `Apply' button, then overload the method `eieio-done-customizing'. 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. Widget extention ================ When widgets are being created, one new widget extention has been added, called the `: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. (choice (const :tag "None" nil) :slotofchoices morestuff) and if the slot `morestuff' contains `(sym1 sym2 sym3)', the above example is converted into: (choice (const :tag "None" nil) (const sym1) (const sym2) (const sym3)) This is useful when a given item needs to be selected from a list of items defined in this second slot.  File: eieio.info, Node: Documentation, Next: Naming Conventions, Prev: Customizing, Up: Top Documentation ************* It is possible to automatically create documentation for your classes in texinfo format by using the tools in the file `eieio-doc.el' - Command: eieiodoc-class class indexstring &optional skiplist This will start at the current point, and created an indented menu of all the child classes of, and including CLASS, but skipping any classes that might be in SKIPLIST It will then create nodes for all these classes, subsection headings, and indexes. Each class will be indexed using the texinfo labeled index INDEXSTRING which is a two letter description. *Note (texinfo) New Indices::. To use this command, the texinfo macro @defindex @var { indexstring } where 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 `: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. Only classes loaded into emacs' memory can be documented.  File: eieio.info, Node: Naming Conventions, Next: Demo Programs, Prev: Documentation, Up: Top Naming Conventions ****************** The Emacs Lisp programming manual has a great chapter programming conventions that help keep each Emacs package working nicely with the entire system. *Note (elisp)Standards:: An EIEIO based program needs to follow these conventions, while simultaneously taking advantage of the Object Oriented features. The below tips are things that I do when I program an EIEIO based package. * Come up with a package prefix that is relatively short. Prefix all classes, and methods with your prefix. This is a standard convention for functions and variables in Emacs. * Do not prefix method names with the class name. All methods in EIEIO are "virtual", and are dynamically dispatched. Anyone can override your methods at any time. Your methods should be prefixed with your package name. * Do not prefix slots in your class. The slots are always locally scoped to your class, and need no prefixing. * If your library inherits from other libraries of classes, you must "require" that library with the `require' command.  File: eieio.info, Node: Demo Programs, Next: Function Index, Prev: Naming Conventions, Up: Top Demo Programs ************* There are many sample programs I have written for eieio which could become useful components of other applications, or are good stand alone programs providing some useful functionality. The file, and functionality of these appear below: `tree' Maintains and displays a tree structure in a buffer. Nodes in the tree can be clicked on for editing, node expansion, and simple information. Includes a sample program for showing directory trees, and to draw trees of the eieio class structures. `call-tree' Parses a non-byte-compiled function, and generates a call tree from it, and all sub-non-byte-compiled functions. Provides protection from recursive functions. `chart' Draw bar charts from data. Examples include displaying sizes of emacs values, file distribution, and rmail distributions.  File: eieio.info, Node: Function Index, Prev: Demo Programs, Up: Top Function Index ************** * Menu: * call-next-method: Writing Methods. * call-next-method-p: Writing Methods. * child-of-class-p: Predicates. * class-children: Predicates. * class-children-fast: Predicates. * class-constructor: Predicates. * class-name: Predicates. * class-of: Predicates. * class-option: Predicates. * class-p: Predicates. * class-parent: Predicates. * class-parents: Predicates. * class-parents-fast: Predicates. * class-slot-initarg: Introspection. * class-v: Predicates. * classname: Making New Objects. * clone: Default Superclass. * defclass: Building Classes. * defgeneric: Writing Methods. * defmethod: Writing Methods. * delete-instance on eieio-instance-tracker: eieio-instance-tracker. * eieio-build-class-alist: Association Lists. * eieio-custom-widget-insert: Customizing. * eieio-customize-object: Customizing. * eieio-persistent-path-relative on eieio-persistent: eieio-persistent. * eieio-persistent-read: eieio-persistent. * eieio-save on eieio-persistent: eieio-persistent. * eieio-speedbar-child-description on eieio-speedbar: eieio-speedbar. * eieio-speedbar-child-make-tag-lines on eieio-speedbar: eieio-speedbar. * eieio-speedbar-derive-line-path on eieio-speedbar: eieio-speedbar. * eieio-speedbar-description on eieio-speedbar: eieio-speedbar. * eieio-speedbar-object-buttonname on eieio-speedbar: eieio-speedbar. * eieio-speedbar-object-children on eieio-speedbar: eieio-speedbar. * eieiodoc-class: Documentation. * find-class: Predicates. * generic-p: Predicates. * initialize-instance: Default Superclass. * initialize-instance on eieio-instance-tracker: eieio-instance-tracker. * invalid-slot-name: Signals. * invalid-slot-type: Signals. * key: eieio-instance-tracker. * make-map: eieio-speedbar. * no-applicable-method: Default Superclass. * no-method-definition: Signals. * no-next-method <1>: Signals. * no-next-method: Default Superclass. * object-add-to-list: Accessing Slots. * object-assoc: Association Lists. * object-assoc-list: Association Lists. * object-class: Predicates. * object-class-fast: Predicates. * object-class-name: Predicates. * object-name: Predicates. * object-of-class-p: Predicates. * object-p: Predicates. * object-print: Default Superclass. * object-slots: Introspection. * object-write: Default Superclass. * object-write on eieio-persistent: eieio-persistent. * oref: Accessing Slots. * oref-default: Accessing Slots. * oset: Accessing Slots. * oset-default: Accessing Slots. * same-class-fast-p: Predicates. * same-class-p: Predicates. * set-slot-value: Accessing Slots. * shared-initialize: Default Superclass. * slot-boundp: Predicates. * slot-exists-p: Predicates. * slot-makeunbound: Accessing Slots. * slot-missing: Default Superclass. * slot-unbound: Default Superclass. * slot-value: Accessing Slots. * unbound-slot: Signals. * with-slots: Accessing Slots.  Tag Table: Node: Top154 Node: Introduction1730 Node: CLOS compatibility5038 Node: Building Classes7977 Node: Default Superclass16041 Node: Making New Objects20322 Node: Accessing Slots21696 Node: Writing Methods25168 Node: Predicates29855 Node: Association Lists34109 Node: Introspection35197 Node: Signals35870 Node: Base Classes37267 Node: eieio-instance-inheritor37995 Node: eieio-instance-tracker39266 Node: eieio-singleton40667 Node: eieio-persistent41087 Node: eieio-named42960 Node: eieio-speedbar43278 Node: Browsing47094 Node: Class Values48112 Node: Customizing48606 Node: Documentation51096 Node: Naming Conventions52655 Node: Demo Programs53868 Node: Function Index54847  End Tag Table