Name: Triples

Maintainer: Paul Rovner (D. Swinehart)

Date: 24-Apr-81 22:44:28 (19-Oct-81 11:39:26)

Purpose: Provision of a simple but general "associative" data structure (abstract binary relations) for Cedar client programmers.

Filed as: [ivy]<Swinehart>Triples>Triples.doc

This package is intended for use with Cedar for dealing with a single store of abstract binary relations called "Triples" among abstract "Items". Items are represented as REF ANYs. 

The interface described herein is defined in the file named [ivy]<Swinehart>Triples>Triples.bcd. An implementation resides in [ivy]<Swinehart>Triples>TriplesImpl.bcd.

The distinguished Item "Any" is used as a wild card in arguments to the procedures described below for the purpose of matching patterns of triples in the store.

A TripleRec is a RECORD [att, obj, val: Item]. nullTripleRec will not occur in the store. sure to call Stop to terminate the enumeration, either before or
	after Get begins returning null

The following procedures are defined in the Triples interface:

    Make, Erase: PROC[att, obj, val: Item];
        Make adds the specified triple to the store (unless it already exists). "Any" may not be a
        parameter to Make (ArgFault is raised). Erase removes from the store triples that match
        the specified pattern.

    Is: PROC[att, obj, val: Item ← Any] RETURNS[BOOLEAN];
        This returns TRUE if a triple which matches the specified pattern exists in the store.

    Select: PROC[att, obj, val: Item ← Any] RETURNS[Item];
        Exactly one of the parameters must have the value "Any", else "ArgFault" is raised.
        This returns the Item corresponding to the "Any" argument of some (arbitrary)
        Triple in the store that matches the specified pattern if there is such a Triple, NIL
        otherwise.
	
    Foreach: PROC[att, obj, val: Item] RETURNS[Get: Triples.GetTrip, Stop: Triples.StopIt];
        This enumerates the Triples in the store that match the specified pattern. Call
	Foreach to initiate the enumeration and to obtain the Get and Stop procedures.  Get
	returns a TripleRec on each call, returning Triples.nullTriple after the enumeration
	is exhausted.  Be sure to call Stop to terminate the enumeration, either before or
	after Get begins returning nullTriple. Triples added to or deleted from the store
	during the enumeration may or may not be included in the enumeration.


  -- SIGNALS

    ArgFault: ERROR[att, obj, val: Item];
        This is raised by Make and Select.