home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / languages / turbo_part1.lha / modula / m2 / FIO.def < prev    next >
Encoding:
Modula Definition  |  1994-12-28  |  9.8 KB  |  365 lines
  1. (* The REAL & LONGREAL functions (WriteReal etc) requice 'C' floating point *)
  2. (* so will not work with the unregisterd version of DICE                    *)
  3. (* If you have the registered version of DICE then you must                 *)
  4. (* link with the math library, either:                                *)
  5. (* m2l x -lm or m2b x -lm , alternatively set -lm in the DCCOPTS env var    *)
  6. (* This is only required if you use the floating point functions:           *)
  7. (* If you only use WriteChar etc, you dont need to link the math library    *)
  8.  
  9. DEFINITION MODULE FIO ;
  10. (*
  11.  *    Simple but flexible File based I/O system
  12.  *
  13.  *    This module provides a collection of procedures to perform
  14.  *    I/O operations on text files. File access can be sequential
  15.  *      or random.
  16.  *      The following table states the operations that may be applied
  17.  *      according to the file's access mode.
  18.  *
  19.  *                          OPERATIONS
  20.  *
  21.  *                  Rewind    Set &    EOF &    Reads    Writes
  22.  *            ------    FindPos    EOLN    -----    ------
  23.  *                -------    ----
  24.  *      MODE:
  25.  *    Read        y        y    y
  26.  *    Write                        y
  27.  *    Random        y    y    y    y    y
  28.  *)
  29.  
  30.  
  31. FROM SYSTEM IMPORT ADDRESS ;
  32.  
  33. CONST
  34.   TabCh     = "\t" ;    (* some useful character constants  *)
  35.   NewLineCh = "\n" ;    (* shouldn't really be here at all! *)
  36.   SpaceCh   = " "  ;
  37.  
  38.   MaxFiles     = 20 ;    (* open simulataneously *)
  39.   MaxFileName = 500 ;    (* length of filename   *)
  40.  
  41. TYPE
  42.   File     = LONGINT ;        (* a file descriptor: treat this as OPAQUE *)
  43.  
  44.   FileName = ARRAY [0..MaxFileName] OF CHAR ;
  45.  
  46.   Status   = ( UnInitialized, NoError, CantOpenFile, CantCreateFile,
  47.            TooManyOpen, OpFailed, Overflow ) ;
  48.  
  49.   EndType  = ( FromStart, FromCurrent, AddToEnd ) ;
  50.  
  51.   BufferingMode = ( NoBuffer, LineBuffer, FullBuffer ) ;
  52.  
  53. VAR
  54.   StdIn, StdOut, StdErr : File ;
  55.  
  56. (* ------------------------- Error Procedures ------------------------- *)
  57.  
  58. PROCEDURE IOStatus( id : File ) : Status ;
  59.  
  60. (*
  61.  * Task:    find out the status of the last IO operation
  62.  *        on the given file..
  63.  * Returns:    the status
  64.  *)
  65.  
  66.  
  67. PROCEDURE ReportError( id : File ) ;
  68.  
  69. (*
  70.  * Task:    If the last IO operation on the given file failed,
  71.  *        generate a suitable error message and HALT
  72.  * Returns:    Only if the last IO operation was a success.
  73.  *)
  74.  
  75.  
  76. (* -------------------------- Open Procedures ------------------------- *)
  77.  
  78.  
  79. PROCEDURE OpenToRead( extName : ARRAY OF CHAR ) : File ;
  80.  
  81. (*
  82.  * Task:    open a file for reading
  83.  * Returns:    the file descriptor for further use.
  84.  * Status:    NoError if success.
  85.  *        CantOpenFile if failure.
  86.  *)
  87.  
  88.  
  89. PROCEDURE OpenToWrite( extName : ARRAY OF CHAR ) : File ;
  90.  
  91. (*
  92.  * Task:    open a file for writing
  93.  * Returns:    the file descriptor for further use.
  94.  * Status:    NoError if success.
  95.  *        CantCreateFile if failure.
  96.  *)
  97.  
  98.  
  99. PROCEDURE OpenForRandom( extName : ARRAY OF CHAR ; Create : BOOLEAN ) : File ;
  100.  
  101. (*
  102.  * Task:    open a file for random access, creating it [erasing any
  103.  *        previous contents] if Create is set, otherwise leaving
  104.  *        the previous data available for reading.
  105.  * Returns:    the file descriptor for further use.
  106.  * Status:    NoError if success
  107.  *        else:    CantCreateFile if Create
  108.  *            CantOpenFile otherwise
  109.  *)
  110.  
  111. PROCEDURE SetBuffer( file : File ;
  112.              mode : BufferingMode ;
  113.              size : LONGINT ;
  114.              buff : ADDRESS ) ;
  115. (*
  116.  * Task:    Controls file buffering.
  117.  *            mode:
  118.  *            FullBuffer: output flushed only if buffer full
  119.  *            LineBuffer: output flushed every newline
  120.  *            NoBuffer  : no buffering at all
  121.  *        Default mode is line buffering.
  122.  *            For mode = NoBuffer the buf and size arguments should be passed
  123.  *            as NIL & 0.
  124.  *        For other modes, if buff is not NIL then the first size bytes
  125.  *        of buff are used as the file buffer otherwise the buffer will be
  126.  *        allocated for you.
  127.  *        If buffering is turned on/off for a file representing a
  128.  *        console device, the console device is set to buffered/unbuffered
  129.  *        as well. ie raw/cooked.
  130.  *
  131.  * Access-Mode:    Read,Write or Random
  132.  * Status:    NoError if success
  133.  *        OpFailed otherwise.
  134.  *)
  135.  
  136. (* ------------------------- Other Procedures ------------------------- *)
  137.  
  138. (*
  139.  * Notes about the remaining functions:
  140.  *    1).    They will call ReportError [and thus HALT] when given a file
  141.  *        that has not been sussessfully opened in the correct mode.
  142.  *
  143.  *    2).    However, if they themselves fail, they will set
  144.  *        the error status and return painlessly..
  145.  *)
  146.  
  147.  
  148. PROCEDURE Close( id : File ) ;
  149.  
  150. (* Task:    to close the given file (if the file has been opened
  151.  *        successfully, this cannot fail).
  152.  * Access-Mode:    Read, Write or Random
  153.  * Status:    Unitialized
  154.  *)
  155.  
  156.  
  157. PROCEDURE FlushFile( f : File ) ;
  158.  
  159. (* Task:    to flush the given file - force any pending output
  160.  *        to leave the buffer and appear on the screen/physical
  161.  *        file (if the file has been opened successfully, this
  162.  *        cannot fail).
  163.  * Access-Mode:    Read, Write or Random
  164.  * Status:    unchanged
  165.  *)
  166.  
  167.  
  168. PROCEDURE EOF( id : File ) : BOOLEAN ;
  169.  
  170. (*
  171.  * Task:    Finds out whether the end-of-file has been reached
  172.  *        on the given file
  173.  * Returns:    TRUE if so.
  174.  * Access-Mode:    Read or Random
  175.  * Status:    NoError
  176.  *)
  177.  
  178.  
  179. PROCEDURE EOLN( id : File ) : BOOLEAN ;
  180.  
  181. (*
  182.  * Task:    Finds out whether an end-of-line has been reached on the
  183.  *        current file
  184.  * Returns:    True if so.
  185.  * Access-Mode:    Read or Random
  186.  * Status:    NoError
  187.  *)
  188.  
  189. (* --------------------- Read <object> Procedures --------------------- *)
  190.  
  191. (*
  192.  * Task:        read an object [of some type]
  193.  * Returns:        the next object of the appropriate type.
  194.  * Access-Mode:        Read or Random
  195.  * NOTE:        ReadString discards leading whitespace,
  196.  *            then reads characters up to the next whitespace
  197.  *            (which is pushed back and left).
  198.  *            ReadLn discards NOTHING: reads the whole rest of line,
  199.  *            discarding the newline itself.
  200.  * Status:        NoError if success,
  201.  *            OpFailed otherwise.
  202.  * NOTE:        Any of these will abort if they encounter premature
  203.  *            EOF.
  204.  *)
  205.  
  206.  
  207. PROCEDURE ReadInteger( id : File ) : LONGINT ;
  208. PROCEDURE ReadReal( id : File ) : REAL ;
  209. PROCEDURE ReadLongReal( id : File ) : LONGREAL ;
  210. PROCEDURE ReadChar( id : File ) : CHAR ;
  211. PROCEDURE ReadString( id : File ; VAR object : ARRAY OF CHAR ) ;
  212. PROCEDURE ReadLn( f : File ; VAR s : ARRAY OF CHAR ) ;
  213. PROCEDURE ReadLine( id : File ) ;
  214.  
  215.  
  216. (* -------------------- Write <object> Procedures --------------------- *)
  217.  
  218. (*
  219.  * Task:        Write an object [of some type] to the given file
  220.  * NOTE:        WriteLn simply writes the given message and then
  221.  *            a newline
  222.  * Access-Mode:        Write or Random
  223.  * Status:        NoError if success,
  224.  *            OpFailed otherwise.
  225.  *)
  226.  
  227.  
  228. PROCEDURE WriteInteger( id : File ; object : LONGINT ) ;
  229. PROCEDURE WriteReal( id : File ; object : REAL ) ;
  230. PROCEDURE WriteLongReal( id : File ; object : LONGREAL ) ;
  231. PROCEDURE WriteChar( id : File ; object : CHAR ) ;
  232. PROCEDURE WriteString( id : File ; object : ARRAY OF CHAR ) ;
  233. PROCEDURE WriteLn( f : File ; s : ARRAY OF CHAR ) ;
  234. PROCEDURE WriteLine( id : File ) ;
  235.  
  236.  
  237. (* -------------------- Random Access Procedures ---------------------- *)
  238.  
  239.  
  240. PROCEDURE SetPosition( id : File ; pos : LONGINT ; end : EndType ) ;
  241.  
  242. (*
  243.  * Task:    position the file pointer on a random access file.
  244.  * Receives:    the file, id, the position, Pos [measured in bytes],
  245.  *        and an indicator of from which end the position is
  246.  *        measured.
  247.  * Access-Mode:    Random
  248.  * Status:    NoError if success,
  249.  *        OpFailed otherwise.
  250.  *)
  251.  
  252.  
  253. PROCEDURE FindPosition( id : File ) : LONGINT ;
  254.  
  255. (*
  256.  * Task:    shows the user the current position in a random access file.
  257.  * Receives:    the file, id.
  258.  * Returns:    the current position
  259.  * Access-Mode:    Random
  260.  * Status:    NoError.
  261.  *)
  262.  
  263.  
  264. PROCEDURE Rewind( id : File ) ;
  265.  
  266. (*
  267.  * Task:    rewind the given file.
  268.  * Access-Mode:    Read or Random
  269.  * Status:    NoError if success,
  270.  *        OpFailed otherwise.
  271.  *)
  272.  
  273.  
  274. (* ---------------------- Miscellaneous procedures -------------------- *)
  275.  
  276.  
  277. PROCEDURE SkipBlanks( f : File ) ;
  278.  
  279. (*
  280.  * Task:    skip all leading blanks (spaces or tabs - not newlines)
  281.  *        from the given file.
  282.  *)
  283.  
  284.  
  285. PROCEDURE SkipWS( f : File ) ;
  286.  
  287. (*
  288.  * Task:    Skip all whitespace (spaces, tabs and newlines)..
  289.  *)
  290.  
  291.  
  292. PROCEDURE EOFAfterWS( f : File ) : BOOLEAN ;
  293.  
  294. (*
  295.  * Task:    Skip whitespace and then; is the file at EOF?
  296.  *)
  297.  
  298.  
  299. PROCEDURE UnReadChar( id : File ; c : CHAR ) ;
  300.  
  301. (*
  302.  * Task:    push the given character back onto the given input file
  303.  * Receives:    the file id and the character to push back..
  304.  * Access-Mode:    Read or Random
  305.  * Status:    NoError.
  306.  *)
  307.  
  308.  
  309. PROCEDURE ReadNBytes( file : File ; n : LONGINT ; buffer : ADDRESS ) ;
  310.  
  311. (*
  312.  * Task:    read N bytes from the given file, into the area of memory
  313.  *        starting at Buffer.
  314.  * Suggestion:    use SIZE(var) and ADR(var) when calling
  315.  * Access-Mode:    Read or Random
  316.  * Status:    NoError if success,
  317.  *        OpFailed otherwise.
  318.  * NOTE:    This will abort if it encounters a premature EOF.
  319.  *)
  320.  
  321.  
  322. PROCEDURE WriteNBytes( file : File ; n : LONGINT ; buffer : ADDRESS ) ;
  323.  
  324. (*
  325.  * Task:    Write N bytes to the given file, into the area of memory
  326.  *        starting at Buffer.
  327.  * Suggestion:    use SIZE(var) and ADR(var) when calling
  328.  * Access-Mode:    Write or Random
  329.  * Status:    NoError if success,
  330.  *        OpFailed otherwise.
  331.  *)
  332.  
  333.  
  334. PROCEDURE WriteRealFmt( file : File ; r : REAL ; width, decplaces : LONGINT ) ;
  335.  
  336. (* Task:    writes the given real to the given file, formatting the value
  337.  *        so that it is right justified in a field of the given width,
  338.  *        and contains the given number of decimal places.
  339.  * Access-Mode:    Write or Random
  340.  * Status:    NoError if success,
  341.  *        OpFailed otherwise.
  342.  *)
  343.  
  344.  
  345. PROCEDURE WriteLongRealFmt( file : File ; r : LONGREAL ;
  346.                 width, decplaces : LONGINT ) ;
  347.  
  348. (* Task:    writes the given longreal to the given file, formatting the
  349.  *        value so that it is right justified in a field of the given
  350.  *        width, and contains the given number of decimal places.
  351.  * Access-Mode:    Write or Random
  352.  * Status:    NoError if success,
  353.  *        OpFailed otherwise.
  354.  *)
  355.  
  356. (*------- Some useful functions that shouldn't really be here either ---------*)
  357.  
  358. PROCEDURE Delete( name : ARRAY OF CHAR ) : BOOLEAN ;
  359. (* Status: Returns TRUE on success, FALSE otherwise *)
  360.  
  361. PROCEDURE Rename( from, to : ARRAY OF CHAR ) : BOOLEAN ;
  362. (* Status: Returns TRUE on success, FALSE otherwise *)
  363.  
  364. END FIO.
  365.