D.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 following generic functions.

stream-write-char [Generic Function]

Arguments: stream character

Summary: 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 [Generic Function]

Arguments: stream

Summary: 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 [Generic Function]

Arguments: stream

Summary: Returns t if stream is positioned at the beginning of a line; otherwise, it returns nil . It is permissible to always return nil . 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 , a method should be provided for either stream-start-line-p or stream-fresh-line .

stream-write-string [Generic Function]

Arguments: stream string &optional (start 0 ) end

Summary: 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 [Generic Function]

Arguments: stream

Summary: Writes an end-of-line character on stream and returns nil . This is used by terpri . The default method does stream-write-char of #\Newline .

stream-fresh-line [Generic Function]

Arguments: stream

Summary: 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 [Generic Function]

Arguments: stream

Summary: Ensures that all the output sent to stream has reached its destination, and only then return nil . This is used by finish-output . The default method does nothing.

stream-force-output [Generic Function]

Arguments: stream

Summary: Like stream-finish-output , except that it may return nil without waiting for the output to complete. This is used by force-output . The default method does nothing.

stream-clear-output [Generic Function]

Arguments: stream

Summary: Aborts any outstanding output operation in progress and returns nil . This is used by clear-output . The default method does nothing.

stream-advance-to-column [Generic Function]

Arguments: stream column

Summary: Writes enough blank space on stream so that the next character will be written at the position specified by column . Returns t 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 .

CommonLisp Interface Manager 2.0 User's Guide - 30 Jul 2004