(cl:in-package #:sod)
+;;; Note! You'll notice that none of the classes defined here store property
+;;; sets persistently, even though there's a `:pset' keyword argument
+;;; accepted by many of the classes' initialization methods. That's because
+;;; part of the pset protocol involves checking that there are no unused
+;;; properties, and this typically happens shortly after the appropriate
+;;; objects are constructed. It would be tempting to stash the pset at
+;;; initialization time, and then pick some property from it out later -- but
+;;; that won't work in general because an error might have been signalled
+;;; about that property. It wouldn't surprise me greatly to discover that
+;;; `most' code paths resulted in the property being looked up in time to
+;;; avoid the unused-property error, but a subtle change in circumstances
+;;; then causes a thing done on demand to be done later, leading to
+;;; irritating and misleading errors being reported to the user. So please
+;;; don't do that.
+
;;;--------------------------------------------------------------------------
;;; Classes.
computed on demand via methods on `slot-unbound'.
* The ILAYOUT describes the layout for an instance of the class. It's
- quite complicated; see the documentation of the ILAYOUT class for
+ quite complicated; see the documentation of the `ilayout' class for
detais.
* The EFFECTIVE-METHODS are a list of effective methods, specialized for
the class.
* The VTABLES are a list of descriptions of vtables for the class. The
- individual elements are VTABLE objects, which are even more
- complicated than ILAYOUT structures. See the class documentation for
- details."))
+ individual elements are `vtable' objects, which are even more
+ complicated than `ilayout' structures. See the class documentation
+ for details."))
(defmethod print-object ((class sod-class) stream)
(maybe-print-unreadable-object (class stream :type t)
(class :initarg :class :type sod-class :reader sod-message-class)
(type :initarg :type :type c-function-type :reader sod-message-type))
(:documentation
- "Messages the means for stimulating an object to behave.
+ "Messages are the means for stimulating an object to behave.
SOD is a single-dispatch object system, like Smalltalk, C++, Python and so
on, but unlike CLOS and Dylan. Behaviour is invoked by `sending messages'
will, in general, differ from the type of the message for several
reasons.
- -- Firstly, the method type must include names for all of the
- method's parameters. The message definition can omit the
- parameter names (in the same way as a function declaration can).
- Formally, the message definition can contain abstract
- declarators, whereas method definitions must not.
+ -- The method type must include names for all of the method's
+ parameters. The message definition can omit the parameter
+ names (in the same way as a function declaration can). Formally,
+ the message definition can contain abstract declarators, whereas
+ method definitions must not.
-- Method combinations may require different parameter or return
- types. For example, `before' and `after' methods don't
- contribute to the message's return value, so they must be defined
- as returning `void'.
+ types. For example, `before' and `after' methods don't
+ contribute to the message's return value, so they must be defined
+ as returning `void'.
-- Method combinations may permit methods whose parameter and/or
- return types don't exactly match the corresponding types of the
- message. For example, one might have methods with covariant
- return types and contravariant parameter types. (This sounds
- nice, but it doesn't actually seem like such a clever idea when
- you consider that the co-/contravariance must hold among all the
- applicable methods ordered according to the class precedence
- list. As a result, a user might have to work hard to build
- subclasses whose CPLs match the restrictions implied by the
- method types.)
+ return types don't exactly match the corresponding types of the
+ message. For example, one might have methods with covariant
+ return types and contravariant parameter types. (This sounds
+ nice, but it doesn't actually seem like such a clever idea when
+ you consider that the co-/contravariance must hold among all the
+ applicable methods ordered according to the class precedence
+ list. As a result, a user might have to work hard to build
+ subclasses whose CPLs match the restrictions implied by the
+ method types.)
Method objects are fairly passive in the SOD translator. However,
subclasses of `sod-message' may (and probably will) construct instances of