./../../src/assoc-list.lsp

## assoc-list/add [ Methods ]

[ Top ] [ assoc-list ] [ Methods ]

DESCRIPTION

     Add a new element to the given assoc-list object.

ARGUMENTS

     - A key/data pair as a list.
     - The assoc-list object to which it is to be added.

OPTIONAL ARGUMENTS

     - (This optional argument will be ignored; it exists only because of its use
       in the recursive-assoc-list class).

RETURN VALUE

     Returns T if the specified named-object is successfully added to the given
     assoc-list.

     Returns an error if an attempt is made to add NIL to the given assoc-list
     or if the given named-object is already present in the given assoc-list.

EXAMPLE

    (let ((al (make-assoc-list 'test '((jim beam)
                                       (four roses)
                                       (wild turkey)))))
      (add '(makers mark) al))

    => T

    (let ((al (make-assoc-list 'test '((jim beam)
                                       (four roses)
                                       (wild turkey)))))
      (add '(makers mark) al)
      (get-data 'makers al))

    =>
    NAMED-OBJECT: id: MAKERS, tag: NIL,
    data: MARK

    (let ((al (make-assoc-list 'test '((jim beam)
                                       (four roses)
                                       (wild turkey)))))
      (add '(makers mark) al)
      (get-position 'makers al))

    => 3

    (let ((al (make-assoc-list 'test '((jim beam)
                                       (four roses)
                                       (wild turkey)))))
      (add '(knob creek) al))

    => T

SYNOPSIS

    (defmethod add (named-object (al assoc-list) &optional ignore)

## assoc-list/add-to-list-data [ Methods ]

[ Top ] [ assoc-list ] [ Methods ]

DESCRIPTION

     Add an element of any type to the end of the data (list) associated with a
     given key of a given assoc-list.

     The data associated with the given key must already be a list.

ARGUMENTS

     - An item of any type.
     - A given key that must be present in the given assoc-list.
     - The given assoc-list.

RETURN VALUE

     Returns the whole named-object to which the new element was added.

     This method will abort with an error if a key is sought which does not
     exist within the given assoc-list. For such cases, use
     add-to-list-data-force instead.

EXAMPLE

    (let ((al (make-assoc-list 'test '((cat felix)
                                       (dog (fido spot))
                                       (cow bessie)))))
      (add-to-list-data 'rover 'dog al))

    =>
    NAMED-OBJECT: id: DOG, tag: NIL,
    data: (FIDO SPOT ROVER)

SYNOPSIS

    (defmethod add-to-list-data (new-element key (al assoc-list))

## assoc-list/add-to-list-data-force [ Methods ]

[ Top ] [ assoc-list ] [ Methods ]

DESCRIPTION

     Similar to add-to-list-data, but if the given key doesn't already exist in
     the given assoc-list, it is first added, then the given new element is
     added to that as a 1-element list.

     If the given key already exists within the given assoc-list, its data must
     already be in the form of a list.

ARGUMENTS

     - A (new) element of any type.
     - A given key that may or may not be present in the given assoc-list.
     - The the given assoc-list.

RETURN VALUE

     Returns the whole named-object to which the element was added when used
     with a key that already exists within the given assoc-list.

     Returns T when used with a key that does not already exist in the given
     assoc-list.

EXAMPLE

    (let ((al (make-assoc-list 'test '((cat felix)
                                       (dog (fido spot))
                                       (cow bessie)))))
      (add-to-list-data-force 'rover 'dog al))

    =>
    NAMED-OBJECT: id: DOG, tag: NIL,
    data: (FIDO SPOT ROVER)

    (let ((al (make-assoc-list 'test '((cat felix)
                                       (dog (fido spot))
                                       (cow bessie)))))
      (add-to-list-data-force 'wilbur 'pig al)
      (get-keys al))

    => (CAT DOG COW PIG)

SYNOPSIS

    (defmethod add-to-list-data-force (new-element key (al assoc-list))

## assoc-list/get-data [ Methods ]

[ Top ] [ assoc-list ] [ Methods ]

DESCRIPTION

     Return the named-object (id, tag and data) that is identified by a
     specified key within a given assoc-list.

     NB: This method returns the named object itself, not just the data
         associated with the key (use get-data-data for that).

ARGUMENTS

     - A symbol that is the key (id) of the named-object sought.
     - The assoc-list object in which it is be sought.

OPTIONAL ARGUMENTS

     - T or NIL to indicate whether a warning is printed if the specified key
       cannot be found within the given assoc-list. T = print. Default = T.
       Mostly we define whether we want to warn in the instance itself, but
       sometimes it would be good to warn or not on a call basis, hence the
       optional argument.

RETURN VALUE

     A named-object is returned if the specified key is found within the given
     assoc-list object.

     NIL is returned and a warning is printed if the specified key is not found
     in the given assoc-list object.

EXAMPLE

    (let ((al (make-assoc-list 'test '((jim beam)
                                       (four roses)
                                       (wild turkey)))))
      (get-data 'four al))

    =>
    NAMED-OBJECT: id: FOUR, tag: NIL,
    data: ROSES

    (let ((al (make-assoc-list 'test '((jim beam)
                                       (four roses)
                                       (wild turkey)))))
      (get-data 'jack al))

    => NIL
    WARNING:
       assoc-list::get-data: Could not find data with key JACK in assoc-list with
       id TEST

    (let ((al (make-assoc-list 'test '((jim beam)
                                       (four roses)
                                       (wild turkey)))))
      (get-data 'jack al t))

    => NIL
    WARNING:
       assoc-list::get-data: Could not find data with key JACK in assoc-list with
       id TEST

    (let ((al (make-assoc-list 'test '((jim beam)
                                       (four roses)
                                       (wild turkey)))))
      (get-data 'jack al nil))

    => NIL

SYNOPSIS

    (defmethod get-data (key (al assoc-list) &optional (warn t))

## assoc-list/get-data-data [ Methods ]

[ Top ] [ assoc-list ] [ Methods ]

DESCRIPTION

     (Short-cut for (data (get-data ...))
     Get the data associated with the given key of the given assoc-list.

ARGUMENTS

     - The assoc-list key symbol associated with the data list which is sought.
     - The assoc-list in which it is to be sought.

OPTIONAL ARGUMENTS

     - T or NIL to indicate whether to print a warning if no such named-object
       can be found within the given assoc-list (default = T).

RETURN VALUE

     If the given key is found within the given assoc-list, the data associated
     with that key is returned.

EXAMPLE

    (let ((al (make-assoc-list 'test '((jim beam)
                                       (four roses)
                                       (wild turkey)))))
      (get-data-data 'jim al))

    => BEAM

    (let ((al (make-assoc-list 'test '((jim beam)
                                       (four roses)
                                       (wild turkey)))))
      (get-data-data 'jack al))

    => NIL
    WARNING:
       assoc-list::get-data: Could not find data with key JACK in assoc-list with
       id TEST

SYNOPSIS

    (defmethod get-data-data (key (al assoc-list) &optional (warn t))

## assoc-list/get-first [ Methods ]

[ Top ] [ assoc-list ] [ Methods ]

DESCRIPTION

     Returns the first named-object in the DATA slot of the given assoc-list
     object.

ARGUMENTS

     - An assoc-list object.

RETURN VALUE

     A named-object that is the first object in the DATA slot of the given
     assoc-list object.

EXAMPLE

    (let ((al (make-assoc-list 'test '((jim beam)
                                       (four roses)
                                       (wild turkey)))))
      (get-first al))

    =>
    NAMED-OBJECT: id: JIM, tag: NIL,
    data BEAM

SYNOPSIS

    (defmethod get-first ((al assoc-list))

## assoc-list/get-keys [ Methods ]

[ Top ] [ assoc-list ] [ Methods ]

DESCRIPTION

     Get a simple list of the keys in a given association list.

ARGUMENTS

     - An assoc-list.

OPTIONAL ARGUMENTS

     - Optional argument: T or NIL (default T) to indicate whether a warning
       should be printed when the first argument is a recursive assoc-list.

RETURN VALUE

     A list of the keys only of all top-level association list pairs in the
     given assoc-list.

     get-keys is a method of the assoc-list class and therefore returns only
     top-level keys if accessing a recursive assoc-list.

EXAMPLE

    (let ((al (make-assoc-list 'test '((cat felix)
                                       (dog fido)
                                       (cow bessie)))))
      (get-keys al))

    => (CAT DOG COW)

    (let ((al (make-assoc-list 'test '((cat felix)
                                       (dog ((scottish terrier)
                                             (german shepherd)
                                             (irish wolfhound)))
                                       (cow bessie)))))
      (get-keys al))

    => (CAT DOG COW)

SYNOPSIS

    (defmethod get-keys ((al assoc-list) &optional (warn t))

## assoc-list/get-last [ Methods ]

[ Top ] [ assoc-list ] [ Methods ]

DESCRIPTION

     Returns the last named-object in the data list of a given assoc-list.

ARGUMENTS

     - An assoc-list.

RETURN VALUE

     The last object in the data list of a given assoc-list.

EXAMPLE

    (let ((al (make-assoc-list 'test '((jim beam)
                                       (four roses)
                                       (wild turkey)))))
      (get-last al))

    =>
    NAMED-OBJECT: id: WILD, tag: NIL,
    data TURKEY

SYNOPSIS

    (defmethod get-last ((al assoc-list))

## assoc-list/get-position [ Methods ]

[ Top ] [ assoc-list ] [ Methods ]

DESCRIPTION

     Returns the index position (zero-based) of a named-object within a given
     assoc-list.

ARGUMENTS

     - The assoc-list key symbol (named-object id) of the object for which the
       position is sought.
     - The assoc-list in which it is to be sought.

OPTIONAL ARGUMENTS

     - Optional argument: An indexing integer. In this case, get-position will
       search for the given object starting part-way into the list, skipping all
       objects located at indices lower than the given integer (default = 0).

RETURN VALUE

     The integer index of the named-object within the given assoc-list.

     NIL is returned if the object is not present in the assoc-list starting
     with the index number given as the start argument (i.e., in the entire list
     if the optional start argument is omitted).

EXAMPLE

    (let ((al (make-assoc-list 'test '((jim beam)
                                       (four roses)
                                       (wild turkey)))))
      (get-position 'four al))

    => 1

    (let ((al (make-assoc-list 'test '((jim beam)
                                       (four roses)
                                       (wild turkey)))))
      (get-position 'jack al))

    => NIL

    (let ((al (make-assoc-list 'test '((jim beam)
                                       (four roses)
                                       (wild turkey)))))
      (get-position 'jim al 1))

    => NIL

SYNOPSIS

    (defmethod get-position (key (al assoc-list) &optional (start 0))

## assoc-list/make-assoc-list [ Functions ]

[ Top ] [ assoc-list ] [ Functions ]

DESCRIPTION

     A function that provides a shortcut to creating an assoc-list, filling it
     with data, and assigning a name to it.

ARGUMENTS

     - The name of the assoc-list to be created.
     - The data with which to fill it.

OPTIONAL ARGUMENTS

     keyword arguments:
     - :warn-not-found. T or NIL to indicate whether a warning is printed when an
       index which doesn't exist is used for look-up.  T = warn. Default = T.

RETURN VALUE

     Returns the assoc-list as a named-object.

EXAMPLE

    (make-assoc-list 'looney-tunes '((bugs bunny)
                                     (daffy duck)
                                     (porky pig)))
    =>
    ASSOC-LIST: warn-not-found T
    CIRCULAR-SCLIST: current 0
    SCLIST: sclist-length: 3, bounds-alert: T, copy: T
    LINKED-NAMED-OBJECT: previous: NIL
                         this: NIL
                         next: NIL
    NAMED-OBJECT: id: LOONEY-TUNES, tag: NIL,
    data: (
    NAMED-OBJECT: id: BUGS, tag: NIL,
    data: BUNNY

    NAMED-OBJECT: id: DAFFY, tag: NIL,
    data: DUCK

    NAMED-OBJECT: id: PORKY, tag: NIL,
    data: PIG)

SYNOPSIS

    (defun make-assoc-list (id al &key (warn-not-found t))

## assoc-list/map-data [ Methods ]

[ Top ] [ assoc-list ] [ Methods ]

DESCRIPTION

     Map a function over the data in the assoc-list.

ARGUMENTS

     - The assoc-list to which the function is to be applied.
     - The function to be applied.  This must take the data in the assoc-list as
       a first argument.

OPTIONAL ARGUMENTS

     - Optional argument(s): Further arguments for the function.

RETURN VALUE

     Returns a list of the values returned by the function call on the data.

EXAMPLE

    (let ((al (make-assoc-list 'al-test
                               '((1 (1 2 3 4))
                                 (2 (5 6 7 8))
                                 (3 (9 10 11 12))))))
      (map-data al #'(lambda (y)
                       (loop for i in (data y) collect
                            (* i 2)))))

    => ((2 4 6 8) (10 12 14 16) (18 20 22 24))

SYNOPSIS

    (defmethod map-data ((al assoc-list) function &optional further-arguments)

## assoc-list/set-data [ Methods ]

[ Top ] [ assoc-list ] [ Methods ]

DESCRIPTION

     Replace the named-object associated with a specified key within a given
     assoc-list object. This method replaces the whole named-object, not just
     the data of that object.

ARGUMENTS

     - A key present within the given assoc-list object.
     - A key/data pair as a list.
     - The assoc-list object in which to find and replace the named-object
       associated with the specified key.

RETURN VALUE

     Returns the new named-object.

     Returns NIL when the given key is not present within the given assoc-list.

EXAMPLE

    (let ((al (make-assoc-list 'test '((cat felix)
                                       (dog fido)
                                       (cow bessie)))))
      (set-data 'dog '(dog spot) al))

    =>
    NAMED-OBJECT: id: DOG, tag: NIL,
    data: SPOT

    (let ((al (make-assoc-list 'test '((cat felix)
                                       (dog fido)
                                       (cow bessie)))))
      (set-data 'pig '(pig wilbur) al))

    => NIL
    WARNING:
       assoc-list::set-data: Could not find data with key PIG in assoc-list with id
       TEST

    (let ((al (make-assoc-list 'test '((cat felix)
                                       (dog fido)
                                       (cow bessie)))))
      (set-data 'dog '(pig wilbur) al))

    =>
    NAMED-OBJECT: id: PIG, tag: NIL,
    data: WILBUR

SYNOPSIS

    (defmethod set-data (key new-value (al assoc-list))

## assoc-list/set-nth-of-data [ Methods ]

[ Top ] [ assoc-list ] [ Methods ]

DESCRIPTION

     Replace a given member of a given data list within a given assoc-list.

ARGUMENTS

     - The key (named-object id) associated with the data to be changed.
     - The zero-based integer index of the member of the list to be changed.
     - The new value.
     - The assoc-list in which the change is to be made.

     The data to be modified must already be in the form of a list.

     The index integer given must be less than the length of the data list to be
     modified.

RETURN VALUE

     Returns the new value only.

EXAMPLE

    (let ((al (make-assoc-list 'test '((cat felix)
                                       (dog (fido spot rover))
                                       (cow bessie)))))
      (set-nth-of-data 'dog 0 'snoopy al))

    => SNOOPY

    (let ((al (make-assoc-list 'test '((cat felix)
                                       (dog (fido spot rover))
                                       (cow bessie)))))
      (set-nth-of-data 'dog 0 'snoopy al)
      (get-data 'dog al))

    =>
    NAMED-OBJECT: id: DOG, tag: NIL,
    data: (SNOOPY SPOT ROVER)

SYNOPSIS

    (defmethod set-nth-of-data (key nth new-value (al assoc-list))

## circular-sclist/assoc-list [ Classes ]

[ Top ] [ circular-sclist ] [ Classes ]

NAME

     assoc-list

     File:             assoc-list.lsp

     Class Hierarchy:  named-object -> linked-named-object -> sclist ->
                       circular-sclist -> assoc-list

     Version:          1.0.2

     Project:          slippery chicken (algorithmic composition)

     Purpose:          Implementation of the assoc-list class that is somewhat
                       like the lisp association list but with more
                       error-checking.

     Author:           Michael Edwards: m@michael-edwards.org

     Creation date:    February 18th 2001

     $$ Last modified: 08:15:35 Mon May  7 2012 BST

     SVN ID: $Id: assoc-list.lsp 3674 2013-06-10 11:07:52Z medward2 $