34 Common Lisp Streams
CLIM performs all of its character-based input and output operations on objects
called streams . Streams are divided into two layers, the
basic stream protocol , which is character-based and compatible with
existing Common Lisp programs, and the extended stream protocol , which
introduces extended gestures such as pointer gestures and synchronous
window-manager communication.
This appendix describes the basic stream-based input and output protocol used by
CLIM. The protocol is taken from the STREAM-DEFINITION-BY-USER proposal to
the X3J13 committee, made by David Gray of TI. This proposal was not accepted
by the X3J13 committee as part of the ANSI Common Lisp language definition, but
many Lisp implementations do support it. For those implementations that do not
support it, it is implemented as part of CLIM.
34.1 Stream Classes
The following classes must be used as superclasses of user-defined stream
classes. They are not intended to be directly instantiated; they just provide
places to hang default methods.
| fundamental-stream | [Class] |
This class is the base class for all CLIM streams. It is a subclass of
stream and of standard-object .
| streamp | object | [Generic function] |
Returns true if object is a member of the class
fundamental-stream . It may return true for other objects that are
not members of the fundamental-stream class, but claim to serve as streams.
(It is not sufficient to implement streamp as (typep object
'fundamental-stream) , because implementations may have additional ways of
defining streams.)
| fundamental-input-stream | [Class] |
A subclass of fundamental-stream that implements input streams.
| input-stream-p | object | [Generic function] |
Returns true when called on any object that is a member of the class
fundamental-input-stream . It may return true for other objects that
are not members of the fundamental-input-stream class, but claim to serve
as input streams.
| fundamental-output-stream | [Class] |
A subclass of fundamental-stream that implements output streams.
| output-stream-p | object | [Generic function] |
Returns true when called on any object that is a member of the class
fundamental-output-stream . It may return true for other objects
that are not members of the fundamental-output-stream class, but claim to
serve as output streams.
Bidirectional streams can be formed by including both
fundamental-input-stream and fundamental-output-stream .
| fundamental-character-stream | [Class] |
A subclass of fundamental-stream . It provides a method for
stream-element-type , which returns character .
| fundamental-binary-stream | [Class] |
A subclass of fundamental-stream . Any instantiable class that includes
this needs to define a method for stream-element-type .
| fundamental-character-input-stream | [Class] |
A subclass of both fundamental-input-stream and
fundamental-character-stream . It provides default methods for several
generic functions used for character input.
| fundamental-character-output-stream | [Class] |
A subclass of both fundamental-output-stream and
fundamental-character-stream . It provides default methods for several
generic functions used for character output.
| fundamental-binary-input-stream | [Class] |
A subclass of both fundamental-input-stream and
fundamental-binary-stream .
| fundamental-binary-output-stream | [Class] |
A subclass of both fundamental-output-stream and
fundamental-binary-stream .
34.2 Basic Stream Functions
These generic functions must be defined for all stream classes.
| stream-element-type | stream | [Generic function] |
This existing Common Lisp function is made generic, but otherwise behaves the
same. Class fundamental-character-stream provides a default method that
returns character .
| open-stream-p | stream | [Generic function] |
This function is made generic. A default method is provided by class
fundamental-stream that returns true if close has not been
called on the stream.
| close | stream &key abort | [Generic function] |
The existing Common Lisp function close is redefined to be a generic
function, but otherwise behaves the same. The default method provided by the
class fundamental-stream sets a flag used by open-stream-p . The value
returned by close will be as specified by the X3J13 issue
closed-stream-operations .
| stream-pathname | stream | [Generic function] |
| stream-truename | stream | [Generic function] |
These are used to implement pathname and truename . There is no
default method since these are not valid for all streams.
34.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 generic
functions below.
| stream-read-char | stream | [Generic function] |
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 | stream character | [Generic function] |
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 | stream | [Generic function] |
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 | stream | [Generic function] |
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 | stream | [Generic function] |
Returns true if there is any input pending on stream , otherwise it
returns false . 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 since it will usually be trivial and will generally be
more efficient than the default method.
| stream-read-line | stream | [Generic function] |
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 | stream | [Generic function] |
Clears any buffered input associated with stream , and returns
false . This is used to implement clear-input . The default method
does nothing.
34.4 Character Output
A character output stream can be created by defining a class that includes
fundamental-character-output-stream and defining methods for the generic
functions below.
| stream-write-char | stream character | [Generic function] |
Writes character to stream , and returns character as its
value. Every subclass of fundamental-character-output-stream must have a
method defined for this function.
| stream-line-column | stream | [Generic function] |
This function returns the column number where the next character will be written
on stream , or nil if that is not meaningful. The first column on a
line is numbered 0. This function is used in the implementation of pprint and the format ~T directive. Every character output stream class
must define a method for this, although it is permissible for it to always
return nil .
| stream-start-line-p | stream | [Generic function] |
Returns true if stream is positioned at the beginning of a line,
otherwise returns false . It is permissible to always return
false . This is used in the implementation of fresh-line .
Note that while a value of 0 from stream-line-column also indicates the
beginning of a line, there are cases where stream-start-line-p can be
meaningfully implemented when stream-line-column cannot. For example, for
a window using variable-width characters, the column number isn't very
meaningful, but the beginning of the line does have a clear meaning. The
default method for stream-start-line-p on class
fundamental-character-output-stream uses stream-line-column , so if
that is defined to return nil , then a method should be provided for either
stream-start-line-p or stream-fresh-line .
| stream-write-string | stream string &optional (start 0 ) end | [Generic function] |
Writes the string string to stream . If start and end are supplied, they specify what part of string to output. string is
returned as the value. This is used by write-string . The default method
provided by fundamental-character-output-stream uses repeated calls to
stream-write-char .
| stream-terpri | stream | [Generic function] |
Writes an end of line character on stream , and returns false . This
is used by terpri . The default method does stream-write-char of
#\Newline.
| stream-fresh-line | stream | [Generic function] |
Writes an end of line character on stream only if the stream is not at the
beginning of the line. This is used by fresh-line . The default method
uses stream-start-line-p and stream-terpri .
| stream-finish-output | stream | [Generic function] |
Ensures that all the output sent to stream has reached its destination,
and only then return false . This is used by finish-output . The
default method does nothing.
| stream-force-output | stream | [Generic function] |
Like stream-finish-output , except that it may return false without
waiting for the output to complete. This is used by force-output . The
default method does nothing.
| stream-clear-output | stream | [Generic function] |
Aborts any outstanding output operation in progress, and returns false .
This is used by clear-output . The default method does nothing.
| stream-advance-to-column | stream column | [Generic function] |
Writes enough blank space on stream so that the next character will be
written at the position specified by column . Returns true if the
operation is successful, or nil if it is not supported for this stream.
This is intended for use by pprint and format ~T. The default
method uses stream-line-column and repeated calls to stream-write-char with a #\Space character; it returns nil if stream-line-column returns nil .
34.5 Binary Streams
Binary streams can be created by defining a class that includes either
fundamental-binary-input-stream or fundamental-binary-output-stream (or both) and defining a method for stream-element-type and for one or both
of the following generic functions.
| stream-read-byte | stream | [Generic function] |
Returns either an integer, or the symbol :eof if stream is at
end-of-file. This is used by read-byte .
| stream-write-byte | stream integer | [Generic function] |
Writes integer to stream , and returns integer as the
result. This is used by write-byte .