Modula-2 Reloaded

A Modern Typesafe & Literate Programming Notation

Site Menu

Project

Specification

Implementation

Recommendations

Reference

Needs Updating

Work in Progress

Wastebasket

Wiki Manual

edit SideBar

Spec ⋄ File

File

Spec.File History

Hide minor edits - Show changes to output

2010-01-09 15:23 by benjk -
Changed lines 3-4 from:
(* 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. *)
to:
(* 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. *)
Changed line 40 from:
    echoFlag         (* echoing to StdIO.StdOutFile () on reading requested/applies if his flag is presdent *)
to:
    echoFlag         (* echoing to StdIO.StdOutFile () on reading requested/applies if his flag is present *)
Changed lines 60-63 from:
(* 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" *)
to:
(* 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" *)
Changed lines 77-78 from:
  (* 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 *)
to:
  (* 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 *)
Changed lines 84-87 from:
(* 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. *)
to:
(* 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. *)
Changed lines 93-95 from:
(* If a file with the given name is accessible on the current device sets res to allRight otherwise to an appropriate error. *)
to:
(* If a file with the given name is accessible on the current device sets res to allRight
   otherwise to an appropriate error. *)
Changed lines 97-99 from:
  (* Deletes the file specified in 'filename'.  Use with caution! Sets res to allRight or an appropriate error. *)
to:
  (* Deletes the file specified in 'filename'.  Use with caution! Sets res to allRight
     or an appropriate error. *)
Changed lines 101-104 from:
  (* 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. *)
to:
  (* 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. *)
Added line 109:
Changed lines 113-114 from:
(* 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. *)
to:
(* 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. *)
Changed lines 120-128 from:
     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
    *)
to:
      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 *)
Changed lines 134-135 from:
     'write' and not 'old' implies that if the file does not exist, Create is called with the supplied parameters
to:
     'write' and not 'old' implies that if the file does not exist, Create is called with the supplied
   parameters
Changed lines 151-152 from:
(* The following procedures operate correctly only on files already opened. The File's status is set to allRight or notOpened or as noted below *)
to:
(* The following procedures operate correctly only on files already opened. The File's status is set
   to allRight or notOpened or as noted below *)
Changed lines 158-159 from:
  (* 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*)
to:
  (* 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*)
Changed lines 171-173 from:
  (* 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. *)
to:
  (* 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. *)
Changed lines 176-177 from:
  (* An attempt will be made to flush and close the  file specified. If successful, res is set to allRight; otherwise to an appropriate error *)
to:
  (* An attempt will be made to flush and close the  file specified. If successful, res is set to
     allRight; otherwise to an appropriate error *)
Changed lines 181-183 from:
  (* 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. *)
to:
  (* 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. *)
Changed lines 186-187 from:
  (* 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. *)
to:
  (* 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. *)
Restore
2010-01-09 15:14 by benjk - imported from Rick's email of Jan 8, 2010
Added lines 1-162:
[@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 presdent *)
    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.@]
Restore