3. 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. See section 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. See (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.

See section 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.

[ << ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.