⟦3e17c6d76⟧

TextFile

with Errors;
with Heap_Strings;
with Mapping;

package Abstract_Document is

    subtype Astring is Heap_Strings.Astring;

    subtype Pathname   is String;
    subtype Pathnames  is String;  -- NAMING.NAME format.
    subtype Text       is String;
    subtype Title_Text is String;

    Point : constant := 1.0 / 72;

    type Inches is digits 5 range 0.0 .. 100.0;      -- For Graphic sizes
    Default_Size : constant Inches := 0.0;

    type Percentage is digits 5 range 0.0 .. 100.0;  -- For Table column sizes
    Default_Percentage : constant Percentage := 1.0;

    type Position is (Left,  
                      Right,  
                      Center,  
                      Fill);            -- For Cover_Item & column-header

    type Linkage_Info (Valid : Boolean := False) is private;
    Nil_Linkage : constant Linkage_Info;

    -- Return True if the Linkage_Info is null
    function Is_Nil (For_Linkage : Linkage_Info) return Boolean;


    subtype Font_Families is Text;
    Default_Font_Family : constant Font_Families := "";

    subtype Font_Styles is Text;
    Default_Font_Style : constant Font_Styles := "";

    type Point_Sizes is new Natural range 0 .. 255;
    Default_Point_Size : constant Point_Sizes := 0;

    Default_User_Info : constant Text := "";

    type Format_Info (Valid : Boolean := False) is private;
    Nil_Format : constant Format_Info;

    -- Return True if the Format_Info is null
    function Is_Nil (For_Format : Format_Info) return Boolean;


    type Handle is private;


    type Access_Mode is (Read,  
                         Write,  
                         Read_Write);


    -- Open a document file
    procedure Open (The_Document       : in out Handle;
                    Name               : Pathname;
                    Status             : in out Errors.Condition;
                    Mode               : Access_Mode := Abstract_Document.Read;
                    Check_Obsolescence : Boolean := True);

    -- Create a new document file
    procedure Create (The_Document : in out Handle;
                      Name : Pathname;
                      Status : in out Errors.Condition;
                      Mode : Access_Mode := Abstract_Document.Write;
                      Check_Obsolescence : Boolean := True);

    -- Close a document file
    procedure Close (The_Document : in out Handle);


    -- If an interface operation raises FAILED, a status condition
    --   can be extracted from the handle associated with that operation,
    --   and an error message can be written.

    Failed               : exception;
    Uninitialized_Handle : exception;


    -- Get the status condition associated with a document file
    procedure Get_Status (From_Handle :        Handle;
                          Result      : in out Errors.Condition);


    pragma Page;


    -- Documents are organized as trees with nodes having a kind.
    -- Documents may be traversed by asking for Parent, Brother,
    --   and children starting at the Root node.
    -- Kind-dependent operations may be performed on nodes
    --   to extract interesting information about them.

    type Node_Kinds is (Nil,  
                        Root,  
                        Cover,  
                        Cover_Item,  
                        Paragraph,  
                        Appendix,  
                        Text_Block,  
                        File,  
                        Graphic,  
                        List,  
                        List_Item,  
                        Table,  
                        Table_Row,  
                        Table_Column,  
                        Table_Entry,  
                        White_Space,  
                        User_Defined,  
                        Future_Node_1,  
                        Future_Node_2,  
                        Future_Node_3,  
                        Future_Node_4);

    type Node is private;
    Nil_Node : constant Node;


    -- Return True if a Node is null
    function Is_Nil (For_Node : Node) return Boolean;

    -- Get the Node_Kind of a Node
    function Kind (Of_Node : Node) return Node_Kinds;

    -- Return True if a node is the Root node
    function Is_Root (A_Node : Node) return Boolean;

    -- Get the Root node of a document
    function Root_Node (Of_Document : Handle) return Node;


    --------------------------------------------------------
    -- This generic VISITs the nodes in the document in   --
    --   the order appropriate for printing a document.   --
    -- NOTE : This generic generates garbage and thus     --
    --   should only be instantiated within a procedure   --
    --   or in a non-permanent job.                       --
    --------------------------------------------------------

    type Visit_Status is (Ok,  
                          Abandon_Children,  
                          Abandon_Brothers,  
                          Complete);

    generic
        with procedure Operation (On_Node : Node; Status : out Visit_Status);
    procedure Visit_Nodes (Start_Node : Node);

    pragma Page;


    ------------------------------
    -- DOCUMENT ENTRY INTERFACE --
    ------------------------------

    package Specify is

        ----------------------------------------------------------------
        -- Every document must start with a COVER, which may be null,
        --   and every non-null Cover must contain at least one Cover_Item.
        -- A COVER_ITEM can only be inserted within a Cover, but a Cover
        --   can also contain File, Graphic, or White_Space nodes.
        --   The Cover is done when the first PARAGRAPH call is made, or
        --   when the document ends if there are no Paragraphs.
        ----------------------------------------------------------------

        procedure Cover (Document : Handle;
                         User_Info : Text;
                         Linkage : Linkage_Info :=
                            Abstract_Document.Nil_Linkage;
                         Format : Format_Info := Abstract_Document.Nil_Format);

        procedure Cover_Item
                     (Document : Handle;
                      Item : Title_Text;
                      Line_Positions : Position := Abstract_Document.Center;
                      Linkage : Linkage_Info := Abstract_Document.Nil_Linkage;
                      Format : Format_Info := Abstract_Document.Nil_Format);


        -----------------------------------------------------------------------
        -- Sectioning operations.
        -----------------------------------------------------------------------
        --
        -- PARAGRAPH causes the section level to be reset to 1 and sets the
        --   level-1 section number (the current paragraph number) to NUMBERED.
        --   Every document must have at least one Paragraph, and
        --   Paragraph numbers (NUMBERED) must be in increasing order.
        -- A Paragraph is composed of a sequence of Text_Block, File, Graphic,
        --   List, Table, White_Space, User_Defined and/or sub-Paragraph nodes.
        -- NEW_LEVEL increments to the next section level and sets that
        --   level's section number to 0.  Nothing is output to the document.
        -- NEXT_SUB_PARAGRAPH causes the current level's (rightmost) section
        --   number to be incremented.
        -- NEW_SUB_PARAGRAPH is equivalent to NEW_LEVEL followed by
        --   NEXT_SUB_PARAGRAPH, i.e., it increments to the next
        --   section level and sets that level's section number to 1.
        -- END_LEVEL decrements the section level.
        -- xxx_LEVEL operations are used for setting up a loop which uses
        --   NEXT_SUB_PARAGRAPH to generate nested sections.
        -- APPENDIX is like PARAGRAPH except for the numbering format
        --   (Roman numerals or letters).
        --   Appendix numbers (NUMBERED) must be in increasing order.
        --   A PARAGRAPH cannot follow an APPENDIX.
        -----------------------------------------------------------------------

        procedure Paragraph
                     (Document : Handle;
                      Numbered : Positive;
                      Title    : Title_Text;
                      Linkage  : Linkage_Info := Abstract_Document.Nil_Linkage;
                      Format   : Format_Info  := Abstract_Document.Nil_Format);

        procedure Appendix (Document : Handle;
                            Numbered : Positive;
                            Title    : Title_Text;
                            Linkage  : Linkage_Info :=
                               Abstract_Document.Nil_Linkage;
                            Format   : Format_Info  :=
                               Abstract_Document.Nil_Format);

        procedure New_Sub_Paragraph
                     (Document : Handle;
                      Title    : Title_Text;
                      Linkage  : Linkage_Info := Abstract_Document.Nil_Linkage;
                      Format   : Format_Info  := Abstract_Document.Nil_Format);

        procedure Next_Sub_Paragraph
                     (Document : Handle;
                      Title    : Title_Text;
                      Linkage  : Linkage_Info := Abstract_Document.Nil_Linkage;
                      Format   : Format_Info  := Abstract_Document.Nil_Format);

        procedure New_Level (Document : Handle);

        procedure End_Level (Document : Handle);


        -----------------------------------------------------------------
        -- The TEXT_BLOCK procedure causes a block of text to be inserted
        --   in the body of the document (within a Paragraph or Appendix)
        --   or in the body of a List_Item.
        -----------------------------------------------------------------
        procedure Text_Block
                     (Document : Handle;
                      T        : Text;
                      Linkage  : Linkage_Info := Abstract_Document.Nil_Linkage;
                      Format   : Format_Info  := Abstract_Document.Nil_Format);


        -----------------------------------------------------------------------
        -- Operations to insert text FILE or GRAPHIC objects into the DOCUMENT.
        --   They can go into the Cover, a Paragraph/Appendix, or a List_Item.
        --   For GRAPHIC objects, the FROM_PATHNAMES parameter may resolve to
        --   multiple objects. These objects map to device-dependent graphic
        --   files to be included in the generated markup language.
        -----------------------------------------------------------------------
        procedure File (Document : Handle;
                        From_Pathnames : Pathnames;
                        Explain : Text := "";
                        Format : Format_Info := Abstract_Document.Nil_Format);

        procedure Graphic
                     (Document : Handle;
                      From_Pathnames : Pathnames;
                      Title : Title_Text;
                      Preface : Text;
                      Size : Inches := Abstract_Document.Default_Size;
                      Perform_Scaling : Boolean := False;
                      Explain : Text := "";  
                      Format : Format_Info := Abstract_Document.Nil_Format);


        --------------------------------------------------------------------
        -- List description operations.
        --------------------------------------------------------------------
        --
        -- A List is composed of one or more List_Items, each of which has a
        --   header, and a body composed of a sequence of Text_Block, File,
        --   Graphic, List, Table, White_Space, and/or User_Defined nodes.
        --   If Linkage and/or Format is not included in a List node when
        --   it is constructed (by a START_LIST), it can be inserted by
        --   the corresponding END_LIST.
        --------------------------------------------------------------------
        procedure Start_List
                     (Document : Handle;
                      Title    : Title_Text;
                      Linkage  : Linkage_Info := Abstract_Document.Nil_Linkage;
                      Format   : Format_Info  := Abstract_Document.Nil_Format);

        procedure List_Item
                     (Document : Handle;
                      Header_Text : Text;
                      Linkage : Linkage_Info := Abstract_Document.Nil_Linkage;
                      Format : Format_Info := Abstract_Document.Nil_Format);

        procedure End_List (Document : Handle;
                            Linkage  : Linkage_Info :=
                               Abstract_Document.Nil_Linkage;
                            Format   : Format_Info  :=
                               Abstract_Document.Nil_Format);


        ----------------------------------------------------------------------
        -- Table description operations.
        ----------------------------------------------------------------------
        --
        -- COLUMN_INFORMATION is used to define a table's columns.
        --   The column information is done when the first TABLE_ENTRY
        --   call is made.  If COLUMNS is defaulted to 0, the actual number
        --   of columns supplied will be used, but otherwise the number
        --   supplied must match COLUMNS.  All rows of a Table must be filled,
        --   so if there are 3 columns, the total number of Table_Entrys
        --   must be a multiple of 3.  A Table must have at least one entry
        --   (at least one column and one row).
        --   If Linkage and/or Format is not included in a Table node when
        --   it is constructed (by a START_TABLE), it can be inserted by
        --   the corresponding END_TABLE.
        ----------------------------------------------------------------------
        procedure Start_Table
                     (Document : Handle;
                      Name     : Title_Text;
                      Preface  : Text;
                      Columns  : Natural      := 0;
                      Linkage  : Linkage_Info := Abstract_Document.Nil_Linkage;
                      Format   : Format_Info  := Abstract_Document.Nil_Format);

        procedure Column_Information
                     (Document : Handle;
                      Title : Title_Text;
                      Entry_Justification : Position :=
                         Abstract_Document.Center;
                      Percentage_Size : Percentage :=
                         Abstract_Document.Default_Percentage;
                      Linkage : Linkage_Info := Abstract_Document.Nil_Linkage;
                      Format : Format_Info := Abstract_Document.Nil_Format);

        procedure Table_Entry
                     (Document  : Handle;
                      Item_Text : Title_Text;
                      Linkage   : Linkage_Info := Abstract_Document.Nil_Linkage;
                      Format    : Format_Info  := Abstract_Document.Nil_Format);

        procedure End_Table (Document : Handle;
                             Linkage  : Linkage_Info :=
                                Abstract_Document.Nil_Linkage;
                             Format   : Format_Info  :=
                                Abstract_Document.Nil_Format);


        ----------------------------------------------------------------
        -- Miscellaneous
        ----------------------------------------------------------------
        --
        --   These 'White-Space' nodes can appear in a Cover, Paragraph,
        --     Appendix, or List, but not in a Table.
        ----------------------------------------------------------------
        procedure New_Page (Document : Handle; Count : Positive := 1);

        procedure Blank_Line (Document : Handle; Count : Positive := 1);


        -----------------------------------------------------------------------
        -- A USER_DEFINED node is similar to a TEXT_BLOCK but has an additional
        --   user-defined data that will not be presented in the PREVIEW OE.
        --   USER_DEFINED nodes can appear anywhere in a document.
        -----------------------------------------------------------------------
        procedure User_Defined
                     (Document  : Handle;
                      T         : Text;
                      User_Data : Text;
                      Linkage   : Linkage_Info := Abstract_Document.Nil_Linkage;
                      Format    : Format_Info  := Abstract_Document.Nil_Format);


        -----------------------------------------------
        -- Routines for generating Linkages.
        -- Storage is allocated in the document's heap.
        -----------------------------------------------
        function Gen_Linkage (Document   : Handle;
                              Explain    : Text                := "";
                              Definition : Mapping.Target_Info :=
                                 Mapping.Nil_Target_Info;
                              Usage      : Mapping.Target_Info :=
                                 Mapping.Nil_Target_Info;
                              Derivation : Mapping.Target_Info :=
                                 Mapping.Nil_Target_Info) return Linkage_Info;

        -----------------------------------------------
        -- Construction operation for Format data.
        -- Storage is allocated in the document's heap.
        -----------------------------------------------

        function Gen_Format
                    (Document    : Handle;
                     Font_Family : Font_Families :=
                        Abstract_Document.Default_Font_Family;
                     Font_Style  : Font_Styles :=
                        Abstract_Document.Default_Font_Style;
                     Point_Size  : Point_Sizes :=
                        Abstract_Document.Default_Point_Size;
                     User_Info   : Text := Abstract_Document.Default_User_Info)
                    return Format_Info;
    end Specify;

    pragma Page;


    --------------------------
    -- EXTRACTION INTERFACE --
    --------------------------

    package Extract is

        ---------------------------------
        -- Node-independent operations --
        ---------------------------------
        function Parent (Of_Node : Node) return Node;

        function Brother (Of_Node : Node) return Node;

        function Linkage (Of_Node : Node) return Linkage_Info;

        function Format (Of_Node : Node) return Format_Info;

        function Image (Of_Node : Node)     return String;
        function Image (Of_Handle : Handle) return String;


        -- The following provide debugger Image functions --
        --   for Abstract_Document's private types        --

        function Debug_Image (Of_Linkage      : Linkage_Info;
                              Level           : Natural;
                              Prefix          : String;
                              Expand_Pointers : Boolean) return String;

        function Debug_Image (Of_Format       : Format_Info;
                              Level           : Natural;
                              Prefix          : String;
                              Expand_Pointers : Boolean) return String;

        function Debug_Image (Of_Handle       : Handle;
                              Level           : Natural;
                              Prefix          : String;
                              Expand_Pointers : Boolean) return String;

        function Debug_Image (Of_Node         : Node;
                              Level           : Natural;
                              Prefix          : String;
                              Expand_Pointers : Boolean) return String;


        -- ROOT --
        function Cover           (Root_Node : Node) return Node;
        function First_Paragraph (Root_Node : Node) return Node;


        -- COVER --
        function First_Cover_Item (Cover_Node : Node) return Node;
        function Cover_Info       (Cover_Node : Node) return String;

        function Cover_Item_Text (Cover_Item_Node : Node) return String;
        function Cover_Item_Justification
                    (Cover_Item_Node : Node)              return Position;


        -- PARAGRAPHs and APPENDIXs - composed of NUMBER and TITLE --
        function Paragraph_Number
                    (Paragraph_Or_Appendix_Node : Node) return String;
        -- eg : "3.4.5".
        function Para_Depth (Paragraph_Or_Appendix_Node : Node) return Natural;
        function Para_Index (Paragraph_Or_Appendix_Node : Node) return Natural;
        function Paragraph_Title
                    (Paragraph_Or_Appendix_Node : Node) return String;
        function First_Contents (Paragraph_Or_Appendix_Node : Node) return Node;


        -- TEXT_BLOCKs and USER_DEFINED                           --
        -- Use IMAGE, LINKAGE, and FORMAT to get info about these --
        function User_Data (User_Defined_Node : Node) return String;


        -- GRAPHICs and FILEs - composed of FILE_NAME and optional scaling info
        function File_Name (Graphic_Or_File_Node : Node) return String;

        function Graphic_Title   (Graphic_Node : Node) return String;
        function Graphic_Preface (Graphic_Node : Node) return String;
        function Graphic_Size    (Graphic_Node : Node) return Inches;
        function Perform_Scaling (Graphic_Node : Node) return Boolean;


        -- LISTs - composed of LIST_ITEMs, each with a header.   --
        -- Use BROTHER on a LIST_ITEM node to get the next item. --
        function List_Count      (List_Node : Node) return Natural;
        function List_Title      (List_Node : Node) return String;
        function First_List_Item (List_Node : Node) return Node;

        function Header_Text         (List_Item_Node : Node) return String;
        function First_List_Contents (List_Item_Node : Node) return Node;


        -- TABLEs - composed of column information and rows of TABLE_ENTRYs --
        function Table_Title   (Table_Node : Node) return String;
        function Table_Preface (Table_Node : Node) return String;
        function Column_Count  (Table_Node : Node) return Natural;
        function Row_Count     (Table_Node : Node) return Natural;
        function First_Column  (Table_Node : Node) return Node;
        function First_Row     (Table_Node : Node) return Node;

        function Column_Title (Table_Column_Node : Node) return String;
        function Column_Justification
                    (Table_Column_Node : Node)           return Position;
        function Column_Percentage_Size
                    (Table_Column_Node : Node)           return Percentage;

        function First_Table_Entry (Table_Row_Node : Node) return Node;

        -- COLUMNs may have LINKAGE/FORMAT info; so may TABLE_ENTRYs.     --
        -- Use IMAGE, LINKAGE, and FORMAT to get info about TABLE_ENTRYs. --
        -- Use BROTHER to get next for ROWs, COLUMNs, and TABLE_ENTRYs.   --


        -- WHITE_SPACE - composed of an image of the requested spacing     --
        -- (use IMAGE). ASCII.LFs indicate new lines, ASCII.FFs new pages. --


        -- LINKAGE --
        function Explain_Text (For_Linkage : Linkage_Info) return String;

        function Definition (For_Linkage : Linkage_Info)
                            return Mapping.Target_Info;

        function Usage (For_Linkage : Linkage_Info) return Mapping.Target_Info;

        function Derivation (For_Linkage : Linkage_Info)
                            return Mapping.Target_Info;

        function Image (Of_Linkage : Linkage_Info) return String;


        -- The following produce string representations of the items LINKed to
        function Definition (For_Linkage : Linkage_Info) return String;

        function Usage (For_Linkage : Linkage_Info) return String;

        function Derivation (For_Linkage : Linkage_Info) return String;


        -- FORMAT --
        function Font_Family (For_Format : Format_Info) return Font_Families;
        function Font_Style  (For_Format : Format_Info) return Font_Styles;
        function Point_Size  (For_Format : Format_Info) return Point_Sizes;
        function User_Info   (For_Format : Format_Info) return String;

        function Image (Of_Format : Format_Info) return String;


        -- Raise this exception if anything is wrong with the node --
        Bad_Node : exception;

        -- Raise this exception if DEFINITION, USAGE or DERIVATION
        -- have resolution problems.  Use the STATUS call to get the
        -- error status associated with the resolution problem.
        Bad_Linkage : exception;

        function Status return Errors.Condition;

        -- Returns the number of consecutive graphic nodes, including the
        -- specified node. If the specified node is not a graphic node, this
        -- function returns a value of zero.
        --
        function Number_Of_Figures (Graphic_Node : Node) return Natural;

        -- Returns the last consecutive graphic node following the specified
        -- node. If there is only one graphics node, this becomes the identity
        -- function.
        --
        function Last_Figure (Graphic_Node : Node)
                             return Abstract_Document.Node;

    end Extract;


    -- Delete a document file
    procedure Delete (The_Document : Handle; Status : in out Errors.Condition);

    -- Get the Form of a document file
    --[This merely returns the null string for now]
    function Form (The_Document : Handle) return String;

    -- Return True if a document file is open
    function Is_Open (The_Document : Handle) return Boolean;

    -- Get the access mode (Read, Write, Read_Write) of a document file
    function Mode (The_Document : Handle) return Access_Mode;

    -- Get the name of a document file
    function Name (The_Document : Handle) return String;


    pragma Subsystem (Design_Facility, Closed);
    pragma Module_Name (4, 3590);
    pragma Bias_Key (27);

