The following constructs provide access to the pretty printer:
Without any modifiers, ~_ is the same as (pprint-newline :linear).
~@_ is the same as (pprint-newline :miser).
~:_ is the same as (pprint-newline :fill).
~:@_ is the same as (pprint-newline :mandatory).
If ~:> is used to terminate a ~<...~>,
the directive is equivalent to a call to pprint-logical-block.
The argument corresponding to the ~<...~:> directive is treated in
the same way as the list argument to pprint-logical-block,
thereby providing automatic support for non-list arguments and
the detection of circularity, sharing, and depth abbreviation.
The portion of the control-string nested within the ~<...~:>
specifies the :prefix (or :per-line-prefix), :suffix,
and body of the pprint-logical-block.
The control-string portion enclosed by ~<...~:> can be divided
into segments ~<prefix~;body~;suffix~:>
by ~; directives. If the first section is terminated by ~@;,
it specifies a per-line prefix rather than a simple prefix.
The prefix and suffix cannot contain format directives.
An error is signaled if either the prefix or suffix fails to be a
constant string or if the enclosed portion is divided into more than three segments.
If the enclosed portion is divided into only two segments, the suffix
defaults to the null string. If the enclosed portion consists of only
a single segment, both the prefix and the suffix default to
the null string. If the colon modifier is used (i.e., ~:<...~:>),
the prefix and suffix default to "(" and ")"
(respectively) instead of the null string.
The body segment can be any arbitrary format string.
This format string is applied to the elements of the list
corresponding to the ~<...~:> directive as a whole.
Elements are extracted from this list using pprint-pop,
thereby providing automatic support for malformed lists, and the detection
of circularity, sharing, and length abbreviation.
Within the body segment, ~^ acts like pprint-exit-if-list-exhausted.
~<...~:> supports a feature not supported by pprint-logical-block.
If ~:@> is used to terminate the directive (i.e., ~<...~:@>),
then a fill-style conditional newline is automatically inserted after each
group of blanks immediately contained in the body (except for blanks
after a <Newline> directive). This makes it easy to achieve the
equivalent of paragraph filling.
If the at-sign modifier is used with ~<...~:>, the entire remaining argument
list is passed to the directive as its argument. All of the remaining
arguments are always consumed by ~@<...~:>, even if they are not all used
by the format string nested in the directive. Other than the difference in
its argument, ~@<...~:> is exactly the same as ~<...~:> except that
circularity detection is not applied if ~@<...~:> is encountered at top
level in a format string. This ensures that circularity detection is
applied only to data lists, not to format argument lists.
" . #n#" is printed if circularity or sharing has to be indicated
for its argument as a whole.
To a considerable extent, the basic form of the directive ~<...~> is
incompatible with the dynamic control of the arrangement of output by
~W, ~_, ~<...~:>, ~I, and ~:T. As a result, an error
is signaled if any of these directives is nested within ~<...~>.
Beyond this, an error is also signaled if the ~<...~:;...~> form of
~<...~> is used in the same format string with
~W, ~_, ~<...~:>, ~I, or ~:T.
See also Section 22.3.6.2 (Tilde Less-Than-Sign. Justification).
~nI is the same as (pprint-indent :block n).
~n:I is the same as (pprint-indent :current n).
In both cases, n defaults to zero, if it is omitted.
User defined functions can be called from within a format
string by using the directive ~/name/.
The colon modifier, the at-sign modifier, and arbitrarily many parameters
can be specified with the ~/name/ directive.
name can be any arbitrary string that does not contain a "/".
All of the characters in name are treated as if they were upper case.
If name contains a single colon (:) or double colon (::),
then everything up to but not including the first ":" or "::"
is taken to be a string that names a package.
Everything after the first ":" or "::" (if any) is taken to be a
string that names a symbol. The function corresponding to a
~/name/ directive is obtained by looking up the symbol
that has the indicated name in the indicated package.
If name does not contain a ":" or "::",
then the whole name string is looked up in the COMMON-LISP-USER package.
When a ~/name/ directive is encountered,
the indicated function is called with four or more arguments.
The first four arguments are:
the output stream,
the format argument corresponding to the directive,
a generalized boolean that is true if the colon modifier was used,
and a generalized boolean that is true if the at-sign modifier was used.
The remaining arguments consist of any parameters specified with the directive.
The function should print the argument appropriately.
Any values returned by the function are ignored.
The three functions
pprint-linear,
pprint-fill,
and pprint-tabular
are specifically designed so that they can be called by ~/.../
(i.e., ~/pprint-linear/, ~/pprint-fill/, and ~/pprint-tabular/).
In particular they take colon and at-sign arguments.