1 ;;; eieio.el --- Enhanced Implementation of Emacs Interpreted Objects
2 ;;; or maybe Eric's Implementation of Emacs Interpreted Objects
4 ;; Copyright (C) 1995-1996, 1998-2013 Free Software Foundation, Inc.
6 ;; Author: Eric M. Ludlam <zappo@gnu.org>
10 ;; This file is part of GNU Emacs.
12 ;; GNU Emacs is free software: you can redistribute it and/or modify
13 ;; it under the terms of the GNU General Public License as published by
14 ;; the Free Software Foundation, either version 3 of the License, or
15 ;; (at your option) any later version.
17 ;; GNU Emacs is distributed in the hope that it will be useful,
18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 ;; GNU General Public License for more details.
22 ;; You should have received a copy of the GNU General Public License
23 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
27 ;; EIEIO is a series of Lisp routines which implements a subset of
28 ;; CLOS, the Common Lisp Object System. In addition, EIEIO also adds
29 ;; a few new features which help it integrate more strongly with the
30 ;; Emacs running environment.
32 ;; See eieio.texi for complete documentation on using this package.
34 ;; Note: the implementation of the c3 algorithm is based on:
35 ;; Kim Barrett et al.: A Monotonic Superclass Linearization for Dylan
37 ;; http://192.220.96.201/dylan/linearization-oopsla96.html
39 ;; There is funny stuff going on with typep and deftype. This
40 ;; is the only way I seem to be able to make this stuff load properly.
42 ;; @TODO - fix :initform to be a form, not a quoted value
43 ;; @TODO - Prefix non-clos functions with `eieio-'.
47 (eval-when-compile (require 'cl
)) ;FIXME: Use cl-lib!
49 (defvar eieio-version
"1.4"
50 "Current version of EIEIO.")
52 (defun eieio-version ()
53 "Display the current version of EIEIO."
55 (message eieio-version
))
60 ;;; Defining a new class
62 (defmacro defclass
(name superclass slots
&rest options-and-doc
)
63 "Define NAME as a new class derived from SUPERCLASS with SLOTS.
64 OPTIONS-AND-DOC is used as the class' options and base documentation.
65 SUPERCLASS is a list of superclasses to inherit from, with SLOTS
66 being the slots residing in that class definition. NOTE: Currently
67 only one slot may exist in SUPERCLASS as multiple inheritance is not
68 yet supported. Supported tags are:
70 :initform - Initializing form.
71 :initarg - Tag used during initialization.
72 :accessor - Tag used to create a function to access this slot.
73 :allocation - Specify where the value is stored.
74 Defaults to `:instance', but could also be `:class'.
75 :writer - A function symbol which will `write' an object's slot.
76 :reader - A function symbol which will `read' an object.
77 :type - The type of data allowed in this slot (see `typep').
79 - A string documenting use of this slot.
81 The following are extensions on CLOS:
82 :protection - Specify protection for this slot.
83 Defaults to `:public'. Also use `:protected', or `:private'.
84 :custom - When customizing an object, the custom :type. Public only.
85 :label - A text string label used for a slot when customizing.
86 :group - Name of a customization group this slot belongs in.
87 :printer - A function to call to print the value of a slot.
88 See `eieio-override-prin1' as an example.
90 A class can also have optional options. These options happen in place
91 of documentation (including a :documentation tag), in addition to
92 documentation, or not at all. Supported options are:
94 :documentation - The doc-string used for this class.
96 Options added to EIEIO:
98 :allow-nil-initform - Non-nil to skip typechecking of null initforms.
99 :custom-groups - List of custom group names. Organizes slots into
100 reasonable groups for customizations.
101 :abstract - Non-nil to prevent instances of this class.
102 If a string, use as an error string if someone does
103 try to make an instance.
104 :method-invocation-order
105 - Control the method invocation order if there is
106 multiple inheritance. Valid values are:
107 :breadth-first - The default.
110 Options in CLOS not supported in EIEIO:
112 :metaclass - Class to use in place of `standard-class'
113 :default-initargs - Initargs to use when initializing new objects of
116 Due to the way class options are set up, you can add any tags you wish,
117 and reference them using the function `class-option'."
118 `(eieio-defclass ',name
',superclass
',slots
',options-and-doc
))
121 ;;; CLOS style implementation of object creators.
123 (defun make-instance (class &rest initargs
)
124 "Make a new instance of CLASS based on INITARGS.
125 CLASS is a class symbol. For example:
129 INITARGS is a property list with keywords based on the :initarg
130 for each slot. For example:
132 (make-instance 'foo :slot1 value1 :slotN valueN)
136 If the first element of INITARGS is a string, it is used as the
139 In EIEIO, the class' constructor requires a name for use when printing.
140 `make-instance' in CLOS doesn't use names the way Emacs does, so the
141 class is used as the name slot instead when INITARGS doesn't start with
143 (if (and (car initargs
) (stringp (car initargs
)))
144 (apply (class-constructor class
) initargs
)
145 (apply (class-constructor class
)
146 (cond ((symbolp class
) (symbol-name class
))
147 (t (format "%S" class
)))
151 ;;; CLOS methods and generics
153 (defmacro defgeneric
(method args
&optional doc-string
)
154 "Create a generic function METHOD.
155 DOC-STRING is the base documentation for this class. A generic
156 function has no body, as its purpose is to decide which method body
157 is appropriate to use. Uses `defmethod' to create methods, and calls
158 `defgeneric' for you. With this implementation the ARGS are
159 currently ignored. You can use `defgeneric' to apply specialized
160 top level documentation to a method."
161 `(eieio--defalias ',method
162 (eieio--defgeneric-init-form ',method
,doc-string
)))
164 (defmacro defmethod
(method &rest args
)
165 "Create a new METHOD through `defgeneric' with ARGS.
167 The optional second argument KEY is a specifier that
168 modifies how the method is called, including:
169 :before - Method will be called before the :primary
170 :primary - The default if not specified
171 :after - Method will be called after the :primary
172 :static - First arg could be an object or class
173 The next argument is the ARGLIST. The ARGLIST specifies the arguments
174 to the method as with `defun'. The first argument can have a type
176 ((VARNAME CLASS) ARG2 ...)
177 where VARNAME is the name of the local variable for the method being
178 created. The CLASS is a class symbol for a class made with `defclass'.
179 A DOCSTRING comes after the ARGLIST, and is optional.
180 All the rest of the args are the BODY of the method. A method will
181 return the value of the last form in the BODY.
185 (defmethod mymethod [:before | :primary | :after | :static]
186 ((typearg class-name) arg2 &optional opt &rest rest)
189 (let* ((key (if (keywordp (car args
)) (pop args
)))
192 (fargs (if (consp arg1
)
193 (cons (car arg1
) (cdr params
))
195 (class (if (consp arg1
) (nth 1 arg1
)))
196 (code `(lambda ,fargs
,@(cdr args
))))
198 ;; Make sure there is a generic and the byte-compiler sees it.
199 (defgeneric ,method
,args
200 ,(or (documentation code
)
201 (format "Generically created method `%s'." method
)))
202 (eieio--defmethod ',method
',key
',class
#',code
))))
204 ;;; Get/Set slots in an object.
206 (defmacro oref
(obj slot
)
207 "Retrieve the value stored in OBJ in the slot named by SLOT.
208 Slot is the name of the slot when created by `defclass' or the label
209 created by the :initarg tag."
210 `(eieio-oref ,obj
(quote ,slot
)))
212 (defalias 'slot-value
'eieio-oref
)
213 (defalias 'set-slot-value
'eieio-oset
)
215 (defmacro oref-default
(obj slot
)
216 "Get the default value of OBJ (maybe a class) for SLOT.
217 The default value is the value installed in a class with the :initform
218 tag. SLOT can be the slot name, or the tag specified by the :initarg
219 tag in the `defclass' call."
220 `(eieio-oref-default ,obj
(quote ,slot
)))
222 ;;; Handy CLOS macros
224 (defmacro with-slots
(spec-list object
&rest body
)
225 "Bind SPEC-LIST lexically to slot values in OBJECT, and execute BODY.
226 This establishes a lexical environment for referring to the slots in
227 the instance named by the given slot-names as though they were
228 variables. Within such a context the value of the slot can be
229 specified by using its slot name, as if it were a lexically bound
230 variable. Both setf and setq can be used to set the value of the
233 SPEC-LIST is of a form similar to `let'. For example:
240 Where each VAR is the local variable given to the associated
241 SLOT. A slot specified without a variable name is given a
242 variable name of the same name as the slot."
244 ;; Transform the spec-list into a symbol-macrolet spec-list.
245 (let ((mappings (mapcar (lambda (entry)
246 (let ((var (if (listp entry
) (car entry
) entry
))
247 (slot (if (listp entry
) (cadr entry
) entry
)))
248 (list var
`(slot-value ,object
',slot
))))
250 (append (list 'symbol-macrolet mappings
)
253 ;;; Simple generators, and query functions. None of these would do
254 ;; well embedded into an object.
256 (define-obsolete-function-alias
257 'object-class-fast
#'eieio--object-class
"24.4")
259 (defun eieio-object-name (obj &optional extra
)
260 "Return a Lisp like symbol string for object OBJ.
261 If EXTRA, include that in the string returned to represent the symbol."
262 (eieio--check-type eieio-object-p obj
)
263 (format "#<%s %s%s>" (symbol-name (eieio--object-class obj
))
264 (eieio--object-name obj
) (or extra
"")))
265 (define-obsolete-function-alias 'object-name
#'eieio-object-name
"24.4")
267 (defun eieio-object-name-string (obj) "Return a string which is OBJ's name."
268 (eieio--check-type eieio-object-p obj
)
269 (eieio--object-name obj
))
270 (define-obsolete-function-alias
271 'object-name-string
#'eieio-object-name-string
"24.4")
273 (defun eieio-object-set-name-string (obj name
)
274 "Set the string which is OBJ's NAME."
275 (eieio--check-type eieio-object-p obj
)
276 (eieio--check-type stringp name
)
277 (setf (eieio--object-name obj
) name
))
278 (define-obsolete-function-alias
279 'object-set-name-string
'eieio-object-set-name-string
"24.4")
281 (defun eieio-object-class (obj) "Return the class struct defining OBJ."
282 (eieio--check-type eieio-object-p obj
)
283 (eieio--object-class obj
))
284 (define-obsolete-function-alias 'object-class
#'eieio-object-class
"24.4")
286 (define-obsolete-function-alias 'class-of
#'eieio-object-class
"24.4")
288 (defun eieio-object-class-name (obj)
289 "Return a Lisp like symbol name for OBJ's class."
290 (eieio--check-type eieio-object-p obj
)
291 (eieio-class-name (eieio--object-class obj
)))
292 (define-obsolete-function-alias
293 'object-class-name
'eieio-object-class-name
"24.4")
295 (defun eieio-class-parents (class)
296 "Return parent classes to CLASS. (overload of variable).
298 The CLOS function `class-direct-superclasses' is aliased to this function."
299 (eieio--check-type class-p class
)
300 (eieio-class-parents-fast class
))
301 (define-obsolete-function-alias 'class-parents
#'eieio-class-parents
"24.4")
303 (defun eieio-class-children (class)
304 "Return child classes to CLASS.
305 The CLOS function `class-direct-subclasses' is aliased to this function."
306 (eieio--check-type class-p class
)
307 (eieio-class-children-fast class
))
308 (define-obsolete-function-alias
309 'class-children
#'eieio-class-children
"24.4")
311 ;; Official CLOS functions.
312 (define-obsolete-function-alias
313 'class-direct-superclasses
#'eieio-class-parents
"24.4")
314 (define-obsolete-function-alias
315 'class-direct-subclasses
#'eieio-class-children
"24.4")
317 (defmacro eieio-class-parent
(class)
318 "Return first parent class to CLASS. (overload of variable)."
319 `(car (eieio-class-parents ,class
)))
320 (define-obsolete-function-alias 'class-parent
#'eieio-class-parent
"24.4")
322 (defun same-class-p (obj class
) "Return t if OBJ is of class-type CLASS."
323 (eieio--check-type class-p class
)
324 (eieio--check-type eieio-object-p obj
)
325 (same-class-fast-p obj class
))
327 (defun object-of-class-p (obj class
)
328 "Return non-nil if OBJ is an instance of CLASS or CLASS' subclasses."
329 (eieio--check-type eieio-object-p obj
)
330 ;; class will be checked one layer down
331 (child-of-class-p (eieio--object-class obj
) class
))
332 ;; Backwards compatibility
333 (defalias 'obj-of-class-p
'object-of-class-p
)
335 (defun child-of-class-p (child class
)
336 "Return non-nil if CHILD class is a subclass of CLASS."
337 (eieio--check-type class-p class
)
338 (eieio--check-type class-p child
)
340 (while (and child
(not (eq child class
)))
341 (setq p
(append p
(eieio--class-parent (class-v child
)))
346 (defun object-slots (obj)
347 "Return list of slots available in OBJ."
348 (eieio--check-type eieio-object-p obj
)
349 (eieio--class-public-a (class-v (eieio--object-class obj
))))
351 (defun class-slot-initarg (class slot
) "Fetch from CLASS, SLOT's :initarg."
352 (eieio--check-type class-p class
)
353 (let ((ia (eieio--class-initarg-tuples (class-v class
)))
355 (while (and ia
(not f
))
356 (if (eq (cdr (car ia
)) slot
)
357 (setq f
(car (car ia
))))
361 ;;; Object Set macros
363 (defmacro oset
(obj slot value
)
364 "Set the value in OBJ for slot SLOT to VALUE.
365 SLOT is the slot name as specified in `defclass' or the tag created
366 with in the :initarg slot. VALUE can be any Lisp object."
367 `(eieio-oset ,obj
(quote ,slot
) ,value
))
369 (defmacro oset-default
(class slot value
)
370 "Set the default slot in CLASS for SLOT to VALUE.
371 The default value is usually set with the :initform tag during class
372 creation. This allows users to change the default behavior of classes
373 after they are created."
374 `(eieio-oset-default ,class
(quote ,slot
) ,value
))
376 ;;; CLOS queries into classes and slots
378 (defun slot-boundp (object slot
)
379 "Return non-nil if OBJECT's SLOT is bound.
380 Setting a slot's value makes it bound. Calling `slot-makeunbound' will
382 OBJECT can be an instance or a class."
383 ;; Skip typechecking while retrieving this value.
384 (let ((eieio-skip-typecheck t
))
385 ;; Return nil if the magic symbol is in there.
387 ((eieio-object-p object
) (eieio-oref object slot
))
388 ((class-p object
) (eieio-oref-default object slot
))
389 (t (signal 'wrong-type-argument
(list 'eieio-object-p object
))))
392 (defun slot-makeunbound (object slot
)
393 "In OBJECT, make SLOT unbound."
394 (eieio-oset object slot eieio-unbound
))
396 (defun slot-exists-p (object-or-class slot
)
397 "Return non-nil if OBJECT-OR-CLASS has SLOT."
398 (let ((cv (class-v (cond ((eieio-object-p object-or-class
)
399 (eieio-object-class object-or-class
))
400 ((class-p object-or-class
)
403 (or (memq slot
(eieio--class-public-a cv
))
404 (memq slot
(eieio--class-class-allocation-a cv
)))
407 (defun find-class (symbol &optional errorp
)
408 "Return the class that SYMBOL represents.
409 If there is no class, nil is returned if ERRORP is nil.
410 If ERRORP is non-nil, `wrong-argument-type' is signaled."
411 (if (not (class-p symbol
))
412 (if errorp
(signal 'wrong-type-argument
(list 'class-p symbol
))
416 ;;; Slightly more complex utility functions for objects
418 (defun object-assoc (key slot list
)
419 "Return an object if KEY is `equal' to SLOT's value of an object in LIST.
420 LIST is a list of objects whose slots are searched.
421 Objects in LIST do not need to have a slot named SLOT, nor does
422 SLOT need to be bound. If these errors occur, those objects will
424 (eieio--check-type listp list
)
425 (while (and list
(not (condition-case nil
426 ;; This prevents errors for missing slots.
427 (equal key
(eieio-oref (car list
) slot
))
429 (setq list
(cdr list
)))
432 (defun object-assoc-list (slot list
)
433 "Return an association list with the contents of SLOT as the key element.
434 LIST must be a list of objects with SLOT in it.
435 This is useful when you need to do completing read on an object group."
436 (eieio--check-type listp list
)
437 (let ((assoclist nil
))
439 (setq assoclist
(cons (cons (eieio-oref (car list
) slot
)
442 (setq list
(cdr list
)))
443 (nreverse assoclist
)))
445 (defun object-assoc-list-safe (slot list
)
446 "Return an association list with the contents of SLOT as the key element.
447 LIST must be a list of objects, but those objects do not need to have
448 SLOT in it. If it does not, then that element is left out of the association
450 (eieio--check-type listp list
)
451 (let ((assoclist nil
))
453 (if (slot-exists-p (car list
) slot
)
454 (setq assoclist
(cons (cons (eieio-oref (car list
) slot
)
457 (setq list
(cdr list
)))
458 (nreverse assoclist
)))
460 (defun object-add-to-list (object slot item
&optional append
)
461 "In OBJECT's SLOT, add ITEM to the list of elements.
462 Optional argument APPEND indicates we need to append to the list.
463 If ITEM already exists in the list in SLOT, then it is not added.
464 Comparison is done with `equal' through the `member' function call.
465 If SLOT is unbound, bind it to the list containing ITEM."
467 ;; Find the originating list.
468 (if (not (slot-boundp object slot
))
469 (setq ov
(list item
))
470 (setq ov
(eieio-oref object slot
))
471 ;; turn it into a list.
474 ;; Do the combination
475 (if (not (member item ov
))
478 (append ov
(list item
))
480 ;; Set back into the slot.
481 (eieio-oset object slot ov
)))
483 (defun object-remove-from-list (object slot item
)
484 "In OBJECT's SLOT, remove occurrences of ITEM.
485 Deletion is done with `delete', which deletes by side effect,
486 and comparisons are done with `equal'.
487 If SLOT is unbound, do nothing."
488 (if (not (slot-boundp object slot
))
490 (eieio-oset object slot
(delete item
(eieio-oref object slot
)))))
493 ;; Method Calling Functions
495 (defun next-method-p ()
496 "Return non-nil if there is a next method.
497 Returns a list of lambda expressions which is the `next-method'
499 eieio-generic-call-next-method-list
)
501 (defun call-next-method (&rest replacement-args
)
502 "Call the superclass method from a subclass method.
503 The superclass method is specified in the current method list,
504 and is called the next method.
506 If REPLACEMENT-ARGS is non-nil, then use them instead of
507 `eieio-generic-call-arglst'. The generic arg list are the
508 arguments passed in at the top level.
510 Use `next-method-p' to find out if there is a next method to call."
511 (if (not (eieio--scoped-class))
512 (error "`call-next-method' not called within a class specific method"))
513 (if (and (/= eieio-generic-call-key method-primary
)
514 (/= eieio-generic-call-key method-static
))
515 (error "Cannot `call-next-method' except in :primary or :static methods")
517 (let ((newargs (or replacement-args eieio-generic-call-arglst
))
518 (next (car eieio-generic-call-next-method-list
))
520 (if (or (not next
) (not (car next
)))
521 (apply 'no-next-method
(car newargs
) (cdr newargs
))
522 (let* ((eieio-generic-call-next-method-list
523 (cdr eieio-generic-call-next-method-list
))
524 (eieio-generic-call-arglst newargs
)
527 (eieio--with-scoped-class (cdr next
)
528 (apply fcn newargs
)) ))))
530 ;;; Here are some CLOS items that need the CL package
533 (defsetf eieio-oref eieio-oset
)
535 (if (eval-when-compile (fboundp 'gv-define-expander
))
536 ;; Not needed for Emacs>=24.3 since gv.el's setf expands macros and
539 (defsetf slot-value eieio-oset
)
541 ;; The below setf method was written by Arnd Kohrs <kohrs@acm.org>
542 (define-setf-method oref
(obj slot
)
545 (let ((obj-temp (gensym))
547 (store-temp (gensym)))
548 (list (list obj-temp slot-temp
)
549 (list obj
`(quote ,slot
))
551 (list 'set-slot-value obj-temp slot-temp
553 (list 'slot-value obj-temp slot-temp
))))))
557 ;; We want all objects created by EIEIO to have some default set of
558 ;; behaviors so we can create object utilities, and allow various
559 ;; types of error checking. To do this, create the default EIEIO
560 ;; class, and when no parent class is specified, use this as the
561 ;; default. (But don't store it in the other classes as the default,
562 ;; allowing for transparent support.)
565 (defclass eieio-default-superclass nil
567 "Default parent class for classes with no specified parent class.
568 Its slots are automatically adopted by classes with no specified parents.
569 This class is not stored in the `parent' slot of a class vector."
572 (defalias 'standard-class
'eieio-default-superclass
)
574 (defgeneric constructor
(class newname
&rest slots
)
575 "Default constructor for CLASS `eieio-default-superclass'.")
577 (defmethod constructor :static
578 ((class eieio-default-superclass
) newname
&rest slots
)
579 "Default constructor for CLASS `eieio-default-superclass'.
580 NEWNAME is the name to be given to the constructed object.
581 SLOTS are the initialization slots used by `shared-initialize'.
582 This static method is called when an object is constructed.
583 It allocates the vector used to represent an EIEIO object, and then
584 calls `shared-initialize' on that object."
585 (let* ((new-object (copy-sequence (eieio--class-default-object-cache (class-v class
)))))
586 ;; Update the name for the newly created object.
587 (setf (eieio--object-name new-object
) newname
)
588 ;; Call the initialize method on the new object with the slots
589 ;; that were passed down to us.
590 (initialize-instance new-object slots
)
591 ;; Return the created object.
594 (defgeneric shared-initialize
(obj slots
)
595 "Set slots of OBJ with SLOTS which is a list of name/value pairs.
596 Called from the constructor routine.")
598 (defmethod shared-initialize ((obj eieio-default-superclass
) slots
)
599 "Set slots of OBJ with SLOTS which is a list of name/value pairs.
600 Called from the constructor routine."
601 (eieio--with-scoped-class (eieio--object-class obj
)
603 (let ((rn (eieio-initarg-to-attribute (eieio--object-class obj
)
606 (slot-missing obj
(car slots
) 'oset
(car (cdr slots
)))
607 (eieio-oset obj rn
(car (cdr slots
)))))
608 (setq slots
(cdr (cdr slots
))))))
610 (defgeneric initialize-instance
(this &optional slots
)
611 "Construct the new object THIS based on SLOTS.")
613 (defmethod initialize-instance ((this eieio-default-superclass
)
615 "Construct the new object THIS based on SLOTS.
616 SLOTS is a tagged list where odd numbered elements are tags, and
617 even numbered elements are the values to store in the tagged slot.
618 If you overload the `initialize-instance', there you will need to
619 call `shared-initialize' yourself, or you can call `call-next-method'
620 to have this constructor called automatically. If these steps are
621 not taken, then new objects of your class will not have their values
622 dynamically set from SLOTS."
623 ;; First, see if any of our defaults are `lambda', and
624 ;; re-evaluate them and apply the value to our slots.
625 (let* ((this-class (class-v (eieio--object-class this
)))
626 (slot (eieio--class-public-a this-class
))
627 (defaults (eieio--class-public-d this-class
)))
629 ;; For each slot, see if we need to evaluate it.
631 ;; Paul Landes said in an email:
632 ;; > CL evaluates it if it can, and otherwise, leaves it as
633 ;; > the quoted thing as you already have. This is by the
634 ;; > Sonya E. Keene book and other things I've look at on the
636 (let ((dflt (eieio-default-eval-maybe (car defaults
))))
637 (when (not (eq dflt
(car defaults
)))
638 (eieio-oset this
(car slot
) dflt
) ))
640 (setq slot
(cdr slot
)
641 defaults
(cdr defaults
))))
642 ;; Shared initialize will parse our slots for us.
643 (shared-initialize this slots
))
645 (defgeneric slot-missing
(object slot-name operation
&optional new-value
)
646 "Method invoked when an attempt to access a slot in OBJECT fails.")
648 (defmethod slot-missing ((object eieio-default-superclass
) slot-name
649 operation
&optional new-value
)
650 "Method invoked when an attempt to access a slot in OBJECT fails.
651 SLOT-NAME is the name of the failed slot, OPERATION is the type of access
652 that was requested, and optional NEW-VALUE is the value that was desired
655 This method is called from `oref', `oset', and other functions which
656 directly reference slots in EIEIO objects."
657 (signal 'invalid-slot-name
(list (eieio-object-name object
)
660 (defgeneric slot-unbound
(object class slot-name fn
)
661 "Slot unbound is invoked during an attempt to reference an unbound slot.")
663 (defmethod slot-unbound ((object eieio-default-superclass
)
665 "Slot unbound is invoked during an attempt to reference an unbound slot.
666 OBJECT is the instance of the object being reference. CLASS is the
667 class of OBJECT, and SLOT-NAME is the offending slot. This function
668 throws the signal `unbound-slot'. You can overload this function and
669 return the value to use in place of the unbound value.
670 Argument FN is the function signaling this error.
671 Use `slot-boundp' to determine if a slot is bound or not.
673 In CLOS, the argument list is (CLASS OBJECT SLOT-NAME), but
674 EIEIO can only dispatch on the first argument, so the first two are swapped."
675 (signal 'unbound-slot
(list (eieio-class-name class
) (eieio-object-name object
)
678 (defgeneric no-applicable-method
(object method
&rest args
)
679 "Called if there are no implementations for OBJECT in METHOD.")
681 (defmethod no-applicable-method ((object eieio-default-superclass
)
683 "Called if there are no implementations for OBJECT in METHOD.
684 OBJECT is the object which has no method implementation.
685 ARGS are the arguments that were passed to METHOD.
687 Implement this for a class to block this signal. The return
688 value becomes the return value of the original method call."
689 (signal 'no-method-definition
(list method
(eieio-object-name object
)))
692 (defgeneric no-next-method
(object &rest args
)
693 "Called from `call-next-method' when no additional methods are available.")
695 (defmethod no-next-method ((object eieio-default-superclass
)
697 "Called from `call-next-method' when no additional methods are available.
698 OBJECT is othe object being called on `call-next-method'.
699 ARGS are the arguments it is called by.
700 This method signals `no-next-method' by default. Override this
701 method to not throw an error, and its return value becomes the
702 return value of `call-next-method'."
703 (signal 'no-next-method
(list (eieio-object-name object
) args
))
706 (defgeneric clone
(obj &rest params
)
707 "Make a copy of OBJ, and then supply PARAMS.
708 PARAMS is a parameter list of the same form used by `initialize-instance'.
710 When overloading `clone', be sure to call `call-next-method'
711 first and modify the returned object.")
713 (defmethod clone ((obj eieio-default-superclass
) &rest params
)
714 "Make a copy of OBJ, and then apply PARAMS."
715 (let ((nobj (copy-sequence obj
))
716 (nm (eieio--object-name obj
))
717 (passname (and params
(stringp (car params
))))
719 (if params
(shared-initialize nobj
(if passname
(cdr params
) params
)))
722 (if (string-match "-\\([0-9]+\\)" nm
)
723 (setq num
(1+ (string-to-number (match-string 1 nm
)))
724 nm
(substring nm
0 (match-beginning 0))))
725 (setf (eieio--object-name nobj
) (concat nm
"-" (int-to-string num
))))
726 (setf (eieio--object-name nobj
) (car params
)))
729 (defgeneric destructor
(this &rest params
)
730 "Destructor for cleaning up any dynamic links to our object.")
732 (defmethod destructor ((this eieio-default-superclass
) &rest params
)
733 "Destructor for cleaning up any dynamic links to our object.
734 Argument THIS is the object being destroyed. PARAMS are additional
736 ;; No cleanup... yet.
739 (defgeneric object-print
(this &rest strings
)
740 "Pretty printer for object THIS. Call function `object-name' with STRINGS.
742 It is sometimes useful to put a summary of the object into the
743 default #<notation> string when using EIEIO browsing tools.
744 Implement this method to customize the summary.")
746 (defmethod object-print ((this eieio-default-superclass
) &rest strings
)
747 "Pretty printer for object THIS. Call function `object-name' with STRINGS.
748 The default method for printing object THIS is to use the
749 function `object-name'.
751 It is sometimes useful to put a summary of the object into the
752 default #<notation> string when using EIEIO browsing tools.
754 Implement this function and specify STRINGS in a call to
755 `call-next-method' to provide additional summary information.
756 When passing in extra strings from child classes, always remember
758 (eieio-object-name this
(apply 'concat strings
)))
760 (defvar eieio-print-depth
0
761 "When printing, keep track of the current indentation depth.")
763 (defgeneric object-write
(this &optional comment
)
764 "Write out object THIS to the current stream.
765 Optional COMMENT will add comments to the beginning of the output.")
767 (defmethod object-write ((this eieio-default-superclass
) &optional comment
)
768 "Write object THIS out to the current stream.
769 This writes out the vector version of this object. Complex and recursive
770 object are discouraged from being written.
771 If optional COMMENT is non-nil, include comments when outputting
775 (princ (eieio-object-name-string this
))
779 (let* ((cl (eieio-object-class this
))
781 ;; Now output readable lisp to recreate this object
782 ;; It should look like this:
783 ;; (<constructor> <name> <slot> <slot> ... )
784 ;; Each slot's slot is writen using its :writer.
785 (princ (make-string (* eieio-print-depth
2) ?
))
787 (princ (symbol-name (class-constructor (eieio-object-class this
))))
789 (prin1 (eieio-object-name-string this
))
791 ;; Loop over all the public slots
792 (let ((publa (eieio--class-public-a cv
))
793 (publd (eieio--class-public-d cv
))
794 (publp (eieio--class-public-printer cv
))
795 (eieio-print-depth (1+ eieio-print-depth
)))
797 (when (slot-boundp this
(car publa
))
798 (let ((i (class-slot-initarg cl
(car publa
)))
799 (v (eieio-oref this
(car publa
)))
801 (unless (or (not i
) (equal v
(car publd
)))
804 (princ (make-string (* eieio-print-depth
2) ?
))
805 (princ (symbol-name i
))
807 ;; Use our public printer
810 (funcall (car publp
) v
))
811 ;; Use our generic override prin1 function.
812 (princ (if (or (eieio-object-p v
)
813 (eieio-object-p (car-safe v
)))
815 (eieio-override-prin1 v
)))))
816 (setq publa
(cdr publa
) publd
(cdr publd
)
819 (when (= eieio-print-depth
0)
822 (defun eieio-override-prin1 (thing)
823 "Perform a `prin1' on THING taking advantage of object knowledge."
824 (cond ((eieio-object-p thing
)
825 (object-write thing
))
827 (eieio-list-prin1 thing
))
829 (princ (eieio-class-name thing
)))
830 ((or (keywordp thing
) (booleanp thing
))
833 (princ (concat "'" (symbol-name thing
))))
836 (defun eieio-list-prin1 (list)
837 "Display LIST where list may contain objects."
838 (if (not (eieio-object-p (car list
)))
842 (princ (make-string (* eieio-print-depth
2) ?
))
844 (let ((eieio-print-depth (1+ eieio-print-depth
)))
847 (if (eieio-object-p (car list
))
848 (object-write (car list
))
849 (princ (make-string (* eieio-print-depth
2) ?
))
850 (eieio-override-prin1 (car list
)))
851 (setq list
(cdr list
))))
855 ;;; Unimplemented functions from CLOS
857 (defun change-class (obj class
)
858 "Change the class of OBJ to type CLASS.
859 This may create or delete slots, but does not affect the return value
861 (error "EIEIO: `change-class' is unimplemented"))
863 ;;; Interfacing with edebug
865 (defun eieio-edebug-prin1-to-string (object &optional noescape
)
866 "Display EIEIO OBJECT in fancy format.
867 Overrides the edebug default.
868 Optional argument NOESCAPE is passed to `prin1-to-string' when appropriate."
869 (cond ((class-p object
) (eieio-class-name object
))
870 ((eieio-object-p object
) (object-print object
))
871 ((and (listp object
) (or (class-p (car object
))
872 (eieio-object-p (car object
))))
873 (concat "(" (mapconcat 'eieio-edebug-prin1-to-string object
" ") ")"))
874 (t (prin1-to-string object noescape
))))
876 (add-hook 'edebug-setup-hook
878 (def-edebug-spec defmethod
879 (&define
; this means we are defining something
880 [&or name
("setf" :name setf name
)]
881 ;; ^^ This is the methods symbol
882 [ &optional symbolp
] ; this is key :before etc
884 [ &optional stringp
] ; documentation string
885 def-body
; part to be debugged
887 ;; The rest of the macros
888 (def-edebug-spec oref
(form quote
))
889 (def-edebug-spec oref-default
(form quote
))
890 (def-edebug-spec oset
(form quote form
))
891 (def-edebug-spec oset-default
(form quote form
))
892 (def-edebug-spec class-v form
)
893 (def-edebug-spec class-p form
)
894 (def-edebug-spec eieio-object-p form
)
895 (def-edebug-spec class-constructor form
)
896 (def-edebug-spec generic-p form
)
897 (def-edebug-spec with-slots
(list list def-body
))
898 ;; I suspect this isn't the best way to do this, but when
899 ;; cust-print was used on my system all my objects
900 ;; appeared as "#1 =" which was not useful. This allows
901 ;; edebug to print my objects in the nice way they were
902 ;; meant to with `object-print' and `class-name'
903 ;; (defalias 'edebug-prin1-to-string 'eieio-edebug-prin1-to-string)
907 ;;; Autoloading some external symbols, and hooking into the help system
911 ;;; Start of automatically extracted autoloads.
913 ;;;### (autoloads (customize-object) "eieio-custom" "eieio-custom.el"
914 ;;;;;; "928623502e8bf40454822355388542b5")
915 ;;; Generated autoloads from eieio-custom.el
917 (autoload 'customize-object
"eieio-custom" "\
918 Customize OBJ in a custom buffer.
919 Optional argument GROUP is the sub-group of slots to display.
921 \(fn OBJ &optional GROUP)" nil nil
)
925 ;;;### (autoloads (eieio-help-mode-augmentation-maybee eieio-describe-generic
926 ;;;;;; eieio-describe-constructor eieio-describe-class eieio-browse)
927 ;;;;;; "eieio-opt" "eieio-opt.el" "d808328f9c0156ecbd412d77ba8c569e")
928 ;;; Generated autoloads from eieio-opt.el
930 (autoload 'eieio-browse
"eieio-opt" "\
931 Create an object browser window to show all objects.
932 If optional ROOT-CLASS, then start with that, otherwise start with
933 variable `eieio-default-superclass'.
935 \(fn &optional ROOT-CLASS)" t nil
)
936 (defalias 'describe-class
'eieio-describe-class
)
938 (autoload 'eieio-describe-class
"eieio-opt" "\
939 Describe a CLASS defined by a string or symbol.
940 If CLASS is actually an object, then also display current values of that object.
941 Optional HEADERFCN should be called to insert a few bits of info first.
943 \(fn CLASS &optional HEADERFCN)" t nil
)
945 (autoload 'eieio-describe-constructor
"eieio-opt" "\
946 Describe the constructor function FCN.
947 Uses `eieio-describe-class' to describe the class being constructed.
950 (defalias 'describe-generic
'eieio-describe-generic
)
952 (autoload 'eieio-describe-generic
"eieio-opt" "\
953 Describe the generic function GENERIC.
954 Also extracts information about all methods specific to this generic.
956 \(fn GENERIC)" t nil
)
958 (autoload 'eieio-help-mode-augmentation-maybee
"eieio-opt" "\
959 For buffers thrown into help mode, augment for EIEIO.
960 Arguments UNUSED are not used.
962 \(fn &rest UNUSED)" nil nil
)
966 ;;; End of automatically extracted autoloads.