|
ANSI Common Lisp 22 Printer 22.4 Dictionary of Printer
22.4.8 pprint-newline |
Function |
- Syntax:
-
pprint-newline
kind &optional stream
nil
- Arguments and Values:
-
kind - one of :linear, :fill, :miser, or :mandatory.
stream - a stream designator.
The default is standard output.
- Description:
-
If stream is a pretty printing stream
and the value of *print-pretty* is true,
a line break is inserted in the output
when the appropriate condition below is satisfied;
otherwise, pprint-newline has no effect.
Kind specifies the style of conditional newline.
This parameter is treated as follows:
- :linear
This specifies a
"linear-style" conditional newline.
A line break is inserted
if and only if the immediately containing section
cannot be printed on one line.
The effect of this is that line breaks are
either inserted at every linear-style conditional newline in a logical block
or at none of them.
- :miser
This specifies a
"miser-style" conditional newline.
A line break is inserted
if and only if the immediately containing section
cannot be printed on one line
and miser style is in effect in the immediately containing logical block.
The effect of this is that miser-style conditional newlines
act like linear-style conditional newlines,
but only when miser style is in effect.
Miser style is in effect for a logical block if and only if
the starting position of the logical block
is less than or equal to
*print-miser-width* ems from the right margin.
- :fill
This specifies a
"fill-style" conditional newline.
A line break is inserted if and only if
either (a) the following section cannot be printed
on the end of the current line,
(b) the preceding section was not printed on a single line,
or (c) the immediately containing section cannot
be printed on one line and miser style is in effect
in the immediately containing logical block.
If a logical block is broken up into a number of subsections
by fill-style conditional newlines,
the basic effect is that the logical block
is printed with as many subsections as possible on each line.
However, if miser style is in effect,
fill-style conditional newlines act like linear-style conditional newlines.
- :mandatory
This specifies a
"mandatory-style" conditional newline.
A line break is always inserted.
This implies that none of the containing sections
can be printed on a single line and
will therefore trigger the insertion of line breaks
at linear-style conditional newlines in these sections.
When a line break is inserted by any type of conditional newline,
any blanks that immediately precede the conditional newline are omitted
from the output and indentation is introduced at the beginning of the next line.
By default, the indentation causes the following line to begin
in the same horizontal position
as the first character in the immediately containing logical block.
(The indentation can be changed via pprint-indent.)
There are a variety of ways unconditional newlines can be introduced into
the output (i.e., via terpri or by printing a string containing a newline
character). As with mandatory conditional newlines, this prevents any of
the containing sections from being printed on one line. In general, when
an unconditional newline is encountered, it is printed out without
suppression of the preceding blanks and without any indentation following
it. However, if a per-line prefix has been specified (see
pprint-logical-block), this prefix will always be printed no matter
how a newline originates.
- Examples:
-
See Section 22.2.2 Examples of using the Pretty Printer.
- Side Effects:
-
Output to stream.
- Affected By:
-
*print-pretty*, *print-miser*.
The presence of containing logical blocks.
The placement of newlines and conditional newlines.
- Exceptional Situations:
-
An error of type type-error is signaled if kind
is not one of :linear, :fill, :miser, or :mandatory.
- See Also:
-
Section 22.3.5.1 Tilde Underscore: Conditional Newline,
Section 22.2.2 Examples of using the Pretty Printer
- Allegro CL Implementation Details:
-
None.
|