Next: FORMAT Control-Flow Operations, Previous: FORMAT Pretty Printer Operations, Up: Formatted Output
This spaces over to a given column.
~colnum,colincT will output
sufficient spaces to move the cursor to column colnum. If the cursor
is already at or beyond column colnum, it will output spaces to move it to
column colnum+k*colinc for the smallest positive integer
k possible, unless colinc is zero, in which case no spaces
are output if the cursor is already at or beyond column colnum.
colnum and colinc default to 1.
If for some reason the current absolute column position cannot be determined
by direct inquiry,
format
may be able to deduce the current column position by noting
that certain directives (such as ~%, or ~&,
or ~A
with the argument being a string containing a newline) cause
the column position to be reset to zero, and counting the number of characters
emitted since that point. If that fails, format
may attempt a
similar deduction on the riskier assumption that the destination was
at column zero when format
was invoked. If even this heuristic fails
or is implementationally inconvenient, at worst
the ~T operation will simply output two spaces.
~@T performs relative tabulation.
~colrel,colinc@T outputs colrel spaces
and then outputs the smallest non-negative
number of additional spaces necessary to move the cursor
to a column that is a multiple
of colinc. For example, the directive
~3,8@T outputs
three spaces and then moves the cursor to a “standard multiple-of-eight
tab stop” if not at one already.
If the current output column cannot be determined, however,
then colinc is ignored, and exactly colrel spaces are output.
If the colon modifier is used with the ~T directive,
the tabbing computation is done relative to the horizontal position where the
section immediately containing the directive begins, rather than with
respect to a horizontal position of zero. The numerical parameters are
both interpreted as being in units of ems and both default to 1.
~n,m:T is the same as
(pprint-tab :section n m).
~n,m:@T is the same as
(pprint-tab :section-relative n m).
~mincol,colinc,minpad,padchar<str~>
This justifies the text produced by processing str
within a field at least mincol columns wide. str
may be divided up into segments with ~;, in which case the
spacing is evenly divided between the text segments.
With no modifiers, the leftmost text segment is left justified in the
field, and the rightmost text segment is right justified. If there is
only one text element, as a special case, it is right justified.
The : modifier causes
spacing to be introduced before the first text segment; the
@ modifier causes spacing to be added after the last.
The minpad parameter (default 0) is the minimum number of
padding characters to be output between each segment.
The padding character is supplied by padchar,
which defaults to the space character.
If the total width needed to satisfy these constraints is greater
than mincol, then the width used is mincol+k*colinc
for the smallest possible non-negative integer value k.
colinc defaults to 1, and mincol defaults to 0.
Note that str may include format directives.
All the clauses in str are processed in order;
it is the resulting pieces of text that are justified.
The ~^ directive may be used to terminate processing of the
clauses prematurely, in which case only the completely processed clauses
are justified.
If the first clause of a ~<
is terminated with ~:; instead of
~;, then it is used in a special way. All of the clauses are
processed (subject to ~^ , of course), but the
first one is not used
in performing the spacing and padding. When the padded result has been
determined, then if it will fit on the current line of output, it is
output, and the text for the first clause is discarded. If, however, the
padded text will not fit on the current line, then the text segment for
the first clause is output before the padded text. The first clause
ought to contain a newline (such as a ~% directive). The first
clause is always processed, and so any arguments it refers to will be
used; the decision is whether to use the resulting segment of text, not
whether to process the first clause. If the ~:; has a prefix
parameter n, then the padded text must fit on the current line with
n character positions to spare to avoid outputting the first clause's
text. For example, the control string
"~%;; ~{ ~<~%;; ~1:; ~S~>~^ ,~} .~%"
can be used to print a list of items separated by commas without
breaking items over line boundaries, beginning each line with
;; . The prefix parameter
1 in ~1:; accounts for the width of the
comma that will follow the justified item if it is not the last
element in the list, or the period
if it is. If ~:; has a second
prefix parameter, then it is used as the width of the line,
thus overriding the natural line width of the output stream. To make
the preceding example use a line width of 50, one would write
"~%;; ~{ ~<~%;; ~1,50:; ~S~>~^ ,~} .~%"
If the second argument is not supplied, then format uses the
line width of the destination output stream.
If this cannot be determined (for example, when producing a
string result), then format uses 72 as the line length.
See also Section 22.3.5.2 (Tilde Less-Than-Sign. Logical Block).
~> terminates a ~<.
The consequences of using it elsewhere are undefined.