private
    type Handle_Object;
    type Handle is access Handle_Object;
    pragma Segmented_Heap (Handle);

    type Node_Data (Kind        : Node_Kinds := Nil;
                    Has_Linkage : Boolean    := False;
                    Has_Format  : Boolean    := False);
    type Node is access Node_Data;
    pragma Segmented_Heap (Node);

    Nil_Node : constant Node := null;

    type String_Table_Index is new Natural range 0 .. 2 ** 16 - 1;


    type Linkage_Entry (Valid : Boolean := False) is
        record
            case Valid is
                when True =>
                    Explain    : String_Table_Index;
                    Definition : String_Table_Index;
                    Usage      : String_Table_Index;
                    Derivation : String_Table_Index;
                when False =>
                    null;
            end case;
        end record;

    -- This structure is used to pass along linkage information.
    type Linkage_Info (Valid : Boolean := False) is
        record
            The_Entry : Linkage_Entry (Valid => Valid);

            case Valid is
                when True =>
                    Assoc_Node : Node;
                when False =>
                    null;
            end case;
        end record;

    Nil_Linkage : constant Linkage_Info :=
       Linkage_Info'(Valid     => False,
                     The_Entry => Linkage_Entry'(Valid => False));


    type Format_Entry (Valid : Boolean := False) is
        record
            case Valid is
                when True =>
                    Font_Family : String_Table_Index;
                    Font_Style  : String_Table_Index;
                    Point_Size  : Point_Sizes;
                    User_Info   : String_Table_Index;
                when False =>
                    null;
            end case;
        end record;

    -- This structure is used to pass along format information.
    type Format_Info (Valid : Boolean := False) is
        record
            The_Entry : Format_Entry (Valid => Valid);

            case Valid is
                when True =>
                    Assoc_Node : Node;
                when False =>
                    null;
            end case;
        end record;

    Nil_Format : constant Format_Info :=
       Format_Info'(Valid => False, The_Entry => Format_Entry'(Valid => False));


    -- The following limits are enforced for an Abstract Document:
    --
    --      Maximum paragraph number                    = 65535
    --      Maximum number of paragraph levels          = 65535
    --      Maximum paragraph nesting level             =    15
    --      Maximum number of items in a list           = 65535
    --      Maximum nesting level for lists             =    15
    --      Maximum number of columns in a table        =   255
    --      Maximum number of rows in a table           = 65535

end Abstract_Document;
DataMuseum.dk

Rational R1000/400 Tapes

⟦3e17c6d76⟧ TextFile

Derivation

TextFile
