PPrint Module

The Print library implements most of the pretty printing technology described by Richard C. Waters in Common Lisp The Language, second edition. The interface is slightly different because Mindy does not have macros. This section only summarizes the pretty printing functionality to provide a quick reference for users of the Print library, and readers should refer to the Common Lisp manual for more details.

When writing print-object methods, users can ignore whether pretty printing is in effect. If you write your print-object method using pretty printing functions, then when pretty printing is in effect, the output will be pretty printed. When pretty printing is not in effect, your method will produce output as though you had not written it to use pretty printing. All print-object methods that are written to do pretty printing must call the pretty printing functions within the dynamic scope of a call to pprint-logical-block; otherwise, the pretty printing functions are no-ops.


*default-line-length*[Variable]

The length of a single line

Type

<integer>

Description

This is the line length used by the pretty printer to determine how much output will fit on a single line. It defaults to 80.


*print-miser-width*[Variable]

Controls miser mode for pretty printing

Type

false-or(<integer>)

Description

Whenever a logical block (see pprint-logical-block) begins in a column of output that is greater than *default-line-length* - *print-miser-width*, then pretty printing is in miser mode. The value must be an integer or #f (the default). #f indicates that the pretty printer should never enter miser mode.


<pretty-stream>[sealed Class]

Stream used for pretty printing.

Superclasses

<buffered-stream>

Initialization Keywords

target:An instance of <stream>. The stream where the output is finally going to go.
line-length:An instance of <column>. The line length for this stream (0 minimum). Defaults to *default-line-length*.
column:An instance of <column>. The column the first character in the buffer will appear in. Normally zero, but if we end up with a very long line with no breaks in it we might have to output part of it. Then this will no longer be zero. Defaults to 0.

Description

This is a working class for pretty-printing objects. Use an instance of this class when doing a great deal of pretty printing.


pprint-logical-block[Generic]

Start a logical block, creating a pretty-stream if necessary.

Synopsis

pprint-logical-block (stream, #key column, prefix, per-line-prefix, body, suffix) => ()

Parameters

streamAn instance of <stream>.
column:An instance of <integer>.
prefix:An instance of <byte-string>.
per-line-prefix:An instance of <byte-string>.
body:An instance of <function>.
suffix:An instance of <byte-string>.

Return Values

None.

Description

This function groups printing into a logical block. The logical block provides boundaries for new levels of indentation, affects #"linear" newlines, and so on. Prefix is a string to print at the beginning of the logical block. The blocks indentation is automatically set to be one character position greater than the column in which prefix ends. Alternatively, per-line-prefix is a string to print on every line of the logical block. This function signals an error if it is called with both prefix and per-line-prefix supplied as non-#f. Suffix is a string to print at the end of the logical block. Column advises the pretty printer as to the current column of the output stream (defaults to zero). The column argument may be ignored entirely by some methods, and it may be ignored in some cases by methods that can better determine the stream's current output column.

Body must be a <function> that can take one argument, and this argument is a <stream>. The body function should use the stream argument passed to it; the body function should not close over the stream argument to pprint-logical-block. Pprint-logical-block wraps stream with a pretty printing stream when stream is any other kind of stream. If stream is already a pretty printing stream, then the body function is called on stream.

All print-object methods that are written to do pretty printing must call the other pretty printing functions within the dynamic scope of a call to pprint-logical-block; otherwise, the pretty printing functions are no-ops.


pprint-newline[Method]

Output a conditional newline of some kind. If called on a regular stream, ignore it.

Synopsis

pprint-newline (kind, stream) => ()

Parameters

kindAn instance of <pretty-newline-kind>.
streamAn instance of <stream>.

Return Values

None.

Description

This function announces a conditional newline to the pretty printer. The pretty printer emits a newline depending on the kind and the state of the pretty printer's current line buffer. The kind argument has roughly the following meanings:


pprint-indent[Method]

Change the indentation. If called on a regular stream, just ignore it.

Synopsis

pprint-indent (relative-to, n, stream) => ()

Parameters

relative-toAn instance of <indentation-kind>.
nAn instance of <integer>.
streamAn instance of <stream>.

Return Values

None.

Description

This function specifies the indentation to use within the current logical block. When relative-to is #"block", then pprint-indent sets the indentation to the column of the first character of the logical block plus n. When relative-to is #"current", then pprint-indent sets the indentation to the current column plus n.


pprint-tab[Method]

Output a tab. If called on a regular stream, ignore it.

Synopsis

pprint-tab (kind, colnum, colinc, stream) => ()

Parameters

kindAn instance of <tab-kind>.
colnumAn instance of <integer>.
colincAn instance of <integer>.
streamAn instance of <stream>.

Return Values

None.

Description

This function announces a tab to the pretty printer. Colnum and colinc have meaning based on the value of kind: