| 1 | \input texinfo |
| 2 | @setfilename ../../info/eieio |
| 3 | @set TITLE Enhanced Implementation of Emacs Interpreted Objects |
| 4 | @set AUTHOR Eric M. Ludlam |
| 5 | @settitle @value{TITLE} |
| 6 | |
| 7 | @c ************************************************************************* |
| 8 | @c @ Header |
| 9 | @c ************************************************************************* |
| 10 | |
| 11 | @copying |
| 12 | This manual documents EIEIO, an object framework for Emacs Lisp. |
| 13 | |
| 14 | Copyright @copyright{} 2007--2013 Free Software Foundation, Inc. |
| 15 | |
| 16 | @quotation |
| 17 | Permission is granted to copy, distribute and/or modify this document |
| 18 | under the terms of the GNU Free Documentation License, Version 1.3 or |
| 19 | any later version published by the Free Software Foundation; with no |
| 20 | Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' |
| 21 | and with the Back-Cover Texts as in (a) below. A copy of the license |
| 22 | is included in the section entitled ``GNU Free Documentation License.'' |
| 23 | |
| 24 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and |
| 25 | modify this GNU manual.'' |
| 26 | @end quotation |
| 27 | @end copying |
| 28 | |
| 29 | @dircategory Emacs misc features |
| 30 | @direntry |
| 31 | * EIEIO: (eieio). An objects system for Emacs Lisp. |
| 32 | @end direntry |
| 33 | |
| 34 | @titlepage |
| 35 | @center @titlefont{@value{TITLE}} |
| 36 | @sp 4 |
| 37 | @center by @value{AUTHOR} |
| 38 | @end titlepage |
| 39 | @page |
| 40 | |
| 41 | @macro eieio{} |
| 42 | @i{EIEIO} |
| 43 | @end macro |
| 44 | |
| 45 | @node Top, Quick Start, (dir), (dir) |
| 46 | @comment node-name, next, previous, up |
| 47 | @top EIEIO |
| 48 | |
| 49 | @eieio{} (``Enhanced Implementation of Emacs Interpreted Objects'') is |
| 50 | a CLOS (Common Lisp Object System) compatibility layer for Emacs Lisp. |
| 51 | It provides a framework for writing object-oriented applications in |
| 52 | Emacs. |
| 53 | |
| 54 | @ifnottex |
| 55 | @insertcopying |
| 56 | @end ifnottex |
| 57 | |
| 58 | @menu |
| 59 | * Quick Start:: Quick start for EIEIO. |
| 60 | * Introduction:: Why use @eieio{}? Basic overview, samples list. |
| 61 | * Building Classes:: How to write new class structures. |
| 62 | * Making New Objects:: How to construct new objects. |
| 63 | * Accessing Slots:: How to access a slot. |
| 64 | * Writing Methods:: How to write a method. |
| 65 | * Method Invocation:: How methods are invoked. |
| 66 | * Predicates:: Class-p, Object-p, etc-p. |
| 67 | * Association Lists:: List of objects as association lists. |
| 68 | * Customizing:: Customizing objects. |
| 69 | * Introspection:: Looking inside a class. |
| 70 | * Base Classes:: Additional classes you can inherit from. |
| 71 | * Browsing:: Browsing your class lists. |
| 72 | * Class Values:: Displaying information about a class or object. |
| 73 | * Documentation:: Automatically creating texinfo documentation. |
| 74 | * Default Superclass:: The root superclasses. |
| 75 | * Signals:: When you make errors. |
| 76 | * Naming Conventions:: Name your objects in an Emacs friendly way. |
| 77 | * CLOS compatibility:: What are the differences? |
| 78 | * Wish List:: Things about EIEIO that could be improved. |
| 79 | * GNU Free Documentation License:: The license for this documentation. |
| 80 | * Function Index:: |
| 81 | @end menu |
| 82 | |
| 83 | @node Quick Start |
| 84 | @chapter Quick Start |
| 85 | |
| 86 | @eieio{} provides an Object Oriented layer for Emacs Lisp. You can |
| 87 | use @eieio{} to create classes, methods for those classes, and |
| 88 | instances of classes. |
| 89 | |
| 90 | Here is a simple example of a class named @code{record}, containing |
| 91 | three slots named @code{name}, @code{birthday}, and @code{phone}: |
| 92 | |
| 93 | @example |
| 94 | (defclass record () ; No superclasses |
| 95 | ((name :initarg :name |
| 96 | :initform "" |
| 97 | :type string |
| 98 | :custom string |
| 99 | :documentation "The name of a person.") |
| 100 | (birthday :initarg :birthday |
| 101 | :initform "Jan 1, 1970" |
| 102 | :custom string |
| 103 | :type string |
| 104 | :documentation "The person's birthday.") |
| 105 | (phone :initarg :phone |
| 106 | :initform "" |
| 107 | :documentation "Phone number.")) |
| 108 | "A single record for tracking people I know.") |
| 109 | @end example |
| 110 | |
| 111 | Each class can have methods, which are defined like this: |
| 112 | |
| 113 | @example |
| 114 | (defmethod call-record ((rec record) &optional scriptname) |
| 115 | "Dial the phone for the record REC. |
| 116 | Execute the program SCRIPTNAME to dial the phone." |
| 117 | (message "Dialing the phone for %s" (oref rec name)) |
| 118 | (shell-command (concat (or scriptname "dialphone.sh") |
| 119 | " " |
| 120 | (oref rec phone)))) |
| 121 | @end example |
| 122 | |
| 123 | @noindent |
| 124 | In this example, the first argument to @code{call-record} is a list, |
| 125 | of the form (@var{varname} @var{classname}). @var{varname} is the |
| 126 | name of the variable used for the first argument; @var{classname} is |
| 127 | the name of the class that is expected as the first argument for this |
| 128 | method. |
| 129 | |
| 130 | @eieio{} dispatches methods based on the type of the first argument. |
| 131 | You can have multiple methods with the same name for different classes |
| 132 | of object. When the @code{call-record} method is called, the first |
| 133 | argument is examined to determine the class of that argument, and the |
| 134 | method matching the input type is then executed. |
| 135 | |
| 136 | Once the behavior of a class is defined, you can create a new |
| 137 | object of type @code{record}. Objects are created by calling the |
| 138 | constructor. The constructor is a function with the same name as your |
| 139 | class which returns a new instance of that class. Here is an example: |
| 140 | |
| 141 | @example |
| 142 | (setq rec (record "Eric" :name "Eric" :birthday "June" :phone "555-5555")) |
| 143 | @end example |
| 144 | |
| 145 | @noindent |
| 146 | The first argument is the name given to this instance. Each instance |
| 147 | is given a name, so different instances can be easily distinguished |
| 148 | when debugging. |
| 149 | |
| 150 | It can be a bit repetitive to also have a :name slot. To avoid doing |
| 151 | this, it is sometimes handy to use the base class @code{eieio-named}. |
| 152 | @xref{eieio-named}. |
| 153 | |
| 154 | Calling methods on an object is a lot like calling any function. The |
| 155 | first argument should be an object of a class which has had this |
| 156 | method defined for it. In this example it would look like this: |
| 157 | |
| 158 | @example |
| 159 | (call-record rec) |
| 160 | @end example |
| 161 | |
| 162 | @noindent |
| 163 | or |
| 164 | |
| 165 | @example |
| 166 | (call-record rec "my-call-script") |
| 167 | @end example |
| 168 | |
| 169 | In these examples, @eieio{} automatically examines the class of |
| 170 | @code{rec}, and ensures that the method defined above is called. If |
| 171 | @code{rec} is some other class lacking a @code{call-record} method, or |
| 172 | some other data type, Emacs signals a @code{no-method-definition} |
| 173 | error. @ref{Signals}. |
| 174 | |
| 175 | @node Introduction |
| 176 | @comment node-name, next, previous, up |
| 177 | @chapter Introduction |
| 178 | |
| 179 | Due to restrictions in the Emacs Lisp language, CLOS cannot be |
| 180 | completely supported, and a few functions have been added in place of |
| 181 | setf. |
| 182 | |
| 183 | @eieio{} supports the following features: |
| 184 | |
| 185 | @enumerate |
| 186 | @item |
| 187 | A structured framework for the creation of basic classes with attributes |
| 188 | and methods using singular inheritance similar to CLOS. |
| 189 | @item |
| 190 | Type checking, and slot unbinding. |
| 191 | @item |
| 192 | Method definitions similar to CLOS. |
| 193 | @item |
| 194 | Simple and complex class browsers. |
| 195 | @item |
| 196 | Edebug support for methods. |
| 197 | @item |
| 198 | Imenu updates. |
| 199 | @item |
| 200 | Byte compilation support of methods. |
| 201 | @item |
| 202 | Help system extensions for classes and methods. |
| 203 | @item |
| 204 | Automatic texinfo documentation generator. |
| 205 | @item |
| 206 | Several base classes for interesting tasks. |
| 207 | @item |
| 208 | Simple test suite. |
| 209 | @item |
| 210 | Public and private classifications for slots (extensions to CLOS) |
| 211 | @item |
| 212 | Customization support in a class (extension to CLOS) |
| 213 | @end enumerate |
| 214 | |
| 215 | Here are some CLOS features that @eieio{} presently lacks: |
| 216 | |
| 217 | @table @asis |
| 218 | @item Complete @code{defclass} tag support |
| 219 | All CLOS tags are currently supported, but the following are not |
| 220 | currently implemented correctly: |
| 221 | |
| 222 | @table @code |
| 223 | @item :metaclass |
| 224 | There is only one base superclass for all @eieio{} classes, which is |
| 225 | the @code{eieio-default-superclass}. |
| 226 | @item :default-initargs |
| 227 | Each slot has an @code{:initarg} tag, so this is not really necessary. |
| 228 | @end table |
| 229 | |
| 230 | @item Mock object initializers |
| 231 | Each class contains a mock object used for fast initialization of |
| 232 | instantiated objects. Using functions with side effects on object slot |
| 233 | values can potentially cause modifications in the mock object. @eieio{} |
| 234 | should use a deep copy but currently does not. |
| 235 | |
| 236 | @item @code{:around} method tag |
| 237 | This CLOS method tag is non-functional. |
| 238 | |
| 239 | @end table |
| 240 | |
| 241 | @node Building Classes |
| 242 | @comment node-name, next, previous, up |
| 243 | @chapter Building Classes |
| 244 | |
| 245 | A @dfn{class} is a definition for organizing data and methods |
| 246 | together. An @eieio{} class has structures similar to the classes |
| 247 | found in other object-oriented (OO) languages. |
| 248 | |
| 249 | To create a new class, use the @code{defclass} macro: |
| 250 | |
| 251 | @defmac defclass class-name superclass-list slot-list &rest options-and-doc |
| 252 | |
| 253 | Create a new class named @var{class-name}. The class is represented |
| 254 | by a self-referential symbol with the name @var{class-name}. @eieio{} |
| 255 | stores the structure of the class as a symbol property of |
| 256 | @var{class-name} (@pxref{Symbol Components,,,elisp,GNU Emacs Lisp |
| 257 | Reference Manual}). |
| 258 | |
| 259 | The @var{class-name} symbol's variable documentation string is a |
| 260 | modified version of the doc string found in @var{options-and-doc}. |
| 261 | Each time a method is defined, the symbol's documentation string is |
| 262 | updated to include the methods documentation as well. |
| 263 | |
| 264 | The parent classes for @var{class-name} is @var{superclass-list}. |
| 265 | Each element of @var{superclass-list} must be a class. These classes |
| 266 | are the parents of the class being created. Every slot that appears |
| 267 | in each parent class is replicated in the new class. |
| 268 | |
| 269 | If two parents share the same slot name, the parent which appears in |
| 270 | the @var{superclass-list} first sets the tags for that slot. If the |
| 271 | new class has a slot with the same name as the parent, the new slot |
| 272 | overrides the parent's slot. |
| 273 | |
| 274 | When overriding a slot, some slot attributes cannot be overridden |
| 275 | because they break basic OO rules. You cannot override @code{:type} |
| 276 | or @code{:protection}. |
| 277 | @end defmac |
| 278 | |
| 279 | @noindent |
| 280 | Whenever defclass is used to create a new class, two predicates are |
| 281 | created for it, named @code{@var{CLASS-NAME}-p} and |
| 282 | @code{@var{CLASS-NAME}-child-p}: |
| 283 | |
| 284 | @defun CLASS-NAME-p object |
| 285 | Return @code{t} if @var{OBJECT} is of the class @var{CLASS-NAME}. |
| 286 | @end defun |
| 287 | |
| 288 | @defun CLASS-NAME-child-p object |
| 289 | Return @code{t} if @var{OBJECT} is of the class @var{CLASS-NAME}, |
| 290 | or is of a subclass of @var{CLASS-NAME}. |
| 291 | @end defun |
| 292 | |
| 293 | @defvar eieio-error-unsupported-class-tags |
| 294 | If non-nil, @code{defclass} signals an error if a tag in a slot |
| 295 | specifier is unsupported. |
| 296 | |
| 297 | This option is here to support programs written with older versions of |
| 298 | @eieio{}, which did not produce such errors. |
| 299 | @end defvar |
| 300 | |
| 301 | @menu |
| 302 | * Inheritance:: How to specify parents classes. |
| 303 | * Slot Options:: How to specify features of a slot. |
| 304 | * Class Options:: How to specify features for this class. |
| 305 | @end menu |
| 306 | |
| 307 | @node Inheritance |
| 308 | @section Inheritance |
| 309 | |
| 310 | @dfn{Inheritance} is a basic feature of an object-oriented language. |
| 311 | In @eieio{}, a defined class specifies the super classes from which it |
| 312 | inherits by using the second argument to @code{defclass}. Here is an |
| 313 | example: |
| 314 | |
| 315 | @example |
| 316 | (defclass my-baseclass () |
| 317 | ((slot-A :initarg :slot-A) |
| 318 | (slot-B :initarg :slot-B)) |
| 319 | "My Baseclass.") |
| 320 | @end example |
| 321 | |
| 322 | @noindent |
| 323 | To subclass from @code{my-baseclass}, we specify it in the superclass |
| 324 | list: |
| 325 | |
| 326 | @example |
| 327 | (defclass my-subclass (my-baseclass) |
| 328 | ((specific-slot-A :initarg specific-slot-A) |
| 329 | ) |
| 330 | "My subclass of my-baseclass") |
| 331 | @end example |
| 332 | |
| 333 | @indent |
| 334 | Instances of @code{my-subclass} will inherit @code{slot-A} and |
| 335 | @code{slot-B}, in addition to having @code{specific-slot-A} from the |
| 336 | declaration of @code{my-subclass}. |
| 337 | |
| 338 | @eieio{} also supports multiple inheritance. Suppose we define a |
| 339 | second baseclass, perhaps an ``interface'' class, like this: |
| 340 | |
| 341 | @example |
| 342 | (defclass my-interface () |
| 343 | ((interface-slot :initarg :interface-slot)) |
| 344 | "An interface to special behavior." |
| 345 | :abstract t) |
| 346 | @end example |
| 347 | |
| 348 | @noindent |
| 349 | The interface class defines a special @code{interface-slot}, and also |
| 350 | specifies itself as abstract. Abstract classes cannot be |
| 351 | instantiated. It is not required to make interfaces abstract, but it |
| 352 | is a good programming practice. |
| 353 | |
| 354 | We can now modify our definition of @code{my-subclass} to use this |
| 355 | interface class, together with our original base class: |
| 356 | |
| 357 | @example |
| 358 | (defclass my-subclass (my-baseclass my-interface) |
| 359 | ((specific-slot-A :initarg specific-slot-A) |
| 360 | ) |
| 361 | "My subclass of my-baseclass") |
| 362 | @end example |
| 363 | |
| 364 | @noindent |
| 365 | With this, @code{my-subclass} also has @code{interface-slot}. |
| 366 | |
| 367 | If @code{my-baseclass} and @code{my-interface} had slots with the same |
| 368 | name, then the superclass showing up in the list first defines the |
| 369 | slot attributes. |
| 370 | |
| 371 | Inheritance in @eieio{} is more than just combining different slots. |
| 372 | It is also important in method invocation. @ref{Methods}. |
| 373 | |
| 374 | If a method is called on an instance of @code{my-subclass}, and that |
| 375 | method only has an implementation on @code{my-baseclass}, or perhaps |
| 376 | @code{my-interface}, then the implementation for the baseclass is |
| 377 | called. |
| 378 | |
| 379 | If there is a method implementation for @code{my-subclass}, and |
| 380 | another in @code{my-baseclass}, the implementation for |
| 381 | @code{my-subclass} can call up to the superclass as well. |
| 382 | |
| 383 | @node Slot Options |
| 384 | @section Slot Options |
| 385 | |
| 386 | The @var{slot-list} argument to @code{defclass} is a list of elements |
| 387 | where each element defines one slot. Each slot is a list of the form |
| 388 | |
| 389 | @example |
| 390 | (SLOT-NAME :TAG1 ATTRIB-VALUE1 |
| 391 | :TAG2 ATTRIB-VALUE2 |
| 392 | :TAGN ATTRIB-VALUEN) |
| 393 | @end example |
| 394 | |
| 395 | @noindent |
| 396 | where @var{SLOT-NAME} is a symbol that will be used to refer to the |
| 397 | slot. @var{:TAG} is a symbol that describes a feature to be set |
| 398 | on the slot. @var{ATTRIB-VALUE} is a lisp expression that will be |
| 399 | used for @var{:TAG}. |
| 400 | |
| 401 | Valid tags are: |
| 402 | |
| 403 | @table @code |
| 404 | @item :initarg |
| 405 | A symbol that can be used in the argument list of the constructor to |
| 406 | specify a value for the new instance being created. |
| 407 | |
| 408 | A good symbol to use for initarg is one that starts with a colon @code{:}. |
| 409 | |
| 410 | The slot specified like this: |
| 411 | @example |
| 412 | (myslot :initarg :myslot) |
| 413 | @end example |
| 414 | could then be initialized to the number 1 like this: |
| 415 | @example |
| 416 | (myobject "name" :myslot 1) |
| 417 | @end example |
| 418 | |
| 419 | @xref{Making New Objects}. |
| 420 | |
| 421 | @item :initform |
| 422 | A expression used as the default value for this slot. |
| 423 | |
| 424 | If @code{:initform} is left out, that slot defaults to being unbound. |
| 425 | It is an error to reference an unbound slot, so if you need |
| 426 | slots to always be in a bound state, you should always use an |
| 427 | @code{:initform} specifier. |
| 428 | |
| 429 | Use @code{slot-boundp} to test if a slot is unbound |
| 430 | (@pxref{Predicates}). Use @code{slot-makeunbound} to set a slot to |
| 431 | being unbound after giving it a value (@pxref{Accessing Slots}). |
| 432 | |
| 433 | The value passed to initform is automatically quoted. Thus, |
| 434 | @example |
| 435 | :initform (1 2 3) |
| 436 | @end example |
| 437 | appears as the specified list in the default object. |
| 438 | A symbol that is a function like this: |
| 439 | @example |
| 440 | :initform + |
| 441 | @end example |
| 442 | will set the initial value as that symbol. |
| 443 | |
| 444 | After a class has been created with @code{defclass}, you can change |
| 445 | that default value with @code{oset-default}. @ref{Accessing Slots}. |
| 446 | |
| 447 | @item :type |
| 448 | An unquoted type specifier used to validate data set into this slot. |
| 449 | @xref{Type Predicates,,,cl,Common Lisp Extensions}. |
| 450 | Here are some examples: |
| 451 | @table @code |
| 452 | @item symbol |
| 453 | A symbol. |
| 454 | @item number |
| 455 | A number type |
| 456 | @item my-class-name |
| 457 | An object of your class type. |
| 458 | @item (or null symbol) |
| 459 | A symbol, or nil. |
| 460 | @end table |
| 461 | |
| 462 | @item :allocation |
| 463 | Either :class or :instance (defaults to :instance) used to |
| 464 | specify how data is stored. Slots stored per instance have unique |
| 465 | values for each object. Slots stored per class have shared values for |
| 466 | each object. If one object changes a :class allocated slot, then all |
| 467 | objects for that class gain the new value. |
| 468 | |
| 469 | @item :documentation |
| 470 | Documentation detailing the use of this slot. This documentation is |
| 471 | exposed when the user describes a class, and during customization of an |
| 472 | object. |
| 473 | |
| 474 | @item :accessor |
| 475 | Name of a generic function which can be used to fetch the value of this slot. |
| 476 | You can call this function later on your object and retrieve the value |
| 477 | of the slot. |
| 478 | |
| 479 | This options is in the CLOS spec, but is not fully compliant in @eieio{}. |
| 480 | |
| 481 | @item :writer |
| 482 | Name of a generic function which will write this slot. |
| 483 | |
| 484 | This options is in the CLOS spec, but is not fully compliant in @eieio{}. |
| 485 | |
| 486 | @item :reader |
| 487 | Name of a generic function which will read this slot. |
| 488 | |
| 489 | This options is in the CLOS spec, but is not fully compliant in @eieio{}. |
| 490 | |
| 491 | @item :custom |
| 492 | A custom :type specifier used when editing an object of this type. |
| 493 | See documentation for @code{defcustom} for details. This specifier is |
| 494 | equivalent to the :type spec of a @code{defcustom} call. |
| 495 | |
| 496 | This options is specific to Emacs, and is not in the CLOS spec. |
| 497 | |
| 498 | @item :label |
| 499 | When customizing an object, the value of :label will be used instead |
| 500 | of the slot name. This enables better descriptions of the data than |
| 501 | would usually be afforded. |
| 502 | |
| 503 | This options is specific to Emacs, and is not in the CLOS spec. |
| 504 | |
| 505 | @item :group |
| 506 | Similar to @code{defcustom}'s :group command, this organizes different |
| 507 | slots in an object into groups. When customizing an object, only the |
| 508 | slots belonging to a specific group need be worked with, simplifying the |
| 509 | size of the display. |
| 510 | |
| 511 | This options is specific to Emacs, and is not in the CLOS spec. |
| 512 | |
| 513 | @item :printer |
| 514 | This routine takes a symbol which is a function name. The function |
| 515 | should accept one argument. The argument is the value from the slot |
| 516 | to be printed. The function in @code{object-write} will write the |
| 517 | slot value out to a printable form on @code{standard-output}. |
| 518 | |
| 519 | The output format MUST be something that could in turn be interpreted |
| 520 | with @code{read} such that the object can be brought back in from the |
| 521 | output stream. Thus, if you wanted to output a symbol, you would need |
| 522 | to quote the symbol. If you wanted to run a function on load, you |
| 523 | can output the code to do the construction of the value. |
| 524 | |
| 525 | @item :protection |
| 526 | When using a slot referencing function such as @code{slot-value}, and |
| 527 | the value behind @var{slot} is private or protected, then the current |
| 528 | scope of operation must be within a method of the calling object. |
| 529 | |
| 530 | Valid values are: |
| 531 | |
| 532 | @table @code |
| 533 | @item :public |
| 534 | Access this slot from any scope. |
| 535 | @item :protected |
| 536 | Access this slot only from methods of the same class or a child class. |
| 537 | @item :private |
| 538 | Access this slot only from methods of the same class. |
| 539 | @end table |
| 540 | |
| 541 | This options is specific to Emacs, and is not in the CLOS spec. |
| 542 | |
| 543 | @end table |
| 544 | |
| 545 | @node Class Options |
| 546 | @section Class Options |
| 547 | |
| 548 | In the @var{options-and-doc} arguments to @code{defclass}, the |
| 549 | following class options may be specified: |
| 550 | |
| 551 | @table @code |
| 552 | @item :documentation |
| 553 | A documentation string for this class. |
| 554 | |
| 555 | If an Emacs-style documentation string is also provided, then this |
| 556 | option is ignored. An Emacs-style documentation string is not |
| 557 | prefixed by the @code{:documentation} tag, and appears after the list |
| 558 | of slots, and before the options. |
| 559 | |
| 560 | @item :allow-nil-initform |
| 561 | If this option is non-nil, and the @code{:initform} is @code{nil}, but |
| 562 | the @code{:type} is specifies something such as @code{string} then allow |
| 563 | this to pass. The default is to have this option be off. This is |
| 564 | implemented as an alternative to unbound slots. |
| 565 | |
| 566 | This options is specific to Emacs, and is not in the CLOS spec. |
| 567 | |
| 568 | @item :abstract |
| 569 | A class which is @code{:abstract} cannot be instantiated, and instead |
| 570 | is used to define an interface which subclasses should implement. |
| 571 | |
| 572 | This option is specific to Emacs, and is not in the CLOS spec. |
| 573 | |
| 574 | @item :custom-groups |
| 575 | This is a list of groups that can be customized within this class. This |
| 576 | slot is auto-generated when a class is created and need not be |
| 577 | specified. It can be retrieved with the @code{class-option} command, |
| 578 | however, to see what groups are available. |
| 579 | |
| 580 | This option is specific to Emacs, and is not in the CLOS spec. |
| 581 | |
| 582 | @item :method-invocation-order |
| 583 | This controls the order in which method resolution occurs for |
| 584 | @code{:primary} methods in cases of multiple inheritance. The order |
| 585 | affects which method is called first in a tree, and if |
| 586 | @code{call-next-method} is used, it controls the order in which the |
| 587 | stack of methods are run. |
| 588 | |
| 589 | Valid values are: |
| 590 | |
| 591 | @table @code |
| 592 | @item :breadth-first |
| 593 | Search for methods in the class hierarchy in breadth first order. |
| 594 | This is the default. |
| 595 | @item :depth-first |
| 596 | Search for methods in the class hierarchy in a depth first order. |
| 597 | @item :c3 |
| 598 | Searches for methods in in a linearized way that most closely matches |
| 599 | what CLOS does when a monotonic class structure is defined. |
| 600 | @end table |
| 601 | |
| 602 | @xref{Method Invocation}, for more on method invocation order. |
| 603 | |
| 604 | @item :metaclass |
| 605 | Unsupported CLOS option. Enables the use of a different base class other |
| 606 | than @code{standard-class}. |
| 607 | |
| 608 | @item :default-initargs |
| 609 | Unsupported CLOS option. Specifies a list of initargs to be used when |
| 610 | creating new objects. As far as I can tell, this duplicates the |
| 611 | function of @code{:initform}. |
| 612 | @end table |
| 613 | |
| 614 | @xref{CLOS compatibility}, for more details on CLOS tags versus |
| 615 | @eieio{}-specific tags. |
| 616 | |
| 617 | @node Making New Objects |
| 618 | @comment node-name, next, previous, up |
| 619 | @chapter Making New Objects |
| 620 | |
| 621 | Suppose we have a simple class is defined, such as: |
| 622 | |
| 623 | @example |
| 624 | (defclass record () |
| 625 | ( ) "Doc String") |
| 626 | @end example |
| 627 | |
| 628 | @noindent |
| 629 | It is now possible to create objects of that class type. |
| 630 | |
| 631 | Calling @code{defclass} has defined two new functions. One is the |
| 632 | constructor @var{record}, and the other is the predicate, |
| 633 | @var{record-p}. |
| 634 | |
| 635 | @defun record object-name &rest slots |
| 636 | |
| 637 | This creates and returns a new object. This object is not assigned to |
| 638 | anything, and will be garbage collected if not saved. This object |
| 639 | will be given the string name @var{object-name}. There can be |
| 640 | multiple objects of the same name, but the name slot provides a handy |
| 641 | way to keep track of your objects. @var{slots} is just all the slots |
| 642 | you wish to preset. Any slot set as such @emph{will not} get its |
| 643 | default value, and any side effects from a slot's @code{:initform} |
| 644 | that may be a function will not occur. |
| 645 | |
| 646 | An example pair would appear simply as @code{:value 1}. Of course you |
| 647 | can do any valid Lispy thing you want with it, such as |
| 648 | @code{:value (if (boundp 'special-symbol) special-symbol nil)} |
| 649 | |
| 650 | Example of creating an object from a class: |
| 651 | |
| 652 | @example |
| 653 | (record "test" :value 3 :reference nil) |
| 654 | @end example |
| 655 | |
| 656 | @end defun |
| 657 | |
| 658 | To create an object from a class symbol, use @code{make-instance}. |
| 659 | |
| 660 | @defun make-instance class &rest initargs |
| 661 | @anchor{make-instance} |
| 662 | Make a new instance of @var{class} based on @var{initargs}. |
| 663 | @var{class} is a class symbol. For example: |
| 664 | |
| 665 | @example |
| 666 | (make-instance 'foo) |
| 667 | @end example |
| 668 | |
| 669 | @var{initargs} is a property list with keywords based on the @code{:initarg} |
| 670 | for each slot. For example: |
| 671 | |
| 672 | @example |
| 673 | (make-instance @code{'foo} @code{:slot1} value1 @code{:slotN} valueN) |
| 674 | @end example |
| 675 | |
| 676 | Compatibility note: |
| 677 | |
| 678 | If the first element of @var{initargs} is a string, it is used as the |
| 679 | name of the class. |
| 680 | |
| 681 | In @eieio{}, the class' constructor requires a name for use when printing. |
| 682 | @dfn{make-instance} in CLOS doesn't use names the way Emacs does, so the |
| 683 | class is used as the name slot instead when @var{initargs} doesn't start with |
| 684 | a string. |
| 685 | @end defun |
| 686 | |
| 687 | @node Accessing Slots |
| 688 | @comment node-name, next, previous, up |
| 689 | @chapter Accessing Slots |
| 690 | |
| 691 | There are several ways to access slot values in an object. The naming |
| 692 | and argument-order conventions are similar to those used for |
| 693 | referencing vectors (@pxref{Vectors,,,elisp,GNU Emacs Lisp Reference |
| 694 | Manual}). |
| 695 | |
| 696 | @defmac oset object slot value |
| 697 | This macro sets the value behind @var{slot} to @var{value} in |
| 698 | @var{object}. It returns @var{value}. |
| 699 | @end defmac |
| 700 | |
| 701 | @defmac oset-default class slot value |
| 702 | This macro sets the @code{:initform} for @var{slot} in @var{class} to |
| 703 | @var{value}. |
| 704 | |
| 705 | This allows the user to set both public and private defaults after the |
| 706 | class has been constructed, and provides a way to configure the |
| 707 | default behavior of packages built with classes (the same way |
| 708 | @code{setq-default} does for buffer-local variables). |
| 709 | |
| 710 | For example, if a user wanted all @code{data-objects} (@pxref{Building |
| 711 | Classes}) to inform a special object of his own devising when they |
| 712 | changed, this can be arranged by simply executing this bit of code: |
| 713 | |
| 714 | @example |
| 715 | (oset-default data-object reference (list my-special-object)) |
| 716 | @end example |
| 717 | @end defmac |
| 718 | |
| 719 | @defmac oref obj slot |
| 720 | @anchor{oref} |
| 721 | Retrieve the value stored in @var{obj} in the slot named by @var{slot}. |
| 722 | Slot is the name of the slot when created by @dfn{defclass} or the label |
| 723 | created by the @code{:initarg} tag. |
| 724 | @end defmac |
| 725 | |
| 726 | @defmac oref-default obj slot |
| 727 | @anchor{oref-default} |
| 728 | Gets the default value of @var{obj} (maybe a class) for @var{slot}. |
| 729 | The default value is the value installed in a class with the @code{:initform} |
| 730 | tag. @var{slot} can be the slot name, or the tag specified by the @code{:initarg} |
| 731 | tag in the @dfn{defclass} call. |
| 732 | @end defmac |
| 733 | |
| 734 | The following accessors are defined by CLOS to reference or modify |
| 735 | slot values, and use the previously mentioned set/ref routines. |
| 736 | |
| 737 | @defun slot-value object slot |
| 738 | @anchor{slot-value} |
| 739 | This function retrieves the value of @var{slot} from @var{object}. |
| 740 | Unlike @code{oref}, the symbol for @var{slot} must be quoted. |
| 741 | @end defun |
| 742 | |
| 743 | @defun set-slot-value object slot value |
| 744 | @anchor{set-slot-value} |
| 745 | This is not a CLOS function, but is meant to mirror @code{slot-value} if |
| 746 | you don't want to use the cl package's @code{setf} function. This |
| 747 | function sets the value of @var{slot} from @var{object}. Unlike |
| 748 | @code{oset}, the symbol for @var{slot} must be quoted. |
| 749 | @end defun |
| 750 | |
| 751 | @defun slot-makeunbound object slot |
| 752 | This function unbinds @var{slot} in @var{object}. Referencing an |
| 753 | unbound slot can signal an error. |
| 754 | @end defun |
| 755 | |
| 756 | @defun object-add-to-list object slot item &optional append |
| 757 | @anchor{object-add-to-list} |
| 758 | In OBJECT's @var{slot}, add @var{item} to the list of elements. |
| 759 | Optional argument @var{append} indicates we need to append to the list. |
| 760 | If @var{item} already exists in the list in @var{slot}, then it is not added. |
| 761 | Comparison is done with @dfn{equal} through the @dfn{member} function call. |
| 762 | If @var{slot} is unbound, bind it to the list containing @var{item}. |
| 763 | @end defun |
| 764 | |
| 765 | @defun object-remove-from-list object slot item |
| 766 | @anchor{object-remove-from-list} |
| 767 | In OBJECT's @var{slot}, remove occurrences of @var{item}. |
| 768 | Deletion is done with @dfn{delete}, which deletes by side effect |
| 769 | and comparisons are done with @dfn{equal}. |
| 770 | If @var{slot} is unbound, do nothing. |
| 771 | @end defun |
| 772 | |
| 773 | @defun with-slots spec-list object &rest body |
| 774 | @anchor{with-slots} |
| 775 | Bind @var{spec-list} lexically to slot values in @var{object}, and execute @var{body}. |
| 776 | This establishes a lexical environment for referring to the slots in |
| 777 | the instance named by the given slot-names as though they were |
| 778 | variables. Within such a context the value of the slot can be |
| 779 | specified by using its slot name, as if it were a lexically bound |
| 780 | variable. Both setf and setq can be used to set the value of the |
| 781 | slot. |
| 782 | |
| 783 | @var{spec-list} is of a form similar to @dfn{let}. For example: |
| 784 | |
| 785 | @example |
| 786 | ((VAR1 SLOT1) |
| 787 | SLOT2 |
| 788 | SLOTN |
| 789 | (VARN+1 SLOTN+1)) |
| 790 | @end example |
| 791 | |
| 792 | Where each @var{var} is the local variable given to the associated |
| 793 | @var{slot}. A slot specified without a variable name is given a |
| 794 | variable name of the same name as the slot. |
| 795 | |
| 796 | @example |
| 797 | (defclass myclass () (x :initarg 1)) |
| 798 | (setq mc (make-instance 'myclass)) |
| 799 | (with-slots (x) mc x) => 1 |
| 800 | (with-slots ((something x)) mc something) => 1 |
| 801 | @end example |
| 802 | @end defun |
| 803 | |
| 804 | @node Writing Methods |
| 805 | @comment node-name, next, previous, up |
| 806 | @chapter Writing Methods |
| 807 | |
| 808 | Writing a method in @eieio{} is similar to writing a function. The |
| 809 | differences are that there are some extra options and there can be |
| 810 | multiple definitions under the same function symbol. |
| 811 | |
| 812 | Where a method defines an implementation for a particular data type, a |
| 813 | @dfn{generic method} accepts any argument, but contains no code. It |
| 814 | is used to provide the dispatching to the defined methods. A generic |
| 815 | method has no body, and is merely a symbol upon which methods are |
| 816 | attached. It also provides the base documentation for what methods |
| 817 | with that name do. |
| 818 | |
| 819 | @menu |
| 820 | * Generics:: |
| 821 | * Methods:: |
| 822 | * Static Methods:: |
| 823 | @end menu |
| 824 | |
| 825 | @node Generics |
| 826 | @section Generics |
| 827 | |
| 828 | Each @eieio{} method has one corresponding generic. This generic |
| 829 | provides a function binding and the base documentation for the method |
| 830 | symbol (@pxref{Symbol Components,,,elisp,GNU Emacs Lisp Reference |
| 831 | Manual}). |
| 832 | |
| 833 | @defmac defgeneric method arglist [doc-string] |
| 834 | This macro turns the (unquoted) symbol @var{method} into a function. |
| 835 | @var{arglist} is the default list of arguments to use (not implemented |
| 836 | yet). @var{doc-string} is the documentation used for this symbol. |
| 837 | |
| 838 | A generic function acts as a placeholder for methods. There is no |
| 839 | need to call @code{defgeneric} yourself, as @code{defmethod} will call |
| 840 | it if necessary. Currently the argument list is unused. |
| 841 | |
| 842 | @code{defgeneric} signals an error if you attempt to turn an existing |
| 843 | Emacs Lisp function into a generic function. |
| 844 | |
| 845 | You can also create a generic method with @code{defmethod} |
| 846 | (@pxref{Methods}). When a method is created and there is no generic |
| 847 | method in place with that name, then a new generic will be created, |
| 848 | and the new method will use it. |
| 849 | @end defmac |
| 850 | |
| 851 | In CLOS, a generic call also be used to provide an argument list and |
| 852 | dispatch precedence for all the arguments. In @eieio{}, dispatching |
| 853 | only occurs for the first argument, so the @var{arglist} is not used. |
| 854 | |
| 855 | @node Methods |
| 856 | @section Methods |
| 857 | |
| 858 | A method is a function that is executed if the first argument passed |
| 859 | to it matches the method's class. Different @eieio{} classes may |
| 860 | share the same method names. |
| 861 | |
| 862 | Methods are created with the @code{defmethod} macro, which is similar |
| 863 | to @code{defun}. |
| 864 | |
| 865 | @defmac defmethod method [:before | :primary | :after | :static ] arglist [doc-string] forms |
| 866 | |
| 867 | @var{method} is the name of the function to create. |
| 868 | |
| 869 | @code{:before} and @code{:after} specify execution order (i.e., when |
| 870 | this form is called). If neither of these symbols are present, the |
| 871 | default priority is used (before @code{:after} and after |
| 872 | @code{:before}); this default priority is represented in CLOS as |
| 873 | @code{:primary}. |
| 874 | |
| 875 | @b{Note:} The @code{:BEFORE}, @code{:PRIMARY}, @code{:AFTER}, and |
| 876 | @code{:STATIC} method tags were in all capital letters in previous |
| 877 | versions of @eieio{}. |
| 878 | |
| 879 | @var{arglist} is the list of arguments to this method. The first |
| 880 | argument in this list---and @emph{only} the first argument---may have |
| 881 | a type specifier (see the example below). If no type specifier is |
| 882 | supplied, the method applies to any object. |
| 883 | |
| 884 | @var{doc-string} is the documentation attached to the implementation. |
| 885 | All method doc-strings are incorporated into the generic method's |
| 886 | function documentation. |
| 887 | |
| 888 | @var{forms} is the body of the function. |
| 889 | |
| 890 | @end defmac |
| 891 | |
| 892 | @noindent |
| 893 | In the following example, we create a method @code{mymethod} for the |
| 894 | @code{classname} class: |
| 895 | |
| 896 | @example |
| 897 | (defmethod mymethod ((obj classname) secondarg) |
| 898 | "Doc string" ) |
| 899 | @end example |
| 900 | |
| 901 | @noindent |
| 902 | This method only executes if the @var{obj} argument passed to it is an |
| 903 | @eieio{} object of class @code{classname}. |
| 904 | |
| 905 | A method with no type specifier is a @dfn{default method}. If a given |
| 906 | class has no implementation, then the default method is called when |
| 907 | that method is used on a given object of that class. |
| 908 | |
| 909 | Only one default method per execution specifier (@code{:before}, |
| 910 | @code{:primary}, or @code{:after}) is allowed. If two |
| 911 | @code{defmethod}s appear with @var{arglist}s lacking a type specifier, |
| 912 | and having the same execution specifier, then the first implementation |
| 913 | is replaced. |
| 914 | |
| 915 | When a method is called on an object, but there is no method specified |
| 916 | for that object, but there is a method specified for object's parent |
| 917 | class, the parent class' method is called. If there is a method |
| 918 | defined for both, only the child's method is called. A child method |
| 919 | may call a parent's method using @code{call-next-method}, described |
| 920 | below. |
| 921 | |
| 922 | If multiple methods and default methods are defined for the same |
| 923 | method and class, they are executed in this order: |
| 924 | |
| 925 | @enumerate |
| 926 | @item method :before |
| 927 | @item default :before |
| 928 | @item method :primary |
| 929 | @item default :primary |
| 930 | @item method :after |
| 931 | @item default :after |
| 932 | @end enumerate |
| 933 | |
| 934 | If no methods exist, Emacs signals a @code{no-method-definition} |
| 935 | error. @xref{Signals}. |
| 936 | |
| 937 | @defun call-next-method &rest replacement-args |
| 938 | @anchor{call-next-method} |
| 939 | |
| 940 | This function calls the superclass method from a subclass method. |
| 941 | This is the ``next method'' specified in the current method list. |
| 942 | |
| 943 | If @var{replacement-args} is non-@code{nil}, then use them instead of |
| 944 | @code{eieio-generic-call-arglst}. At the top level, the generic |
| 945 | argument list is passed in. |
| 946 | |
| 947 | Use @code{next-method-p} to find out if there is a next method to |
| 948 | call. |
| 949 | @end defun |
| 950 | |
| 951 | @defun next-method-p |
| 952 | @anchor{next-method-p} |
| 953 | Non-@code{nil} if there is a next method. |
| 954 | Returns a list of lambda expressions which is the @code{next-method} |
| 955 | order. |
| 956 | @end defun |
| 957 | |
| 958 | At present, @eieio{} does not implement all the features of CLOS: |
| 959 | |
| 960 | @enumerate |
| 961 | @item |
| 962 | There is currently no @code{:around} tag. |
| 963 | @item |
| 964 | CLOS allows multiple sets of type-cast arguments, but @eieio{} only |
| 965 | allows the first argument to be cast. |
| 966 | @end enumerate |
| 967 | |
| 968 | @node Static Methods |
| 969 | @section Static Methods |
| 970 | |
| 971 | Static methods do not depend on an object instance, but instead |
| 972 | operate on an object's class. You can create a static method by using |
| 973 | the @code{:static} key with @code{defmethod}. |
| 974 | |
| 975 | Do not treat the first argument of a @code{:static} method as an |
| 976 | object unless you test it first. Use the functions |
| 977 | @code{oref-default} or @code{oset-default} which will work on a class, |
| 978 | or on the class of an object. |
| 979 | |
| 980 | A Class' @code{constructor} method is defined as a @code{:static} |
| 981 | method. |
| 982 | |
| 983 | @b{Note:} The @code{:static} keyword is unique to @eieio{}. |
| 984 | |
| 985 | @c TODO - Write some more about static methods here |
| 986 | |
| 987 | @node Method Invocation |
| 988 | @chapter Method Invocation |
| 989 | |
| 990 | When classes are defined, you can specify the |
| 991 | @code{:method-invocation-order}. This is a feature specific to EIEIO. |
| 992 | |
| 993 | This controls the order in which method resolution occurs for |
| 994 | @code{:primary} methods in cases of multiple inheritance. The order |
| 995 | affects which method is called first in a tree, and if |
| 996 | @code{call-next-method} is used, it controls the order in which the |
| 997 | stack of methods are run. |
| 998 | |
| 999 | The original EIEIO order turned out to be broken for multiple |
| 1000 | inheritance, but some programs depended on it. As such this option |
| 1001 | was added when the default invocation order was fixed to something |
| 1002 | that made more sense in that case. |
| 1003 | |
| 1004 | Valid values are: |
| 1005 | |
| 1006 | @table @code |
| 1007 | @item :breadth-first |
| 1008 | Search for methods in the class hierarchy in breadth first order. |
| 1009 | This is the default. |
| 1010 | @item :depth-first |
| 1011 | Search for methods in the class hierarchy in a depth first order. |
| 1012 | @item :c3 |
| 1013 | Searches for methods in in a linearized way that most closely matches |
| 1014 | what CLOS does when CLOS when a monotonic class structure is defined. |
| 1015 | |
| 1016 | This is derived from the Dylan language documents by |
| 1017 | Kim Barrett et al.: A Monotonic Superclass Linearization for Dylan |
| 1018 | Retrieved from: http://192.220.96.201/dylan/linearization-oopsla96.html |
| 1019 | @end table |
| 1020 | |
| 1021 | @node Predicates |
| 1022 | @comment node-name, next, previous, up |
| 1023 | @chapter Predicates and Utilities |
| 1024 | |
| 1025 | Now that we know how to create classes, access slots, and define |
| 1026 | methods, it might be useful to verify that everything is doing ok. To |
| 1027 | help with this a plethora of predicates have been created. |
| 1028 | |
| 1029 | @defun find-class symbol &optional errorp |
| 1030 | @anchor{find-class} |
| 1031 | Return the class that @var{symbol} represents. |
| 1032 | If there is no class, @code{nil} is returned if @var{errorp} is @code{nil}. |
| 1033 | If @var{errorp} is non-@code{nil}, @code{wrong-argument-type} is signaled. |
| 1034 | @end defun |
| 1035 | |
| 1036 | @defun class-p class |
| 1037 | @anchor{class-p} |
| 1038 | Return @code{t} if @var{class} is a valid class vector. |
| 1039 | @var{class} is a symbol. |
| 1040 | @end defun |
| 1041 | |
| 1042 | @defun slot-exists-p object-or-class slot |
| 1043 | @anchor{slot-exists-p} |
| 1044 | Non-@code{nil} if @var{object-or-class} has @var{slot}. |
| 1045 | @end defun |
| 1046 | |
| 1047 | @defun slot-boundp object slot |
| 1048 | @anchor{slot-boundp} |
| 1049 | Non-@code{nil} if OBJECT's @var{slot} is bound. |
| 1050 | Setting a slot's value makes it bound. Calling @dfn{slot-makeunbound} will |
| 1051 | make a slot unbound. |
| 1052 | @var{object} can be an instance or a class. |
| 1053 | @end defun |
| 1054 | |
| 1055 | @defun class-name class |
| 1056 | Return a string of the form @samp{#<class myclassname>} which should look |
| 1057 | similar to other Lisp objects like buffers and processes. Printing a |
| 1058 | class results only in a symbol. |
| 1059 | @end defun |
| 1060 | |
| 1061 | @defun class-option class option |
| 1062 | Return the value in @var{CLASS} of a given @var{OPTION}. |
| 1063 | For example: |
| 1064 | |
| 1065 | @example |
| 1066 | (class-option eieio-default-superclass :documentation) |
| 1067 | @end example |
| 1068 | |
| 1069 | Will fetch the documentation string for @code{eieio-default-superclass}. |
| 1070 | @end defun |
| 1071 | |
| 1072 | @defun class-constructor class |
| 1073 | Return a symbol used as a constructor for @var{class}. The |
| 1074 | constructor is a function used to create new instances of |
| 1075 | @var{CLASS}. This function provides a way to make an object of a class |
| 1076 | without knowing what it is. This is not a part of CLOS. |
| 1077 | @end defun |
| 1078 | |
| 1079 | @defun object-name obj |
| 1080 | Return a string of the form @samp{#<object-class myobjname>} for @var{obj}. |
| 1081 | This should look like Lisp symbols from other parts of Emacs such as |
| 1082 | buffers and processes, and is shorter and cleaner than printing the |
| 1083 | object's vector. It is more useful to use @code{object-print} to get |
| 1084 | and object's print form, as this allows the object to add extra display |
| 1085 | information into the symbol. |
| 1086 | @end defun |
| 1087 | |
| 1088 | @defun object-class obj |
| 1089 | Returns the class symbol from @var{obj}. |
| 1090 | @end defun |
| 1091 | |
| 1092 | @defun class-of obj |
| 1093 | CLOS symbol which does the same thing as @code{object-class} |
| 1094 | @end defun |
| 1095 | |
| 1096 | @defun object-class-fast obj |
| 1097 | Same as @code{object-class} except this is a macro, and no |
| 1098 | type-checking is performed. |
| 1099 | @end defun |
| 1100 | |
| 1101 | @defun object-class-name obj |
| 1102 | Returns the symbol of @var{obj}'s class. |
| 1103 | @end defun |
| 1104 | |
| 1105 | @defun class-parents class |
| 1106 | Returns the direct parents class of @var{class}. Returns @code{nil} if |
| 1107 | it is a superclass. |
| 1108 | @end defun |
| 1109 | |
| 1110 | @defun class-parents-fast class |
| 1111 | Just like @code{class-parent} except it is a macro and no type checking |
| 1112 | is performed. |
| 1113 | @end defun |
| 1114 | |
| 1115 | @defun class-parent class |
| 1116 | Deprecated function which returns the first parent of @var{class}. |
| 1117 | @end defun |
| 1118 | |
| 1119 | @defun class-children class |
| 1120 | Return the list of classes inheriting from @var{class}. |
| 1121 | @end defun |
| 1122 | |
| 1123 | @defun class-children-fast class |
| 1124 | Just like @code{class-children}, but with no checks. |
| 1125 | @end defun |
| 1126 | |
| 1127 | @defun same-class-p obj class |
| 1128 | Returns @code{t} if @var{obj}'s class is the same as @var{class}. |
| 1129 | @end defun |
| 1130 | |
| 1131 | @defun same-class-fast-p obj class |
| 1132 | Same as @code{same-class-p} except this is a macro and no type checking |
| 1133 | is performed. |
| 1134 | @end defun |
| 1135 | |
| 1136 | @defun object-of-class-p obj class |
| 1137 | Returns @code{t} if @var{obj} inherits anything from @var{class}. This |
| 1138 | is different from @code{same-class-p} because it checks for inheritance. |
| 1139 | @end defun |
| 1140 | |
| 1141 | @defun child-of-class-p child class |
| 1142 | Returns @code{t} if @var{child} is a subclass of @var{class}. |
| 1143 | @end defun |
| 1144 | |
| 1145 | @defun generic-p method-symbol |
| 1146 | Returns @code{t} if @code{method-symbol} is a generic function, as |
| 1147 | opposed to a regular Emacs Lisp function. |
| 1148 | @end defun |
| 1149 | |
| 1150 | @node Association Lists |
| 1151 | @chapter Association Lists |
| 1152 | |
| 1153 | Lisp offers the concept of association lists, with primitives such as |
| 1154 | @code{assoc} used to access them. The following functions can be used |
| 1155 | to manage association lists of @eieio{} objects: |
| 1156 | |
| 1157 | @defun object-assoc key slot list |
| 1158 | @anchor{object-assoc} |
| 1159 | Return an object if @var{key} is @dfn{equal} to SLOT's value of an object in @var{list}. |
| 1160 | @var{list} is a list of objects whose slots are searched. |
| 1161 | Objects in @var{list} do not need to have a slot named @var{slot}, nor does |
| 1162 | @var{slot} need to be bound. If these errors occur, those objects will |
| 1163 | be ignored. |
| 1164 | @end defun |
| 1165 | |
| 1166 | |
| 1167 | @defun object-assoc-list slot list |
| 1168 | Return an association list generated by extracting @var{slot} from all |
| 1169 | objects in @var{list}. For each element of @var{list} the @code{car} is |
| 1170 | the value of @var{slot}, and the @code{cdr} is the object it was |
| 1171 | extracted from. This is useful for generating completion tables. |
| 1172 | @end defun |
| 1173 | |
| 1174 | @defun eieio-build-class-alist &optional base-class |
| 1175 | Returns an alist of all currently defined classes. This alist is |
| 1176 | suitable for completion lists used by interactive functions to select a |
| 1177 | class. The optional argument @var{base-class} allows the programmer to |
| 1178 | select only a subset of classes which includes @var{base-class} and |
| 1179 | all its subclasses. |
| 1180 | @end defun |
| 1181 | |
| 1182 | @node Customizing |
| 1183 | @comment node-name, next, previous, up |
| 1184 | @chapter Customizing Objects |
| 1185 | |
| 1186 | @eieio{} supports the Custom facility through two new widget types. |
| 1187 | If a variable is declared as type @code{object}, then full editing of |
| 1188 | slots via the widgets is made possible. This should be used |
| 1189 | carefully, however, because modified objects are cloned, so if there |
| 1190 | are other references to these objects, they will no longer be linked |
| 1191 | together. |
| 1192 | |
| 1193 | If you want in place editing of objects, use the following methods: |
| 1194 | |
| 1195 | @defun eieio-customize-object object |
| 1196 | Create a custom buffer and insert a widget for editing @var{object}. At |
| 1197 | the end, an @code{Apply} and @code{Reset} button are available. This |
| 1198 | will edit the object "in place" so references to it are also changed. |
| 1199 | There is no effort to prevent multiple edits of a singular object, so |
| 1200 | care must be taken by the user of this function. |
| 1201 | @end defun |
| 1202 | |
| 1203 | @defun eieio-custom-widget-insert object flags |
| 1204 | This method inserts an edit object into the current buffer in place. |
| 1205 | It is implemented as @code{(widget-create 'object-edit :value object)}. |
| 1206 | This method is provided as a locale for adding tracking, or |
| 1207 | specializing the widget insert procedure for any object. |
| 1208 | @end defun |
| 1209 | |
| 1210 | To define a slot with an object in it, use the @code{object} tag. This |
| 1211 | widget type will be automatically converted to @code{object-edit} if you |
| 1212 | do in place editing of you object. |
| 1213 | |
| 1214 | If you want to have additional actions taken when a user clicks on the |
| 1215 | @code{Apply} button, then overload the method @code{eieio-done-customizing}. |
| 1216 | This method does nothing by default, but that may change in the future. |
| 1217 | This would be the best way to make your objects persistent when using |
| 1218 | in-place editing. |
| 1219 | |
| 1220 | @section Widget extension |
| 1221 | |
| 1222 | When widgets are being created, one new widget extension has been added, |
| 1223 | called the @code{:slotofchoices}. When this occurs in a widget |
| 1224 | definition, all elements after it are removed, and the slot is specifies |
| 1225 | is queried and converted into a series of constants. |
| 1226 | |
| 1227 | @example |
| 1228 | (choice (const :tag "None" nil) |
| 1229 | :slotofchoices morestuff) |
| 1230 | @end example |
| 1231 | |
| 1232 | and if the slot @code{morestuff} contains @code{(sym1 sym2 sym3)}, the |
| 1233 | above example is converted into: |
| 1234 | |
| 1235 | @example |
| 1236 | (choice (const :tag "None" nil) |
| 1237 | (const sym1) |
| 1238 | (const sym2) |
| 1239 | (const sym3)) |
| 1240 | @end example |
| 1241 | |
| 1242 | This is useful when a given item needs to be selected from a list of |
| 1243 | items defined in this second slot. |
| 1244 | |
| 1245 | @node Introspection |
| 1246 | @chapter Introspection |
| 1247 | |
| 1248 | Introspection permits a programmer to peek at the contents of a class |
| 1249 | without any previous knowledge of that class. While @eieio{} implements |
| 1250 | objects on top of vectors, and thus everything is technically visible, |
| 1251 | some functions have been provided. None of these functions are a part |
| 1252 | of CLOS. |
| 1253 | |
| 1254 | @defun object-slots obj |
| 1255 | Return the list of public slots for @var{obj}. |
| 1256 | @end defun |
| 1257 | |
| 1258 | @defun class-slot-initarg class slot |
| 1259 | For the given @var{class} return the :initarg associated with |
| 1260 | @var{slot}. Not all slots have initargs, so the return value can be |
| 1261 | nil. |
| 1262 | @end defun |
| 1263 | |
| 1264 | @node Base Classes |
| 1265 | @comment node-name, next, previous, up |
| 1266 | @chapter Base Classes |
| 1267 | |
| 1268 | All defined classes, if created with no specified parent class, |
| 1269 | inherit from a special class called @code{eieio-default-superclass}. |
| 1270 | @xref{Default Superclass}. |
| 1271 | |
| 1272 | Often, it is more convenient to inherit from one of the other base |
| 1273 | classes provided by @eieio{}, which have useful pre-defined |
| 1274 | properties. (Since @eieio{} supports multiple inheritance, you can |
| 1275 | even inherit from more than one of these classes at once.) |
| 1276 | |
| 1277 | @menu |
| 1278 | * eieio-instance-inheritor:: Enable value inheritance between instances. |
| 1279 | * eieio-instance-tracker:: Enable self tracking instances. |
| 1280 | * eieio-singleton:: Only one instance of a given class. |
| 1281 | * eieio-persistent:: Enable persistence for a class. |
| 1282 | * eieio-named:: Use the object name as a :name slot. |
| 1283 | * eieio-speedbar:: Enable speedbar support in your objects. |
| 1284 | @end menu |
| 1285 | |
| 1286 | @node eieio-instance-inheritor |
| 1287 | @comment node-name, next, previous, up |
| 1288 | @section @code{eieio-instance-inheritor} |
| 1289 | |
| 1290 | This class is defined in the package @file{eieio-base}. |
| 1291 | |
| 1292 | Instance inheritance is a mechanism whereby the value of a slot in |
| 1293 | object instance can reference the parent instance. If the parent's slot |
| 1294 | value is changed, then the child instance is also changed. If the |
| 1295 | child's slot is set, then the parent's slot is not modified. |
| 1296 | |
| 1297 | @deftp {Class} eieio-instance-inheritor parent-instance |
| 1298 | A class whose instances are enabled with instance inheritance. |
| 1299 | The @var{parent-instance} slot indicates the instance which is |
| 1300 | considered the parent of the current instance. Default is @code{nil}. |
| 1301 | @end deftp |
| 1302 | |
| 1303 | @cindex clone |
| 1304 | To use this class, inherit from it with your own class. |
| 1305 | To make a new instance that inherits from and existing instance of your |
| 1306 | class, use the @code{clone} method with additional parameters |
| 1307 | to specify local values. |
| 1308 | |
| 1309 | @cindex slot-unbound |
| 1310 | The @code{eieio-instance-inheritor} class works by causing cloned |
| 1311 | objects to have all slots unbound. This class' @code{slot-unbound} |
| 1312 | method will cause references to unbound slots to be redirected to the |
| 1313 | parent instance. If the parent slot is also unbound, then |
| 1314 | @code{slot-unbound} will signal an error named @code{slot-unbound}. |
| 1315 | |
| 1316 | @node eieio-instance-tracker |
| 1317 | @section @code{eieio-instance-tracker} |
| 1318 | |
| 1319 | This class is defined in the package @file{eieio-base}. |
| 1320 | |
| 1321 | Sometimes it is useful to keep a master list of all instances of a given |
| 1322 | class. The class @code{eieio-instance-tracker} performs this task. |
| 1323 | |
| 1324 | @deftp {Class} eieio-instance-tracker tracker-symbol |
| 1325 | Enable instance tracking for this class. |
| 1326 | The slot @var{tracker-symbol} should be initialized in inheritors of |
| 1327 | this class to a symbol created with @code{defvar}. This symbol will |
| 1328 | serve as the variable used as a master list of all objects of the given |
| 1329 | class. |
| 1330 | @end deftp |
| 1331 | |
| 1332 | @defmethod eieio-instance-tracker initialize-instance obj slot |
| 1333 | This method is defined as an @code{:after} method. |
| 1334 | It adds new instances to the master list. Do not overload this method |
| 1335 | unless you use @code{call-next-method.} |
| 1336 | @end defmethod |
| 1337 | |
| 1338 | @defmethod eieio-instance-tracker delete-instance obj |
| 1339 | Remove @var{obj} from the master list of instances of this class. |
| 1340 | This may let the garbage collector nab this instance. |
| 1341 | @end defmethod |
| 1342 | |
| 1343 | @deffn eieio-instance-tracker-find key slot list-symbol |
| 1344 | This convenience function lets you find instances. @var{key} is the |
| 1345 | value to search for. @var{slot} is the slot to compare @var{KEY} |
| 1346 | against. The function @code{equal} is used for comparison. |
| 1347 | The parameter @var{list-symbol} is the variable symbol which contains the |
| 1348 | list of objects to be searched. |
| 1349 | @end deffn |
| 1350 | |
| 1351 | @node eieio-singleton |
| 1352 | @comment node-name, next, previous, up |
| 1353 | @section @code{eieio-singleton} |
| 1354 | |
| 1355 | This class is defined in the package @file{eieio-base}. |
| 1356 | |
| 1357 | @deftp {Class} eieio-singleton |
| 1358 | Inheriting from the singleton class will guarantee that there will |
| 1359 | only ever be one instance of this class. Multiple calls to |
| 1360 | @code{make-instance} will always return the same object. |
| 1361 | @end deftp |
| 1362 | |
| 1363 | @node eieio-persistent |
| 1364 | @comment node-name, next, previous, up |
| 1365 | @section @code{eieio-persistent} |
| 1366 | |
| 1367 | This class is defined in the package @file{eieio-base}. |
| 1368 | |
| 1369 | If you want an object, or set of objects to be persistent, meaning the |
| 1370 | slot values are important to keep saved between sessions, then you will |
| 1371 | want your top level object to inherit from @code{eieio-persistent}. |
| 1372 | |
| 1373 | To make sure your persistent object can be moved, make sure all file |
| 1374 | names stored to disk are made relative with |
| 1375 | @code{eieio-persistent-path-relative}. |
| 1376 | |
| 1377 | @deftp {Class} eieio-persistent file file-header-line |
| 1378 | Enables persistence for instances of this class. |
| 1379 | Slot @var{file} with initarg @code{:file} is the file name in which this |
| 1380 | object will be saved. |
| 1381 | Class allocated slot @var{file-header-line} is used with method |
| 1382 | @code{object-write} as a header comment. |
| 1383 | @end deftp |
| 1384 | |
| 1385 | All objects can write themselves to a file, but persistent objects have |
| 1386 | several additional methods that aid in maintaining them. |
| 1387 | |
| 1388 | @defmethod eieio-persistent eieio-persistent-save obj &optional file |
| 1389 | Write the object @var{obj} to its file. |
| 1390 | If optional argument @var{file} is specified, use that file name |
| 1391 | instead. |
| 1392 | @end defmethod |
| 1393 | |
| 1394 | @defmethod eieio-persistent eieio-persistent-path-relative obj file |
| 1395 | Return a file name derived from @var{file} which is relative to the |
| 1396 | stored location of @var{OBJ}. This method should be used to convert |
| 1397 | file names so that they are relative to the save file, making any system |
| 1398 | of files movable from one location to another. |
| 1399 | @end defmethod |
| 1400 | |
| 1401 | @defmethod eieio-persistent object-write obj &optional comment |
| 1402 | Like @code{object-write} for @code{standard-object}, but will derive |
| 1403 | a header line comment from the class allocated slot if one is not |
| 1404 | provided. |
| 1405 | @end defmethod |
| 1406 | |
| 1407 | @defun eieio-persistent-read filename &optional class allow-subclass |
| 1408 | Read a persistent object from @var{filename}, and return it. |
| 1409 | Signal an error if the object in @var{FILENAME} is not a constructor |
| 1410 | for @var{CLASS}. Optional @var{allow-subclass} says that it is ok for |
| 1411 | @code{eieio-persistent-read} to load in subclasses of class instead of |
| 1412 | being pedantic. |
| 1413 | @end defun |
| 1414 | |
| 1415 | @node eieio-named |
| 1416 | @comment node-name, next, previous, up |
| 1417 | @section @code{eieio-named} |
| 1418 | |
| 1419 | This class is defined in the package @file{eieio-base}. |
| 1420 | |
| 1421 | @deftp {Class} eieio-named |
| 1422 | Object with a name. |
| 1423 | Name storage already occurs in an object. This object provides get/set |
| 1424 | access to it. |
| 1425 | @end deftp |
| 1426 | |
| 1427 | @node eieio-speedbar |
| 1428 | @comment node-name, next, previous, up |
| 1429 | @section @code{eieio-speedbar} |
| 1430 | |
| 1431 | This class is in package @file{eieio-speedbar}. |
| 1432 | |
| 1433 | If a series of class instances map to a tree structure, it is possible |
| 1434 | to cause your classes to be displayable in Speedbar. @xref{Top,,,speedbar}. |
| 1435 | Inheriting from these classes will enable a speedbar major display mode |
| 1436 | with a minimum of effort. |
| 1437 | |
| 1438 | @deftp {Class} eieio-speedbar buttontype buttonface |
| 1439 | Enables base speedbar display for a class. |
| 1440 | @cindex speedbar-make-tag-line |
| 1441 | The slot @var{buttontype} is any of the symbols allowed by the |
| 1442 | function @code{speedbar-make-tag-line} for the @var{exp-button-type} |
| 1443 | argument @xref{Extending,,,speedbar}. |
| 1444 | The slot @var{buttonface} is the face to use for the text of the string |
| 1445 | displayed in speedbar. |
| 1446 | The slots @var{buttontype} and @var{buttonface} are class allocated |
| 1447 | slots, and do not take up space in your instances. |
| 1448 | @end deftp |
| 1449 | |
| 1450 | @deftp {Class} eieio-speedbar-directory-button buttontype buttonface |
| 1451 | This class inherits from @code{eieio-speedbar} and initializes |
| 1452 | @var{buttontype} and @var{buttonface} to appear as directory level lines. |
| 1453 | @end deftp |
| 1454 | |
| 1455 | @deftp {Class} eieio-speedbar-file-button buttontype buttonface |
| 1456 | This class inherits from @code{eieio-speedbar} and initializes |
| 1457 | @var{buttontype} and @var{buttonface} to appear as file level lines. |
| 1458 | @end deftp |
| 1459 | |
| 1460 | To use these classes, inherit from one of them in you class. You can |
| 1461 | use multiple inheritance with them safely. To customize your class for |
| 1462 | speedbar display, override the default values for @var{buttontype} and |
| 1463 | @var{buttonface} to get the desired effects. |
| 1464 | |
| 1465 | Useful methods to define for your new class include: |
| 1466 | |
| 1467 | @defmethod eieio-speedbar eieio-speedbar-derive-line-path obj depth |
| 1468 | Return a string representing a directory associated with an instance |
| 1469 | of @var{obj}. @var{depth} can be used to index how many levels of |
| 1470 | indentation have been opened by the user where @var{obj} is shown. |
| 1471 | @end defmethod |
| 1472 | |
| 1473 | |
| 1474 | @defmethod eieio-speedbar eieio-speedbar-description obj |
| 1475 | Return a string description of @var{OBJ}. |
| 1476 | This is shown in the minibuffer or tooltip when the mouse hovers over |
| 1477 | this instance in speedbar. |
| 1478 | @end defmethod |
| 1479 | |
| 1480 | @defmethod eieio-speedbar eieio-speedbar-child-description obj |
| 1481 | Return a string representing a description of a child node of @var{obj} |
| 1482 | when that child is not an object. It is often useful to just use |
| 1483 | item info helper functions such as @code{speedbar-item-info-file-helper}. |
| 1484 | @end defmethod |
| 1485 | |
| 1486 | @defmethod eieio-speedbar eieio-speedbar-object-buttonname obj |
| 1487 | Return a string which is the text displayed in speedbar for @var{obj}. |
| 1488 | @end defmethod |
| 1489 | |
| 1490 | @defmethod eieio-speedbar eieio-speedbar-object-children obj |
| 1491 | Return a list of children of @var{obj}. |
| 1492 | @end defmethod |
| 1493 | |
| 1494 | @defmethod eieio-speedbar eieio-speedbar-child-make-tag-lines obj depth |
| 1495 | This method inserts a list of speedbar tag lines for @var{obj} to |
| 1496 | represent its children. Implement this method for your class |
| 1497 | if your children are not objects themselves. You still need to |
| 1498 | implement @code{eieio-speedbar-object-children}. |
| 1499 | |
| 1500 | In this method, use techniques specified in the Speedbar manual. |
| 1501 | @xref{Extending,,,speedbar}. |
| 1502 | @end defmethod |
| 1503 | |
| 1504 | Some other functions you will need to learn to use are: |
| 1505 | |
| 1506 | @deffn eieio-speedbar-create make-map key-map menu name toplevelfn |
| 1507 | Register your object display mode with speedbar. |
| 1508 | @var{make-map} is a function which initialized you keymap. |
| 1509 | @var{key-map} is a symbol you keymap is installed into. |
| 1510 | @var{menu} is an easy menu vector representing menu items specific to your |
| 1511 | object display. |
| 1512 | @var{name} is a short string to use as a name identifying you mode. |
| 1513 | @var{toplevelfn} is a function called which must return a list of |
| 1514 | objects representing those in the instance system you wish to browse in |
| 1515 | speedbar. |
| 1516 | |
| 1517 | Read the Extending chapter in the speedbar manual for more information |
| 1518 | on how speedbar modes work |
| 1519 | @xref{Extending,,,speedbar}. |
| 1520 | @end deffn |
| 1521 | |
| 1522 | @node Browsing |
| 1523 | @comment node-name, next, previous, up |
| 1524 | @chapter Browsing class trees |
| 1525 | |
| 1526 | The command @kbd{M-x eieio-browse} displays a buffer listing all the |
| 1527 | currently loaded classes in Emacs. The classes are listed in an |
| 1528 | indented tree structure, starting from @code{eieio-default-superclass} |
| 1529 | (@pxref{Default Superclass}). |
| 1530 | |
| 1531 | With a prefix argument, this command prompts for a class name; it then |
| 1532 | lists only that class and its subclasses. |
| 1533 | |
| 1534 | Here is a sample tree from our current example: |
| 1535 | |
| 1536 | @example |
| 1537 | eieio-default-superclass |
| 1538 | +--data-object |
| 1539 | +--data-object-symbol |
| 1540 | @end example |
| 1541 | |
| 1542 | Note: new classes are consed into the inheritance lists, so the tree |
| 1543 | comes out upside-down. |
| 1544 | |
| 1545 | @node Class Values |
| 1546 | @comment node-name, next, previous, up |
| 1547 | @chapter Class Values |
| 1548 | |
| 1549 | Details about any class or object can be retrieved using the function |
| 1550 | @code{eieio-describe-class}. Interactively, type in the name of |
| 1551 | a class. In a program, pass it a string with the name of a class, a |
| 1552 | class symbol, or an object. The resulting buffer will display all slot |
| 1553 | names. |
| 1554 | |
| 1555 | Additionally, all methods defined to have functionality on this class is |
| 1556 | displayed. |
| 1557 | |
| 1558 | @node Documentation |
| 1559 | @comment node-name, next, previous, up |
| 1560 | @chapter Documentation |
| 1561 | |
| 1562 | It is possible to automatically create documentation for your classes in |
| 1563 | texinfo format by using the tools in the file @file{eieio-doc.el} |
| 1564 | |
| 1565 | @deffn Command eieiodoc-class class indexstring &optional skiplist |
| 1566 | |
| 1567 | This will start at the current point, and create an indented menu of |
| 1568 | all the child classes of, and including @var{class}, but skipping any |
| 1569 | classes that might be in @var{skiplist}. It will then create nodes for |
| 1570 | all these classes, subsection headings, and indexes. |
| 1571 | |
| 1572 | Each class will be indexed using the texinfo labeled index |
| 1573 | @var{indexstring} which is a two letter description. |
| 1574 | @xref{New Indices,,,texinfo,Texinfo manual}. |
| 1575 | |
| 1576 | To use this command, the texinfo macro |
| 1577 | |
| 1578 | @example |
| 1579 | @@defindex @@var @{ indexstring @} |
| 1580 | @end example |
| 1581 | |
| 1582 | @noindent |
| 1583 | where @var{indexstring} is replaced with the two letter code. |
| 1584 | |
| 1585 | Next, an inheritance tree will be created listing all parents of that |
| 1586 | section's class. |
| 1587 | |
| 1588 | Then, all the slots will be expanded in tables, and described |
| 1589 | using the documentation strings from the code. Default values will also |
| 1590 | be displayed. Only those slots with @code{:initarg} specified will be |
| 1591 | expanded, others will be hidden. If a slot is inherited from a parent, |
| 1592 | that slot will also be skipped unless the default value is different. |
| 1593 | If there is a change, then the documentation part of the slot will be |
| 1594 | replace with an @@xref back to the parent. |
| 1595 | |
| 1596 | This command can only display documentation for classes whose |
| 1597 | definitions have been loaded in this Emacs session. |
| 1598 | |
| 1599 | @end deffn |
| 1600 | |
| 1601 | @node Default Superclass |
| 1602 | @comment node-name, next, previous, up |
| 1603 | @chapter Default Superclass |
| 1604 | |
| 1605 | All defined classes, if created with no specified parent class, will |
| 1606 | inherit from a special class stored in |
| 1607 | @code{eieio-default-superclass}. This superclass is quite simple, but |
| 1608 | with it, certain default methods or attributes can be added to all |
| 1609 | objects. In CLOS, this would be named @code{STANDARD-CLASS}, and that |
| 1610 | symbol is an alias to @code{eieio-default-superclass}. |
| 1611 | @refill |
| 1612 | |
| 1613 | Currently, the default superclass is defined as follows: |
| 1614 | |
| 1615 | @example |
| 1616 | (defclass eieio-default-superclass nil |
| 1617 | nil |
| 1618 | "Default parent class for classes with no specified parent class. |
| 1619 | Its slots are automatically adopted by classes with no specified |
| 1620 | parents. This class is not stored in the `parent' slot of a class vector." |
| 1621 | :abstract t) |
| 1622 | @end example |
| 1623 | |
| 1624 | The default superclass implements several methods providing a default |
| 1625 | behavior for all objects created by @eieio{}. |
| 1626 | |
| 1627 | @menu |
| 1628 | * Initialization:: How objects are initialized |
| 1629 | * Basic Methods:: Clone, print, and write |
| 1630 | * Signal Handling:: Methods for managing signals. |
| 1631 | @end menu |
| 1632 | |
| 1633 | @node Initialization |
| 1634 | @section Initialization |
| 1635 | |
| 1636 | When creating an object of any type, you can use its constructor, or |
| 1637 | @code{make-instance}. This, in turns calls the method |
| 1638 | @code{initialize-instance}, which then calls the method |
| 1639 | @code{shared-initialize}. |
| 1640 | |
| 1641 | These methods are all implemented on the default superclass so you do |
| 1642 | not need to write them yourself, unless you need to override one of |
| 1643 | their behaviors. |
| 1644 | |
| 1645 | Users should not need to call @code{initialize-instance} or |
| 1646 | @code{shared-initialize}, as these are used by @code{make-instance} to |
| 1647 | initialize the object. They are instead provided so that users can |
| 1648 | augment these behaviors. |
| 1649 | |
| 1650 | @defun initialize-instance obj &rest slots |
| 1651 | Initialize @var{obj}. Sets slots of @var{obj} with @var{slots} which |
| 1652 | is a list of name/value pairs. These are actually just passed to |
| 1653 | @code{shared-initialize}. |
| 1654 | @end defun |
| 1655 | |
| 1656 | @defun shared-initialize obj &rest slots |
| 1657 | Sets slots of @var{obj} with @var{slots} which is a list of name/value |
| 1658 | pairs. |
| 1659 | |
| 1660 | This is called from the default @code{constructor}. |
| 1661 | @end defun |
| 1662 | |
| 1663 | @node Basic Methods |
| 1664 | @section Basic Methods |
| 1665 | |
| 1666 | Additional useful methods defined on the base subclass are: |
| 1667 | |
| 1668 | @defun clone obj &rest params |
| 1669 | @anchor{clone} |
| 1670 | Make a copy of @var{obj}, and then apply @var{params}. |
| 1671 | @var{params} is a parameter list of the same form as @var{initialize-instance} |
| 1672 | which are applied to change the object. When overloading @dfn{clone}, be |
| 1673 | sure to call @dfn{call-next-method} first and modify the returned object. |
| 1674 | @end defun |
| 1675 | |
| 1676 | @defun object-print this &rest strings |
| 1677 | @anchor{object-print} |
| 1678 | Pretty printer for object @var{this}. Call function @dfn{object-name} with @var{strings}. |
| 1679 | The default method for printing object @var{this} is to use the |
| 1680 | function @dfn{object-name}. |
| 1681 | |
| 1682 | It is sometimes useful to put a summary of the object into the |
| 1683 | default #<notation> string when using eieio browsing tools. |
| 1684 | |
| 1685 | Implement this function and specify @var{strings} in a call to |
| 1686 | @dfn{call-next-method} to provide additional summary information. |
| 1687 | When passing in extra strings from child classes, always remember |
| 1688 | to prepend a space. |
| 1689 | |
| 1690 | @example |
| 1691 | (defclass data-object () |
| 1692 | (value) |
| 1693 | "Object containing one data slot.") |
| 1694 | |
| 1695 | (defmethod object-print ((this data-object) &optional strings) |
| 1696 | "Return a string with a summary of the data object as part of the name." |
| 1697 | (apply 'call-next-method this |
| 1698 | (cons (format " value: %s" (render this)) strings))) |
| 1699 | @end example |
| 1700 | |
| 1701 | Here is what some output could look like: |
| 1702 | @example |
| 1703 | (object-print test-object) |
| 1704 | => #<data-object test-object value: 3> |
| 1705 | @end example |
| 1706 | @end defun |
| 1707 | |
| 1708 | @defun object-write obj &optional comment |
| 1709 | Write @var{obj} onto a stream in a readable fashion. The resulting |
| 1710 | output will be Lisp code which can be used with @code{read} and |
| 1711 | @code{eval} to recover the object. Only slots with @code{:initarg}s |
| 1712 | are written to the stream. |
| 1713 | @end defun |
| 1714 | |
| 1715 | @node Signal Handling |
| 1716 | @section Signal Handling |
| 1717 | |
| 1718 | The default superclass defines methods for managing error conditions. |
| 1719 | These methods all throw a signal for a particular error condition. |
| 1720 | |
| 1721 | By implementing one of these methods for a class, you can change the |
| 1722 | behavior that occurs during one of these error cases, or even ignore |
| 1723 | the error by providing some behavior. |
| 1724 | |
| 1725 | @defun slot-missing object slot-name operation &optional new-value |
| 1726 | @anchor{slot-missing} |
| 1727 | Method invoked when an attempt to access a slot in @var{object} fails. |
| 1728 | @var{slot-name} is the name of the failed slot, @var{operation} is the type of access |
| 1729 | that was requested, and optional @var{new-value} is the value that was desired |
| 1730 | to be set. |
| 1731 | |
| 1732 | This method is called from @code{oref}, @code{oset}, and other functions which |
| 1733 | directly reference slots in EIEIO objects. |
| 1734 | |
| 1735 | The default method signals an error of type @code{invalid-slot-name}. |
| 1736 | @xref{Signals}. |
| 1737 | |
| 1738 | You may override this behavior, but it is not expected to return in the |
| 1739 | current implementation. |
| 1740 | |
| 1741 | This function takes arguments in a different order than in CLOS. |
| 1742 | @end defun |
| 1743 | |
| 1744 | @defun slot-unbound object class slot-name fn |
| 1745 | @anchor{slot-unbound} |
| 1746 | Slot unbound is invoked during an attempt to reference an unbound slot. |
| 1747 | @var{object} is the instance of the object being reference. @var{class} is the |
| 1748 | class of @var{object}, and @var{slot-name} is the offending slot. This function |
| 1749 | throws the signal @code{unbound-slot}. You can overload this function and |
| 1750 | return the value to use in place of the unbound value. |
| 1751 | Argument @var{fn} is the function signaling this error. |
| 1752 | Use @dfn{slot-boundp} to determine if a slot is bound or not. |
| 1753 | |
| 1754 | In @var{clos}, the argument list is (@var{class} @var{object} @var{slot-name}), but |
| 1755 | @var{eieio} can only dispatch on the first argument, so the first two are swapped. |
| 1756 | @end defun |
| 1757 | |
| 1758 | @defun no-applicable-method object method &rest args |
| 1759 | @anchor{no-applicable-method} |
| 1760 | Called if there are no implementations for @var{object} in @var{method}. |
| 1761 | @var{object} is the object which has no method implementation. |
| 1762 | @var{args} are the arguments that were passed to @var{method}. |
| 1763 | |
| 1764 | Implement this for a class to block this signal. The return |
| 1765 | value becomes the return value of the original method call. |
| 1766 | @end defun |
| 1767 | |
| 1768 | @defun no-next-method object &rest args |
| 1769 | @anchor{no-next-method} |
| 1770 | Called from @dfn{call-next-method} when no additional methods are available. |
| 1771 | @var{object} is othe object being called on @dfn{call-next-method}. |
| 1772 | @var{args} are the arguments it is called by. |
| 1773 | This method signals @dfn{no-next-method} by default. Override this |
| 1774 | method to not throw an error, and its return value becomes the |
| 1775 | return value of @dfn{call-next-method}. |
| 1776 | @end defun |
| 1777 | |
| 1778 | @node Signals |
| 1779 | @comment node-name, next, previous, up |
| 1780 | @chapter Signals |
| 1781 | |
| 1782 | There are new condition names (signals) that can be caught when using |
| 1783 | @eieio{}. |
| 1784 | |
| 1785 | @deffn Signal invalid-slot-name obj-or-class slot |
| 1786 | This signal is called when an attempt to reference a slot in an |
| 1787 | @var{obj-or-class} is made, and the @var{slot} is not defined for |
| 1788 | it. |
| 1789 | @end deffn |
| 1790 | |
| 1791 | @deffn Signal no-method-definition method arguments |
| 1792 | This signal is called when @var{method} is called, with @var{arguments} |
| 1793 | and nothing is resolved. This occurs when @var{method} has been |
| 1794 | defined, but the arguments make it impossible for @eieio{} to determine |
| 1795 | which method body to run. |
| 1796 | |
| 1797 | To prevent this signal from occurring in your class, implement the |
| 1798 | method @code{no-applicable-method} for your class. This method is |
| 1799 | called when to throw this signal, so implementing this for your class |
| 1800 | allows you block the signal, and perform some work. |
| 1801 | @end deffn |
| 1802 | |
| 1803 | @deffn Signal no-next-method class arguments |
| 1804 | This signal is called if the function @code{call-next-method} is called |
| 1805 | and there is no next method to be called. |
| 1806 | |
| 1807 | Overload the method @code{no-next-method} to protect against this signal. |
| 1808 | @end deffn |
| 1809 | |
| 1810 | @deffn Signal invalid-slot-type slot spec value |
| 1811 | This signal is called when an attempt to set @var{slot} is made, and |
| 1812 | @var{value} doesn't match the specified type @var{spec}. |
| 1813 | |
| 1814 | In @eieio{}, this is also used if a slot specifier has an invalid value |
| 1815 | during a @code{defclass}. |
| 1816 | @end deffn |
| 1817 | |
| 1818 | @deffn Signal unbound-slot object class slot |
| 1819 | This signal is called when an attempt to reference @var{slot} in |
| 1820 | @var{object} is made, and that instance is currently unbound. |
| 1821 | @end deffn |
| 1822 | |
| 1823 | @node Naming Conventions |
| 1824 | @comment node-name, next, previous, up |
| 1825 | @chapter Naming Conventions |
| 1826 | |
| 1827 | @xref{Tips,,Tips and Conventions,elisp,GNU Emacs Lisp Reference |
| 1828 | Manual}, for a description of Emacs Lisp programming conventions. |
| 1829 | These conventions help ensure that Emacs packages work nicely one |
| 1830 | another, so an @eieio{}-based program should follow them. Here are |
| 1831 | some conventions that apply specifically to @eieio{}-based programs: |
| 1832 | |
| 1833 | @itemize |
| 1834 | |
| 1835 | @item Come up with a package prefix that is relatively short. Prefix |
| 1836 | all classes, and methods with your prefix. This is a standard |
| 1837 | convention for functions and variables in Emacs. |
| 1838 | |
| 1839 | @item Do not prefix method names with the class name. All methods in |
| 1840 | @eieio{} are ``virtual'', and are dynamically dispatched. Anyone can |
| 1841 | override your methods at any time. Your methods should be prefixed |
| 1842 | with your package name. |
| 1843 | |
| 1844 | @item Do not prefix slots in your class. The slots are always locally |
| 1845 | scoped to your class, and need no prefixing. |
| 1846 | |
| 1847 | @item If your library inherits from other libraries of classes, you |
| 1848 | must ``require'' that library with the @code{require} command. |
| 1849 | |
| 1850 | @end itemize |
| 1851 | |
| 1852 | @node CLOS compatibility |
| 1853 | @comment node-name, next, previous, up |
| 1854 | @chapter CLOS compatibility |
| 1855 | |
| 1856 | Currently, the following functions should behave almost as expected from |
| 1857 | CLOS. |
| 1858 | |
| 1859 | @table @code |
| 1860 | |
| 1861 | @item defclass |
| 1862 | All slot keywords are available but not all work correctly. |
| 1863 | Slot keyword differences are: |
| 1864 | |
| 1865 | @table @asis |
| 1866 | |
| 1867 | @item :reader, and :writer tags |
| 1868 | Create methods that signal errors instead of creating an unqualified |
| 1869 | method. You can still create new ones to do its business. |
| 1870 | |
| 1871 | @item :accessor |
| 1872 | This should create an unqualified method to access a slot, but |
| 1873 | instead pre-builds a method that gets the slot's value. |
| 1874 | |
| 1875 | @item :type |
| 1876 | Specifier uses the @code{typep} function from the @file{cl} |
| 1877 | package. @xref{Type Predicates,,,cl,Common Lisp Extensions}. |
| 1878 | It therefore has the same issues as that package. Extensions include |
| 1879 | the ability to provide object names. |
| 1880 | @end table |
| 1881 | |
| 1882 | Defclass also supports class options, but does not currently use values |
| 1883 | of @code{:metaclass}, and @code{:default-initargs}. |
| 1884 | |
| 1885 | @item make-instance |
| 1886 | Make instance works as expected, however it just uses the @eieio{} instance |
| 1887 | creator automatically generated when a new class is created. |
| 1888 | @xref{Making New Objects}. |
| 1889 | |
| 1890 | @item defgeneric |
| 1891 | Creates the desired symbol, and accepts all of the expected arguments |
| 1892 | except @code{:around}. |
| 1893 | |
| 1894 | @item defmethod |
| 1895 | Calls defgeneric, and accepts most of the expected arguments. Only |
| 1896 | the first argument to the created method may have a type specifier. |
| 1897 | To type cast against a class, the class must exist before defmethod is |
| 1898 | called. In addition, the @code{:around} tag is not supported. |
| 1899 | |
| 1900 | @item call-next-method |
| 1901 | Inside a method, calls the next available method up the inheritance tree |
| 1902 | for the given object. This is different than that found in CLOS because |
| 1903 | in @eieio{} this function accepts replacement arguments. This permits |
| 1904 | subclasses to modify arguments as they are passed up the tree. If no |
| 1905 | arguments are given, the expected CLOS behavior is used. |
| 1906 | @item setf |
| 1907 | If the common-lisp subsystem is loaded, the setf parameters are also |
| 1908 | loaded so the form @code{(setf (slot-value object slot) t)} should |
| 1909 | work. |
| 1910 | @end table |
| 1911 | |
| 1912 | CLOS supports the @code{describe} command, but @eieio{} only provides |
| 1913 | @code{eieio-describe-class}, and @code{eieio-describe-generic}. These |
| 1914 | functions are adviced into @code{describe-variable}, and |
| 1915 | @code{describe-function}. |
| 1916 | |
| 1917 | When creating a new class (@pxref{Building Classes}) there are several |
| 1918 | new keywords supported by @eieio{}. |
| 1919 | |
| 1920 | In @eieio{} tags are in lower case, not mixed case. |
| 1921 | |
| 1922 | @node Wish List |
| 1923 | @chapter Wish List |
| 1924 | |
| 1925 | @eieio{} is an incomplete implementation of CLOS@. Finding ways to |
| 1926 | improve the compatibility would help make CLOS style programs run |
| 1927 | better in Emacs. |
| 1928 | |
| 1929 | Some important compatibility features that would be good to add are: |
| 1930 | |
| 1931 | @enumerate |
| 1932 | @item |
| 1933 | @code{:around} method key. |
| 1934 | |
| 1935 | @item |
| 1936 | Method dispatch for built-in types. |
| 1937 | @item |
| 1938 | Method dispatch for multiple argument typing. |
| 1939 | @item |
| 1940 | Improve integration with the @file{cl} package. |
| 1941 | @end enumerate |
| 1942 | |
| 1943 | There are also improvements to be made to allow @eieio{} to operate |
| 1944 | better in the Emacs environment. |
| 1945 | |
| 1946 | @enumerate |
| 1947 | @item |
| 1948 | Allow subclassing of Emacs built-in types, such as faces, markers, and |
| 1949 | buffers. |
| 1950 | @item |
| 1951 | Allow method overloading of method-like functions in Emacs. |
| 1952 | @end enumerate |
| 1953 | |
| 1954 | @node GNU Free Documentation License |
| 1955 | @appendix GNU Free Documentation License |
| 1956 | @include doclicense.texi |
| 1957 | |
| 1958 | @node Function Index |
| 1959 | @unnumbered Function Index |
| 1960 | |
| 1961 | @printindex fn |
| 1962 | |
| 1963 | @contents |
| 1964 | @bye |