Rd Interface

An Rd.T (or "reader") is a character input stream. The basic operation on a reader is "GetChar", which returns the source character at the current position and advances the current position by one. Some readers are seekable, which means that they also allow setting the current position anywhere in the source. For example, readers from random access files are seekable; readers from terminals and sequential files are not.

EXCEPTION EndOfFile; Failure(AtomList.T); 

Since there are many classes of readers, there are many ways that a reader can break--for example, the connection to a terminal can be broken, the disk can signal a read error, etc. All problems of this sort are reported by raising the exception "Failure". The documentation of a reader class should specify what failures the class can raise and how they are encoded in the argument to "Failure".

Illegal operations cause a checked runtime error.

PROCEDURE GetChar(rd: T): CHAR RAISES {EndOfFile, Failure, Alerted};

Return the next character from "rd".

PROCEDURE EOF(rd: T): BOOLEAN RAISES {Failure, Alerted};

Return "TRUE" iff "rd" is at end-of-file.

PROCEDURE UnGetChar(rd: T);

"Push back" the last character read from "rd", so that the next call to "GetChar" will read it again. "UnGetChar(rd)" is guaranteed to work only if "GetChar(rd)" was the last operation on "rd". Thus "UnGetChar" cannot be called twice in a row, or after "Seek" or "EOF". If this rule is violated, a checked runtime error may result.

PROCEDURE CharsReady(rd: T): CARDINAL RAISES {Failure};

Return some number of characters that can be read without indefinite waiting. The "end of file marker" counts as one character for this purpose, so "CharsReady" will return 1, not 0, if "EOF(rd)" is true.

PROCEDURE GetSub(rd: T; VAR (*OUT*) str: ARRAY OF CHAR)
: CARDINAL RAISES {Failure, Alerted};

Read from "rd" into "str" until "rd" is exhausted or "str" is filled.

PROCEDURE GetSubLine(rd: T; VAR (*OUT*) str: ARRAY OF CHAR)
: CARDINAL RAISES {Failure, Alerted};

Read from "rd" into "str" until a newline is read, "rd" is exhausted, or "str" is filled. The newline character is not stripped out.

PROCEDURE GetText(rd: T; len: CARDINAL): TEXT RAISES {Failure, Alerted};

Read from "rd" until it is exhausted or "len" characters have been read, and return the result as a "TEXT".

PROCEDURE GetLine(rd: T): TEXT RAISES {EndOfFile, Failure, Alerted};

If "EOF(rd)" then raise "EndOfFile". Otherwise, read characters until a line break is read or "rd" is exhausted, and return the result as a "TEXT"---but discard the line break if it is present.

PROCEDURE Seek(rd: T; n: CARDINAL) RAISES {Failure, Alerted};

If "rd" is seekable, makes the current position := MIN(n, len(rd)).

PROCEDURE Close(rd: T) RAISES {Failure, Alerted};

If "rd" is not already closed, release any resources associated with "rd" and set "closed(rd) := TRUE".

PROCEDURE Index(rd: T): CARDINAL;

Returns the current position of "rd".

PROCEDURE Length(rd: T): INTEGER RAISES {Failure, Alerted};

Returns the total number of characters in "rd". If "len(rd)" is unknown to the implementation of an intermittent reader, "Length(rd)" returns -1.

PROCEDURE Intermittent(rd: T): BOOLEAN;

PROCEDURE Seekable(rd: T): BOOLEAN;

PROCEDURE Closed(rd: T): BOOLEAN;

Return "intermittent(rd)", "seekable(rd)", and "closed(rd)", respectively. These can be applied to closed readers.