Next Prev Up Top Contents Index

17.3 Formatting Text in CLIM

CLIM provides the following three forms for creating textual lists, indenting output, and breaking up lengthy output into multiple lines.

format-textual-list [Function]	

Arguments: sequence printer &key stream separator conjunction

Summary: Outputs the sequence of items in sequence as a "textual list." For example, the list (1 2 3 4) might be printed as

1, 2, 3, and 4

printer is a function of two arguments: an element of the sequence and a stream; it has dynamic extent. It is called to output each element of the sequence.

stream specifies the output stream. The default is *standard-output* .

The separator and conjunction arguments control the appearance of each element of the sequence and the separators used between each pair of elements. separator is a string that is output after every element but the last one; the default for separator is " , " (a comma followed by a space). conjunction is a string that is output before the last element. The default is nil , meaning that there is no conjunction. Typical values for conjunction are the strings " and " and " or ".

indenting-output [Macro]	

Arguments: (stream indentation &key (move-cursor t )) &body body

Summary: Binds stream to a stream that inserts whitespace at the beginning of each line of output produced by body , and then writes the indented output to the stream that is the original value of stream .

The stream argument is not evaluated, and must be a symbol that is bound to an output recording stream. If stream is t , *standard-output* is used. body may have zero or more declarations as its first forms.

indentation specifies how much whitespace should be inserted at the beginning of each line. It is specified in the same way as the :x-spacing option to formatting-table .

If the boolean move-cursor is t (the default), CLIM moves the cursor to the end of the table.

Programmers using indenting-output should begin the body with a call to fresh-line (or some equivalent) to position the stream to the indentation initially. There is a restriction on interactions between indenting-output and filling-output : a call to indenting-output should appear outside of a call to filling-output .

filling-output [Macro]	

Arguments: (stream &key fill-width break-characters after-line-break after-line-break-initially) &body body

Summary: Binds stream to a stream that inserts line breaks into the textual output written to it (by such functions as write-char and write-string ) so that the output is usually no wider then fill-width . The filled output is then written on the original stream.

The stream argument is not evaluated, and must be a symbol that is bound to a stream. If stream is t , *standard-output* is used. body may have zero or more declarations as its first forms.

fill-width specifies the width of filled lines, and defaults to 80 characters. It is specified the same way as the :x-spacing option for formatting-table . 17.1.2, CLIM Operators for Formatting Tables

"Words" are separated by the characters specified in the list break-characters . When a line is broken to prevent wrapping past the end of a line, the line break is made at one of these separators. That is, filling-output does not split "words" across lines, so it might produce output wider than fill-width .

after-line-break specifies a string to be sent to stream after line breaks; the string appears at the beginning of each new line. The string must not be wider than fill-width .

If the boolean after-line-break-initially is t , then the after-line-break text is to be written to stream before executing body , that is, at the beginning of the first line. The default is nil .


CommonLisp Interface Manager 2.0 User's Guide - 8 Aug 2003

Next Prev Up Top Contents Index