DataMuseum.dk

top - metrics - download

    Length: 14246 (0x37a6)
    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

-- There is not necessarily a one-to-one correspondence between the
-- Environment library structure of a software catalog and the contents
-- of the catalog as released. Sections and/or items may be under
-- development or unreleasable for any number of other reasons.
-- Furthermore, it may be desirable to release only code views for
-- certain items.
--
-- Therefore, each version of a software catalog requires a Data_File,
-- which specifies which set of objects should be included in that particular
-- version.
--
-- The Data_File has a rigidly defined syntax which is explained in detail
-- in the package "Syntax". The various annotations in the Data_File contain
-- information about the name, location, kind, and description of each section
-- and item in the catalog. In addition, the Data_File contains information
-- about the imports, spec views, and load views for items which are subsystems.
--
-- This package provides a programmatic interface to the information contained
-- in the Data_File by exporting a set of structures which capture all of the
-- information in the Data_File, as well as operations upon those structures.
-- The details of parsing the Data_File are concealed from the outside world.
--
-- All operations (except diagnostics) raise "Bad_Element" if applied to an
-- object which is bad or which is part of a structure which is bad.
--
-- All "Next" iteration operations raise "No_Next_Element" if there
-- is no next element.
--
-- All "Current" iteration operations raise "No_Current_Element" if
-- there is no current element.
--
-- "Names" are different from "Locations", in that names might be any string,
-- but locations have to be valid Environment pathnames.
--

-- These are needed for the non-private part of the spec:
--
with Io;
with Syntax;
with Subtypes;
use Subtypes;
with Directory_Tools;

-- These are only needed for the private part of the spec:
--
pragma Private_Eyes_Only;
with Lines;
with Files;  
with Singly_Linked_List_Generic;

