D.3 Character Input

A character input stream can be created by defining a class that includes
fundamental-character-input-stream
and defining methods for the following generic functions.

stream-read-char [Generic Function]

Arguments: stream

Summary: Reads one character from
stream
, and returns either a character object or the symbol
:eof
if the stream is at end-of-file. There is no default method for this generic function, so every subclass of
fundamental-character-input-stream
must define a method.

stream-unread-char [Generic Function]

Arguments: stream character

Summary: Undoes the last call to
stream-read-char
, as in
unread-char
, and returns
nil
. There is no default method for this, so every subclass of
fundamental- character-input-stream
must define a method.

stream-read-char-no-hang [Generic Function]

Arguments: stream

Summary: Returns either a character, or
nil
if no input is currently available, or
:eof
if end-of-file is reached. This is used to implement
read-char-no-hang
. The default method provided by
fundamental-character-input-stream
simply calls
stream-read-char
; this is sufficient for file streams, but interactive streams should define their own method.

stream-peek-char [Generic Function]

Arguments: stream

Summary: Returns either a character or
:eof
without removing the character from the stream's input buffer. This is used to implement
peek-char
; this corresponds to peek-type of
nil
. The default method calls
stream-read-char
and
stream-unread-char.

stream-listen [Generic Function]

Arguments: stream

Summary: Returns
t
if there is any input pending on
stream
; otherwise, it returns
nil
. This is used by
listen
. The default method uses
stream-read-char-no-hang
and
stream-unread-char
. Most streams should define their own method, as it will usually be trivial and will generally be more efficient than the default method.

stream-read-line [Generic Function]

Arguments: stream

Summary: Returns a string as the first value, and
t
as the second value if the string was terminated by end-of-file instead of the end of a line. This is used by
read-line
. The default method uses repeated calls to
stream-read-char
.

stream-clear-input [Generic Function]

Arguments: stream

Summary: Clears any buffered input associated with
stream
, and returns
nil
. This is used to implement
clear-input
. The default method does nothing.