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.

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.

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.

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.

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

Synopsis

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

Parameters

stream	An 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.

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

Synopsis

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

Parameters

kind	An instance of <pretty-newline-kind>.
stream	An 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:

• #"fill": Emit a newline if the current section of output does not fit on one line.

• #"linear": Emit a newline if any #"linear" newline in the current section needs to be emitted. That is, if a current section of output cannot fit on one line, and any one of the #"linear" newlines in the section needs to be emitted, then emit them all.

• #"miser": Emit a newline as if it were a #"linear" newline, but only when miser mode is in effect. Miser style is in effect when a logical block starts past a particular column of output.

• #"mandatory": Emit a newline always. Establish that any containing sections cannot be printed on a single line so that #"linear" and #"miser" newlines will be emitted as appropriate.

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

Synopsis

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

Parameters

relative-to	An instance of <indentation-kind>.
n	An instance of <integer>.
stream	An 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.

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

Synopsis

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

Parameters

kind	An instance of <tab-kind>.
colnum	An instance of <integer>.
colinc	An instance of <integer>.
stream	An 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:

• #"line": Tab to output column colnum. If the output is already at or beyond colnum, then add colinc to colnum until printing can continue at a column beyond the end of the output already on the line.

• #"line-relative": Output colnum spaces. Then output enough spaces to tab to a column that is a multiple of colinc from the beginning of the line.

• #"section": This is similar to #"line", but column counting is relative to the beginning of the current section rather than the beginning of the line.

• #"section-relative": This is similar to #"line-relative", but column counting is relative to the beginning of the current section rather than the beginning of the line.