package Structure is

    -- ***** TYPES:

    type Line is private;

    type Text is private;

    type Message is private;

    type Diagnostic is private;

    type Data_File is private;

    type Object is private;

    type Object_List is private;

    type Item is private;

    type Section is private;

    type Catalog is private;

    subtype Physical_Object is Directory_Tools.Object.Handle;

    -- ***** SELECTORS AND ITERATORS:

    -- LINE:

    function Contents_Of (This_Line : in Line) return String;

    -- TEXT:

    procedure Reset (This_Text : in out Text);  
    function Current_Line (This_Text : in Text) return Line;  
    function Done (This_Text : in Text) return Boolean;  
    procedure Next (This_Text : in out Text);

    -- MESSAGE:

    type Diagnostics is (Progress, Warning, Error);

    function Kind_Of (This_Message : in Message) return Diagnostics;
    function Contents_Of (This_Message : in Message) return String;

    -- DIAGNOSTIC:

    procedure Reset (This_Diagnostic : in out Diagnostic);  
    function Current_Message (This_Diagnostic : in Diagnostic) return Message;  
    function Done (This_Diagnostic : in Diagnostic) return Boolean;  
    procedure Next (This_Diagnostic : in out Diagnostic);

    -- OBJECT:

    function Name_Of (This_Object : in Object) return Full_Name;
    function Simple_Name_Of (This_Object : in Object) return Simple_Name;
    function Actual_Object_For (This_Object : in Object) return Physical_Object;

    -- OBJECT LISTS:

    procedure Reset (This_Object_List : in out Object_List);
    function Current_Object (This_Object_List : in Object_List) return Object;
    function Done (This_Object_List : in Object_List) return Boolean;
    procedure Next (This_Object_List : in out Object_List);

    -- ITEM:

    subtype Imports is Object_List;
    subtype Spec_Views is Object_List;
    subtype Load_Views is Object_List;

    function Name_Of (This_Item : in Item) return String;  
    function Kind_Of (This_Item : in Item) return Syntax.Item_Kinds;
    function Description_Of (This_Item : in Item) return Text;  
    function Catalog_Containing (This_Item : in Item) return Catalog;
    function Section_Containing (This_Item : in Item) return Section;

    -- All remaining operations on Items raise "Invalid_Item_Kind" if
    -- the item is of kind "ENVIRONMENT".

    function Location_Of (This_Item : in Item) return Simple_Name;
    function Full_Location_Of (This_Item : in Item) return Full_Name;
    function Imports_For (This_Item : in Item) return Imports;  
    function Spec_Views_For (This_Item : in Item) return Spec_Views;
    function Load_Views_For (This_Item : in Item) return Load_Views;
    function Is_Proprietary (This_Item : in Item) return Boolean;
    function Actual_Item_For (This_Item : in Item) return Physical_Object;

    -- ITEMS:

    procedure Reset (This_Section : in out Section);  
    function Current_Item (This_Section : in Section) return Item;  
    function Done (This_Section : in Section) return Boolean;  
    procedure Next (This_Section : in out Section);

    -- SECTION:

    function Name_Of (This_Section : in Section) return String;  
    function Kind_Of (This_Section : in Section)  
                     return Syntax.Section_Kinds;
    function Location_Of (This_Section : in Section) return Simple_Name;
    function Full_Location_Of (This_Section : in Section) return Full_Name;
    function Description_Of (This_Section : in Section) return Text;
    function Catalog_Containing (This_Section : in Section) return Catalog;

    function Actual_Section_For
                (This_Section : in Section) return Physical_Object;
    --
    -- Raises "Invalid_Section_Kind" if section is of kind "TEXT".

    -- SECTIONS:

    procedure Reset (This_Catalog : in out Catalog);
    function Current_Section (This_Catalog : in Catalog) return Section;
    function Done (This_Catalog : in Catalog) return Boolean;  
    procedure Next (This_Catalog : in out Catalog);

    -- CATALOG:

    subtype Allowable_Models is Object_List;
    subtype Allowable_Links is Object_List;

    function Name_Of (This_Catalog : in Catalog) return String;
    function Version_Of (This_Catalog : in Catalog) return Simple_Name;
    function Full_Version_Of (This_Catalog : in Catalog) return Full_Name;
    function Location_Of (This_Catalog : in Catalog) return Simple_Name;
    function Full_Location_Of (This_Catalog : in Catalog) return Full_Name;
    function Description_Of (This_Catalog : in Catalog) return Text;
    function Allowable_Models_For
                (This_Catalog : in Catalog) return Allowable_Models;
    function Allowable_Links_For
                (This_Catalog : in Catalog) return Allowable_Links;

    function Actual_Catalog_For
                (This_Catalog : in Catalog) return Physical_Object;

    -- ***** CONSTRUCTORS:

    function Catalog_From (This_Data_File : in Full_Name) return Catalog;
    --
    -- Attempts to resolve the specified Data_File. If the Data_File cannot
    -- be resolved, a diagnostic message is stored in the catalog object,
    -- the status of the catalog object is set to "Bad", and the operation
    -- terminates.
    --
    -- If the Data_File is successfully resolved, attempts to parse the
    -- Data_File and to construct a corresponding catalog object. If a
    -- syntax error is encountered while parsing the file, a diagnostic
    -- message is stored in the catalog object, the status of the catalog
    -- object is set to "Bad", and the operation terminates.
    --
    -- No exceptions are propagated out of this function.

    type Traversal_Control is (Continue, Abandon_Children,
                               Abandon_Level, Abandon_Traversal);
    --
    -- Increasingly severe control over the next step in the traversal.
    --
    -- "Continue"          => continue with the traversal
    --
    -- "Abandon_Children"  => visit siblings of the current
    --                        element, but do not visit its children
    --
    -- "Abandon_Level"     => do not visit siblings of the current element,
    --                        but continue traversal at the next level up
    --
    -- "Abandon_Traversal" => stop all traversal

    generic

        type State is private;

        with procedure Operate_On  
                          (This_Catalog : in Catalog;
                           This_State : in out State;
                           Control_Result : out Traversal_Control);

        with procedure Operate_On  
                          (This_Section : in Section;
                           This_State : in out State;
                           Control_Result : out Traversal_Control);

        with procedure Operate_On  
                          (This_Item : in Item;
                           This_State : in out State;
                           Control_Result : out Traversal_Control);

        with procedure Finalize_Traversal (This_Catalog : in Catalog;
                                           This_State : in out State);

    procedure Traverse (This_Catalog : in Catalog; This_State : in out State);
    --
    -- Performs a depth-first traversal of the specified catalog object,
    -- applying the operation appropriat for the current node. After
    -- returning from each operation, the "Control_Result" is checked,
    -- and the action taken next depends on the value.

    generic

        with function Dont_Want (This_Item : in Item) return Boolean;

        with function Dont_Want (This_Section : in Section) return Boolean;

    function Filtered_Version_Of (This_Catalog : in Catalog) return Catalog;
    --
    -- Returns a catalog object filtered in accordance with the supplied
    -- filtering functions. Objects which are copied from the original
    -- catalog object to the new catalog object are true copies (not aliases).
    --
    -- NOTE: It is possible for the filtered catalog to violate the invariants
    -- for catalogs, since consistency is not checked after the fact. To
    -- make sure that the resulting catalog is consistent, it can be saved
    -- to a file and the file can be used to construct a third catalog:
    -- during the construction of the third catalog, any violations of
    -- the invariants will be revealed.

    function Copy_Of (This_Catalog : in Catalog) return Catalog;
    --
    -- Returns a true (non-alised) copy of the specified catalog.
    -- Very different from ":=".

    procedure Save (This_Catalog : in Catalog; To_This_File : in Full_Name);
    --
    -- Attempts to write the specified catalog to the specified file.
    --
    -- NOTE: Since comments are screened out when parsing the original
    -- Data_File, the Data_File which results from saving a catalog will
    -- be stripped of all comments.
    --
    -- Raises "IO_Failure" if a problem is encountered saving the catalog.

    procedure Save_Header (This_Catalog : in Catalog;
                           To_This_File : in out Io.File_Type);
    procedure Save_Header (This_Section : in Section;
                           To_This_File : in out Io.File_Type);
    procedure Save_Header (This_Item : in Item;
                           To_This_File : in out Io.File_Type);
    --
    -- These three operations save all but the description information for
    -- the specified object to the specified file.

    procedure Save_Text (This_Text : in Text;
                         To_This_File : in out Io.File_Type);
    --
    -- This operation saves the specified text (i.e. the descriptive portion
    -- of an object) to the specified file.

    procedure Save_Trailer (This_Catalog : in Catalog;
                            To_This_File : in out Io.File_Type);
    --
    -- This operation saves the trailer information (i.e. models and links)
    -- for the specified catalog to the specified file.

    procedure Set_Version_Of (This_Data_File : in Full_Name;
                              To_This_Version : in Simple_Name);
    --
    -- Changes the argument to the @VERSION annotation in the specified
    -- Data_File to the specified version.
    --
    -- Raises "IO_Failure" if the specified file cannot be opened, or if
    -- it contains no @VERSION annotation.

    -- ***** DIAGNOSTICS:

    function Is_Good (This_Catalog : in Catalog) return Boolean;
    --
    -- Returns True iff the specified catalog object and all of its
    -- sub-elements are good.

    procedure Assert_Is_Good (This_Catalog : in Catalog);
    --
    -- Raises "Bad_Element" if the specified catalog object or any of its
    -- sub-elements is bad.

    function Diagnostic_For (This_Catalog : in Catalog) return Diagnostic;
    --
    -- Returns a diagnostic for the specified catalog object.
    --
    -- All catalog objects, including "Good" ones, have a diagnostic
    -- of one form or another.

    function Diagnostic_For (This_Catalog : in Catalog) return Data_File;
    --
    -- Returns the Data_File iterator from which the specified catalog
    -- was constructed. If the Data_File could not be resolved, the iterator
    -- is empty.

    -- ***** EXCEPTIONS:

    Bad_Element : exception;

    No_Current_Element : exception;  
    No_Next_Element : exception;

    Invalid_Section_Kind : exception;
    Invalid_Item_Kind : exception;

    No_Such_Section : exception;
    No_Such_Item : exception;

    Io_Failure : exception;

private

    type Data_File is new Files.Iterator;

    type Line is new Lines.Line;

    type Text is new Lines.Iterator;

    type Message_Node;

    type Message is access Message_Node;

    package Message_Lists is new Singly_Linked_List_Generic (Message);

    type Diagnostic is new Message_Lists.List;

    type Object_Node;

    type Object is access Object_Node;

    package Object_Lists is new Singly_Linked_List_Generic (Object);

    type Object_List is new Object_Lists.List;

    type Item_Node;

    type Item is access Item_Node;

    package Item_Lists is new Singly_Linked_List_Generic (Item);

    type Section_Node;

    type Section is access Section_Node;

    package Section_Lists is new Singly_Linked_List_Generic (Section);

    type Catalog_Node;

    type Catalog is access Catalog_Node;

end Structure;