Package COM.INFORMATIMAGO.CLEXT.ASSOCIATION

undocumented

CHECK-CHAIN

(check-object expression)
macro
Evaluates the expression and reports an error if it's NIL.
(define-association name endpoints &rest options)
macro
Define functions to manage the association:

    (name-LINK       a b ...)
    (name-UNLINK     a b ...)
    (name-CONTAINS-P a b ...) --> BOOLEAN
    (name-SIZE)  --> INTEGER
    (name-CLEAR) --> INTEGER

taking &KEY arguments named for the ROLE names.

There may be more than two endpoints, in case of ternary, etc associations.

ENDPOINTS      a list of (ROLE &KEY TYPE ACCESSOR SLOT MULTIPLICITY MULTIPLE
                          IMPLEMENTATION COPY TEST ORDERED).


TYPE           needed for ATTACH and DETACH.
               If all the types are present and different, then ATTACH and
               DETACH methods are created for the arguments in any order.

    Note: we should review this macro for TYPE vs. CLASS.
          Slots may be accessed only in instances of standard-class classes.
          Accessors may be used with any type.

ACCESSOR and SLOT are optional, and mutually exclusive.

   --------  ---------  ----------  -------------  -------  ------  --------
   ACCESSOR    SLOT     Slot        Accessor       CreSlot  CreAcc  Use
   --------  ---------  ----------  -------------  -------  ------  --------
    absent    absent    Role name   Role Name       Yes      Yes     slot
                        When both :accessor and :slot are absent, the role
                        name is used to create a slot with an accessor in
                        the associated class. 
                        Note: In this case, :type must be given a class.
   --------  ---------  ----------  -------------  -------  ------  --------
    absent    present   Given slot     N/A           No       No     slot

                        The associated class is not changed.  The given slot
                        is directly used.
   --------  ---------  ----------  -------------  -------  ------  --------
   present    absent        N/A     Given Accessor   No       No    accessor

                        The associated class is not changed.  The given
                        accessor is used.
   --------  ---------  ----------  -------------  -------  ------  --------
   present    present   ...................FORBIDDEN........................
   --------  ---------  ----------  -------------  -------  ------  --------

MULTIPLICITY   may be either an integer, or a string designator the form "MIN-MAX"

MIN, MAX       an integer or * representing infinity; PRE: (< MIN MAX)

MULTIPLE       boolean default NIL indicates whether the same objects may be
               in relation together several times.

COPY           if not NIL, a function used to copy the objects before storing
               or returning them.

LESSP          default is NIL.  A function used to compare the objects
               put into the relation.

TEST           default is (FUNCTION EQL), the function used to compare
               the objects put into the relation.

   Note: If you set COPY, you will probably want to set TEST or LESSP too.
         TEST and LESSP are mutually exclusive.

         For strings, you may want to set TEST to EQUAL or EQUALP or
         LESSP to STRING< or STRING-LESSP

         For numbers, you may want to set TEST to =, or LESSP to <.

         COPY, TEST and LESSP are evaluated, so you can pass 'fun,
         (function fun) or (lambda (x) (fun x)).

ORDERED        (only for REFERENCE, LIST, VECTOR and REIFIED).

               NIL:  the objects are not ordered in the containers.

               T:    If LESSP is not given, then the objects are kept
                     in the order of association in the containers.
                     The KEY of the objects are compared with the TEST
                     function.

                     If LESSP is given, then the objects are kept in
                     the order specified by LESSP applied on the KEY
                     of the objects.

IMPLEMENTATION is (OR (MEMBER REFERENCE LIST VECTOR HASH-TABLE A-LIST P-LIST REIFIED)
                      (CONS (HASH-TABLE A-LIST P-LIST)
                            (CONS (MEMBER REFERENCE LIST VECTOR) NIL)))
               indicates the kind of slot used to implement the role.
    REFERENCE  only when (= 1 MAX) : the related object is stored in the slot.
    LIST       the related objects are stored in a list.
    VECTOR     the related objects are stored in a vector.
               If MAX is finite, then the size of the vector must be = MAX
               else the VECTOR must be adjustable and may have a fill-pointer.
    A-LIST     the related keys and objects are stored in an a-list.
               For qualified roles.
    P-LIST     the related keys and objects are stored in a p-list.
               For qualified roles.
    HASH-TABLE the related keys and objects are stored in a HASH-TABLE.
               For qualified roles.
    REIFIED    the association is reified and nothing is stored in the
               related objects.

    For qualified roles, the multiplicity is per key.
       (persons :multiplicity 0-* :implementation hash-table)
       gives several persons per key (name -> homonyms).
    In case of qualified roles and (< 1 MAX), the IMPLEMENTATION can be given
    as a list of two items, the first giving the implementation of the role,
    and the second the implementation of the values. (HASH-TABLE VECTOR) maps
    with an hash-table keys to vectors of associated objects.

    Currently implemented:  REFERENCE and LIST.
    MULTIPLE is not implemented yet.

OPTIONS        a list of (:keyword ...) options.
   (:DOCUMENTATION string)

BUGS:    If there is an error in handling one association end, after
         handling the other end, the state becomes invalid. No transaction :-(
(define-class class-name superclasses &key slots documentation)
macro
DO:     Define a class, with a slightly different syntax.
        Since there are a lot of classes with no additionnal slots,
        to make the slots optional, we introduce them with a :slots keyword.
        The initarg and accessor are automatically generated with the same
        name as the slot by default.
        The initform is automatically set to nil by default.
(did-link association-name left right)
generic-function
Hook called after a new link for the association is created between LEFT and RIGHT.
(will-unlink association-name left right)
generic-function
Hook called before an old link for the association is removed between LEFT and RIGHT.