lang/m2/libm2/Streams.def

   1 DEFINITION MODULE Streams;
   2 (*
   3   Module:       Stream Input/Output
   4   Author:       Ceriel J.H. Jacobs
   5   Version:      $Id: Streams.def,v 1.4 1994/06/24 12:49:54 ceriel Exp $
   6
   7  * This module provides sequential IO through streams.
   8  * A stream is either a text stream or a binary stream, and is either in
   9  * reading, writing or appending mode.
  10  * By default, there are three open text streams, connected to standard input,
  11  * standard output, and standard error respectively.
  12  * These are text streams.
  13  * When connected to a terminal, the standard output and standard error
  14  * streams are linebuffered.
  15  * The user can create more streams with the OpenStream call, and
  16  * delete streams with the CloseStream call.
  17  * Streams are automatically closed at program termination.
  18  *)
  19
  20   FROM SYSTEM IMPORT BYTE;
  21
  22   TYPE  StreamKind = (text, binary, none);
  23         StreamMode = (reading, writing, appending);
  24         StreamResult = (succeeded, illegaloperation,
  25                         nomemory, openfailed, nostream, endoffile);
  26         StreamBuffering = (unbuffered, linebuffered, blockbuffered);
  27   TYPE  Stream;
  28
  29   VAR   InputStream, OutputStream, ErrorStream: Stream;
  30
  31   PROCEDURE OpenStream(VAR stream: Stream;
  32                        filename: ARRAY OF CHAR;
  33                        kind: StreamKind;
  34                        mode: StreamMode;
  35                        VAR result: StreamResult);
  36   (* Associates a stream with the file named filename.
  37      If kind = none, result is set to illegaloperation.
  38      mode has one of the follwing values:
  39        reading:         the file is opened for reading
  40        writing:         the file is truncated or created for writing
  41        appending:       the file is opened for writing at end of file,
  42                         or created for writing.
  43      On failure, result is set to openfailed.
  44      On success, result is set to succeeded.
  45   *)
  46
  47   PROCEDURE SetStreamBuffering( stream: Stream;
  48                                 b: StreamBuffering;
  49                                 VAR result: StreamResult);
  50   (* This procedure is only allowed for output streams.
  51      The three types of buffering available are unbuffered, linebuffered,
  52      and blockbuffered. When an output stream is unbuffered, the output
  53      appears as soon as written; when it is blockbuffered, output is saved
  54      up and written as a block; When it is linebufferded (only possible for
  55      text output streams), output is saved up until a newline is encountered
  56      or input is read from standard input.
  57   *)
  58
  59   PROCEDURE CloseStream(VAR stream: Stream; VAR result: StreamResult);
  60   (* Closes the stream.
  61      result is set to nostream if "stream" was not associated with a stream.
  62   *)
  63
  64   PROCEDURE FlushStream(stream: Stream; VAR result: StreamResult);
  65   (* Flushes the stream.
  66      result is set to nostream if "stream" was not associated with a stream.
  67      It is set to illegaloperation if "stream" is not an output or
  68      appending stream.
  69   *)
  70
  71   PROCEDURE EndOfStream(stream: Stream; VAR result: StreamResult): BOOLEAN;
  72   (* Returns true if the stream is an input stream, and the end of the file
  73      has been reached.
  74      result is set to nostream if "stream" was not associated with a stream.
  75      It is set to illegaloperation if the stream is not an input stream.
  76   *)
  77
  78   PROCEDURE Read(stream: Stream; VAR ch: CHAR; VAR result: StreamResult);
  79   (* reads a character from the stream. Certain character translations may
  80      occur, such as the mapping of the end-of-line sequence to the
  81      character 12C.
  82      result is set to nostream if "stream" was not associated with a stream.
  83      It is set to endoffile if EndOfStream would have returned TRUE before the
  84      call to Read. In this case, "ch" is set to 0C.
  85      It is set to illegaloperation if the stream is not a text input stream.
  86   *)
  87
  88   PROCEDURE ReadByte(stream: Stream; VAR byte: BYTE; VAR result: StreamResult);
  89   (* reads a byte from the stream. No character translations occur.
  90      result is set to nostream if "stream" was not associated with a stream.
  91      It is set to endoffile if EndOfStream would have returned TRUE before the
  92      call to ReadByte. In this case, "byte" is set to 0C.
  93      It is set to illegaloperation if the stream is not a binary input stream.
  94   *)
  95
  96   PROCEDURE ReadBytes(stream: Stream;
  97                       VAR bytes: ARRAY OF BYTE;
  98                       VAR result: StreamResult);
  99   (* reads bytes from the stream. No character translations occur.
 100      The number of bytes is determined by the size of the parameter.
 101      result is set to nostream if "stream" was not associated with a stream.
 102      It is set to endoffile if there are not enough bytes left on the stream.
 103      In this case, the rest of the bytes are set to 0C.
 104      It is set to illegaloperation if the stream is not a binary input stream.
 105   *)
 106
 107   PROCEDURE Write(stream: Stream; ch: CHAR; VAR result: StreamResult);
 108   (* writes a character to the stream. Certain character translations may
 109      occur, such as the mapping of a line-feed or carriage return (12C or 15C)
 110      to the end-of-line sequence of the system.
 111      result is set to nostream if "stream" was not associated with a stream.
 112      It is set to illegaloperation if the stream is not a text output stream.
 113   *)
 114
 115   PROCEDURE WriteByte(stream: Stream; byte: BYTE; VAR result: StreamResult);
 116   (* writes a byte to the stream. No character translations occur.
 117      result is set to nostream if "stream" was not associated with a stream.
 118      It is set to illegaloperation if the stream is not a binary output stream.
 119   *)
 120
 121   PROCEDURE WriteBytes(stream: Stream;
 122                        bytes: ARRAY OF BYTE;
 123                        VAR result: StreamResult);
 124   (* writes bytes to the stream. No character translations occur.
 125      The number of bytes written is equal to the size of the parameter.
 126      result is set to nostream if "stream" was not associated with a stream.
 127      It is set to illegaloperation if the stream is not a binary output stream.
 128   *)
 129
 130   PROCEDURE GetPosition(stream: Stream;
 131                         VAR position: LONGINT;
 132                         VAR result: StreamResult);
 133   (* gives the actual read/write position in "position".
 134      "result" is set to illegaloperation if "stream" is not a stream.
 135   *)
 136
 137   PROCEDURE SetPosition(stream: Stream;
 138                         position: LONGINT;
 139                         VAR result: StreamResult);
 140   (* sets the actual read/write position to "position".
 141      "result" is set to nostream if "stream" is not a stream.
 142      It is set to illegaloperation if the stream was opened for appending and
 143      the position is in front of the current position, or it failed for some
 144      other reason (f.i. when the stream is connected to a terminal).
 145   *)
 146
 147   PROCEDURE isatty(stream: Stream; VAR result: StreamResult): BOOLEAN;
 148   (* return TRUE if the stream is connected to a terminal.
 149      "result" is set to nostream if "stream" is not a stream, and
 150      set to illegaloperation if the operation failed for some other reason.
 151   *)
 152
 153 END Streams.