Next: , Previous: Ports, Up: Input and Output

27.2 Reading

[Generic procedures for reading from ports.]

— Scheme Procedure: eof-object? x
— C Function: scm_eof_object_p (x)

Return #t if x is an end-of-file object; otherwise #f.

— Scheme Procedure: char-ready? [port]
— C Function: scm_char_ready_p (port) |0 |1 |0

Return #t if a character is ready on input port and #f otherwise. If char-ready? returns #t then the next read-char operation on port is guaranteed not to hang. If port is a file port at end of file then return #t. 1

— Scheme Procedure: read-char [port]
— C Function: scm_read_char (port) |0 |1 |0

Return the next character available from port, updating port to point to the following character. If no more characters are available, an end-of-file object is returned.

— Scheme Procedure: peek-char [port]
— C Function: scm_peek_char (port) |0 |1 |0

Return the next character available from port, without updating port to point to the following character. If no more characters are available, an end-of-file object is returned.2

— Scheme Procedure: unread-char cobj port
— C Function: scm_unread_char (cobj, port)

Place char in port so that it will be read by the next read operation. If called multiple times, the unread characters will be read again in last-in first-out order. If port is not supplied, the current input port is used.

— Scheme Procedure: unread-string str line-buffering-input-port
— C Function: scm_unread_string (str, line-buffering-input-port)

Return string str to line-buffering-input-port. A subsequent call to read-string or read-char from this port will retrieve this string or its first character, respectively, before consulting the underlying port.

— Scheme Procedure: drain-input port
— C Function: scm_drain_input (port)

Drain port's read buffers (including any pushed-back characters) and return the contents as a single string. 

     (define p (open-input-file ...))
     (drain-input p) => empty string, nothing buffered yet.
     (unread-char (read-char p) p)
     (drain-input p) => initial chars from p, up to the buffer size.

Draining the buffers may be useful for cleanly finishing buffered I/O so that the file descriptor can be used directly for further input.

— Scheme Procedure: port-column port
— C Function: scm_port_column (port)
— Scheme Procedure: port-line port
— C Function: scm_port_line (port)

Return the current column number or line number of input-port, using the current input port if none is specified. If the number is unknown, the result is #f. Otherwise, the result is a 0-origin integer - i.e. the first character of the first line is line 0, column 0. (However, when you display a file position, for example in an error message, we recommand you add 1 to get 1-origin integers. This is because lines and column numbers traditionally start with 1, and that is what non-programmers will find most natural.)

— Scheme Procedure: set-port-column! port column
— Scheme Procedure: set-port-line! port line
— C Function: scm_set_port_column_x (port, column)
— C Function: scm_set_port_line_x (port, line)

Set the current column or line number of port, using the current input port if none is specified.

Footnotes

[1] char-ready? exists to make it possible for a program to accept characters from interactive ports without getting stuck waiting for input. Any input editors associated with such ports must make sure that characters whose existence has been asserted by char-ready? cannot be rubbed out. If char-ready? were to return #f at end of file, a port at end of file would be indistinguishable from an interactive port that has no ready characters.

[2] The value returned by a call to peek-char is the same as the value that would have been returned by a call to read-char on the same port. The only difference is that the very next call to read-char or peek-char on that port will return the value returned by the preceding call to peek-char. In particular, a call to peek-char on an interactive port will hang waiting for input whenever a call to read-char would have hung.