REF DATABASE                                       John Gibson Jan 1996

       COPYRIGHT University of Sussex 1996. All Rights Reserved.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<       POP-11 DATABASE       >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

         CONTENTS - (Use <ENTER> g to access required sections)

  1   Overview

  2   Adding Items

  3   Removing Items

  4   Looking Up Items

  5   Associated Variables


-----------
1  Overview
-----------

database is a global permanent variable  containing a list, used by  the
procedures described in this  file (and also  by the looping  constructs
for  ...   equalto  and   for   ...  allequalto,   see   HELP * equalto,
HELP * allequalto).

All  the  procedures  except  database_add  and  database_alladd  take a
pattern or pattern_list  as argument, and  use the operator  = to  match
database items against  their argument. Consequently,  any matchvars  in
pattern or pattern_list will have  their corresponding variables set  by
the match. (For a description of matchvars, see Pattern Matching  With =
in HELP * EQUAL.)

(Note that this is primarily a teaching tool, so the database is  stored
as a simple list of items without any complicated indexing mechanism.)




---------------
2  Adding Items
---------------

database_add(item)                                           [procedure]
        Adds item to  database (and also  assigns item to  database_it).
        item must  not  contain  any  matchvars  (otherwise  the  mishap
        'ADDING UNDER-SPECIFIED ITEM TO DATABASE' results).


database_alladd(item_list)                                   [procedure]
        Uses database_add to add each item in item_list to database (and
        also assigns a copy of item_list to database_them.)




-----------------
3  Removing Items
-----------------

database_remove(pattern)                                     [procedure]
        Removes the  first item  in database  that equals  pattern  (and
        assigns that item to database_it). If no matching item is found,
        the mishap 'REMOVING NON-EXISTENT ITEM FROM DATABASE' occurs.


database_flush(pattern)                                      [procedure]
        Removes all items in database that equal pattern (and  assigns a
        list of those items to database_them). It is permissible for  no
        items to match (in which case database_them will be []).


database_allremove(pattern_list)                             [procedure]
        Applies database_remove  to  each  pattern  in  pattern_list  to
        remove the first  item in database  that equals that  pattern. A
        list of all items removed is assigned to database_them.




-------------------
4  Looking Up Items
-------------------

database_lookup(pattern)                                     [procedure]
        If there is  an item  in database that  equals pattern,  assigns
        that item to database_it. Otherwise, the mishap 'DATABASE LOOKUP
        FAILED' occurs.


database_present(pattern) -> bool                            [procedure]
        If there is  an item  in database that  equals pattern,  assigns
        that item to  database_it and returns  true. Otherwise,  returns
        false.

        Note that if there  is more than one  item that equals  pattern,
        database_present will  find  only  the  first  possibility.  The
        syntax form for ... equalto can  be used to iterate through  all
        possibilities (see HELP * equalto).


database_allpresent(pattern_list) -> bool                    [procedure]
        Takes a list of patterns and  returns true if there is at  least
        one consistent  way of  matching all  of them  against items  in
        database. (That is, not only must each pattern equal an item  in
        database, but  any matchvars  bound must  have the  same  values
        across all patterns.) If a consistent match can be found, a list
        of the database items matched is assigned to database_them,  and
        true is returned; otherwise, false is returned.

        Note that if  there is more  than one possible  way of  matching
        pattern_list,  database_allpresent  will  find  only  the  first
        possibility. The syntax form for  ... allequalto can be used  to
        iterate through all possibilities (see HELP * allequalto).


pattern present_in list -> bool                             [operator 5]
        An operator version of database_present which allows any list to
        be used locally as database. This operator is just defined as

            define 5 pattern present_in database;
                dlocal database;
                database_present(pattern)
            enddefine;


pattern_list allpresent_in list -> bool                     [operator 5]
        An operator version of database_allpresent which allows any list
        to be used locally as database. This operator is just defined as

            define 5 pattern_list allpresent_in database;
                dlocal database;
                database_allpresent(pattern_list)
            enddefine;


database_which(variables, pattern_list) -> value_list        [procedure]
        Using the for ... allequalto  syntax form, this procedure  finds
        all possible  ways  of  consistently matching  the  patterns  in
        pattern_list against items in  database, and returns the  values
        of either one variable, or a set of variables, for each possible
        match.

        variables  may  be  either  (a)  a  single  variable  (i.e.   an
        identifier or a  word), or  (b) a  list of  them. The  resulting
        value_list is then for (a) a list of single variable values,  or
        for (b) a list of lists of values.




-----------------------
5  Associated Variables
-----------------------

database -> list                                              [variable]
list -> database
        The variable used by the procedures in this file to store a list
        of items.


database_it -> item                                           [variable]
item -> database_it
        This variable is  used by various  database procedures to  store
        the last item operated on:

        database_add and database_alladd set it  to the last item  added
        to     database.     database_remove,     database_flush     and
        database_allremove  set   it   to   the   last   item   removed.
        database_lookup, database_present and present_in  set it to  the
        item matched from database.


database_them -> list                                         [variable]
list -> database_them
        This variable is used by various database procedures to  store a
        list of the last set of items operated on:

        database_alladd sets it  to a  copy of  the last  list of  items
        added to database. database_allremove and database_flush set  it
        to  a  list  of  the  items  removed.  database_allpresent   and
        allpresent_in set  it  to  a  list of  the  items  matched  from
        database.




--- C.all/ref/database
--- Copyright University of Sussex 1996. All rights reserved.
