5.8.2.9 Textual input

Procedure: get-char textual-input-port

Read from textual-input-port, blocking as necessary, until a complete character is available, or until an end of file is reached.

If a complete character is available before the next end of file, get-char returns that character and updates the input port to point past the character. If an end of file is reached before any character is read, get-char returns the end–of–file object.

Procedure: lookahead-char textual-input-port

The lookahead-char procedure is like get-char, but it does not update textual-input-port to point past the character.

NOTE With some of the standard transcoders described in this document, up to four bytes of lookahead are needed. Non–standard transcoders may need even more lookahead.

Procedure: get-string-n textual-input-port count

count must be an exact, non–negative integer object, representing the number of characters to be read.

The get-string-n procedure reads from textual-input-port, blocking as necessary, until count characters are available, or until an end of file is reached.

If count characters are available before end of file, get-string-n returns a string consisting of those count characters.

If fewer characters are available before an end of file, but one or more characters can be read, get-string-n returns a string containing those characters.

In either case, the input port is updated to point just past the characters read. If no characters can be read before an end of file, the end-of-file object is returned.

Procedure: get-string-n! textual-input-port string start count

start and count must be exact, non–negative integer objects, with count representing the number of characters to be read. string must be a string with at least start+count characters.

The get-string-n! procedure reads from textual-input-port in the same manner as get-string-n.

If count characters are available before an end of file, they are written into string starting at index start, and count is returned.

If fewer characters are available before an end of file, but one or more can be read, those characters are written into string starting at index start and the number of characters actually read is returned as an exact integer object.

If no characters can be read before an end of file, the end–of–file object is returned.

Procedure: get-string-all textual-input-port

Read from textual-input-port until an end of file, decoding characters in the same manner as get-string-n and get-string-n!.

If characters are available before the end of file, a string containing all the characters decoded from that data is returned. If no character precedes the end of file, the end–of–file object is returned.

Procedure: get-line textual-input-port

Read from textual-input-port up to and including the linefeed character or end of file, decoding characters in the same manner as get-string-n and get-string-n!.

If a linefeed character is read, a string containing all of the text up to (but not including) the linefeed character is returned, and the port is updated to point just past the linefeed character.

If an end of file is encountered before any linefeed character is read, but some characters have been read and decoded as characters, a string containing those characters is returned.

If an end of file is encountered before any characters are read, the end–of–file object is returned.

NOTE The end–of–line style, if not none, will cause all line endings to be read as linefeed characters.

Procedure: get-datum textual-input-port

Read an external representation from textual-input-port and return the datum it represents. The get-datum procedure returns the next datum that can be parsed from the given textual-input-port, updating textual-input-port to point exactly past the end of the external representation of the object.

Any ?interlexeme-space (scheme lex syntax) in the input is first skipped. If an end of file occurs after the ?interlexeme-space, the end–of–file object is returned.

If a character inconsistent with an external representation is encountered in the input, an exception with condition types &lexical and &i/o-read is raised.

Also, if the end of file is encountered after the beginning of an external representation, but the external representation is incomplete and therefore cannot be parsed, an exception with condition types &lexical and &i/o-read is raised.