DEFINITION MODULE File;

(* Part one: These types, values, and procedures relate to program entities, i.e. logical files.
    The effect on any physical files depends on program logic and the operating system. *)

(* Types and values for files, open requests and modes *)
TYPE
  File : OPAQUE;
  FileStatus =
         (* This type is used to classify the result of the last operation on a file *)
   (notKnown       (* no result is set *)
    allRight,      (* last operation on the file worked *)
    badName,       (* an illegal file name was used: perhaps too long, or contains a colon *)
    tooManyOpen,   (* tried to open more than an implementation defined maximum number of files*)
    fileLocked     (* permissions or locking on file or directory do not allow request made *)
    noDialogs      (* dialog boxes were requested but are not available *)
    noSuchFile,    (* a needed file does not exist *)
    fileExists,    (* a file of the given name already exists when a new one is required *)
    fileBusy,      (* the file is already open *)
    notOpen,       (* attempt to access a file not open *)
    deviceFull,    (* there is no more room on the disk *)
    deviceErr,     (* other device error such as media is corrupted *)
    outOfRange,    (* data cannot be represented *)
    wrongFormat,   (* data not in expected format *)
    endOfLine,     (* end of line seen before expected data *)
    endOfFile,     (* end of input seen before expected data or attempt to set FilePos past end of file *)
    otherErr);     (* one of the rarer errors has occurred *)

PROCEDURE FileState (fid: File): FileStatus;
  (* Returns the result for the last operation on fid. *)

PROCEDURE ResetState (fid: File);
  (* Sets the FileStatus for fid to allRight *)

TYPE
  FileFlags =        (* Request flags possibly given when a file is opened *)
  ( readFlag,        (* input operations are requested/available *)
    writeFlag,       (* output operations are requested/available *)
    oldFlag,         (* a file may/must/did exist before we try to open it *)
    echoFlag         (* echoing to StdIO.StdOutFile () on reading requested/applies if his flag is present *)
    dialogFlag       (* use of dialog boxes in creating or opening file is requested *)
  );
 
  FlagSet = SET OF FileFlags;
 
  (* Singleton values of FlagSet, to allow for example, read + old *)
CONST
  read = FlagSet{readFlag};
  write = FlagSet{writeFlag};
  readwrite = read + write;
  old = FlagSet{oldFlag};
  echo = FlagSet{echoFlag};
  dialog = FlagSet{dialogFlag};   

(* Following are for random access file support *)
TYPE
  FilePos = OPAQUE;
  InvalidPos : FilePos;

(* If the file in the following procedures is not open, or if an invalid computation is done
   (a FilePos variable cannot store the value computed, then the FilePos variable returned
   will have the value "invalidPos" *)

PROCEDURE StartPos (fid: File): FilePos;
  (* returns the position of the start of the file.   *)
 
PROCEDURE CurrentPos (fid: File): FilePos;
  (* returns the position of the current read/write position.  *)

PROCEDURE NextPos (fid: File): FilePos;
  (* returns the first position after which there have been no writes.  *)

PROCEDURE NewPos (fid: File; chunks: INTEGER; chunkSize: CARDINAL; from: FilePos): FilePos;
  (* returns the position (chunks * chunkSize) relative to the position given by from  *)

PROCEDURE SetPos (fid: File; pos: FilePos);
  (* sets the read/write position to the value given by pos. The fid.FileState is set to allRight
      or to endOfFile if pos is beyond the end of the file *)

PROCEDURE SetEnd (fid: File; pos: FilePos);
  (* Does SetPos (fid, EndPos (fid))  *)

(* ======================== *)
(* Part Two: These types, values, and procedures relate to physical file entities, typically
   recordings in an implementation defined format on some external channel or device.
   While they may share the use of variable types from the above section, they do not
   otherwise affect program state with respect to logical files *)

 (* The following three procedures attempt to operate on files available on the current
     device and specified by name only. *)

PROCEDURE Lookup (filename : ARRAY OF CHAR; VAR res : FileStatus);
(* If a file with the given name is accessible on the current device sets res to allRight
    otherwise to an appropriate error. *)

PROCEDURE Delete (filename : ARRAY OF CHAR; VAR res : FileStatus));
  (* Deletes the file specified in 'filename'.  Use with caution! Sets res to allRight
      or an appropriate error. *)

