DataMuseum.dk

top - metrics - download

    Length: 7840 (0x1ea0)
    Types: TextFile
    Names: »V«

└─⟦180fe333a⟧ Bits:30000405 8mm tape, Rational 1000, SW CATALOG, 10_20_0
└─⟦180fe333a⟧ Bits:30000537 8mm tape, Rational 1000, SW Catalog 10_20_0
    └─⟦5cb1d1d7f⟧ »DATA« 
        └─⟦3b1ee7bd8⟧ 
            └─⟦this⟧ 

TextFile

-- This package provides a "Map" abstraction. A Map consists of a set
-- of "Mappings". A Mapping relates a key field to an arbitrary number
-- of other fields.
--
-- All operations raise "Not_Initialized" if passed an uninitialized
-- object.
--
-- All strings are returned starting at index 1.
--
with Lines;
with Fields;
generic

    with function Is_Separator (This_Character : in Character) return Boolean;
    --
    -- Specifies which characters are field separators. The beginning and
    -- the end of the string is always a field separator. For example, if
    -- the Is_Separator function recognizes '|' and '.' as field separators,
    -- then the following string contains five fields (three of which are
    -- null):
    --
    --      |a.|bcd|
    --
    -- and the following string contains three fields (one of which is null):
    --
    --      a|.bdc
    --
    -- The null string contains no fields.

package Maps is

    subtype Field is String;

    ---------------------------- MAPPINGS --------------------------------

    type Mapping is private; -- Ordered list of fields.

    function Create (From_String : in String) return Mapping;
    --
    -- Parses the specified string looking for fields, and returns
    -- an initialized mapping. The first field in the string becomes
    -- the key field for the mapping, and it maps to all other fields
    -- in the string (if any).
    --
    -- The mapping's current field is set to the key field before the
    -- mapping is returned.
    --
    -- Raises "Parse_Failure" if the string is null or starts with a
    -- null field.

    function Done (This_Mapping : in Mapping) return Boolean;

    procedure Reset (This_Mapping : in out Mapping);
    --
    -- Resets the current field in the mapping to the key field.

    function Current (This_Mapping : in Mapping) return Field;
    --
    -- Returns the current field in the mapping.
    --
    -- Raises "No_Current_Field" if already "Done".

    procedure Modify (This_Mapping : in out Mapping; New_Field : in Field);
    --
    -- Replaces the current field in the mapping with the new field.
    -- Can be called during iteration without altering iterator's position.
    --
    -- Raises "No_Current_Field" if already "Done".
    --
    -- Raises "Out_Of_Range" if an attempt is made to modify the key field
    -- of the mapping.
    --
    -- Raises "Parse_Failure" if the new field contains a separator.

    procedure Next (This_Mapping : in out Mapping);
    --
    -- Advances the current field in the mapping to the next field.
    --
    -- Raises "No_Next_Field" if already "Done".

    subtype Field_Number is Positive;
    --
    -- Fields are numbered 1..N, and the key field is always 1.

    function Position (In_Mapping : in Mapping) return Field_Number;
    --
    -- Returns the field number corresponding to the current field in
    -- the mapping.
    --
    -- Raises "No_Current_Field" if already "Done".

    procedure Set (This_Mapping : in out Mapping; To_Field : in Field_Number);
    --
    -- Sets the current field in the mapping to the specified field number.
    --
    -- Raises "Out_Of_Range" if the specified field number is out of range.

    function Field_At (This_Position : in Field_Number; In_Mapping : in Mapping)
                      return Field;
    --
    -- Returns the field corresponding to the specified field number.
    -- Can be called during iteration without altering iterator's position.
    --
    -- Raises "Out_Of_Range" if the specified field number is out of range.

    function Fields_In (This_Mapping : in Mapping) return Positive;
    --
    -- Returns the number of fields in the specified mapping.

    ------------------------------- MAPS ---------------------------------

    type Map is private;

    function Create
                (From_Map_File : in String; Ignore_Case : in Boolean := True)
                return Map;
    --
    -- Parses the specified map file, and returns an initialized map
    -- containing N mappings. Each line of the map file must contain
    -- a valid string image of a mapping. All key fields must be unique
    -- (comparison of key fields is NOT case-sensitive unless "Ignore_Case"
    -- is set to False). Empty map files are permitted.
    --
    -- Raises "Parse_Failure" if an invalid mapping (i.e. null string, null
    -- key field, duplicate key, etc) is encountered while parsing the file.
    --
    -- Raises "IO_Failure" if difficulty is encountered opening,
    -- reading from, or closing the specified file.

    procedure Save (To_Map_File : in String; This_Map : in out Map);
    --
    -- Saves the specified map to the specified map file by writing
    -- the string image of each mapping to the file, separating each
    -- field with the field separator.
    --
    -- Raises "IO_Failure" if difficulty is encountered opening,
    -- writing to, or closing the specified file.

    function Is_Mapped (This_Key : in String; In_Map : in Map) return Boolean;
    --
    -- Returns True iff the specified key is found in the specified map.
    -- Comparison of key fields is NOT case-sensitive unless the map was
    -- created with "Ignore_Case" set to False.
    --
    -- Raises "Bad_Mapping" if an invalid mapping is encountered while
    -- searching the map.

    function Mapping_For (This_Key : in String; In_Map : in Map) return Mapping;
    --
    -- Given a key, returns the mapping for the key. Comparison of key
    -- fields is NOT case-sensitive unless the map was created with
    -- "Ignore_Case" set to False.
    --
    -- Raises "No_Mapping" if the key is not found in the map.
    --
    -- Raises "Bad_Mapping" if an invalid mapping is encountered while
    -- searching the map.

    procedure Add (This_Mapping : in String; To_Map : in out Map);
    --
    -- Adds the specified mapping to the specified map. Overwrites any
    -- pre-existing mapping with the same key field. Comparison of key
    -- fields is NOT case-sensitive unless the map was created with
    -- "Ignore_Case" set to False.
    --
    -- Alters iterator state, so is not safe to call while iterating.
    --
    -- Raises "Parse_Failure" if the specified mapping is invalid.
    --
    -- Raises "Bad_Mapping" if an invalid mapping is encountered while
    -- searching the map.

    function Done (This_Map : in Map) return Boolean;

    procedure Reset (This_Map : in out Map);
    --
    -- Resets the current mapping in the map to be the first mapping.
    --
    -- If the map is empty, sets "Done" to True.

    function Current (This_Map : in Map) return Mapping;
    --
    -- Returns the current mapping in the map.
    --
    -- Raises "No_Current_Mapping" if already "Done".
    --
    -- Raises "Bad_Mapping" if the current mapping in the map is
    -- invalid.

    procedure Next (This_Map : in out Map);
    --
    -- Advances the current mapping in the map to the next mapping.
    --
    -- Raises "No_Next_Mapping" if already "Done".

    function Is_Empty (This_Map : in Map) return Boolean;
    --
    -- Returns True iff the specified map contains no mappings.

    function Mappings_In (This_Map : in Map) return Natural;
    --
    -- Returns the number of mappings in the specified map.

    Not_Initialized : exception;

    Parse_Failure : exception;

    No_Current_Field : exception;
    No_Next_Field : exception;

    Out_Of_Range : exception;

    No_Mapping : exception;
    Bad_Mapping : exception;

    No_Current_Mapping : exception;
    No_Next_Mapping : exception;

    Io_Failure : exception;

private

    package Mappings is new Fields (Is_Separator);

    type Mapping is new Mappings.Iterator;

    type Map is
        record
            Contents : Lines.Iterator;  
            Ignore_Case : Boolean := True;
        end record;

end Maps;