123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153 |
- DEFINITION MODULE Streams;
- (*
- Module: Stream Input/Output
- Author: Ceriel J.H. Jacobs
- Version: $Id$
- * This module provides sequential IO through streams.
- * A stream is either a text stream or a binary stream, and is either in
- * reading, writing or appending mode.
- * By default, there are three open text streams, connected to standard input,
- * standard output, and standard error respectively.
- * These are text streams.
- * When connected to a terminal, the standard output and standard error
- * streams are linebuffered.
- * The user can create more streams with the OpenStream call, and
- * delete streams with the CloseStream call.
- * Streams are automatically closed at program termination.
- *)
- FROM SYSTEM IMPORT BYTE;
- TYPE StreamKind = (text, binary, none);
- StreamMode = (reading, writing, appending);
- StreamResult = (succeeded, illegaloperation,
- nomemory, openfailed, nostream, endoffile);
- StreamBuffering = (unbuffered, linebuffered, blockbuffered);
- TYPE Stream;
- VAR InputStream, OutputStream, ErrorStream: Stream;
- PROCEDURE OpenStream(VAR stream: Stream;
- filename: ARRAY OF CHAR;
- kind: StreamKind;
- mode: StreamMode;
- VAR result: StreamResult);
- (* Associates a stream with the file named filename.
- If kind = none, result is set to illegaloperation.
- mode has one of the follwing values:
- reading: the file is opened for reading
- writing: the file is truncated or created for writing
- appending: the file is opened for writing at end of file,
- or created for writing.
- On failure, result is set to openfailed.
- On success, result is set to succeeded.
- *)
- PROCEDURE SetStreamBuffering( stream: Stream;
- b: StreamBuffering;
- VAR result: StreamResult);
- (* This procedure is only allowed for output streams.
- The three types of buffering available are unbuffered, linebuffered,
- and blockbuffered. When an output stream is unbuffered, the output
- appears as soon as written; when it is blockbuffered, output is saved
- up and written as a block; When it is linebufferded (only possible for
- text output streams), output is saved up until a newline is encountered
- or input is read from standard input.
- *)
- PROCEDURE CloseStream(VAR stream: Stream; VAR result: StreamResult);
- (* Closes the stream.
- result is set to nostream if "stream" was not associated with a stream.
- *)
- PROCEDURE FlushStream(stream: Stream; VAR result: StreamResult);
- (* Flushes the stream.
- result is set to nostream if "stream" was not associated with a stream.
- It is set to illegaloperation if "stream" is not an output or
- appending stream.
- *)
- PROCEDURE EndOfStream(stream: Stream; VAR result: StreamResult): BOOLEAN;
- (* Returns true if the stream is an input stream, and the end of the file
- has been reached.
- result is set to nostream if "stream" was not associated with a stream.
- It is set to illegaloperation if the stream is not an input stream.
- *)
- PROCEDURE Read(stream: Stream; VAR ch: CHAR; VAR result: StreamResult);
- (* reads a character from the stream. Certain character translations may
- occur, such as the mapping of the end-of-line sequence to the
- character 12C.
- result is set to nostream if "stream" was not associated with a stream.
- It is set to endoffile if EndOfStream would have returned TRUE before the
- call to Read. In this case, "ch" is set to 0C.
- It is set to illegaloperation if the stream is not a text input stream.
- *)
- PROCEDURE ReadByte(stream: Stream; VAR byte: BYTE; VAR result: StreamResult);
- (* reads a byte from the stream. No character translations occur.
- result is set to nostream if "stream" was not associated with a stream.
- It is set to endoffile if EndOfStream would have returned TRUE before the
- call to ReadByte. In this case, "byte" is set to 0C.
- It is set to illegaloperation if the stream is not a binary input stream.
- *)
- PROCEDURE ReadBytes(stream: Stream;
- VAR bytes: ARRAY OF BYTE;
- VAR result: StreamResult);
- (* reads bytes from the stream. No character translations occur.
- The number of bytes is determined by the size of the parameter.
- result is set to nostream if "stream" was not associated with a stream.
- It is set to endoffile if there are not enough bytes left on the stream.
- In this case, the rest of the bytes are set to 0C.
- It is set to illegaloperation if the stream is not a binary input stream.
- *)
- PROCEDURE Write(stream: Stream; ch: CHAR; VAR result: StreamResult);
- (* writes a character to the stream. Certain character translations may
- occur, such as the mapping of a line-feed or carriage return (12C or 15C)
- to the end-of-line sequence of the system.
- result is set to nostream if "stream" was not associated with a stream.
- It is set to illegaloperation if the stream is not a text output stream.
- *)
- PROCEDURE WriteByte(stream: Stream; byte: BYTE; VAR result: StreamResult);
- (* writes a byte to the stream. No character translations occur.
- result is set to nostream if "stream" was not associated with a stream.
- It is set to illegaloperation if the stream is not a binary output stream.
- *)
- PROCEDURE WriteBytes(stream: Stream;
- bytes: ARRAY OF BYTE;
- VAR result: StreamResult);
- (* writes bytes to the stream. No character translations occur.
- The number of bytes written is equal to the size of the parameter.
- result is set to nostream if "stream" was not associated with a stream.
- It is set to illegaloperation if the stream is not a binary output stream.
- *)
- PROCEDURE GetPosition(stream: Stream;
- VAR position: LONGINT;
- VAR result: StreamResult);
- (* gives the actual read/write position in "position".
- "result" is set to illegaloperation if "stream" is not a stream.
- *)
- PROCEDURE SetPosition(stream: Stream;
- position: LONGINT;
- VAR result: StreamResult);
- (* sets the actual read/write position to "position".
- "result" is set to nostream if "stream" is not a stream.
- It is set to illegaloperation if the stream was opened for appending and
- the position is in front of the current position, or it failed for some
- other reason (f.i. when the stream is connected to a terminal).
- *)
- PROCEDURE isatty(stream: Stream; VAR result: StreamResult): BOOLEAN;
- (* return TRUE if the stream is connected to a terminal.
- "result" is set to nostream if "stream" is not a stream, and
- set to illegaloperation if the operation failed for some other reason.
- *)
- END Streams.
|