[Generic procedures for reading from ports.]
These procedures pertain to reading characters and strings from ports. To read general S-expressions from ports, See Scheme Read.
#t if x is an end-of-file object; otherwise
#t if a character is ready on input port
#f otherwise. If
#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
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.
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.
Return the next character available from port, updating port to point to the following character. If no more characters are available, the end-of-file object is returned.
When port’s data cannot be decoded according to its
character encoding, a
decoding-error is raised and
port points past the erroneous byte sequence.
Read up to size bytes from port and store them in buffer. The return value is the number of bytes actually read, which can be less than size if end-of-file has been reached.
Note that this function does not update
Return the next character available from port, without updating port to point to the following character. If no more characters are available, the end-of-file object is returned.
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
peek-char on that port will
return the value returned by the preceding call to
peek-char. In particular, a call to
an interactive port will hang waiting for input whenever a call
read-char would have hung.
decoding-error may be raised
if such a situation occurs. However, unlike with
port still points at the beginning of the erroneous byte
sequence when the error is raised.
Place character cobj 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.
Place the string str in port so that its characters will
be read from left-to-right as the next characters from port
during subsequent read operations. 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.
This procedure clears a port’s input buffers, similar to the way that force-output clears the output buffer. The contents of the buffers are returned as a single string, e.g.,
(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.
Return the current column number or line number of port. 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 recommend 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.)
Set the current column or line number of port.