PROCEDURE Rename (oldname, newname : ARRAY OF CHAR; VAR res : FileStatus));
  (* Renames the file specified by 'oldname' as specified by 'newname'. Sets res to
      allRight or an appropriate error. *)

(* The following two procedures are optional. If they are supplied and used, new files
    created  here will have the supplied creator and/or type, as applicable. Before either
    are set by a user of this module, they will have an implementation defined initial value. *)

PROCEDURE SetCreator (creator: ARRAY OF CHAR);

PROCEDURE SetType (type: ARRAY OF CHAR);

(* ======================== *)
(* Part Three: These types, values, and procedures relate to the connections between
    physical file entities, typically recordings in an implementation defined format on
    some external channel or device, and logical files, i.e. program entities, and may
    affect the state of both. *)

PROCEDURE Create (VAR filename : ARRAY OF CHAR; flags: FlagSet; VAR res : FileStatus);
  (* Attempts to create a new, empty file in the current directory.
      The new file will be named as specified in 'name'
      If creators and types are applicable and set, they will be used
      Independently, if a file extension is desired, it must be included in the name
      e.g. Myfile.txt. A newly created file must still be opened to be used.
      The standard dialog is used if dialogFlag is passed or if the filename passed is
      an empty string. In the latter case, the actual filename opened by the user is passed
      back in filename. res is set accordingly *)

PROCEDURE Open (VAR fid : File; flags: FlagSet; VAR filename : ARRAY OF CHAR; VAR res : FileStatus);
  (* Attempts to open a file in the current directory.
     The file whose name is specified in 'filename' will be opened.
     'file' is set to refer to the opened file.
     'read' implies 'old'. If successful, the reading position will be the start of the file.
     'old' implies the file must exist
     'write' and not 'old' implies that if the file does not exist, Create is called with the supplied
     parameters
     'write' and not 'read' implies that any information previously stored in an existing file will be lost.
     The standard dialog is used if dialogFlag is passed or if the filename passed is an empty string.
     res is set accordingly
     *)

PROCEDURE OpenAppend (VAR fid : File; flags: FlagSet; VAR filename : ARRAY OF CHAR; VAR res : FileStatus);
  (* Attempts to open a file in the current directory.
     The file whose name is specified in 'filename' will be opened.
     'file' is set to refer to the opened file
     'old' and 'write' are implied; the file must exist
     information previously stored in the file is retained and the writing position is set to the end of the file
     The standard dialog is used if dialogFlag is passed or if the filename passed is an empty string.
     res is set accordingly
     *)

(* The following procedures operate correctly only on files already opened. The File's status is set
    to allRight or notOpened or as noted below *)

PROCEDURE GetName (fid: File; VAR filename : ARRAY OF CHAR);
  (* Returns the name of the file that was used when it was opened. *)

PROCEDURE Eof (fid : File) : BOOLEAN;
  (* Returns TRUE if the file position is at or past logical EOF. The return result is defined only if
      the error  state is FileOK or endOfInput*)

PROCEDURE FileFlags (fid : File) : FlagSet;
  (* Returns the current flags on this file *)

PROCEDURE SetFlags (fid : File; flags : FlagSet);
  (* Sets the current flags on this file *)

PROCEDURE ResetFlags (fid : File);
  (* Resets the current flags on this file to what they were when it was opened*)
 
PROCEDURE Flush (fid : File);
  (* Any file buffer for the file will have its data written out to the device, but the file will
      remain open There is no guarantee that any data for a file has been written to the disk
      until the associated volume has been flushed, either by this procedure or by closing the file. *)

PROCEDURE Close (fid : File; VAR res : FileStatus);
  (* An attempt will be made to flush and close the  file specified. If successful, res is set to
      allRight; otherwise to an appropriate error *)

(* Following give very low level IO *)
PROCEDURE Look (fid : File; VAR b: SYSTEM.BYTE; VAR res: FileStatus);
  (* If there is a byte as the next item in the input stream fid, assigns its value to b without
      removing it from the stream; otherwise the value of b is not defined.  res is set to the
      value allRight, endOfLine, or endOfInput. *)
 
PROCEDURE Skip (fid : File);
  (* If the input file fid is not at the end of the file, the next byte or line mark in fid is removed,
      and the stored FileStatus is set to the value allRight; otherwise it is set to endOfFile. *)

END File.