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 to0
.
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
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 whichprefix
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 bothprefix
andper-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). Thecolumn
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>
. Thebody
function should use thestream
argument passed to it; thebody
function should not close over thestream
argument topprint-logical-block
.Pprint-logical-block
wrapsstream
with a pretty printing stream whenstream
is any other kind of stream. Ifstream
is already a pretty printing stream, then thebody
function is called onstream
.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 topprint-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
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 currentsection
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 whenmiser 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.
pprint-indent | [Method] |
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"
, thenpprint-indent
sets the indentation to the column of the first character of the logical block plusn
. Whenrelative-to
is#"current"
, thenpprint-indent
sets the indentation to the current column plusn
.
pprint-tab | [Method] |
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
andcolinc
have meaning based on the value ofkind
:
#"line"
: Tab to output columncolnum
. If the output is already at or beyondcolnum
, then addcolinc
tocolnum
until printing can continue at a column beyond the end of the output already on the line.
#"line-relative"
: Outputcolnum
spaces. Then output enough spaces to tab to a column that is a multiple ofcolinc
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.