nilstream-symbol—a stream variable designator.
object—an object; evaluated.
:prefix—a string; evaluated. Complicated defaulting behavior; see below.
:per-line-prefix—a string; evaluated. Complicated defaulting behavior; see below.
:suffix—a string; evaluated. The default is the null string.
declaration—a declare expression; not evaluated.
forms—an implicit progn.
Causes printing to be grouped into a logical block.
The logical block is printed to the stream that is the value
of the variable denoted by stream-symbol.
During the execution of the forms,
that variable is bound to a pretty printing stream
that supports decisions about the arrangement of output
and then forwards the output to the destination stream.
All the standard printing functions
(e.g., write,
princ,
and terpri)
can be used to print output to the pretty printing stream.
All and only the output sent to this pretty printing stream
is treated as being in the logical block.
The prefix specifies a prefix to be printed before the beginning of the logical block. The per-line-prefix specifies a prefix that is printed before the block and at the beginning of each new line in the block. The :prefix and :pre-line-prefix arguments are mutually exclusive. If neither :prefix nor :per-line-prefix is specified, a prefix of the null string is assumed.
The suffix specifies a suffix that is printed just after the logical block.
The object is
normally
a list that the body forms are responsible for printing.
If object is not a list,
it is printed using write.
(This makes it easier to write printing functions that are robust
in the face of malformed arguments.)
If *print-circle*
is non-nil and object is a circular (or shared) reference to a cons,
then an appropriate “#n#” marker is printed. (This
makes it easy to write printing functions that provide full support
for circularity and sharing abbreviation.) If *print-level* is not
nil and the logical block is at a dynamic nesting depth of greater
than *print-level* in logical blocks, “#” is printed.
(This makes easy to write printing functions that provide full support for depth
abbreviation.)
If either of the three conditions above occurs, the indicated output is
printed on stream-symbol and the body forms are skipped
along with the printing of the :prefix and :suffix.
(If the body forms are not to be responsible for printing a list,
then the first two tests above can be turned off by supplying nil for
the object argument.)
In addition to the object argument of pprint-logical-block,
the arguments of the standard printing functions (such as write,
print, prin1, and pprint, as well as the arguments
of the standard format directives such as ‘~A’, ‘~S’,
(and ‘~W’) are all checked (when necessary) for circularity and sharing.
However, such checking is not applied to the arguments of the
functions write-line, write-string, and write-char
or to the literal text output by format. A consequence of this is
that you must use one of the latter functions if you want to print some
literal text in the output that is not supposed to be checked for circularity
or sharing.
The body forms of a pprint-logical-block form
must not perform any side-effects on the surrounding environment; for
example, no variables must be assigned which have not been
bound within its scope.
The pprint-logical-block macro may be used regardless of the value of *print-pretty*.
*print-circle*, *print-level*.
An error of type type-error is signaled if any of the :suffix,
:prefix, or :per-line-prefix is supplied but does not evaluate
to a string.
An error is signaled if :prefix and :pre-line-prefix are both used.
pprint-logical-block and the pretty printing stream it creates
have dynamic extent. The consequences are undefined if, outside
of this extent, output is attempted to the pretty printing stream it creates.
It is also unspecified what happens if, within this extent, any output is sent directly to the underlying destination stream.
pprint-pop, pprint-exit-if-list-exhausted, Section 22.3.5.2 (Tilde Less-Than-Sign. Logical Block)
One reason for using the pprint-logical-block macro when the value of *print-pretty*
is nil would be to allow it to perform checking for dotted lists,
as well as (in conjunction with pprint-pop)
checking for *print-level* or *print-length* being exceeded.
Detection of circularity and sharing is supported by the pretty printer
by in essence performing requested output twice. On the first pass,
circularities and sharing are detected and the actual outputting of characters
is suppressed. On the second pass, the appropriate “#n=”
and “#n#” markers are inserted and characters are output.
This is why the restriction on side-effects is necessary.
Obeying this restriction is facilitated by using pprint-pop,
instead of an ordinary pop when traversing a list being printed by
the body forms of the pprint-logical-block form.)