* erc-desktop-notifications.el (erc-notifications-bus):
[emacs.git] / lisp / emacs-lisp / eieio.el
1 ;;; eieio.el --- Enhanced Implementation of Emacs Interpreted Objects  -*- lexical-binding:t -*-
2 ;;;              or maybe Eric's Implementation of Emacs Interpreted Objects
3
4 ;; Copyright (C) 1995-1996, 1998-2014 Free Software Foundation, Inc.
5
6 ;; Author: Eric M. Ludlam <zappo@gnu.org>
7 ;; Version: 1.4
8 ;; Keywords: OO, lisp
9
10 ;; This file is part of GNU Emacs.
11
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.
16
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.
21
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/>.
24
25 ;;; Commentary:
26 ;;
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.
31 ;;
32 ;; See eieio.texi for complete documentation on using this package.
33 ;;
34 ;; Note: the implementation of the c3 algorithm is based on:
35 ;;   Kim Barrett et al.: A Monotonic Superclass Linearization for Dylan
36 ;;   Retrieved from:
37 ;;   http://192.220.96.201/dylan/linearization-oopsla96.html
38
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.
41
42 ;; @TODO - fix :initform to be a form, not a quoted value
43 ;; @TODO - Prefix non-clos functions with `eieio-'.
44
45 ;;; Code:
46
47 (defvar eieio-version "1.4"
48   "Current version of EIEIO.")
49
50 (defun eieio-version ()
51   "Display the current version of EIEIO."
52   (interactive)
53   (message eieio-version))
54
55 (require 'eieio-core)
56
57 \f
58 ;;; Defining a new class
59 ;;
60 (defmacro defclass (name superclass slots &rest options-and-doc)
61   "Define NAME as a new class derived from SUPERCLASS with SLOTS.
62 OPTIONS-AND-DOC is used as the class' options and base documentation.
63 SUPERCLASS is a list of superclasses to inherit from, with SLOTS
64 being the slots residing in that class definition.  NOTE: Currently
65 only one slot may exist in SUPERCLASS as multiple inheritance is not
66 yet supported.  Supported tags are:
67
68   :initform   - Initializing form.
69   :initarg    - Tag used during initialization.
70   :accessor   - Tag used to create a function to access this slot.
71   :allocation - Specify where the value is stored.
72                 Defaults to `:instance', but could also be `:class'.
73   :writer     - A function symbol which will `write' an object's slot.
74   :reader     - A function symbol which will `read' an object.
75   :type       - The type of data allowed in this slot (see `typep').
76   :documentation
77               - A string documenting use of this slot.
78
79 The following are extensions on CLOS:
80   :protection - Specify protection for this slot.
81                 Defaults to `:public'.  Also use `:protected', or `:private'.
82   :custom     - When customizing an object, the custom :type.  Public only.
83   :label      - A text string label used for a slot when customizing.
84   :group      - Name of a customization group this slot belongs in.
85   :printer    - A function to call to print the value of a slot.
86                 See `eieio-override-prin1' as an example.
87
88 A class can also have optional options.  These options happen in place
89 of documentation (including a :documentation tag), in addition to
90 documentation, or not at all.  Supported options are:
91
92   :documentation - The doc-string used for this class.
93
94 Options added to EIEIO:
95
96   :allow-nil-initform - Non-nil to skip typechecking of null initforms.
97   :custom-groups      - List of custom group names.  Organizes slots into
98                         reasonable groups for customizations.
99   :abstract           - Non-nil to prevent instances of this class.
100                         If a string, use as an error string if someone does
101                         try to make an instance.
102   :method-invocation-order
103                       - Control the method invocation order if there is
104                         multiple inheritance.  Valid values are:
105                          :breadth-first - The default.
106                          :depth-first
107
108 Options in CLOS not supported in EIEIO:
109
110   :metaclass - Class to use in place of `standard-class'
111   :default-initargs - Initargs to use when initializing new objects of
112                       this class.
113
114 Due to the way class options are set up, you can add any tags you wish,
115 and reference them using the function `class-option'."
116   (declare (doc-string 4))
117   ;; This is eval-and-compile only to silence spurious compiler warnings
118   ;; about functions and variables not known to be defined.
119   ;; When eieio-defclass code is merged here and this becomes
120   ;; transparent to the compiler, the eval-and-compile can be removed.
121   `(eval-and-compile
122      (eieio-defclass ',name ',superclass ',slots ',options-and-doc)))
123
124
125 ;;; CLOS style implementation of object creators.
126 ;;
127 (defun make-instance (class &rest initargs)
128   "Make a new instance of CLASS based on INITARGS.
129 CLASS is a class symbol.  For example:
130
131   (make-instance 'foo)
132
133   INITARGS is a property list with keywords based on the :initarg
134 for each slot.  For example:
135
136   (make-instance 'foo :slot1 value1 :slotN valueN)
137
138 Compatibility note:
139
140 If the first element of INITARGS is a string, it is used as the
141 name of the class.
142
143 In EIEIO, the class' constructor requires a name for use when printing.
144 `make-instance' in CLOS doesn't use names the way Emacs does, so the
145 class is used as the name slot instead when INITARGS doesn't start with
146 a string."
147   (if (and (car initargs) (stringp (car initargs)))
148       (apply (class-constructor class) initargs)
149     (apply  (class-constructor class)
150             (cond ((symbolp class) (symbol-name class))
151                   (t (format "%S" class)))
152             initargs)))
153
154 \f
155 ;;; CLOS methods and generics
156 ;;
157 (defmacro defgeneric (method _args &optional doc-string)
158   "Create a generic function METHOD.
159 DOC-STRING is the base documentation for this class.  A generic
160 function has no body, as its purpose is to decide which method body
161 is appropriate to use.  Uses `defmethod' to create methods, and calls
162 `defgeneric' for you.  With this implementation the ARGS are
163 currently ignored.  You can use `defgeneric' to apply specialized
164 top level documentation to a method."
165   (declare (doc-string 3))
166   `(eieio--defalias ',method
167                     (eieio--defgeneric-init-form ',method ,doc-string)))
168
169 (defmacro defmethod (method &rest args)
170   "Create a new METHOD through `defgeneric' with ARGS.
171
172 The optional second argument KEY is a specifier that
173 modifies how the method is called, including:
174    :before  - Method will be called before the :primary
175    :primary - The default if not specified
176    :after   - Method will be called after the :primary
177    :static  - First arg could be an object or class
178 The next argument is the ARGLIST.  The ARGLIST specifies the arguments
179 to the method as with `defun'.  The first argument can have a type
180 specifier, such as:
181   ((VARNAME CLASS) ARG2 ...)
182 where VARNAME is the name of the local variable for the method being
183 created.  The CLASS is a class symbol for a class made with `defclass'.
184 A DOCSTRING comes after the ARGLIST, and is optional.
185 All the rest of the args are the BODY of the method.  A method will
186 return the value of the last form in the BODY.
187
188 Summary:
189
190  (defmethod mymethod [:before | :primary | :after | :static]
191                      ((typearg class-name) arg2 &optional opt &rest rest)
192     \"doc-string\"
193      body)"
194   (declare (doc-string 3))
195   (let* ((key (if (keywordp (car args)) (pop args)))
196          (params (car args))
197          (arg1 (car params))
198          (fargs (if (consp arg1)
199                    (cons (car arg1) (cdr params))
200                  params))
201          (class (if (consp arg1) (nth 1 arg1)))
202          (code `(lambda ,fargs ,@(cdr args))))
203     `(progn
204        ;; Make sure there is a generic and the byte-compiler sees it.
205        (defgeneric ,method ,args
206          ,(or (documentation code)
207               (format "Generically created method `%s'." method)))
208        (eieio--defmethod ',method ',key ',class #',code))))
209
210 ;;; Get/Set slots in an object.
211 ;;
212 (defmacro oref (obj slot)
213   "Retrieve the value stored in OBJ in the slot named by SLOT.
214 Slot is the name of the slot when created by `defclass' or the label
215 created by the :initarg tag."
216   `(eieio-oref ,obj (quote ,slot)))
217
218 (defalias 'slot-value 'eieio-oref)
219 (defalias 'set-slot-value 'eieio-oset)
220
221 (defmacro oref-default (obj slot)
222   "Get the default value of OBJ (maybe a class) for SLOT.
223 The default value is the value installed in a class with the :initform
224 tag.  SLOT can be the slot name, or the tag specified by the :initarg
225 tag in the `defclass' call."
226   `(eieio-oref-default ,obj (quote ,slot)))
227
228 ;;; Handy CLOS macros
229 ;;
230 (defmacro with-slots (spec-list object &rest body)
231   "Bind SPEC-LIST lexically to slot values in OBJECT, and execute BODY.
232 This establishes a lexical environment for referring to the slots in
233 the instance named by the given slot-names as though they were
234 variables.  Within such a context the value of the slot can be
235 specified by using its slot name, as if it were a lexically bound
236 variable.  Both setf and setq can be used to set the value of the
237 slot.
238
239 SPEC-LIST is of a form similar to `let'.  For example:
240
241   ((VAR1 SLOT1)
242     SLOT2
243     SLOTN
244    (VARN+1 SLOTN+1))
245
246 Where each VAR is the local variable given to the associated
247 SLOT.  A slot specified without a variable name is given a
248 variable name of the same name as the slot."
249   (declare (indent 2))
250   (require 'cl-lib)
251   ;; Transform the spec-list into a cl-symbol-macrolet spec-list.
252   (let ((mappings (mapcar (lambda (entry)
253                             (let ((var  (if (listp entry) (car entry) entry))
254                                   (slot (if (listp entry) (cadr entry) entry)))
255                               (list var `(slot-value ,object ',slot))))
256                           spec-list)))
257     (append (list 'cl-symbol-macrolet mappings)
258             body)))
259 \f
260 ;;; Simple generators, and query functions.  None of these would do
261 ;;  well embedded into an object.
262 ;;
263 (define-obsolete-function-alias
264   'object-class-fast #'eieio--object-class "24.4")
265
266 (defun eieio-object-name (obj &optional extra)
267   "Return a Lisp like symbol string for object OBJ.
268 If EXTRA, include that in the string returned to represent the symbol."
269   (eieio--check-type eieio-object-p obj)
270   (format "#<%s %s%s>" (symbol-name (eieio--object-class obj))
271           (eieio--object-name obj) (or extra "")))
272 (define-obsolete-function-alias 'object-name #'eieio-object-name "24.4")
273
274 (defun eieio-object-name-string (obj) "Return a string which is OBJ's name."
275   (eieio--check-type eieio-object-p obj)
276   (eieio--object-name obj))
277 (define-obsolete-function-alias
278   'object-name-string #'eieio-object-name-string "24.4")
279
280 (defun eieio-object-set-name-string (obj name)
281   "Set the string which is OBJ's NAME."
282   (eieio--check-type eieio-object-p obj)
283   (eieio--check-type stringp name)
284   (setf (eieio--object-name obj) name))
285 (define-obsolete-function-alias
286   'object-set-name-string 'eieio-object-set-name-string "24.4")
287
288 (defun eieio-object-class (obj) "Return the class struct defining OBJ."
289   (eieio--check-type eieio-object-p obj)
290   (eieio--object-class obj))
291 (define-obsolete-function-alias 'object-class #'eieio-object-class "24.4")
292 ;; CLOS name, maybe?
293 (define-obsolete-function-alias 'class-of #'eieio-object-class "24.4")
294
295 (defun eieio-object-class-name (obj)
296   "Return a Lisp like symbol name for OBJ's class."
297   (eieio--check-type eieio-object-p obj)
298   (eieio-class-name (eieio--object-class obj)))
299 (define-obsolete-function-alias
300   'object-class-name 'eieio-object-class-name "24.4")
301
302 (defun eieio-class-parents (class)
303   "Return parent classes to CLASS.  (overload of variable).
304
305 The CLOS function `class-direct-superclasses' is aliased to this function."
306   (eieio--check-type class-p class)
307   (eieio-class-parents-fast class))
308 (define-obsolete-function-alias 'class-parents #'eieio-class-parents "24.4")
309
310 (defun eieio-class-children (class)
311   "Return child classes to CLASS.
312 The CLOS function `class-direct-subclasses' is aliased to this function."
313   (eieio--check-type class-p class)
314   (eieio-class-children-fast class))
315 (define-obsolete-function-alias
316   'class-children #'eieio-class-children "24.4")
317
318 ;; Official CLOS functions.
319 (define-obsolete-function-alias
320   'class-direct-superclasses #'eieio-class-parents "24.4")
321 (define-obsolete-function-alias
322   'class-direct-subclasses #'eieio-class-children "24.4")
323
324 (defmacro eieio-class-parent (class)
325   "Return first parent class to CLASS.  (overload of variable)."
326   `(car (eieio-class-parents ,class)))
327 (define-obsolete-function-alias 'class-parent 'eieio-class-parent "24.4")
328
329 (defun same-class-p (obj class) "Return t if OBJ is of class-type CLASS."
330   (eieio--check-type class-p class)
331   (eieio--check-type eieio-object-p obj)
332   (same-class-fast-p obj class))
333
334 (defun object-of-class-p (obj class)
335   "Return non-nil if OBJ is an instance of CLASS or CLASS' subclasses."
336   (eieio--check-type eieio-object-p obj)
337   ;; class will be checked one layer down
338   (child-of-class-p (eieio--object-class obj) class))
339 ;; Backwards compatibility
340 (defalias 'obj-of-class-p 'object-of-class-p)
341
342 (defun child-of-class-p (child class)
343   "Return non-nil if CHILD class is a subclass of CLASS."
344   (eieio--check-type class-p class)
345   (eieio--check-type class-p child)
346   (let ((p nil))
347     (while (and child (not (eq child class)))
348       (setq p (append p (eieio--class-parent (class-v child)))
349             child (car p)
350             p (cdr p)))
351     (if child t)))
352
353 (defun object-slots (obj)
354   "Return list of slots available in OBJ."
355   (eieio--check-type eieio-object-p obj)
356   (eieio--class-public-a (class-v (eieio--object-class obj))))
357
358 (defun class-slot-initarg (class slot) "Fetch from CLASS, SLOT's :initarg."
359   (eieio--check-type class-p class)
360   (let ((ia (eieio--class-initarg-tuples (class-v class)))
361         (f nil))
362     (while (and ia (not f))
363       (if (eq (cdr (car ia)) slot)
364           (setq f (car (car ia))))
365       (setq ia (cdr ia)))
366     f))
367
368 ;;; Object Set macros
369 ;;
370 (defmacro oset (obj slot value)
371   "Set the value in OBJ for slot SLOT to VALUE.
372 SLOT is the slot name as specified in `defclass' or the tag created
373 with in the :initarg slot.  VALUE can be any Lisp object."
374   `(eieio-oset ,obj (quote ,slot) ,value))
375
376 (defmacro oset-default (class slot value)
377   "Set the default slot in CLASS for SLOT to VALUE.
378 The default value is usually set with the :initform tag during class
379 creation.  This allows users to change the default behavior of classes
380 after they are created."
381   `(eieio-oset-default ,class (quote ,slot) ,value))
382
383 ;;; CLOS queries into classes and slots
384 ;;
385 (defun slot-boundp (object slot)
386   "Return non-nil if OBJECT's SLOT is bound.
387 Setting a slot's value makes it bound.  Calling `slot-makeunbound' will
388 make a slot unbound.
389 OBJECT can be an instance or a class."
390   ;; Skip typechecking while retrieving this value.
391   (let ((eieio-skip-typecheck t))
392     ;; Return nil if the magic symbol is in there.
393     (not (eq (cond
394               ((eieio-object-p object) (eieio-oref object slot))
395               ((class-p object)        (eieio-oref-default object slot))
396               (t (signal 'wrong-type-argument (list 'eieio-object-p object))))
397              eieio-unbound))))
398
399 (defun slot-makeunbound (object slot)
400   "In OBJECT, make SLOT unbound."
401   (eieio-oset object slot eieio-unbound))
402
403 (defun slot-exists-p (object-or-class slot)
404   "Return non-nil if OBJECT-OR-CLASS has SLOT."
405   (let ((cv (class-v (cond ((eieio-object-p object-or-class)
406                             (eieio-object-class object-or-class))
407                            ((class-p object-or-class)
408                             object-or-class))
409                      )))
410     (or (memq slot (eieio--class-public-a cv))
411         (memq slot (eieio--class-class-allocation-a cv)))
412     ))
413
414 (defun find-class (symbol &optional errorp)
415   "Return the class that SYMBOL represents.
416 If there is no class, nil is returned if ERRORP is nil.
417 If ERRORP is non-nil, `wrong-argument-type' is signaled."
418   (if (not (class-p symbol))
419       (if errorp (signal 'wrong-type-argument (list 'class-p symbol))
420         nil)
421     (class-v symbol)))
422
423 ;;; Slightly more complex utility functions for objects
424 ;;
425 (defun object-assoc (key slot list)
426   "Return an object if KEY is `equal' to SLOT's value of an object in LIST.
427 LIST is a list of objects whose slots are searched.
428 Objects in LIST do not need to have a slot named SLOT, nor does
429 SLOT need to be bound.  If these errors occur, those objects will
430 be ignored."
431   (eieio--check-type listp list)
432   (while (and list (not (condition-case nil
433                             ;; This prevents errors for missing slots.
434                             (equal key (eieio-oref (car list) slot))
435                           (error nil))))
436     (setq list (cdr list)))
437   (car list))
438
439 (defun object-assoc-list (slot list)
440   "Return an association list with the contents of SLOT as the key element.
441 LIST must be a list of objects with SLOT in it.
442 This is useful when you need to do completing read on an object group."
443   (eieio--check-type listp list)
444   (let ((assoclist nil))
445     (while list
446       (setq assoclist (cons (cons (eieio-oref (car list) slot)
447                                   (car list))
448                             assoclist))
449       (setq list (cdr list)))
450     (nreverse assoclist)))
451
452 (defun object-assoc-list-safe (slot list)
453   "Return an association list with the contents of SLOT as the key element.
454 LIST must be a list of objects, but those objects do not need to have
455 SLOT in it.  If it does not, then that element is left out of the association
456 list."
457   (eieio--check-type listp list)
458   (let ((assoclist nil))
459     (while list
460       (if (slot-exists-p (car list) slot)
461           (setq assoclist (cons (cons (eieio-oref (car list) slot)
462                                       (car list))
463                                 assoclist)))
464       (setq list (cdr list)))
465     (nreverse assoclist)))
466
467 (defun object-add-to-list (object slot item &optional append)
468   "In OBJECT's SLOT, add ITEM to the list of elements.
469 Optional argument APPEND indicates we need to append to the list.
470 If ITEM already exists in the list in SLOT, then it is not added.
471 Comparison is done with `equal' through the `member' function call.
472 If SLOT is unbound, bind it to the list containing ITEM."
473   (let (ov)
474     ;; Find the originating list.
475     (if (not (slot-boundp object slot))
476         (setq ov (list item))
477       (setq ov (eieio-oref object slot))
478       ;; turn it into a list.
479       (unless (listp ov)
480         (setq ov (list ov)))
481       ;; Do the combination
482       (if (not (member item ov))
483           (setq ov
484                 (if append
485                     (append ov (list item))
486                   (cons item ov)))))
487     ;; Set back into the slot.
488     (eieio-oset object slot ov)))
489
490 (defun object-remove-from-list (object slot item)
491   "In OBJECT's SLOT, remove occurrences of ITEM.
492 Deletion is done with `delete', which deletes by side effect,
493 and comparisons are done with `equal'.
494 If SLOT is unbound, do nothing."
495   (if (not (slot-boundp object slot))
496       nil
497     (eieio-oset object slot (delete item (eieio-oref object slot)))))
498
499 ;;;
500 ;; Method Calling Functions
501
502 (defun next-method-p ()
503   "Return non-nil if there is a next method.
504 Returns a list of lambda expressions which is the `next-method'
505 order."
506   eieio-generic-call-next-method-list)
507
508 (defun call-next-method (&rest replacement-args)
509   "Call the superclass method from a subclass method.
510 The superclass method is specified in the current method list,
511 and is called the next method.
512
513 If REPLACEMENT-ARGS is non-nil, then use them instead of
514 `eieio-generic-call-arglst'.  The generic arg list are the
515 arguments passed in at the top level.
516
517 Use `next-method-p' to find out if there is a next method to call."
518   (if (not (eieio--scoped-class))
519       (error "`call-next-method' not called within a class specific method"))
520   (if (and (/= eieio-generic-call-key method-primary)
521            (/= eieio-generic-call-key method-static))
522       (error "Cannot `call-next-method' except in :primary or :static methods")
523     )
524   (let ((newargs (or replacement-args eieio-generic-call-arglst))
525         (next (car eieio-generic-call-next-method-list))
526         )
527     (if (or (not next) (not (car next)))
528         (apply #'no-next-method (car newargs) (cdr newargs))
529       (let* ((eieio-generic-call-next-method-list
530               (cdr eieio-generic-call-next-method-list))
531              (eieio-generic-call-arglst newargs)
532              (fcn (car next))
533              )
534         (eieio--with-scoped-class (cdr next)
535           (apply fcn newargs)) ))))
536
537 ;;; Here are some CLOS items that need the CL package
538 ;;
539
540 (gv-define-simple-setter eieio-oref eieio-oset)
541
542 \f
543 ;;;
544 ;; We want all objects created by EIEIO to have some default set of
545 ;; behaviors so we can create object utilities, and allow various
546 ;; types of error checking.  To do this, create the default EIEIO
547 ;; class, and when no parent class is specified, use this as the
548 ;; default.  (But don't store it in the other classes as the default,
549 ;; allowing for transparent support.)
550 ;;
551
552 (defclass eieio-default-superclass nil
553   nil
554   "Default parent class for classes with no specified parent class.
555 Its slots are automatically adopted by classes with no specified parents.
556 This class is not stored in the `parent' slot of a class vector."
557   :abstract t)
558
559 (defalias 'standard-class 'eieio-default-superclass)
560
561 (defgeneric constructor (class newname &rest slots)
562   "Default constructor for CLASS `eieio-default-superclass'.")
563
564 (defmethod constructor :static
565   ((class eieio-default-superclass) newname &rest slots)
566   "Default constructor for CLASS `eieio-default-superclass'.
567 NEWNAME is the name to be given to the constructed object.
568 SLOTS are the initialization slots used by `shared-initialize'.
569 This static method is called when an object is constructed.
570 It allocates the vector used to represent an EIEIO object, and then
571 calls `shared-initialize' on that object."
572   (let* ((new-object (copy-sequence (eieio--class-default-object-cache (class-v class)))))
573     ;; Update the name for the newly created object.
574     (setf (eieio--object-name new-object) newname)
575     ;; Call the initialize method on the new object with the slots
576     ;; that were passed down to us.
577     (initialize-instance new-object slots)
578     ;; Return the created object.
579     new-object))
580
581 (defgeneric shared-initialize (obj slots)
582   "Set slots of OBJ with SLOTS which is a list of name/value pairs.
583 Called from the constructor routine.")
584
585 (defmethod shared-initialize ((obj eieio-default-superclass) slots)
586   "Set slots of OBJ with SLOTS which is a list of name/value pairs.
587 Called from the constructor routine."
588   (eieio--with-scoped-class (eieio--object-class obj)
589     (while slots
590       (let ((rn (eieio-initarg-to-attribute (eieio--object-class obj)
591                                             (car slots))))
592         (if (not rn)
593             (slot-missing obj (car slots) 'oset (car (cdr slots)))
594           (eieio-oset obj rn (car (cdr slots)))))
595       (setq slots (cdr (cdr slots))))))
596
597 (defgeneric initialize-instance (this &optional slots)
598   "Construct the new object THIS based on SLOTS.")
599
600 (defmethod initialize-instance ((this eieio-default-superclass)
601                                 &optional slots)
602   "Construct the new object THIS based on SLOTS.
603 SLOTS is a tagged list where odd numbered elements are tags, and
604 even numbered elements are the values to store in the tagged slot.
605 If you overload the `initialize-instance', there you will need to
606 call `shared-initialize' yourself, or you can call `call-next-method'
607 to have this constructor called automatically.  If these steps are
608 not taken, then new objects of your class will not have their values
609 dynamically set from SLOTS."
610   ;; First, see if any of our defaults are `lambda', and
611   ;; re-evaluate them and apply the value to our slots.
612   (let* ((this-class (class-v (eieio--object-class this)))
613          (slot (eieio--class-public-a this-class))
614          (defaults (eieio--class-public-d this-class)))
615     (while slot
616       ;; For each slot, see if we need to evaluate it.
617       ;;
618       ;; Paul Landes said in an email:
619       ;; > CL evaluates it if it can, and otherwise, leaves it as
620       ;; > the quoted thing as you already have.  This is by the
621       ;; > Sonya E. Keene book and other things I've look at on the
622       ;; > web.
623       (let ((dflt (eieio-default-eval-maybe (car defaults))))
624         (when (not (eq dflt (car defaults)))
625           (eieio-oset this (car slot) dflt) ))
626       ;; Next.
627       (setq slot (cdr slot)
628             defaults (cdr defaults))))
629   ;; Shared initialize will parse our slots for us.
630   (shared-initialize this slots))
631
632 (defgeneric slot-missing (object slot-name operation &optional new-value)
633   "Method invoked when an attempt to access a slot in OBJECT fails.")
634
635 (defmethod slot-missing ((object eieio-default-superclass) slot-name
636                          _operation &optional _new-value)
637   "Method invoked when an attempt to access a slot in OBJECT fails.
638 SLOT-NAME is the name of the failed slot, OPERATION is the type of access
639 that was requested, and optional NEW-VALUE is the value that was desired
640 to be set.
641
642 This method is called from `oref', `oset', and other functions which
643 directly reference slots in EIEIO objects."
644   (signal 'invalid-slot-name (list (eieio-object-name object)
645                                    slot-name)))
646
647 (defgeneric slot-unbound (object class slot-name fn)
648   "Slot unbound is invoked during an attempt to reference an unbound slot.")
649
650 (defmethod slot-unbound ((object eieio-default-superclass)
651                          class slot-name fn)
652   "Slot unbound is invoked during an attempt to reference an unbound slot.
653 OBJECT is the instance of the object being reference.  CLASS is the
654 class of OBJECT, and SLOT-NAME is the offending slot.  This function
655 throws the signal `unbound-slot'.  You can overload this function and
656 return the value to use in place of the unbound value.
657 Argument FN is the function signaling this error.
658 Use `slot-boundp' to determine if a slot is bound or not.
659
660 In CLOS, the argument list is (CLASS OBJECT SLOT-NAME), but
661 EIEIO can only dispatch on the first argument, so the first two are swapped."
662   (signal 'unbound-slot (list (eieio-class-name class) (eieio-object-name object)
663                               slot-name fn)))
664
665 (defgeneric no-applicable-method (object method &rest args)
666   "Called if there are no implementations for OBJECT in METHOD.")
667
668 (defmethod no-applicable-method ((object eieio-default-superclass)
669                                  method &rest _args)
670   "Called if there are no implementations for OBJECT in METHOD.
671 OBJECT is the object which has no method implementation.
672 ARGS are the arguments that were passed to METHOD.
673
674 Implement this for a class to block this signal.  The return
675 value becomes the return value of the original method call."
676   (signal 'no-method-definition (list method (eieio-object-name object)))
677   )
678
679 (defgeneric no-next-method (object &rest args)
680 "Called from `call-next-method' when no additional methods are available.")
681
682 (defmethod no-next-method ((object eieio-default-superclass)
683                            &rest args)
684   "Called from `call-next-method' when no additional methods are available.
685 OBJECT is othe object being called on `call-next-method'.
686 ARGS are the arguments it is called by.
687 This method signals `no-next-method' by default.  Override this
688 method to not throw an error, and its return value becomes the
689 return value of `call-next-method'."
690   (signal 'no-next-method (list (eieio-object-name object) args))
691   )
692
693 (defgeneric clone (obj &rest params)
694   "Make a copy of OBJ, and then supply PARAMS.
695 PARAMS is a parameter list of the same form used by `initialize-instance'.
696
697 When overloading `clone', be sure to call `call-next-method'
698 first and modify the returned object.")
699
700 (defmethod clone ((obj eieio-default-superclass) &rest params)
701   "Make a copy of OBJ, and then apply PARAMS."
702   (let ((nobj (copy-sequence obj))
703         (nm (eieio--object-name obj))
704         (passname (and params (stringp (car params))))
705         (num 1))
706     (if params (shared-initialize nobj (if passname (cdr params) params)))
707     (if (not passname)
708         (save-match-data
709           (if (string-match "-\\([0-9]+\\)" nm)
710               (setq num (1+ (string-to-number (match-string 1 nm)))
711                     nm (substring nm 0 (match-beginning 0))))
712           (setf (eieio--object-name nobj) (concat nm "-" (int-to-string num))))
713       (setf (eieio--object-name nobj) (car params)))
714     nobj))
715
716 (defgeneric destructor (this &rest params)
717   "Destructor for cleaning up any dynamic links to our object.")
718
719 (defmethod destructor ((_this eieio-default-superclass) &rest _params)
720   "Destructor for cleaning up any dynamic links to our object.
721 Argument THIS is the object being destroyed.  PARAMS are additional
722 ignored parameters."
723   ;; No cleanup... yet.
724   )
725
726 (defgeneric object-print (this &rest strings)
727   "Pretty printer for object THIS.  Call function `object-name' with STRINGS.
728
729 It is sometimes useful to put a summary of the object into the
730 default #<notation> string when using EIEIO browsing tools.
731 Implement this method to customize the summary.")
732
733 (defmethod object-print ((this eieio-default-superclass) &rest strings)
734   "Pretty printer for object THIS.  Call function `object-name' with STRINGS.
735 The default method for printing object THIS is to use the
736 function `object-name'.
737
738 It is sometimes useful to put a summary of the object into the
739 default #<notation> string when using EIEIO browsing tools.
740
741 Implement this function and specify STRINGS in a call to
742 `call-next-method' to provide additional summary information.
743 When passing in extra strings from child classes, always remember
744 to prepend a space."
745   (eieio-object-name this (apply #'concat strings)))
746
747 (defvar eieio-print-depth 0
748   "When printing, keep track of the current indentation depth.")
749
750 (defgeneric object-write (this &optional comment)
751   "Write out object THIS to the current stream.
752 Optional COMMENT will add comments to the beginning of the output.")
753
754 (defmethod object-write ((this eieio-default-superclass) &optional comment)
755   "Write object THIS out to the current stream.
756 This writes out the vector version of this object.  Complex and recursive
757 object are discouraged from being written.
758   If optional COMMENT is non-nil, include comments when outputting
759 this object."
760   (when comment
761     (princ ";; Object ")
762     (princ (eieio-object-name-string this))
763     (princ "\n")
764     (princ comment)
765     (princ "\n"))
766   (let* ((cl (eieio-object-class this))
767          (cv (class-v cl)))
768     ;; Now output readable lisp to recreate this object
769     ;; It should look like this:
770     ;; (<constructor> <name> <slot> <slot> ... )
771     ;; Each slot's slot is writen using its :writer.
772     (princ (make-string (* eieio-print-depth 2) ? ))
773     (princ "(")
774     (princ (symbol-name (class-constructor (eieio-object-class this))))
775     (princ " ")
776     (prin1 (eieio-object-name-string this))
777     (princ "\n")
778     ;; Loop over all the public slots
779     (let ((publa (eieio--class-public-a cv))
780           (publd (eieio--class-public-d cv))
781           (publp (eieio--class-public-printer cv))
782           (eieio-print-depth (1+ eieio-print-depth)))
783       (while publa
784         (when (slot-boundp this (car publa))
785           (let ((i (class-slot-initarg cl (car publa)))
786                 (v (eieio-oref this (car publa)))
787                 )
788             (unless (or (not i) (equal v (car publd)))
789               (unless (bolp)
790                 (princ "\n"))
791               (princ (make-string (* eieio-print-depth 2) ? ))
792               (princ (symbol-name i))
793               (if (car publp)
794                   ;; Use our public printer
795                   (progn
796                     (princ " ")
797                     (funcall (car publp) v))
798                 ;; Use our generic override prin1 function.
799                 (princ (if (or (eieio-object-p v)
800                                (eieio-object-p (car-safe v)))
801                            "\n" " "))
802                 (eieio-override-prin1 v)))))
803         (setq publa (cdr publa) publd (cdr publd)
804               publp (cdr publp))))
805     (princ ")")
806     (when (= eieio-print-depth 0)
807       (princ "\n"))))
808
809 (defun eieio-override-prin1 (thing)
810   "Perform a `prin1' on THING taking advantage of object knowledge."
811   (cond ((eieio-object-p thing)
812          (object-write thing))
813         ((consp thing)
814          (eieio-list-prin1 thing))
815         ((class-p thing)
816          (princ (eieio-class-name thing)))
817         ((or (keywordp thing) (booleanp thing))
818          (prin1 thing))
819         ((symbolp thing)
820          (princ (concat "'" (symbol-name thing))))
821         (t (prin1 thing))))
822
823 (defun eieio-list-prin1 (list)
824   "Display LIST where list may contain objects."
825   (if (not (eieio-object-p (car list)))
826       (progn
827         (princ "'")
828         (prin1 list))
829     (princ (make-string (* eieio-print-depth 2) ? ))
830     (princ "(list")
831     (let ((eieio-print-depth (1+ eieio-print-depth)))
832       (while list
833         (princ "\n")
834         (if (eieio-object-p (car list))
835             (object-write (car list))
836           (princ (make-string (* eieio-print-depth 2) ? ))
837           (eieio-override-prin1 (car list)))
838         (setq list (cdr list))))
839     (princ ")")))
840
841 \f
842 ;;; Unimplemented functions from CLOS
843 ;;
844 (defun change-class (_obj _class)
845   "Change the class of OBJ to type CLASS.
846 This may create or delete slots, but does not affect the return value
847 of `eq'."
848   (error "EIEIO: `change-class' is unimplemented"))
849
850 ;; Hook ourselves into help system for describing classes and methods.
851 (add-hook 'help-fns-describe-function-functions 'eieio-help-generic)
852 (add-hook 'help-fns-describe-function-functions 'eieio-help-constructor)
853
854 ;;; Interfacing with edebug
855 ;;
856 (defun eieio-edebug-prin1-to-string (print-function object &optional noescape)
857   "Display EIEIO OBJECT in fancy format.
858
859 Used as advice around `edebug-prin1-to-string', held in the
860 variable PRINT-FUNCTION.  Optional argument NOESCAPE is passed to
861 `prin1-to-string' when appropriate."
862   (cond ((class-p object) (eieio-class-name object))
863         ((eieio-object-p object) (object-print object))
864         ((and (listp object) (or (class-p (car object))
865                                  (eieio-object-p (car object))))
866          (concat "(" (mapconcat #'eieio-edebug-prin1-to-string object " ")
867                  ")"))
868         (t (funcall print-function object noescape))))
869
870 (add-hook 'edebug-setup-hook
871           (lambda ()
872             (def-edebug-spec defmethod
873               (&define                  ; this means we are defining something
874                [&or name ("setf" :name setf name)]
875                ;; ^^ This is the methods symbol
876                [ &optional symbolp ]    ; this is key :before etc
877                list              ; arguments
878                [ &optional stringp ]    ; documentation string
879                def-body                 ; part to be debugged
880                ))
881             ;; The rest of the macros
882             (def-edebug-spec oref (form quote))
883             (def-edebug-spec oref-default (form quote))
884             (def-edebug-spec oset (form quote form))
885             (def-edebug-spec oset-default (form quote form))
886             (def-edebug-spec class-v form)
887             (def-edebug-spec class-p form)
888             (def-edebug-spec eieio-object-p form)
889             (def-edebug-spec class-constructor form)
890             (def-edebug-spec generic-p form)
891             (def-edebug-spec with-slots (list list def-body))
892             (advice-add 'edebug-prin1-to-string
893                         :around #'eieio-edebug-prin1-to-string)))
894
895 \f
896 ;;; Start of automatically extracted autoloads.
897 \f
898 ;;;### (autoloads nil "eieio-custom" "eieio-custom.el" "ab711689b2bae8a7d8c4b1e99c892306")
899 ;;; Generated autoloads from eieio-custom.el
900
901 (autoload 'customize-object "eieio-custom" "\
902 Customize OBJ in a custom buffer.
903 Optional argument GROUP is the sub-group of slots to display.
904
905 \(fn OBJ &optional GROUP)" nil nil)
906
907 ;;;***
908 \f
909 ;;;### (autoloads nil "eieio-opt" "eieio-opt.el" "889c0a935dddf758dbb65488470ffa06")
910 ;;; Generated autoloads from eieio-opt.el
911
912 (autoload 'eieio-browse "eieio-opt" "\
913 Create an object browser window to show all objects.
914 If optional ROOT-CLASS, then start with that, otherwise start with
915 variable `eieio-default-superclass'.
916
917 \(fn &optional ROOT-CLASS)" t nil)
918
919 (autoload 'eieio-help-class "eieio-opt" "\
920 Print help description for CLASS.
921 If CLASS is actually an object, then also display current values of that object.
922
923 \(fn CLASS)" nil nil)
924
925 (autoload 'eieio-help-constructor "eieio-opt" "\
926 Describe CTR if it is a class constructor.
927
928 \(fn CTR)" nil nil)
929
930 (autoload 'eieio-help-generic "eieio-opt" "\
931 Describe GENERIC if it is a generic function.
932
933 \(fn GENERIC)" nil nil)
934
935 ;;;***
936 \f
937 ;;; End of automatically extracted autoloads.
938
939 (provide 'eieio)
940
941 ;;; eieio ends here