gm2-libs/FIO (The GNU Modula-2 Compiler)

#### 4.1.14 gm2-libs/FIO ¶

    DEFINITION MODULE FIO ;

    (* Provides a simple buffered file input/output library.  *)

    FROM SYSTEM IMPORT ADDRESS, BYTE ;

    EXPORT QUALIFIED (* types *)
                     File,
                     (* procedures *)
                     OpenToRead, OpenToWrite, OpenForRandom, Close,
                     EOF, EOLN, WasEOLN, IsNoError, Exists, IsActive,
                     exists, openToRead, openToWrite, openForRandom,
                     SetPositionFromBeginning,
                     SetPositionFromEnd,
                     FindPosition,
                     ReadChar, ReadString,
                     WriteChar, WriteString, WriteLine,
                     WriteCardinal, ReadCardinal,
                     UnReadChar,
                     WriteNBytes, ReadNBytes,
                     FlushBuffer,
                     GetUnixFileDescriptor,
                     GetFileName, getFileName, getFileNameLength,
                     FlushOutErr,
                     (* variables *)
                     StdIn, StdOut, StdErr ;

    TYPE
       File = CARDINAL ;

    (* the following variables are initialized to their UNIX equivalents *)
    VAR
       StdIn, StdOut, StdErr: File ;

    (*
       IsNoError - returns a TRUE if no error has occured on file, f.
    *)

    PROCEDURE IsNoError (f: File) : BOOLEAN ;

    (*
       IsActive - returns TRUE if the file, f, is still active.
    *)

    PROCEDURE IsActive (f: File) : BOOLEAN ;

    (*
       Exists - returns TRUE if a file named, fname exists for reading.
    *)

    PROCEDURE Exists (fname: ARRAY OF CHAR) : BOOLEAN ;

    (*
       OpenToRead - attempts to open a file, fname, for reading and
                    it returns this file.
                    The success of this operation can be checked by
                    calling IsNoError.
    *)

    PROCEDURE OpenToRead (fname: ARRAY OF CHAR) : File ;

    (*
       OpenToWrite - attempts to open a file, fname, for write and
                     it returns this file.
                     The success of this operation can be checked by
                     calling IsNoError.
    *)

    PROCEDURE OpenToWrite (fname: ARRAY OF CHAR) : File ;

    (*
       OpenForRandom - attempts to open a file, fname, for random access
                       read or write and it returns this file.
                       The success of this operation can be checked by
                       calling IsNoError.
                       towrite, determines whether the file should be
                       opened for writing or reading.
                       newfile, determines whether a file should be
                       created if towrite is TRUE or whether the
                       previous file should be left alone,
                       allowing this descriptor to seek
                       and modify an existing file.
    *)

    PROCEDURE OpenForRandom (fname: ARRAY OF CHAR;
                             towrite, newfile: BOOLEAN) : File ;

    (*
       Close - close a file which has been previously opened using:
               OpenToRead, OpenToWrite, OpenForRandom.
               It is correct to close a file which has an error status.
    *)

    PROCEDURE Close (f: File) ;

    (* the following functions are functionally equivalent to the above
       except they allow C style names.
    *)

    PROCEDURE exists        (fname: ADDRESS; flength: CARDINAL) : BOOLEAN ;
    PROCEDURE openToRead    (fname: ADDRESS; flength: CARDINAL) : File ;
    PROCEDURE openToWrite   (fname: ADDRESS; flength: CARDINAL) : File ;
    PROCEDURE openForRandom (fname: ADDRESS; flength: CARDINAL;
                             towrite, newfile: BOOLEAN) : File ;

    (*
       FlushBuffer - flush contents of the FIO file, f, to libc.
    *)

    PROCEDURE FlushBuffer (f: File) ;

    (*
       ReadNBytes - reads nBytes of a file into memory area, dest, returning
                    the number of bytes actually read.
                    This function will consume from the buffer and then
                    perform direct libc reads. It is ideal for large reads.
    *)

    PROCEDURE ReadNBytes (f: File; nBytes: CARDINAL;
                          dest: ADDRESS) : CARDINAL ;

    (*
       ReadAny - reads HIGH (a) + 1 bytes into, a.  All input
                 is fully buffered, unlike ReadNBytes and thus is more
                 suited to small reads.
    *)

    PROCEDURE ReadAny (f: File; VAR a: ARRAY OF BYTE) ;

    (*
       WriteNBytes - writes nBytes from memory area src to a file
                     returning the number of bytes actually written.
                     This function will flush the buffer and then
                     write the nBytes using a direct write from libc.
                     It is ideal for large writes.
    *)

    PROCEDURE WriteNBytes (f: File; nBytes: CARDINAL;
                           src: ADDRESS) : CARDINAL ;

    (*
       WriteAny - writes HIGH (a) + 1 bytes onto, file, f.  All output
                  is fully buffered, unlike WriteNBytes and thus is more
                  suited to small writes.
    *)

    PROCEDURE WriteAny (f: File; VAR a: ARRAY OF BYTE) ;

    (*
       WriteChar - writes a single character to file, f.
    *)

    PROCEDURE WriteChar (f: File; ch: CHAR) ;

    (*
       EOF - tests to see whether a file, f, has reached end of file.
    *)

    PROCEDURE EOF (f: File) : BOOLEAN ;

    (*
       EOLN - tests to see whether a file, f, is about to read a newline.
              It does NOT consume the newline.  It reads the next character
              and then immediately unreads the character.
    *)

    PROCEDURE EOLN (f: File) : BOOLEAN ;

    (*
       WasEOLN - tests to see whether a file, f, has just read a newline
                 character.
    *)

    PROCEDURE WasEOLN (f: File) : BOOLEAN ;

    (*
       ReadChar - returns a character read from file, f.
                  Sensible to check with IsNoError or EOF after calling
                  this function.
    *)

    PROCEDURE ReadChar (f: File) : CHAR ;

    (*
       UnReadChar - replaces a character, ch, back into file, f.
                    This character must have been read by ReadChar
                    and it does not allow successive calls.  It may
                    only be called if the previous read was successful,
                    end of file or end of line seen.
    *)

    PROCEDURE UnReadChar (f: File ; ch: CHAR) ;

    (*
       WriteLine - writes out a linefeed to file, f.
    *)

    PROCEDURE WriteLine (f: File) ;

    (*
       WriteString - writes a string to file, f.
    *)

    PROCEDURE WriteString (f: File; a: ARRAY OF CHAR) ;

    (*
       ReadString - reads a string from file, f, into string, a.
                    It terminates the string if HIGH is reached or
                    if a newline is seen or an error occurs.
    *)

    PROCEDURE ReadString (f: File; VAR a: ARRAY OF CHAR) ;

    (*
       WriteCardinal - writes a CARDINAL to file, f.
                       It writes the binary image of the CARDINAL.
                       to file, f.
    *)

    PROCEDURE WriteCardinal (f: File; c: CARDINAL) ;

    (*
       ReadCardinal - reads a CARDINAL from file, f.
                      It reads a bit image of a CARDINAL
                      from file, f.
    *)

    PROCEDURE ReadCardinal (f: File) : CARDINAL ;

    (*
       GetUnixFileDescriptor - returns the UNIX file descriptor of a file.
                               Useful when combining FIO.mod with select
                               (in Selective.def - but note the comments in
                                Selective about using read/write primatives)
    *)

    PROCEDURE GetUnixFileDescriptor (f: File) : INTEGER ;

    (*
       SetPositionFromBeginning - sets the position from the beginning
                                  of the file.
    *)

    PROCEDURE SetPositionFromBeginning (f: File; pos: LONGINT) ;

    (*
       SetPositionFromEnd - sets the position from the end of the file.
    *)

    PROCEDURE SetPositionFromEnd (f: File; pos: LONGINT) ;

    (*
       FindPosition - returns the current absolute position in file, f.
    *)

    PROCEDURE FindPosition (f: File) : LONGINT ;

    (*
       GetFileName - assigns, a, with the filename associated with, f.
    *)

    PROCEDURE GetFileName (f: File; VAR a: ARRAY OF CHAR) ;

    (*
       getFileName - returns the address of the filename associated with, f.
    *)

    PROCEDURE getFileName (f: File) : ADDRESS ;

    (*
       getFileNameLength - returns the number of characters associated with
                           filename, f.
    *)

    PROCEDURE getFileNameLength (f: File) : CARDINAL ;

    (*
       FlushOutErr - flushes, StdOut, and, StdErr.
    *)

    PROCEDURE FlushOutErr ;

    END FIO.