⟦cf99738d3⟧

TextFile

with System;
package User_Io is

    -- ************************************************************************
    --
    --    This package specification defines the implementation dependent
    --    treatments to be supported by user-supplied code located within
    --    the package body (or called from it).
    --
    --    Thus, this specification has been compiled into the predefined
    --    Alsys library to be called from the Alsys i/o system.
    --    When implementing the Ada i/o features on their target system, user
    --    will have to get a link to it (via the ACQUIRE command of the
    --    unit manager, kind=ALTERNATE) and then compile a corresponding
    --    package body into their application library
    --
    -- NOTE:
    --    In each user suplied routine, the predefined io-exceptions may (and
    --    should, if the Ada semantic requires it) be raised when this is
    --    appropriate
    --
    -- ************************************************************************

    type Long_Natural is range 0 .. System.Max_Int;


    -- 1. Data types

    type File_Id is private;
    -- This user defined "name" uniquely identifies a logical file from its
    -- opening (or creation) to its closure.


    type Identification is limited private;
    -- This user defined identification uniquely identifies a file (used for
    -- sharing control).


    type File_Mode is (In_File, Out_File, In_Out_File);
    -- File access mode


    type Sharing_Mode is (Any, Not_Shared, Readers, Single_Writer);
    -- File sharing mode


    type Io_Type is (Text_File, Sequential_File, Direct_File);
    -- File logical type


    type Create_Option is (Overwrite, Error);
    -- File creation option


    type File_Type is (Terminal, Mass_Storage);
    -- Device kind


    type File_Offset is range -2 ** 31 .. 2 ** 31 - 1;
    -- Used for setting the index position.


    subtype File_Index is File_Offset range 1 .. File_Offset'Last;
    -- Read/write index within the file. index = N means that the Nth  item
    -- of the file is accessible. Note that an 'item' may be a character
    -- (text-files) or a record, whose size and structure depend on the
    -- type of data stored in it. (Refer to appendix F8)


    -- 2. File-names management


    function Path (File_Name : String) return String;
    -- ------------------------------------------------------------------------
    -- Extends a file-name relative to the current directory to an absolute
    -- name (include device name if needed).
    -- ------------------------------------------------------------------------


    function Standard_Input_File return String;
    -- ------------------------------------------------------------------------
    -- Returns the (absolute) name of the standard input file
    -- ------------------------------------------------------------------------


    function Standard_Output_File return String;
    -- ------------------------------------------------------------------------
    -- Returns the (absolute) name of the standard output file
    -- ------------------------------------------------------------------------


    function Temporary_File return String;
    -- ------------------------------------------------------------------------
    -- Returns an (absolute) file name to be given  to  a  the  next  temporary
    -- file to be created.  This name will be reusable after  the  deletion  of
    -- this file
    -- ------------------------------------------------------------------------



    -- 3. Basic file management


    function Create (Path : String;
                     Mode : File_Mode := In_Out_File;
                     Sharing : Sharing_Mode := Not_Shared;
                     Option : Create_Option := Overwrite;
                     Io_Kind : Io_Type := Text_File) return File_Id;
    -- ------------------------------------------------------------------------
    -- Creates an external file of the (absolute) name 'PATH' and opens  it  in
    -- mode 'MODE'.   The  (user-defined)  file  identifier  will  be  used  to
    -- designate  this  file  for  any  further  operations  until  the  file's
    -- closure.  The user may decide what to do  if  the  file  already  exists
    -- (overwrite? , raise use_error? , ...) or if the creation or the mode  is
    -- meaningless on the underlaying device.
    -- ------------------------------------------------------------------------


    function Open (Path : String;
                   Mode : File_Mode := In_Out_File;
                   Sharing : Sharing_Mode := Not_Shared;
                   Io_Kind : Io_Type := Text_File) return File_Id;
    -- ------------------------------------------------------------------------
    -- Opens an external file of the (absolute) name  'PATH'  in  mode  'MODE'.
    -- The (user-defined) file identifier will be used to designate  this  file
    -- for any further operations until the file's closure.
    -- ------------------------------------------------------------------------


    procedure Close (Id : in out File_Id);
    -- ------------------------------------------------------------------------
    -- Closes the given file, releasing its user-defined identifier
    -- ------------------------------------------------------------------------


    procedure Delete (Path : String);
    -- ------------------------------------------------------------------------
    -- Deletes the file with the (absolute) name 'PATH'.
    -- ------------------------------------------------------------------------


    procedure Reset (Id : File_Id; New_Mode : File_Mode);
    -- ------------------------------------------------------------------------
    -- Resets the given file. The current index is  set  to  1  (to  point  the
    -- first item) and the given mode is installed (if not already done)
    -- ------------------------------------------------------------------------



    -- 3. File attributes


    function Device (Id : File_Id) return File_Type;
    -- ------------------------------------------------------------------------
    -- Returns the kind of device implementing the given file
    -- ------------------------------------------------------------------------


    function Can_Be_Deleted (Id : File_Id) return Boolean;
    -- ------------------------------------------------------------------------
    -- Decides whether the implementation supports deletion of the given file
    -- ------------------------------------------------------------------------


    function Can_Be_Reset (Id : File_Id; New_Mode : File_Mode) return Boolean;
    -- ------------------------------------------------------------------------
    -- Decides whether the implementation supports  resetting  the  given  file
    -- and deletion of the given file can be acceeded in mode 'NEW_MODE'
    -- ------------------------------------------------------------------------


    function Size (Id : File_Id) return Long_Natural;
    -- ------------------------------------------------------------------------
    -- Returns the file's size (in bytes)
    -- ------------------------------------------------------------------------


    procedure Get_Identification (Id : File_Id; Ident : Identification);
    -- ------------------------------------------------------------------------
    -- Returns the file's identification in ident.all
    -- Note: must raise NAME_ERROR if the file does not exist.
    -- ------------------------------------------------------------------------


    procedure Get_Identification (Path : String; Ident : Identification);
    -- ------------------------------------------------------------------------
    -- Returns the file's identification in ident.all
    -- Note: must raise NAME_ERROR if the file does not exist.
    -- ------------------------------------------------------------------------


    function Is_Regular (Id : File_Id) return Boolean;
    -- ------------------------------------------------------------------------
    -- Indicates whether a file is "regular" or not. Regular means that the
    -- file can be buffered and can be accessed backward (ex. a terminal or a
    -- pipe is not "regular").
    -- ------------------------------------------------------------------------



    -- 4. Data transfer


    procedure Set_Index (Id : File_Id; Index : File_Index);
    -- ------------------------------------------------------------------------
    -- Moves the current index to the given location
    -- ------------------------------------------------------------------------


    procedure Input (Id : in File_Id;
                     Data_Address : in System.Address;
                     To_Read : in Long_Natural;
                     Read : out Long_Natural);
    -- ------------------------------------------------------------------------
    -- Fills buffer at DATA_ADDRESS with bytes (or characters) read from the
    -- file's current index. READ is the number of bytes actually read.
    -- ------------------------------------------------------------------------


    procedure Output (Id : in File_Id;
                      Data_Address : in System.Address;
                      To_Send : in Long_Natural;
                      Sent : out Long_Natural);
    -- ------------------------------------------------------------------------
    -- Outputs all the bytes (or characters) stored at DATA_ADDRESS to the
    -- given file at the current location. SENT is the number of bytes
    -- actually written.
    -- ------------------------------------------------------------------------



    -- 5. Operations on identification type.


    function Allocate_Identification return Identification;
    -- ------------------------------------------------------------------------
    -- Allocates space for identification variable.
    -- ------------------------------------------------------------------------


    procedure Free_Identification (Ident : in Identification);
    -- ------------------------------------------------------------------------
    -- Free space.
    -- ------------------------------------------------------------------------


    procedure Copy (From : in Identification; To : in Identification);
    -- ------------------------------------------------------------------------
    -- Do TO.all := FROM.all
    -- ------------------------------------------------------------------------


    function "=" (Left, Right : in Identification) return Boolean;
    -- ------------------------------------------------------------------------
    --  Test if 2 objects of identification type are equal or not.
    -- ------------------------------------------------------------------------


private


    type File_Descriptor;
    -- This type has to be fully declared in the package body.

    type File_Id is access File_Descriptor;

    type File_Identification;
    -- This type has to be fully declared in the package body.

    type Identification is access File_Identification;

end User_Io;
DataMuseum.dk

Rational R1000/400 Tapes

⟦cf99738d3⟧ TextFile

Derivation

TextFile
