3
@node Printer, Reader, Streams, Top
8
* The Lisp Pretty Printer::
10
* Printer Dictionary::
13
@node The Lisp Printer, The Lisp Pretty Printer, Printer, Printer
14
@section The Lisp Printer
16
@c including concept-print
19
* Overview of The Lisp Printer::
20
* Printer Dispatching::
21
* Default Print-Object Methods::
22
* Examples of Printer Behavior::
25
@node Overview of The Lisp Printer, Printer Dispatching, The Lisp Printer, The Lisp Printer
26
@subsection Overview of The Lisp Printer
28
@r{Common Lisp} provides a representation of most @i{objects} in the form
29
of printed text called the printed representation.
30
Functions such as @b{print} take an @i{object}
31
and send the characters of its printed representation to a @i{stream}.
32
The collection of routines that does this is known as the (@r{Common Lisp}) printer.
34
Reading a printed representation
36
produces an @i{object} that is @b{equal} to the
37
originally printed @i{object}.
40
* Multiple Possible Textual Representations::
44
@node Multiple Possible Textual Representations, Printer Escaping, Overview of The Lisp Printer, Overview of The Lisp Printer
45
@subsubsection Multiple Possible Textual Representations
47
Most @i{objects} have more than one possible textual representation.
48
For example, the positive @i{integer} with a magnitude of twenty-seven
49
can be textually expressed in any of these ways:
52
27 27. #o33 #x1B #b11011 #.(* 3 3 3) 81/3
55
A list containing the two symbols @t{A} and @t{B} can also be textually
56
expressed in a variety of ways:
59
(A B) (a b) ( a b ) (\A |B|)
67
from the point of view of the @i{Lisp reader},
69
wherever @i{whitespace} is permissible in a textual representation,
70
any number of @i{spaces} and @i{newlines} can appear in @i{standard syntax}.
72
When a function such as @b{print} produces a printed representation,
74
from among many possible textual representations.
75
In most cases, it chooses a
76
program readable representation,
77
but in certain cases it might use a more compact notation that is not
80
A number of option variables, called
81
@i{printer control variables}
82
@IGindex{printer control variable}
84
are provided to permit control of individual aspects of the
85
printed representation of @i{objects}.
86
Figure 22--1 shows the @i{standardized} @i{printer control variables};
87
there might also be @i{implementation-defined} @i{printer control variables}.
92
@w{ *print-array* *print-gensym* *print-pprint-dispatch* }
93
@w{ *print-base* *print-length* *print-pretty* }
94
@w{ *print-case* *print-level* *print-radix* }
95
@w{ *print-circle* *print-lines* *print-readably* }
96
@w{ *print-escape* *print-miser-width* *print-right-margin* }
99
@w{ Figure 22--1: Standardized Printer Control Variables }
104
In addition to the @i{printer control variables},
105
the following additional @i{defined names}
106
relate to or affect the behavior of the @i{Lisp printer}:
111
@w{ *package* *read-eval* readtable-case }
112
@w{ *read-default-float-format* *readtable* }
115
@w{ Figure 22--2: Additional Influences on the Lisp printer. }
120
@node Printer Escaping, , Multiple Possible Textual Representations, Overview of The Lisp Printer
121
@subsubsection Printer Escaping
123
The @i{variable} @b{*print-escape*} controls whether the @i{Lisp printer}
124
tries to produce notations such as escape characters and package prefixes.
126
The @i{variable} @b{*print-readably*} can be used to override
127
many of the individual aspects controlled by the other
128
@i{printer control variables} when program-readable output
129
is especially important.
131
One of the many effects of making the @i{value} of @b{*print-readably*} be @i{true}
132
is that the @i{Lisp printer} behaves as if @b{*print-escape*} were also @i{true}.
133
For notational convenience, we say that
134
if the value of either @b{*print-readably*} or @b{*print-escape*} is @i{true},
135
then @i{printer escaping}
136
@IGindex{printer escaping}
139
if the values of both @b{*print-readably*} and @b{*print-escape*} are @i{false},
140
then @i{printer escaping} is ``disabled''.
142
@node Printer Dispatching, Default Print-Object Methods, Overview of The Lisp Printer, The Lisp Printer
143
@subsection Printer Dispatching
145
The @i{Lisp printer} makes its determination of how to print an
146
@i{object} as follows:
148
If the @i{value} of @b{*print-pretty*} is @i{true},
149
printing is controlled by the @i{current pprint dispatch table};
150
see @ref{Pretty Print Dispatch Tables}.
152
Otherwise (if the @i{value} of @b{*print-pretty*} is @i{false}),
153
the object's @b{print-object} method is used;
154
see @ref{Default Print-Object Methods}.
156
@node Default Print-Object Methods, Examples of Printer Behavior, Printer Dispatching, The Lisp Printer
157
@subsection Default Print-Object Methods
159
This section describes the default behavior of
160
@b{print-object} methods for the @i{standardized} @i{types}.
164
* Printing Integers::
167
* Printing Complexes::
168
* Note about Printing Numbers::
169
* Printing Characters::
171
* Package Prefixes for Symbols::
172
* Effect of Readtable Case on the Lisp Printer::
173
* Examples of Effect of Readtable Case on the Lisp Printer::
175
* Printing Lists and Conses::
176
* Printing Bit Vectors::
177
* Printing Other Vectors::
178
* Printing Other Arrays::
179
* Examples of Printing Arrays::
180
* Printing Random States::
181
* Printing Pathnames::
182
* Printing Structures::
183
* Printing Other Objects::
186
@node Printing Numbers, Printing Integers, Default Print-Object Methods, Default Print-Object Methods
187
@subsubsection Printing Numbers
189
@node Printing Integers, Printing Ratios, Printing Numbers, Default Print-Object Methods
190
@subsubsection Printing Integers
192
@i{Integers} are printed in the radix specified by the @i{current output base}
193
in positional notation, most significant digit first.
194
If appropriate, a radix specifier can be printed; see @b{*print-radix*}.
195
If an @i{integer} is negative, a minus sign is printed and then the
196
absolute value of the @i{integer} is printed.
197
The @i{integer} zero is represented
198
by the single digit @t{0} and never has a sign.
199
A decimal point might be printed,
200
depending on the @i{value} of @b{*print-radix*}.
202
For related information about the syntax of an @i{integer},
203
see @ref{Syntax of an Integer}.
205
@node Printing Ratios, Printing Floats, Printing Integers, Default Print-Object Methods
206
@subsubsection Printing Ratios
210
@i{Ratios} are printed as follows:
211
the absolute value of the numerator is printed, as for an @i{integer};
212
then a @t{/}; then the denominator. The numerator and denominator are
213
both printed in the radix specified by the @i{current output base};
214
they are obtained as if by
215
@b{numerator} and @b{denominator}, and so @i{ratios}
216
are printed in reduced form (lowest terms).
217
If appropriate, a radix specifier can be printed; see
219
If the ratio is negative, a minus sign is printed before the numerator.
221
For related information about the syntax of a @i{ratio},
222
see @ref{Syntax of a Ratio}.
224
@node Printing Floats, Printing Complexes, Printing Ratios, Default Print-Object Methods
225
@subsubsection Printing Floats
229
If the magnitude of the @i{float} is either zero or between 10^@r{-3} (inclusive)
230
and 10^7 (exclusive), it is printed as the integer part of the number,
231
then a decimal point,
232
followed by the fractional part of the number;
233
there is always at least one
234
digit on each side of the decimal point.
235
If the sign of the number
236
(as determined by @b{float-sign})
237
is negative, then a minus sign is printed before the number.
238
If the format of the number
239
does not match that specified by
240
@b{*read-default-float-format*}, then the @i{exponent marker} for
241
that format and the digit @t{0} are also printed.
242
For example, the base of the natural logarithms as a @i{short float}
243
might be printed as @t{2.71828S0}.
245
For non-zero magnitudes outside of the range 10^@r{-3} to 10^7,
246
a @i{float} is printed in computerized scientific notation.
247
The representation of the number is scaled to be between
248
1 (inclusive) and 10 (exclusive) and then printed, with one digit
249
before the decimal point and at least one digit after the decimal point.
250
Next the @i{exponent marker} for the format is printed,
252
if the format of the number matches that specified by
253
@b{*read-default-float-format*}, then the @i{exponent marker} @t{E}
255
Finally, the power of ten by which the fraction must be multiplied
256
to equal the original number is printed as a decimal integer.
257
For example, Avogadro's number as a @i{short float}
258
is printed as @t{6.02S23}.
260
For related information about the syntax of a @i{float},
261
see @ref{Syntax of a Float}.
263
@node Printing Complexes, Note about Printing Numbers, Printing Floats, Default Print-Object Methods
264
@subsubsection Printing Complexes
268
A @i{complex} is printed as @t{#C}, an open parenthesis,
269
the printed representation of its real part, a space,
270
the printed representation of its imaginary part, and finally
273
For related information about the syntax of a @i{complex},
274
see @ref{Syntax of a Complex} and @ref{Sharpsign C}.
276
@node Note about Printing Numbers, Printing Characters, Printing Complexes, Default Print-Object Methods
277
@subsubsection Note about Printing Numbers
279
The printed representation of a number must not contain @i{escape} @i{characters};
280
see @ref{Escape Characters and Potential Numbers}.
282
@node Printing Characters, Printing Symbols, Note about Printing Numbers, Default Print-Object Methods
283
@subsubsection Printing Characters
285
When @i{printer escaping} is disabled,
287
a @i{character} prints as itself;
288
it is sent directly to the output @i{stream}.
290
When @i{printer escaping} is enabled,
292
then @t{#\} syntax is used.
294
When the printer types out the name of a @i{character},
295
it uses the same table as the @t{#\} @i{reader macro} would use;
296
therefore any @i{character} name that is typed out
297
is acceptable as input (in that @i{implementation}).
298
If a @i{non-graphic} @i{character} has a @i{standardized} @i{name}_5,
299
that @i{name} is preferred over non-standard @i{names}
300
for printing in @t{#\} notation.
301
For the @i{graphic} @i{standard characters},
302
the @i{character} itself is always used
303
for printing in @t{#\} notation---even if
304
the @i{character} also has a @i{name}_5.
306
For details about the @t{#\} @i{reader macro}, see @ref{Sharpsign Backslash}.
308
@node Printing Symbols, Package Prefixes for Symbols, Printing Characters, Default Print-Object Methods
309
@subsubsection Printing Symbols
311
When @i{printer escaping} is disabled,
313
only the characters of the @i{symbol}'s @i{name} are output
315
(but the case in which to print characters in the @i{name} is
316
controlled by @b{*print-case*};
317
see @ref{Effect of Readtable Case on the Lisp Printer}).
319
The remainder of this section applies only
321
when @i{printer escaping} is enabled.
323
When printing a @i{symbol}, the printer inserts enough
324
@i{single escape} and/or @i{multiple escape}
325
characters (@i{backslashes} and/or @i{vertical-bars}) so that if
326
@b{read} were called with the same @b{*readtable*} and
327
with @b{*read-base*} bound to the @i{current output base}, it
328
would return the same @i{symbol} (if it is not
329
@i{apparently uninterned}) or an @i{uninterned} @i{symbol}
330
with the same @i{print name} (otherwise).
332
For example, if the @i{value} of @b{*print-base*} were @t{16}
333
when printing the symbol @t{face}, it would have to be printed as
334
@t{\FACE} or @t{\Face} or @t{|FACE|},
335
because the token @t{face} would be read as a hexadecimal
336
number (decimal value 64206) if the @i{value} of @b{*read-base*} were @t{16}.
338
For additional restrictions concerning characters with nonstandard
339
@i{syntax types} in the @i{current readtable}, see the @i{variable} @b{*print-readably*}
341
For information about how the @i{Lisp reader} parses @i{symbols},
342
see @ref{Symbols as Tokens} and @ref{Sharpsign Colon}.
344
@b{nil} might be printed as @t{()}
346
when @b{*print-pretty*} is @i{true}
347
and @i{printer escaping} is enabled.
349
@node Package Prefixes for Symbols, Effect of Readtable Case on the Lisp Printer, Printing Symbols, Default Print-Object Methods
350
@subsubsection Package Prefixes for Symbols
352
@i{Package prefixes} are printed if necessary.
353
The rules for @i{package prefixes} are as follows.
354
When the @i{symbol} is printed, if it is in the @t{KEYWORD} @i{package},
355
then it is printed with a preceding @i{colon}; otherwise, if
356
it is @i{accessible} in the @i{current package}, it is printed without any
357
@i{package prefix}; otherwise, it is printed with a @i{package prefix}.
359
A @i{symbol} that is @i{apparently uninterned} is printed
360
preceded by ``@t{#:}''
362
if @b{*print-gensym*} is @i{true} and @i{printer escaping} is enabled;
363
if @b{*print-gensym*} is @i{false} or @i{printer escaping} is disabled,
365
then the @i{symbol} is printed without a prefix,
366
as if it were in the @i{current package}.
368
Because the @t{#:} syntax does not intern the
369
following symbol, it is necessary to use circular-list syntax
370
if @b{*print-circle*} is @i{true} and
371
the same uninterned symbol appears several times in an expression
372
to be printed. For example, the result of
375
(let ((x (make-symbol "FOO"))) (list x x))
378
would be printed as @t{(#:foo #:foo)} if @b{*print-circle*}
379
were @i{false}, but as @t{(#1=#:foo #1#)} if @b{*print-circle*}
382
A summary of the preceding package prefix rules follows:
387
@t{foo:bar} is printed when @i{symbol} @t{bar}
388
is external in its @i{home package} @t{foo}
389
and is not @i{accessible} in the @i{current package}.
392
@t{foo::bar} is printed when @t{bar} is internal in its @i{home package}
393
@t{foo} and is not @i{accessible} in the @i{current package}.
396
@t{:bar} is printed when the home package of @t{bar} is the @t{KEYWORD} @i{package}.
399
@t{#:bar} is printed when @t{bar} is @i{apparently uninterned},
400
even in the pathological case that @t{bar}
401
has no @i{home package} but is nevertheless somehow @i{accessible}
402
in the @i{current package}.
405
@node Effect of Readtable Case on the Lisp Printer, Examples of Effect of Readtable Case on the Lisp Printer, Package Prefixes for Symbols, Default Print-Object Methods
406
@subsubsection Effect of Readtable Case on the Lisp Printer
409
@i{printer escaping} is disabled,
410
or the characters under consideration are not already
411
quoted specifically by @i{single escape} or @i{multiple escape}
414
the @i{readtable case} of the @i{current readtable}
415
affects the way the @i{Lisp printer} writes @i{symbols}
416
in the following ways:
421
When the @i{readtable case} is @t{:upcase},
422
@i{uppercase} @i{characters}
423
are printed in the case specified by @b{*print-case*}, and
424
@i{lowercase} @i{characters} are printed in their own case.
427
When the @i{readtable case} is @t{:downcase},
428
@i{uppercase} @i{characters} are printed in their own case, and
429
@i{lowercase} @i{characters}
430
are printed in the case specified by @b{*print-case*}.
433
When the @i{readtable case} is @t{:preserve},
434
all @i{alphabetic} @i{characters} are printed in their own case.
437
When the @i{readtable case} is @t{:invert},
438
the case of all @i{alphabetic} @i{characters}
439
in single case symbol names is inverted.
440
Mixed-case symbol names are printed as is.
443
The rules for escaping @i{alphabetic} @i{characters} in symbol names are affected by
444
the @b{readtable-case}
446
if @i{printer escaping} is enabled.
448
@i{Alphabetic} @i{characters} are escaped as follows:
452
When the @i{readtable case} is @t{:upcase},
453
all @i{lowercase} @i{characters} must be escaped.
456
When the @i{readtable case} is @t{:downcase},
457
all @i{uppercase} @i{characters} must be escaped.
460
When the @i{readtable case} is @t{:preserve},
461
no @i{alphabetic} @i{characters} need be escaped.
464
When the @i{readtable case} is @t{:invert},
465
no @i{alphabetic} @i{characters} need be escaped.
469
@node Examples of Effect of Readtable Case on the Lisp Printer, Printing Strings, Effect of Readtable Case on the Lisp Printer, Default Print-Object Methods
470
@subsubsection Examples of Effect of Readtable Case on the Lisp Printer
473
(defun test-readtable-case-printing ()
474
(let ((*readtable* (copy-readtable nil))
475
(*print-case* *print-case*))
476
(format t "READTABLE-CASE *PRINT-CASE* Symbol-name Output~
479
(dolist (readtable-case '(:upcase :downcase :preserve :invert))
480
(setf (readtable-case *readtable*) readtable-case)
481
(dolist (print-case '(:upcase :downcase :capitalize))
482
(dolist (symbol '(|ZEBRA| |Zebra| |zebra|))
483
(setq *print-case* print-case)
484
(format t "~&:~A~15T:~A~29T~A~42T~A"
485
(string-upcase readtable-case)
486
(string-upcase print-case)
488
(prin1-to-string symbol)))))))
491
The output from @t{(test-readtable-case-printing)} should be as follows:
494
READTABLE-CASE *PRINT-CASE* Symbol-name Output
495
--------------------------------------------------
496
:UPCASE :UPCASE ZEBRA ZEBRA
497
:UPCASE :UPCASE Zebra |Zebra|
498
:UPCASE :UPCASE zebra |zebra|
499
:UPCASE :DOWNCASE ZEBRA zebra
500
:UPCASE :DOWNCASE Zebra |Zebra|
501
:UPCASE :DOWNCASE zebra |zebra|
502
:UPCASE :CAPITALIZE ZEBRA Zebra
503
:UPCASE :CAPITALIZE Zebra |Zebra|
504
:UPCASE :CAPITALIZE zebra |zebra|
505
:DOWNCASE :UPCASE ZEBRA |ZEBRA|
506
:DOWNCASE :UPCASE Zebra |Zebra|
507
:DOWNCASE :UPCASE zebra ZEBRA
508
:DOWNCASE :DOWNCASE ZEBRA |ZEBRA|
509
:DOWNCASE :DOWNCASE Zebra |Zebra|
510
:DOWNCASE :DOWNCASE zebra zebra
511
:DOWNCASE :CAPITALIZE ZEBRA |ZEBRA|
512
:DOWNCASE :CAPITALIZE Zebra |Zebra|
513
:DOWNCASE :CAPITALIZE zebra Zebra
514
:PRESERVE :UPCASE ZEBRA ZEBRA
515
:PRESERVE :UPCASE Zebra Zebra
516
:PRESERVE :UPCASE zebra zebra
517
:PRESERVE :DOWNCASE ZEBRA ZEBRA
518
:PRESERVE :DOWNCASE Zebra Zebra
519
:PRESERVE :DOWNCASE zebra zebra
520
:PRESERVE :CAPITALIZE ZEBRA ZEBRA
521
:PRESERVE :CAPITALIZE Zebra Zebra
522
:PRESERVE :CAPITALIZE zebra zebra
523
:INVERT :UPCASE ZEBRA zebra
524
:INVERT :UPCASE Zebra Zebra
525
:INVERT :UPCASE zebra ZEBRA
526
:INVERT :DOWNCASE ZEBRA zebra
527
:INVERT :DOWNCASE Zebra Zebra
528
:INVERT :DOWNCASE zebra ZEBRA
529
:INVERT :CAPITALIZE ZEBRA zebra
530
:INVERT :CAPITALIZE Zebra Zebra
531
:INVERT :CAPITALIZE zebra ZEBRA
534
@node Printing Strings, Printing Lists and Conses, Examples of Effect of Readtable Case on the Lisp Printer, Default Print-Object Methods
535
@subsubsection Printing Strings
537
The characters of the @i{string} are output in order.
539
If @i{printer escaping} is enabled,
541
a @i{double-quote} is output before and after, and all
542
@i{double-quotes} and @i{single escapes} are preceded by @i{backslash}.
543
The printing of @i{strings} is not affected by @b{*print-array*}.
544
Only the @i{active} @i{elements} of the @i{string} are printed.
546
For information on how the @i{Lisp reader} parses @i{strings},
547
see @ref{Double-Quote}.
549
@node Printing Lists and Conses, Printing Bit Vectors, Printing Strings, Default Print-Object Methods
550
@subsubsection Printing Lists and Conses
552
Wherever possible, list notation is preferred over dot notation.
553
Therefore the following algorithm is used to print a @i{cons} x:
558
A @i{left-parenthesis} is printed.
561
The @i{car} of x is printed.
564
If the @i{cdr} of x is itself a @i{cons},
565
it is made to be the current @i{cons}
566
(@i{i.e.}, x becomes that @i{cons}),
571
and step 2 is re-entered.
574
If the @i{cdr} of x is not @i{null},
582
and the @i{cdr} of x are printed.
585
A @i{right-parenthesis} is printed.
588
Actually, the above algorithm is only used when @b{*print-pretty*}
589
is @i{false}. When @b{*print-pretty*} is @i{true} (or
590
when @b{pprint} is used),
591
additional @i{whitespace}_1
592
may replace the use of a single @i{space},
593
and a more elaborate algorithm with similar goals but more presentational
594
flexibility is used; see @ref{Printer Dispatching}.
596
Although the two expressions below are equivalent,
597
and the reader accepts
600
the same @i{cons}, the printer
601
always prints such a @i{cons} in the second form.
604
(a . (b . ((c . (d . nil)) . (e . nil))))
608
The printing of @i{conses} is affected by @b{*print-level*},
609
@b{*print-length*}, and @b{*print-circle*}.
611
Following are examples of printed representations of @i{lists}:
614
(a . b) ;A dotted pair of a and b
615
(a.b) ;A list of one element, the symbol named a.b
616
(a. b) ;A list of two elements a. and b
617
(a .b) ;A list of two elements a and .b
618
(a b . c) ;A dotted list of a and b with c at the end; two conses
619
.iot ;The symbol whose name is .iot
620
(. b) ;Invalid -- an error is signaled if an attempt is made to read
622
(a .) ;Invalid -- an error is signaled.
623
(a .. b) ;Invalid -- an error is signaled.
624
(a . . b) ;Invalid -- an error is signaled.
625
(a b c ...) ;Invalid -- an error is signaled.
626
(a \. b) ;A list of three elements a, ., and b
627
(a |.| b) ;A list of three elements a, ., and b
628
(a \... b) ;A list of three elements a, ..., and b
629
(a |...| b) ;A list of three elements a, ..., and b
632
For information on how the @i{Lisp reader} parses @i{lists} and @i{conses},
633
see @ref{Left-Parenthesis}.
635
@node Printing Bit Vectors, Printing Other Vectors, Printing Lists and Conses, Default Print-Object Methods
636
@subsubsection Printing Bit Vectors
638
A @i{bit vector} is printed as @t{#*} followed by the bits of the @i{bit vector}
639
in order. If @b{*print-array*} is @i{false}, then the @i{bit vector} is
640
printed in a format (using @t{#<}) that is concise but not readable.
641
Only the @i{active} @i{elements} of the @i{bit vector} are printed.
643
[Reviewer Note by Barrett: Need to provide for @t{#5*0} as an alternate
644
notation for @t{#*00000}.]
646
For information on @i{Lisp reader} parsing of @i{bit vectors},
647
see @ref{Sharpsign Asterisk}.
649
@node Printing Other Vectors, Printing Other Arrays, Printing Bit Vectors, Default Print-Object Methods
650
@subsubsection Printing Other Vectors
652
If @b{*print-array*} is @i{true}
653
and @b{*print-readably*} is @i{false},
657
other than a @i{string} or @i{bit vector} is printed using
658
general-vector syntax; this means that information
659
about specialized vector representations does not appear.
660
The printed representation of a zero-length @i{vector} is @t{#()}.
661
The printed representation of a non-zero-length @i{vector} begins with @t{#(}.
662
Following that, the first element of the @i{vector} is printed.
664
If there are any other elements, they are printed in turn, with
665
each such additional element preceded by
666
a @i{space} if @b{*print-pretty*} is @i{false},
667
or @i{whitespace}_1 if @b{*print-pretty*} is @i{true}.
669
A @i{right-parenthesis} after the last element
670
terminates the printed representation of the @i{vector}.
671
The printing of @i{vectors}
672
is affected by @b{*print-level*} and @b{*print-length*}.
673
If the @i{vector} has a @i{fill pointer},
674
then only those elements below
675
the @i{fill pointer} are printed.
677
If both @b{*print-array*} and @b{*print-readably*} are @i{false},
679
the @i{vector} is not printed as described above,
680
but in a format (using @t{#<}) that is concise but not readable.
682
If @b{*print-readably*} is @i{true},
683
the @i{vector} prints in an @i{implementation-defined} manner;
684
see the @i{variable} @b{*print-readably*}.
686
For information on how the @i{Lisp reader} parses these ``other @i{vectors},''
687
see @ref{Sharpsign Left-Parenthesis}.
689
@node Printing Other Arrays, Examples of Printing Arrays, Printing Other Vectors, Default Print-Object Methods
690
@subsubsection Printing Other Arrays
692
If @b{*print-array*} is @i{true}
693
and @b{*print-readably*} is @i{false},
696
@i{array} other than a @i{vector} is printed
697
using @t{#}@t{n}@t{A} format.
698
Let @t{n} be the @i{rank} of the @i{array}.
699
Then @t{#} is printed, then @t{n} as a decimal integer,
700
then @t{A}, then @t{n} open parentheses.
701
Next the @i{elements} are scanned in row-major order,
702
using @b{write} on each @i{element},
703
and separating @i{elements} from each other with @i{whitespace}_1.
704
The array's dimensions are numbered 0 to @t{n}-1 from left to right,
705
and are enumerated with the rightmost index changing fastest.
706
Every time the index for dimension @t{j} is incremented,
707
the following actions are taken:
712
If @t{j} < @t{n}-1, then a close parenthesis is printed.
715
If incrementing the index for dimension @t{j} caused it to equal
716
dimension @t{j}, that index is reset to zero and the
717
index for dimension @t{j}-1 is incremented (thereby performing these three steps recursively),
718
unless @t{j}=0, in which case the entire algorithm is terminated.
719
If incrementing the index for dimension @t{j} did not cause it to
720
equal dimension @t{j}, then a space is printed.
723
If @t{j} < @t{n}-1, then an open parenthesis is printed.
726
This causes the contents to be printed in a format suitable for
727
@t{:initial-contents} to @b{make-array}.
728
The lists effectively printed by this procedure are subject to
729
truncation by @b{*print-level*} and @b{*print-length*}.
732
is of a specialized @i{type}, containing bits or characters,
733
then the innermost lists generated by the algorithm given above can instead
734
be printed using bit-vector or string syntax, provided that these innermost
735
lists would not be subject to truncation by @b{*print-length*}.
737
If both @b{*print-array*} and @b{*print-readably*} are @i{false},
739
then the @i{array} is printed
740
in a format (using @t{#<}) that is concise but not readable.
742
If @b{*print-readably*} is @i{true},
743
the @i{array} prints in an @i{implementation-defined} manner;
744
see the @i{variable} @b{*print-readably*}.
747
this may be important for arrays having some dimension @t{0}.
749
For information on how the @i{Lisp reader} parses these ``other @i{arrays},''
750
see @ref{Sharpsign A}.
752
@node Examples of Printing Arrays, Printing Random States, Printing Other Arrays, Default Print-Object Methods
753
@subsubsection Examples of Printing Arrays
756
(let ((a (make-array '(3 3)))
759
(dotimes (i 3) (dotimes (j 3) (setf (aref a i j) (format nil "<~D,~D>" i j))))
761
(print (make-array 9 :displaced-to a)))
762
@t{ |> } #2A(("<0,0>" "<0,1>" "<0,2>")
763
@t{ |> } ("<1,0>" "<1,1>" "<1,2>")
764
@t{ |> } ("<2,0>" "<2,1>" "<2,2>"))
765
@t{ |> } #("<0,0>" "<0,1>" "<0,2>" "<1,0>" "<1,1>" "<1,2>" "<2,0>" "<2,1>" "<2,2>")
766
@result{} #<ARRAY 9 indirect 36363476>
769
@node Printing Random States, Printing Pathnames, Examples of Printing Arrays, Default Print-Object Methods
770
@subsubsection Printing Random States
772
A specific syntax for printing @i{objects} of @i{type} @b{random-state} is
773
not specified. However, every @i{implementation}
774
must arrange to print a @i{random state} @i{object} in such a way that,
775
within the same implementation, @b{read}
776
can construct from the printed representation a copy of the
778
object as if the copy had been made by @b{make-random-state}.
780
If the type @i{random state} is effectively implemented
781
by using the machinery for @b{defstruct},
782
the usual structure syntax can then be used for printing
784
objects; one might look something like
787
#S(RANDOM-STATE :DATA #(14 49 98436589 786345 8734658324 ... ))
790
where the components are @i{implementation-dependent}.
792
@node Printing Pathnames, Printing Structures, Printing Random States, Default Print-Object Methods
793
@subsubsection Printing Pathnames
795
When @i{printer escaping} is enabled,
797
the syntax @t{#P"..."} is how a
798
@i{pathname} is printed by @b{write} and the other functions herein described.
799
The @t{"..."} is the namestring representation of the pathname.
801
When @i{printer escaping} is disabled,
803
@b{write} writes a @i{pathname} @i{P}
804
by writing @t{(namestring @i{P})} instead.
806
For information on how the @i{Lisp reader} parses @i{pathnames},
807
see @ref{Sharpsign P}.
809
@node Printing Structures, Printing Other Objects, Printing Pathnames, Default Print-Object Methods
810
@subsubsection Printing Structures
812
By default, a @i{structure} of type S is printed using @t{#S} syntax.
813
This behavior can be customized by specifying a @t{:print-function}
814
or @t{:print-object} option to the @b{defstruct} @i{form} that defines S,
815
or by writing a @b{print-object} @i{method}
816
that is @i{specialized} for @i{objects} of type S.
818
Different structures might print out in different ways;
819
the default notation for structures is:
822
#S(@i{structure-name} @{@i{slot-key} @i{slot-value}@}*)
825
where @t{#S} indicates structure syntax,
826
@i{structure-name} is a @i{structure name},
827
each @i{slot-key} is an initialization argument @i{name}
828
for a @i{slot} in the @i{structure},
829
and each corresponding @i{slot-value} is a representation
830
of the @i{object} in that @i{slot}.
832
For information on how the @i{Lisp reader} parses @i{structures},
833
see @ref{Sharpsign S}.
835
@node Printing Other Objects, , Printing Structures, Default Print-Object Methods
836
@subsubsection Printing Other Objects
838
Other @i{objects} are printed in an @i{implementation-dependent} manner.
839
It is not required that an @i{implementation} print those @i{objects}
842
For example, @i{hash tables},
847
might not print @i{readably}.
849
A common notation to use in this circumstance is @t{#<...>}.
850
Since @t{#<} is not readable by the @i{Lisp reader},
851
the precise format of the text which follows is not important,
852
but a common format to use is that provided by the @b{print-unreadable-object} @i{macro}.
854
For information on how the @i{Lisp reader} treats this notation,
855
see @ref{Sharpsign Less-Than-Sign}.
856
For information on how to notate @i{objects} that cannot be printed @i{readably},
857
see @ref{Sharpsign Dot}.
859
@node Examples of Printer Behavior, , Default Print-Object Methods, The Lisp Printer
860
@subsection Examples of Printer Behavior
863
(let ((*print-escape* t)) (fresh-line) (write #\a))
866
(let ((*print-escape* nil) (*print-readably* nil))
871
(progn (fresh-line) (prin1 #\a))
874
(progn (fresh-line) (print #\a))
878
(progn (fresh-line) (princ #\a))
882
(dolist (val '(t nil))
883
(let ((*print-escape* val) (*print-readably* val))
885
(prin1 #\a) (write-char #\Space)
886
(princ #\a) (write-char #\Space)
888
@t{ |> } #\a #\a a #\a
892
(progn (fresh-line) (write '(let ((a 1) (b 2)) (+ a b))))
893
@t{ |> } (LET ((A 1) (B 2)) (+ A B))
894
@result{} (LET ((A 1) (B 2)) (+ A B))
896
(progn (fresh-line) (pprint '(let ((a 1) (b 2)) (+ a b))))
900
@result{} (LET ((A 1) (B 2)) (+ A B))
903
(write '(let ((a 1) (b 2)) (+ a b)) :pretty t))
907
@result{} (LET ((A 1) (B 2)) (+ A B))
909
(with-output-to-string (s)
910
(write 'write :stream s)
912
@result{} "WRITEPRIN1"
915
@c end of including concept-print
917
@node The Lisp Pretty Printer, Formatted Output, The Lisp Printer, Printer
918
@section The Lisp Pretty Printer
920
@c including concept-pprint
923
* Pretty Printer Concepts::
924
* Examples of using the Pretty Printer::
925
* Notes about the Pretty Printer`s Background::
928
@node Pretty Printer Concepts, Examples of using the Pretty Printer, The Lisp Pretty Printer, The Lisp Pretty Printer
929
@subsection Pretty Printer Concepts
931
The facilities provided by the @i{pretty printer}
932
@IGindex{pretty printer}
934
@i{programs} to redefine the way in which @i{code} is displayed,
935
and allow the full power of @i{pretty printing} to be applied
936
to complex combinations of data structures.
938
Whether any given style of output is in fact ``pretty'' is inherently a
939
somewhat subjective issue. However, since the effect of the
940
@i{pretty printer} can be customized by @i{conforming programs},
941
the necessary flexibility is provided for individual @i{programs}
942
to achieve an arbitrary degree of aesthetic control.
944
By providing direct access to the mechanisms within the pretty printer
945
that make dynamic decisions about layout, the macros and functions
946
@b{pprint-logical-block}, @b{pprint-newline}, and
947
@b{pprint-indent} make it possible to specify pretty printing
948
layout rules as a part of any function that produces output. They also
949
make it very easy for the detection of circularity and sharing, and
950
abbreviation based on length and nesting depth to be supported by the
953
The @i{pretty printer} is driven entirely by dispatch based on
954
the @i{value} of @b{*print-pprint-dispatch*}.
955
The @i{function} @b{set-pprint-dispatch} makes it possible
956
for @i{conforming programs} to associate new pretty printing
957
functions with a @i{type}.
960
* Dynamic Control of the Arrangement of Output::
961
* Format Directive Interface::
962
* Compiling Format Strings::
963
* Pretty Print Dispatch Tables::
964
* Pretty Printer Margins::
967
@node Dynamic Control of the Arrangement of Output, Format Directive Interface, Pretty Printer Concepts, Pretty Printer Concepts
968
@subsubsection Dynamic Control of the Arrangement of Output
970
The actions of the @i{pretty printer} when a piece of output is too
971
large to fit in the space available can be precisely controlled.
972
Three concepts underlie
973
the way these operations work---@i{logical blocks}
974
@IGindex{logical blocks}
976
@i{conditional newlines}
977
@IGindex{conditional newlines}
982
Before proceeding further, it is important to define these terms.
984
The first line of Figure 22--3 shows a schematic piece of output. Each of
985
the characters in the output is represented by ``@t{-}''. The positions of
986
conditional newlines are indicated by digits. The beginnings and ends of
987
logical blocks are indicated by ``@t{<}'' and ``@t{>}'' respectively.
989
The output as a whole is a logical block and the outermost section. This
990
section is indicated by the @t{0}'s on the second line of Figure 1. Logical
991
blocks nested within the output are specified by the macro
992
@b{pprint-logical-block}. Conditional newline positions are specified
993
by calls to @b{pprint-newline}. Each conditional newline defines
994
two sections (one before it and one after it) and is associated with a
995
third (the section immediately containing it).
997
The section after a conditional newline consists of: all the output up to,
998
but not including, (a) the next conditional newline immediately contained
999
in the same logical block; or if (a) is not applicable, (b) the next
1000
newline that is at a lesser level of nesting in logical blocks; or if (b)
1001
is not applicable, (c) the end of the output.
1003
The section before a conditional newline consists of: all the output back
1004
to, but not including, (a) the previous conditional newline that is
1005
immediately contained in the same logical block; or if (a) is not
1006
applicable, (b) the beginning of the immediately containing logical block.
1007
The last four lines in Figure 1 indicate the sections before and after the
1008
four conditional newlines.
1010
The section immediately containing a conditional newline is the shortest
1011
section that contains the conditional newline in question. In Figure 22--3,
1012
the first conditional newline is immediately contained in the section
1013
marked with @t{0}'s, the second and third conditional newlines are immediately
1014
contained in the section before the fourth conditional newline, and the
1015
fourth conditional newline is immediately contained in the section after
1016
the first conditional newline.
1019
<-1---<--<--2---3->--4-->->
1020
000000000000000000000000000
1021
11 111111111111111111111111
1024
44444444444444 44444
1027
@w{ Figure 22--2: Example of Logical Blocks, Conditional Newlines, and Sections}
1029
Whenever possible, the pretty printer displays the entire contents of a
1030
section on a single line. However, if the section is too long to fit in
1031
the space available, line breaks are inserted at conditional newline
1032
positions within the section.
1034
@node Format Directive Interface, Compiling Format Strings, Dynamic Control of the Arrangement of Output, Pretty Printer Concepts
1035
@subsubsection Format Directive Interface
1037
The primary interface to operations for dynamically determining the
1038
arrangement of output is provided through the functions and macros of the
1039
pretty printer. Figure 22--3 shows the defined names related to @i{pretty printing}.
1044
@w{ *print-lines* pprint-dispatch pprint-pop }
1045
@w{ *print-miser-width* pprint-exit-if-list-exhausted pprint-tab }
1046
@w{ *print-pprint-dispatch* pprint-fill pprint-tabular }
1047
@w{ *print-right-margin* pprint-indent set-pprint-dispatch }
1048
@w{ copy-pprint-dispatch pprint-linear write }
1049
@w{ format pprint-logical-block }
1050
@w{ formatter pprint-newline }
1053
@w{ Figure 22--3: Defined names related to pretty printing. }
1058
Figure 22--4 identifies a set of @i{format directives} which serve
1059
as an alternate interface to the same pretty printing operations in a
1060
more textually compact form.
1065
@w{ @t{~I} @t{~W} @t{~<...~:>} }
1066
@w{ @t{~:T} @t{~/.../} @t{~_} }
1069
@w{ Figure 22--4: Format directives related to Pretty Printing}
1074
@node Compiling Format Strings, Pretty Print Dispatch Tables, Format Directive Interface, Pretty Printer Concepts
1075
@subsubsection Compiling Format Strings
1077
A @i{format string} is essentially a program in a special-purpose language
1078
that performs printing, and that is interpreted by the @i{function} @b{format}.
1079
The @b{formatter} @i{macro} provides the efficiency of using a @i{compiled function}
1080
to do that same printing but without losing the textual compactness of @i{format strings}.
1082
A @i{format control}
1083
@IGindex{format control}
1084
is either a @i{format string} or a @i{function}
1085
that was returned by the the @b{formatter} @i{macro}.
1087
@node Pretty Print Dispatch Tables, Pretty Printer Margins, Compiling Format Strings, Pretty Printer Concepts
1088
@subsubsection Pretty Print Dispatch Tables
1090
A @i{pprint dispatch table}
1091
@IGindex{pprint dispatch table}
1092
is a mapping from keys to pairs of values.
1093
Each key is a @i{type specifier}.
1094
The values associated with a key are
1095
a ``function'' (specifically, a @i{function designator} or @b{nil})
1096
and a ``numerical priority'' (specifically, a @i{real}).
1097
Basic insertion and retrieval is done based on the keys with the equality
1098
of keys being tested by @b{equal}.
1100
When @b{*print-pretty*} is @i{true},
1101
the @i{current pprint dispatch table}
1102
@IGindex{current pprint dispatch table}
1103
(in @b{*print-pprint-dispatch*})
1104
controls how @i{objects} are printed.
1105
The information in this table takes precedence over
1106
all other mechanisms for specifying how to print @i{objects}.
1109
user-defined @b{print-object} @i{methods}
1111
because the @i{current pprint dispatch table} is consulted first.
1113
The function is chosen from the @i{current pprint dispatch table}
1114
by finding the highest priority function
1115
that is associated with a @i{type specifier} that matches the @i{object};
1116
if there is more than one such function,
1117
it is @i{implementation-dependent} which is used.
1119
However, if there is no
1120
information in the table
1121
about how to @i{pretty print} a particular kind of @i{object},
1122
a @i{function} is invoked which uses @b{print-object} to print the @i{object}.
1123
The value of @b{*print-pretty*} is still @i{true}
1124
when this function is @i{called},
1125
and individual methods for @b{print-object} might still elect to
1126
produce output in a special format conditional on the @i{value} of @b{*print-pretty*}.
1128
@node Pretty Printer Margins, , Pretty Print Dispatch Tables, Pretty Printer Concepts
1129
@subsubsection Pretty Printer Margins
1131
A primary goal of pretty printing is to keep the output between a pair of
1133
The column where the output begins is taken as the left margin.
1134
If the current column cannot be determined at the time output begins,
1135
the left margin is assumed to be zero.
1136
The right margin is controlled by @b{*print-right-margin*}.
1138
@node Examples of using the Pretty Printer, Notes about the Pretty Printer`s Background, Pretty Printer Concepts, The Lisp Pretty Printer
1139
@subsection Examples of using the Pretty Printer
1141
As an example of the interaction of logical blocks, conditional newlines,
1142
and indentation, consider the function @t{simple-pprint-defun} below. This
1143
function prints out lists whose @i{cars} are @b{defun} in the
1144
standard way assuming that the list has exactly length @t{4}.
1147
(defun simple-pprint-defun (*standard-output* list)
1148
(pprint-logical-block (*standard-output* list :prefix "(" :suffix ")")
1149
(write (first list))
1150
(write-char #\Space)
1151
(pprint-newline :miser)
1152
(pprint-indent :current 0)
1153
(write (second list))
1154
(write-char #\Space)
1155
(pprint-newline :fill)
1156
(write (third list))
1157
(pprint-indent :block 1)
1158
(write-char #\Space)
1159
(pprint-newline :linear)
1160
(write (fourth list))))
1163
Suppose that one evaluates the following:
1166
(simple-pprint-defun *standard-output* '(defun prod (x y) (* x y)))
1169
If the line width available is greater than or equal to @t{26}, then all of the
1170
output appears on one line. If the line width available is reduced to @t{25},
1171
a line break is inserted at the
1172
linear-style conditional newline
1173
@ITindex{linear-style conditional newline}
1176
@i{expression} @t{(* x y)}, producing the output shown. The
1177
@t{(pprint-indent :block 1)} causes @t{(* x y)} to be printed at a relative
1178
indentation of @t{1} in the logical block.
1185
If the line width available is @t{15}, a line break is also inserted at the
1186
fill style conditional newline before the argument list. The call on
1187
@t{(pprint-indent :current 0)} causes the argument list to line up under the
1196
If @b{*print-miser-width*} were greater than or equal to 14, the example
1197
output above would have been as follows, because all indentation changes
1198
are ignored in miser mode and line breaks are inserted at
1199
miser-style conditional newlines.
1200
@ITindex{miser-style conditional newline}
1209
As an example of a per-line prefix, consider that evaluating the following
1210
produces the output shown with a line width of @t{20} and
1211
@b{*print-miser-width*} of @b{nil}.
1214
(pprint-logical-block (*standard-output* nil :per-line-prefix ";;; ")
1215
(simple-pprint-defun *standard-output* '(defun prod (x y) (* x y))))
1222
As a more complex (and realistic) example, consider the function @t{pprint-let}
1223
below. This specifies how to print a @b{let} @i{form} in the traditional
1224
style. It is more complex than the example above, because it has to deal with
1225
nested structure. Also, unlike the example above it contains complete code to
1226
readably print any possible list that begins with the @i{symbol} @b{let}.
1227
The outermost @b{pprint-logical-block} @i{form} handles the printing of
1228
the input list as a whole and specifies that parentheses should be printed in the
1229
output. The second @b{pprint-logical-block} @i{form} handles the list
1230
of binding pairs. Each pair in the list is itself printed by the innermost
1231
@b{pprint-logical-block}. (A @b{loop} @i{form} is used instead of
1232
merely decomposing the pair into two @i{objects} so that readable output will
1233
be produced no matter whether the list corresponding to the pair has one element,
1234
two elements, or (being malformed) has more than two elements.)
1236
fill-style conditional newline
1237
@ITindex{fill-style conditional newline}
1240
each pair except the last. The loop at the end of the topmost
1241
@b{pprint-logical-block} @i{form} prints out the forms in the body
1242
of the @b{let} @i{form} separated by spaces and
1243
linear-style conditional newlines.
1246
(defun pprint-let (*standard-output* list)
1247
(pprint-logical-block (nil list :prefix "(" :suffix ")")
1248
(write (pprint-pop))
1249
(pprint-exit-if-list-exhausted)
1250
(write-char #\Space)
1251
(pprint-logical-block (nil (pprint-pop) :prefix "(" :suffix ")")
1252
(pprint-exit-if-list-exhausted)
1253
(loop (pprint-logical-block (nil (pprint-pop) :prefix "(" :suffix ")")
1254
(pprint-exit-if-list-exhausted)
1255
(loop (write (pprint-pop))
1256
(pprint-exit-if-list-exhausted)
1257
(write-char #\Space)
1258
(pprint-newline :linear)))
1259
(pprint-exit-if-list-exhausted)
1260
(write-char #\Space)
1261
(pprint-newline :fill)))
1262
(pprint-indent :block 1)
1263
(loop (pprint-exit-if-list-exhausted)
1264
(write-char #\Space)
1265
(pprint-newline :linear)
1266
(write (pprint-pop)))))
1269
Suppose that one evaluates the following with @b{*print-level*} being 4,
1270
and @b{*print-circle*} being @i{true}.
1273
(pprint-let *standard-output*
1274
'#1=(let (x (*print-length* (f (g 3)))
1275
(z . 2) (k (car y)))
1276
(setq x (sqrt z)) #1#))
1279
If the line length is greater than or equal to @t{77}, the output produced
1280
appears on one line. However, if the line length is @t{76}, line breaks are
1281
inserted at the linear-style conditional newlines separating the forms in
1282
the body and the output below is produced. Note that, the degenerate
1283
binding pair @t{x} is printed readably even though it fails to be a list; a
1284
depth abbreviation marker is printed in place of @t{(g 3)}; the binding pair
1285
@t{(z . 2)} is printed readably even though it is not a proper list; and
1286
appropriate circularity markers are printed.
1289
#1=(LET (X (*PRINT-LENGTH* (F #)) (Z . 2) (K (CAR Y)))
1294
If the line length is reduced to @t{35}, a line break is inserted at one of the
1295
fill-style conditional newlines separating the binding pairs.
1298
#1=(LET (X (*PRINT-PRETTY* (F #))
1299
(Z . 2) (K (CAR Y)))
1304
Suppose that the line length is further reduced to @t{22} and @b{*print-length*} is
1305
set to @t{3}. In this situation, line breaks are inserted after both the first
1306
and second binding pairs. In addition, the second binding pair is itself
1307
broken across two lines. Clause (b) of the description of fill-style
1308
conditional newlines (see the @i{function} @b{pprint-newline})
1309
prevents the binding pair @t{(z . 2)} from being printed
1310
at the end of the third line. Note that the length abbreviation hides the
1311
circularity from view and therefore the printing of circularity markers
1323
The next function prints a vector using ``@t{#(...)}'' notation.
1326
(defun pprint-vector (*standard-output* v)
1327
(pprint-logical-block (nil nil :prefix "#(" :suffix ")")
1328
(let ((end (length v)) (i 0))
1332
(if (= (incf i) end) (return nil))
1333
(write-char #\Space)
1334
(pprint-newline :fill))))))
1337
Evaluating the following with a line length of 15 produces the output shown.
1340
(pprint-vector *standard-output* '#(12 34 567 8 9012 34 567 89 0 1 23))
1347
As examples of the convenience of specifying pretty printing with
1348
@i{format strings}, consider that the functions @t{simple-pprint-defun}
1349
and @t{pprint-let} used as examples above can be compactly defined as follows.
1350
(The function @t{pprint-vector} cannot be defined using @b{format}
1351
because the data structure it traverses is not a list.)
1354
(defun simple-pprint-defun (*standard-output* list)
1355
(format T "~:<~W ~@@_~:I~W ~:_~W~1I ~_~W~:>" list))
1357
(defun pprint-let (*standard-output* list)
1358
(format T "~:<~W~@t{^}~:<~@@@{~:<~@@@{~W~@t{^}~_~@}~:>~@t{^}~:_~@}~:>~1I~@@@{~@t{^}~_~W~@}~:>" list))
1361
In the following example, the first @i{form} restores
1362
@b{*print-pprint-dispatch*} to the equivalent of its initial value.
1363
The next two forms then set up a special way to pretty print ratios.
1364
Note that the more specific @i{type specifier} has to be associated
1365
with a higher priority.
1368
(setq *print-pprint-dispatch* (copy-pprint-dispatch nil))
1370
(set-pprint-dispatch 'ratio
1372
(format s "#.(/ ~W ~W)"
1373
(numerator obj) (denominator obj))))
1375
(set-pprint-dispatch '(and ratio (satisfies minusp))
1377
(format s "#.(- (/ ~W ~W))"
1378
(- (numerator obj)) (denominator obj)))
1381
(pprint '(1/3 -2/3))
1382
(#.(/ 1 3) #.(- (/ 2 3)))
1385
The following two @i{forms} illustrate the definition of
1386
pretty printing functions for types of @i{code}. The first
1387
@i{form} illustrates how to specify the traditional method
1388
for printing quoted objects using @i{single-quote}. Note
1389
the care taken to ensure that data lists that happen to begin
1390
with @b{quote} will be printed readably. The second form
1391
specifies that lists beginning with the symbol @t{my-let}
1392
should print the same way that lists beginning with @b{let}
1393
print when the initial @i{pprint dispatch table} is in effect.
1396
(set-pprint-dispatch '(cons (member quote)) ()
1398
(if (and (consp (cdr list)) (null (cddr list)))
1399
(funcall (formatter "'~W") s (cadr list))
1400
(pprint-fill s list))))
1402
(set-pprint-dispatch '(cons (member my-let))
1403
(pprint-dispatch '(let) nil))
1406
The next example specifies a default method for printing lists that do not
1407
correspond to function calls. Note that the functions @b{pprint-linear},
1408
@b{pprint-fill}, and @b{pprint-tabular} are all defined with
1409
optional @i{colon-p} and @i{at-sign-p} arguments so that they can
1410
be used as @b{pprint dispatch functions} as well as @t{~/.../}
1414
(set-pprint-dispatch '(cons (not (and symbol (satisfies fboundp))))
1417
;; Assume a line length of 9
1418
(pprint '(0 b c d e f g h i j k))
1424
This final example shows how to define a pretty printing function for a
1425
user defined data structure.
1428
(defstruct family mom kids)
1430
(set-pprint-dispatch 'family
1432
(funcall (formatter "~@@<#<~;~W and ~2I~_~/pprint-fill/~;>~:>")
1433
s (family-mom f) (family-kids f))))
1436
The pretty printing function for the structure @t{family} specifies how to
1437
adjust the layout of the output so that it can fit aesthetically into
1438
a variety of line widths. In addition, it obeys
1439
the printer control variables @b{*print-level*},
1440
@b{*print-length*}, @b{*print-lines*},
1442
and @b{*print-escape*},
1443
and can tolerate several different kinds of malformity in the data structure.
1444
The output below shows what is printed out with a right margin of @t{25},
1445
@b{*print-pretty*} being @i{true}, @b{*print-escape*} being @i{false},
1446
and a malformed @t{kids} list.
1449
(write (list 'principal-family
1450
(make-family :mom "Lucy"
1451
:kids '("Mark" "Bob" . "Dan")))
1452
:right-margin 25 :pretty T :escape nil :miser-width nil)
1458
Note that a pretty printing function for a structure is different from
1459
the structure's @b{print-object} @i{method}.
1461
@b{print-object} @i{methods}
1462
are permanently associated with a structure,
1463
pretty printing functions are stored in
1464
@i{pprint dispatch tables} and can be rapidly changed to reflect
1465
different printing needs. If there is no pretty printing function for
1466
a structure in the current @i{pprint dispatch table},
1467
its @b{print-object} @i{method}
1470
@node Notes about the Pretty Printer`s Background, , Examples of using the Pretty Printer, The Lisp Pretty Printer
1471
@subsection Notes about the Pretty Printer`s Background
1473
For a background reference to the abstract concepts detailed in this
1474
section, see @i{XP: A Common Lisp Pretty Printing System}. The details of that paper are not binding on
1475
this document, but may be helpful in establishing a conceptual basis for
1476
understanding this material.
1478
@c end of including concept-pprint
1480
@node Formatted Output, Printer Dictionary, The Lisp Pretty Printer, Printer
1481
@section Formatted Output
1483
@c including concept-format
1485
[Editorial Note by KMP: This is transplanted from FORMAT and will need a bit of work before
1486
it looks good standing alone. Bear with me.]
1488
@b{format} is useful for producing nicely formatted text, producing
1489
good-looking messages, and so on. @b{format} can generate and return
1490
a @i{string} or output to @i{destination}.
1492
The @i{control-string} argument to @b{format} is actually a @i{format control}.
1493
That is, it can be either a @i{format string} or a @i{function},
1494
for example a @i{function} returned
1495
by the @b{formatter} @i{macro}.
1497
If it is a @i{function}, the @i{function} is called with the appropriate
1498
output stream as its first argument and the data arguments to @b{format}
1499
as its remaining arguments. The function should perform whatever output is
1500
necessary and return the unused tail of the arguments (if any).
1502
The compilation process performed by @b{formatter} produces a @i{function}
1503
that would do with its @i{arguments} as the @b{format} interpreter
1504
would do with those @i{arguments}.
1506
The remainder of this section describes what happens if the @i{control-string}
1507
is a @i{format string}.
1509
@i{Control-string} is composed of simple text (@i{characters})
1510
and embedded directives.
1512
@b{format} writes the simple text as is;
1513
each embedded directive specifies further text output
1514
that is to appear at the corresponding point within the simple text.
1515
Most directives use one or more elements of @i{args} to
1516
create their output.
1518
A directive consists of a @i{tilde},
1519
optional prefix parameters
1520
separated by commas, optional @i{colon} and @i{at-sign} modifiers,
1521
and a single character indicating what kind of directive this is.
1523
There is no required ordering between the @i{at-sign} and @i{colon} modifier.
1525
The @i{case} of the directive character is ignored.
1526
Prefix parameters are notated as signed (sign is optional) decimal numbers,
1527
or as a @i{single-quote} followed by a character.
1528
For example, @t{~5,'0d} can be used
1529
to print an @i{integer}
1530
in decimal radix in five columns with leading zeros,
1531
or @t{~5,'*d} to get leading asterisks.
1533
In place of a prefix parameter to a directive, @t{V} (or @t{v}) can be used.
1534
In this case, @b{format} takes an argument from @i{args} as a parameter to
1535
the directive. The argument should be an @i{integer} or @i{character}.
1536
If the @i{arg} used by a @t{V} parameter is @b{nil},
1537
the effect is as if the parameter had been omitted.
1538
@t{#} can be used in place of a prefix parameter; it
1539
represents the number of @i{args} remaining to be processed.
1540
When used within a recursive format, in the context of @t{~?} or @t{~@{},
1541
the @t{#} prefix parameter represents the number of @i{format arguments}
1542
remaining within the recursive call.
1544
Examples of @i{format strings}:
1549
@w{ @t{"~S"} ;This is an S directive with no parameters or modifiers. }
1550
@w{ @t{"~3,-4:@@s"} ;This is an S directive with two parameters, @t{3} and @t{-4}, }
1551
@w{ ; and both the @i{colon} and @i{at-sign} flags. }
1552
@w{ @t{"~,+4S"} ;Here the first prefix parameter is omitted and takes }
1553
@w{ ; on its default value, while the second parameter is @t{4}. }
1556
@w{ Figure 22--5: Examples of format control strings }
1561
@b{format} sends the output to @i{destination}.
1562
If @i{destination} is @b{nil},
1563
@b{format} creates and returns a @i{string}
1564
containing the output from @i{control-string}.
1565
If @i{destination} is @i{non-nil},
1566
it must be a @i{string} with a @i{fill pointer},
1567
a @i{stream}, or the symbol @b{t}.
1568
If @i{destination} is a @i{string} with a @i{fill pointer},
1569
the output is added to the end of the @i{string}.
1570
If @i{destination} is a @i{stream},
1571
the output is sent to that @i{stream}.
1572
If @i{destination} is @b{t},
1573
the output is sent to @i{standard output}.
1575
In the description of the directives that follows,
1576
the term @i{arg} in general
1577
refers to the next item of the set of @i{args} to be processed.
1578
The word or phrase at the beginning of each description is a mnemonic
1581
@b{format} directives do not bind any of the printer control
1582
variables (@b{*print-...*}) except as specified in the following
1584
Implementations may specify the binding of new, implementation-specific
1585
printer control variables for each @b{format} directive, but they
1586
may neither bind any standard printer control variables not
1587
specified in description of a @b{format}
1588
directive nor fail to bind
1589
any standard printer control variables as specified in the
1593
* FORMAT Basic Output::
1594
* FORMAT Radix Control::
1595
* FORMAT Floating-Point Printers::
1596
* FORMAT Printer Operations::
1597
* FORMAT Pretty Printer Operations::
1598
* FORMAT Layout Control::
1599
* FORMAT Control-Flow Operations::
1600
* FORMAT Miscellaneous Operations::
1601
* FORMAT Miscellaneous Pseudo-Operations::
1602
* Additional Information about FORMAT Operations::
1603
* Examples of FORMAT::
1604
* Notes about FORMAT::
1607
@node FORMAT Basic Output, FORMAT Radix Control, Formatted Output, Formatted Output
1608
@subsection FORMAT Basic Output
1611
* Tilde C-> Character::
1612
* Tilde Percent-> Newline::
1613
* Tilde Ampersand-> Fresh-Line::
1614
* Tilde Vertical-Bar-> Page::
1615
* Tilde Tilde-> Tilde::
1618
@node Tilde C-> Character, Tilde Percent-> Newline, FORMAT Basic Output, FORMAT Basic Output
1619
@subsubsection Tilde C: Character
1621
The next @i{arg} should be a @i{character};
1623
according to the modifier flags.
1625
@t{~C} prints the @i{character}
1626
as if by using @b{write-char} if it is a @i{simple character}.
1627
@i{Characters} that are not @i{simple}
1628
are not necessarily printed as if by @b{write-char},
1629
but are displayed in an @i{implementation-defined}, abbreviated format.
1633
(format nil "~C" #\A) @result{} "A"
1634
(format nil "~C" #\Space) @result{} " "
1637
@t{~:C} is the same as @t{~C} for @i{printing} @i{characters},
1638
but other @i{characters} are ``spelled out.'' The intent is that this
1639
is a ``pretty'' format for printing characters.
1640
For @i{simple} @i{characters} that are not @i{printing},
1641
what is spelled out is the @i{name} of the @i{character} (see @b{char-name}).
1642
For @i{characters} that are not @i{simple} and not @i{printing},
1643
what is spelled out is @i{implementation-defined}.
1647
(format nil "~:C" #\A) @result{} "A"
1648
(format nil "~:C" #\Space) @result{} "Space"
1649
;; This next example assumes an implementation-defined "Control" attribute.
1650
(format nil "~:C" #\Control-Space)
1651
@result{} "Control-Space"
1652
@i{OR}@result{} "c-Space"
1655
@t{~:@@C} prints what @t{~:C} would, and then
1656
if the @i{character} requires unusual shift keys on the keyboard to type it,
1657
this fact is mentioned. For example,
1660
(format nil "~:@@C" #\Control-Partial) @result{} "Control-\partial (Top-F)"
1663
This is the format used for telling the user about a key he is expected to type,
1664
in prompts, for instance. The precise output may depend not only
1665
on the implementation, but on the particular I/O devices in use.
1668
prints the @i{character} in a way that the @i{Lisp reader} can understand,
1669
using @t{#\} syntax.
1671
@t{~@@C} binds @b{*print-escape*} to @b{t}.
1673
@node Tilde Percent-> Newline, Tilde Ampersand-> Fresh-Line, Tilde C-> Character, FORMAT Basic Output
1674
@subsubsection Tilde Percent: Newline
1676
This outputs a @t{#\Newline} character, thereby terminating the current
1677
output line and beginning a new one.
1678
@t{~@i{n}%} outputs @i{n} newlines.
1681
@node Tilde Ampersand-> Fresh-Line, Tilde Vertical-Bar-> Page, Tilde Percent-> Newline, FORMAT Basic Output
1682
@subsubsection Tilde Ampersand: Fresh-Line
1684
Unless it can be determined that the output stream
1685
is already at the beginning of a line,
1686
this outputs a newline.
1687
@t{~@i{n}&} calls @b{fresh-line}
1688
and then outputs @i{n}- 1 newlines.
1689
@t{~0&} does nothing.
1691
@node Tilde Vertical-Bar-> Page, Tilde Tilde-> Tilde, Tilde Ampersand-> Fresh-Line, FORMAT Basic Output
1692
@subsubsection Tilde Vertical-Bar: Page
1694
This outputs a page separator character, if possible.
1695
@t{~@i{n}|} does this @i{n} times.
1697
@node Tilde Tilde-> Tilde, , Tilde Vertical-Bar-> Page, FORMAT Basic Output
1698
@subsubsection Tilde Tilde: Tilde
1700
This outputs a @i{tilde}. @t{~@i{n}~} outputs @i{n} tildes.
1702
@node FORMAT Radix Control, FORMAT Floating-Point Printers, FORMAT Basic Output, Formatted Output
1703
@subsection FORMAT Radix Control
1707
* Tilde D-> Decimal::
1708
* Tilde B-> Binary::
1710
* Tilde X-> Hexadecimal::
1713
@node Tilde R-> Radix, Tilde D-> Decimal, FORMAT Radix Control, FORMAT Radix Control
1714
@subsubsection Tilde R: Radix
1716
@t{~@i{n}R} prints @i{arg} in radix @i{n}.
1717
The modifier flags and any remaining parameters are used as for
1718
the @t{~D} directive.
1719
@t{~D} is the same as @t{~10R}.
1721
@t{~@i{radix},@i{mincol},@i{padchar},@i{commachar},@i{comma-interval}R}.
1723
If no prefix parameters are given to @t{~R}, then a different
1724
interpretation is given. The argument should be an @i{integer}.
1725
For example, if @i{arg} is 4:
1730
@t{~R} prints @i{arg} as a cardinal English number: @t{four}.
1733
@t{~:R} prints @i{arg} as an ordinal English number: @t{fourth}.
1736
@t{~@@R} prints @i{arg} as a Roman numeral: @t{IV}.
1739
@t{~:@@R} prints @i{arg} as an old Roman numeral: @t{IIII}.
1745
(format nil "~,,' ,4:B" 13) @result{} "1101"
1746
(format nil "~,,' ,4:B" 17) @result{} "1 0001"
1747
(format nil "~19,0,' ,4:B" 3333) @result{} "0000 1101 0000 0101"
1748
(format nil "~3,,,' ,2:R" 17) @result{} "1 22"
1749
(format nil "~,,'|,2:D" #xFFFF) @result{} "6|55|35"
1752
If and only if the first parameter, @i{n}, is supplied,
1754
@b{*print-escape*} to @i{false},
1755
@b{*print-radix*} to @i{false},
1756
@b{*print-base*} to @i{n},
1758
and @b{*print-readably*} to @i{false}.
1760
If and only if no parameters are supplied,
1761
@t{~R} binds @b{*print-base*} to @t{10}.
1763
@node Tilde D-> Decimal, Tilde B-> Binary, Tilde R-> Radix, FORMAT Radix Control
1764
@subsubsection Tilde D: Decimal
1766
An @i{arg}, which should be an @i{integer},
1767
is printed in decimal radix.
1768
@t{~D} will never put a decimal point after the number.
1770
@t{~@i{mincol}D} uses
1771
a column width of @i{mincol}; spaces are inserted on
1772
the left if the number requires fewer than @i{mincol} columns for its digits
1773
and sign. If the number doesn't fit in @i{mincol} columns, additional columns
1776
@t{~@i{mincol},@i{padchar}D} uses @i{padchar} as the pad character
1779
If @i{arg} is not an @i{integer}, it is printed in @t{~A} format and decimal base.
1781
The @t{@@} modifier causes the number's sign to be printed always; the default
1782
is to print it only if the number is negative.
1784
The @t{:} modifier causes commas to be printed between groups of digits;
1785
@i{commachar} may be used to change the character used as the comma.
1787
must be an @i{integer} and defaults to 3. When the @t{:}
1788
modifier is given to any of
1789
these directives, the @i{commachar}
1790
is printed between groups of @i{comma-interval}
1793
Thus the most general form of @t{~D} is
1794
@t{~@i{mincol},@i{padchar},@i{commachar},@i{comma-interval}D}.
1797
@b{*print-escape*} to @i{false},
1798
@b{*print-radix*} to @i{false},
1799
@b{*print-base*} to @t{10},
1801
and @b{*print-readably*} to @i{false}.
1803
@node Tilde B-> Binary, Tilde O-> Octal, Tilde D-> Decimal, FORMAT Radix Control
1804
@subsubsection Tilde B: Binary
1806
This is just like @t{~D} but prints in binary radix (radix 2)
1807
instead of decimal. The full form is therefore
1808
@t{~@i{mincol},@i{padchar},@i{commachar},@i{comma-interval}B}.
1811
@b{*print-escape*} to @i{false},
1812
@b{*print-radix*} to @i{false},
1813
@b{*print-base*} to @t{2},
1815
and @b{*print-readably*} to @i{false}.
1817
@node Tilde O-> Octal, Tilde X-> Hexadecimal, Tilde B-> Binary, FORMAT Radix Control
1818
@subsubsection Tilde O: Octal
1820
This is just like @t{~D} but prints in octal radix (radix 8)
1821
instead of decimal. The full form is therefore
1822
@t{~@i{mincol},@i{padchar},@i{commachar},@i{comma-interval}O}.
1825
@b{*print-escape*} to @i{false},
1826
@b{*print-radix*} to @i{false},
1827
@b{*print-base*} to @t{8},
1829
and @b{*print-readably*} to @i{false}.
1831
@node Tilde X-> Hexadecimal, , Tilde O-> Octal, FORMAT Radix Control
1832
@subsubsection Tilde X: Hexadecimal
1834
This is just like @t{~D} but prints in hexadecimal radix
1835
(radix 16) instead of decimal. The full form is therefore
1836
@t{~@i{mincol},@i{padchar},@i{commachar},@i{comma-interval}X}.
1839
@b{*print-escape*} to @i{false},
1840
@b{*print-radix*} to @i{false},
1841
@b{*print-base*} to @t{16},
1843
and @b{*print-readably*} to @i{false}.
1845
@node FORMAT Floating-Point Printers, FORMAT Printer Operations, FORMAT Radix Control, Formatted Output
1846
@subsection FORMAT Floating-Point Printers
1849
* Tilde F-> Fixed-Format Floating-Point::
1850
* Tilde E-> Exponential Floating-Point::
1851
* Tilde G-> General Floating-Point::
1852
* Tilde Dollarsign-> Monetary Floating-Point::
1855
@node Tilde F-> Fixed-Format Floating-Point, Tilde E-> Exponential Floating-Point, FORMAT Floating-Point Printers, FORMAT Floating-Point Printers
1856
@subsubsection Tilde F: Fixed-Format Floating-Point
1858
The next @i{arg} is printed as a @i{float}.
1860
The full form is @t{~@i{w},@i{d},@i{k},@i{overflowchar},@i{padchar}F}.
1862
is the width of the field to be printed; @i{d} is the number
1863
of digits to print after the decimal point; @i{k} is a scale factor
1864
that defaults to zero.
1866
Exactly @i{w} characters will
1867
be output. First, leading copies of the character @i{padchar}
1868
(which defaults to a space) are printed, if necessary, to pad the
1870
If the @i{arg} is negative, then a minus sign is printed;
1871
if the @i{arg} is not negative, then a plus sign is printed
1872
if and only if the @t{@@}
1873
modifier was supplied. Then a sequence
1874
of digits, containing a single embedded decimal point, is printed;
1875
this represents the magnitude of the value of @i{arg} times 10^@i{k},
1876
rounded to @i{d} fractional digits.
1877
When rounding up and rounding down would produce printed values
1878
equidistant from the scaled value of @i{arg}, then the implementation
1879
is free to use either one. For example, printing the argument
1880
@t{6.375} using the format @t{~4,2F} may correctly produce
1881
either @t{6.37} or @t{6.38}.
1882
Leading zeros are not permitted, except that a single
1883
zero digit is output before the decimal point if the printed value
1884
is less than one, and this single zero digit is not output
1885
at all if @i{w}=@i{d}+1.
1887
If it is impossible to print the value in the required format in a field
1888
of width @i{w}, then one of two actions is taken. If the
1889
parameter @i{overflowchar} is supplied, then @i{w} copies of that
1890
parameter are printed instead of the scaled value of @i{arg}.
1891
If the @i{overflowchar} parameter is omitted, then the scaled value
1892
is printed using more than @i{w} characters, as many more as may be
1895
If the @i{w} parameter is omitted, then the field is of variable width.
1896
In effect, a value is chosen
1897
for @i{w} in such a way that no leading pad characters need to be printed
1898
and exactly @i{d} characters will follow the decimal point.
1899
For example, the directive @t{~,2F} will print exactly
1900
two digits after the decimal point and as many as necessary before the
1903
If the parameter @i{d} is omitted, then there is no constraint
1904
on the number of digits to appear after the decimal point.
1905
A value is chosen for @i{d} in such a way that as many digits
1906
as possible may be printed subject to the width constraint
1907
imposed by the parameter @i{w} and the constraint that no trailing
1908
zero digits may appear in the fraction, except that if the
1909
fraction to be printed is zero, then a single zero digit should
1910
appear after the decimal point if permitted by the width constraint.
1912
If both @i{w} and @i{d} are omitted, then the effect is to print
1913
the value using ordinary free-format output; @b{prin1} uses this format
1914
for any number whose magnitude is either zero or between
1915
10^@r{-3} (inclusive) and 10^7 (exclusive).
1917
If @i{w} is omitted, then if the magnitude of @i{arg} is so large (or, if
1918
@i{d} is also omitted, so small) that more than 100 digits would have to
1919
be printed, then an implementation is free, at its discretion, to print
1920
the number using exponential notation instead, as if by the directive
1921
@t{~E} (with all parameters to @t{~E} defaulted, not
1922
taking their values from the @t{~F} directive).
1924
If @i{arg} is a @i{rational}
1925
number, then it is coerced to be a @i{single float}
1926
and then printed. Alternatively, an implementation is permitted to
1927
process a @i{rational}
1928
number by any other method that has essentially the
1929
same behavior but avoids loss of precision or overflow
1930
because of the coercion. If @i{w} and @i{d} are
1931
not supplied and the number has no exact decimal representation,
1932
for example @t{1/3}, some precision cutoff must be chosen
1933
by the implementation since only a finite number of digits may be printed.
1935
If @i{arg} is a @i{complex} number or some non-numeric
1937
then it is printed using the format directive @t{~@i{w}D},
1938
thereby printing it in decimal radix and a minimum field width of @i{w}.
1941
@b{*print-escape*} to @i{false}
1943
and @b{*print-readably*} to @i{false}.
1945
@node Tilde E-> Exponential Floating-Point, Tilde G-> General Floating-Point, Tilde F-> Fixed-Format Floating-Point, FORMAT Floating-Point Printers
1946
@subsubsection Tilde E: Exponential Floating-Point
1948
The next @i{arg} is printed as a @i{float} in exponential notation.
1951
@t{~@i{w},@i{d},@i{e},@i{k},@i{overflowchar},@i{padchar},@i{exponentchar}E}.
1953
is the width of the field to be printed; @i{d} is the number
1954
of digits to print after the decimal point; @i{e} is the number
1955
of digits to use when printing the exponent;
1956
@i{k} is a scale factor that defaults to one (not zero).
1958
Exactly @i{w} characters will
1959
be output. First, leading copies of the character @i{padchar}
1960
(which defaults to a space) are printed, if necessary, to pad the
1962
If the @i{arg} is negative, then a minus sign is printed;
1963
if the @i{arg} is not negative, then a plus sign is printed
1964
if and only if the @t{@@}
1965
modifier was supplied. Then a sequence
1966
of digits containing a single embedded decimal point is printed.
1967
The form of this sequence of digits depends on the scale factor @i{k}.
1968
If @i{k} is zero, then @i{d} digits are printed after the decimal
1969
point, and a single zero digit appears before the decimal point if
1970
the total field width will permit it. If @i{k} is positive,
1971
then it must be strictly less than @i{d}+2; @i{k} significant digits
1972
are printed before the decimal point, and @i{d}- @i{k}+1
1973
digits are printed after the decimal point. If @i{k} is negative,
1974
then it must be strictly greater than - @i{d};
1975
a single zero digit appears before the decimal point if
1976
the total field width will permit it, and after the decimal point
1978
- @i{k} zeros and then @i{d}+@i{k} significant digits.
1979
The printed fraction must be properly rounded.
1980
When rounding up and rounding down would produce printed values
1981
equidistant from the scaled value of @i{arg}, then the implementation
1982
is free to use either one. For example, printing the argument
1983
@t{637.5} using the format @t{~8,2E} may correctly produce
1984
either @t{6.37E+2} or @t{6.38E+2}.
1986
Following the digit sequence, the exponent is printed.
1987
First the character parameter @i{exponentchar} is printed; if this
1988
parameter is omitted, then the @i{exponent marker} that
1989
@b{prin1} would use is printed, as determined from the
1990
type of the @i{float} and the current value of
1991
@b{*read-default-float-format*}.
1992
Next, either a plus sign or a minus sign
1993
is printed, followed by @i{e} digits representing the power of
1994
ten by which the printed fraction must be multiplied
1995
to properly represent the rounded value of @i{arg}.
1997
If it is impossible to print the value in the required format in a field
1998
of width @i{w}, possibly because @i{k} is too large or too small
1999
or because the exponent cannot be printed in @i{e} character positions,
2000
then one of two actions is taken. If the
2001
parameter @i{overflowchar} is supplied, then @i{w} copies of that
2002
parameter are printed instead of the scaled value of @i{arg}.
2003
If the @i{overflowchar} parameter is omitted, then the scaled value
2004
is printed using more than @i{w} characters, as many more as may be
2005
needed; if the problem is that @i{d} is too small for the supplied @i{k}
2006
or that @i{e} is too small, then a larger value is used for @i{d} or @i{e}
2009
If the @i{w} parameter is omitted, then the field is of variable width.
2010
In effect a value is chosen
2011
for @i{w} in such a way that no leading pad characters need to be printed.
2013
If the parameter @i{d} is omitted, then there is no constraint
2014
on the number of digits to appear.
2015
A value is chosen for @i{d} in such a way that as many digits
2016
as possible may be printed subject to the width constraint
2017
imposed by the parameter @i{w}, the constraint of the scale factor @i{k},
2018
and the constraint that no trailing
2019
zero digits may appear in the fraction, except that if the
2020
fraction to be printed is zero then a single zero digit should
2021
appear after the decimal point.
2023
If the parameter @i{e} is omitted, then the exponent is printed
2024
using the smallest number of digits necessary to represent its value.
2026
If all of @i{w}, @i{d}, and @i{e} are omitted, then the effect is to print
2027
the value using ordinary free-format exponential-notation output;
2032
format for any non-zero number whose magnitude
2033
is less than 10^@r{-3} or greater than or equal to 10^7.
2035
The only difference is that the @t{~E}
2036
directive always prints a plus or minus sign in front of the
2037
exponent, while @b{prin1} omits the plus sign if the exponent is
2040
If @i{arg} is a @i{rational}
2041
number, then it is coerced to be a @i{single float}
2042
and then printed. Alternatively, an implementation is permitted to
2043
process a @i{rational}
2044
number by any other method that has essentially the
2045
same behavior but avoids loss of precision or overflow
2046
because of the coercion. If @i{w} and @i{d} are
2047
unsupplied and the number has no exact decimal representation,
2048
for example @t{1/3}, some precision cutoff must be chosen
2049
by the implementation since only a finite number of digits may be printed.
2051
If @i{arg} is a @i{complex} number or some non-numeric
2053
then it is printed using the format directive @t{~@i{w}D},
2054
thereby printing it in decimal radix and a minimum field width of @i{w}.
2057
@b{*print-escape*} to @i{false}
2059
and @b{*print-readably*} to @i{false}.
2061
@node Tilde G-> General Floating-Point, Tilde Dollarsign-> Monetary Floating-Point, Tilde E-> Exponential Floating-Point, FORMAT Floating-Point Printers
2062
@subsubsection Tilde G: General Floating-Point
2064
The next @i{arg} is printed as a @i{float}
2065
in either fixed-format or exponential notation as appropriate.
2067
The full form is @t{~@i{w},@i{d},@i{e},@i{k},@i{overflowchar},@i{padchar},@i{exponentchar}G}.
2068
The format in which to print @i{arg} depends on the magnitude (absolute
2069
value) of the @i{arg}. Let @i{n} be an integer such that
2070
10^@r{@r{n}-1} \le |@i{arg}| < 10^@i{n}.
2071
Let @i{ee} equal @i{e}+2, or 4 if @i{e} is omitted.
2072
Let @i{ww} equal @i{w}- @i{ee},
2073
or @b{nil} if @i{w} is omitted. If @i{d} is omitted, first let @i{q}
2074
be the number of digits needed to print @i{arg} with no loss
2075
of information and without leading or trailing zeros;
2076
then let @i{d} equal @t{(max @i{q} (min @i{n} 7))}.
2077
Let @i{dd} equal @i{d}- @i{n}.
2079
If 0 \le @i{dd} \le @i{d}, then @i{arg} is printed
2080
as if by the format directives
2082
@t{~@i{ww},@i{dd},,@i{overflowchar},@i{padchar}F~@i{ee}@@T}
2084
Note that the scale factor @i{k} is not passed to the @t{~F}
2085
directive. For all other values of @i{dd}, @i{arg} is printed as if
2086
by the format directive
2088
@t{~@i{w},@i{d},@i{e},@i{k},@i{overflowchar},@i{padchar},@i{exponentchar}E}
2090
In either case, an @t{@@}
2091
modifier is supplied to the @t{~F}
2092
or @t{~E} directive if and only if one was supplied to the
2096
@b{*print-escape*} to @i{false}
2098
and @b{*print-readably*} to @i{false}.
2100
@node Tilde Dollarsign-> Monetary Floating-Point, , Tilde G-> General Floating-Point, FORMAT Floating-Point Printers
2101
@subsubsection Tilde Dollarsign: Monetary Floating-Point
2103
The next @i{arg} is printed as a @i{float} in fixed-format notation.
2105
The full form is @t{~@i{d},@i{n},@i{w},@i{padchar}$}.
2106
The parameter @i{d} is the number
2107
of digits to print after the decimal point (default value 2);
2108
@i{n} is the minimum number of digits to print before the decimal
2109
point (default value 1);
2110
@i{w} is the minimum total width of the field to be printed (default
2113
First padding and the sign are output.
2114
If the @i{arg} is negative, then a minus sign is printed;
2115
if the @i{arg} is not negative, then a plus sign is printed
2116
if and only if the @t{@@} modifier was supplied.
2117
If the @t{:} modifier is used, the sign appears before any padding,
2118
and otherwise after the padding.
2119
If @i{w} is supplied and the number of other characters to be output
2120
is less than @i{w}, then copies of @i{padchar} (which defaults
2121
to a space) are output to
2122
make the total field width equal @i{w}.
2123
Then @i{n} digits are printed for the integer part of @i{arg},
2124
with leading zeros if necessary; then a decimal point;
2125
then @i{d} digits of fraction, properly rounded.
2127
If the magnitude of @i{arg} is so large that more than @i{m} digits would
2128
have to be printed, where @i{m} is the larger of @i{w} and 100, then an
2129
implementation is free, at its discretion, to print the number using
2130
exponential notation instead, as if by the directive
2131
@t{~@i{w},@i{q},,,,@i{padchar}E}, where @i{w} and @i{padchar} are
2132
present or omitted according to whether they were present or omitted in
2133
the @t{~$} directive, and where @i{q}=@i{d}+@i{n}- 1,
2134
where @i{d} and @i{n} are the (possibly default) values given to the
2137
If @i{arg} is a @i{rational}
2138
number, then it is coerced to be a @i{single float}
2139
and then printed. Alternatively, an implementation is permitted to
2140
process a @i{rational} number by any
2141
other method that has essentially the
2142
same behavior but avoids loss of precision or overflow
2143
because of the coercion.
2145
If @i{arg} is a @i{complex} number or some non-numeric
2147
then it is printed using the format directive @t{~@i{w}D},
2148
thereby printing it in decimal radix and a minimum field width of @i{w}.
2150
@t{~$} binds @b{*print-escape*} to @i{false}
2152
and @b{*print-readably*} to @i{false}.
2154
@node FORMAT Printer Operations, FORMAT Pretty Printer Operations, FORMAT Floating-Point Printers, Formatted Output
2155
@subsection FORMAT Printer Operations
2158
* Tilde A-> Aesthetic::
2159
* Tilde S-> Standard::
2163
@node Tilde A-> Aesthetic, Tilde S-> Standard, FORMAT Printer Operations, FORMAT Printer Operations
2164
@subsubsection Tilde A: Aesthetic
2166
An @i{arg}, any @i{object},
2167
is printed without escape characters
2168
(as by @b{princ}). If @i{arg} is a @i{string},
2170
will be output verbatim.
2171
If @i{arg} is @b{nil} it will be printed as @b{nil};
2172
the @i{colon} modifier (@t{~:A}) will cause an @i{arg} of @b{nil} to be printed as @t{()},
2173
but if @i{arg} is a composite structure, such as a @i{list} or @i{vector},
2174
any contained occurrences of @b{nil} will still be printed as @b{nil}.
2176
@t{~@i{mincol}A} inserts spaces on the right, if necessary, to make the
2177
width at least @i{mincol} columns. The @t{@@}
2178
modifier causes the spaces
2179
to be inserted on the left rather than the right.
2181
@t{~@i{mincol},@i{colinc},@i{minpad},@i{padchar}A}
2182
is the full form of @t{~A},
2183
which allows control of the padding.
2184
The @i{string} is padded on the right (or on the left if the
2185
@t{@@} modifier is used) with at least @i{minpad} copies
2186
of @i{padchar}; padding characters are then inserted @i{colinc} characters
2187
at a time until the total width is at least @i{mincol}.
2188
The defaults are @t{0} for @i{mincol} and @i{minpad}, @t{1} for @i{colinc},
2189
and the space character for @i{padchar}.
2191
@t{~A} binds @b{*print-escape*} to @i{false},
2193
and @b{*print-readably*} to @i{false}.
2195
@node Tilde S-> Standard, Tilde W-> Write, Tilde A-> Aesthetic, FORMAT Printer Operations
2196
@subsubsection Tilde S: Standard
2198
This is just like @t{~A}, but @i{arg} is printed with escape
2199
characters (as by @b{prin1} rather than @t{princ}). The output is
2200
therefore suitable for input to @b{read}. @t{~S} accepts
2201
all the arguments and modifiers that @t{~A} does.
2203
@t{~S} binds @b{*print-escape*} to @b{t}.
2205
@node Tilde W-> Write, , Tilde S-> Standard, FORMAT Printer Operations
2206
@subsubsection Tilde W: Write
2208
An argument, any @i{object}, is printed obeying every printer control
2209
variable (as by @b{write}). In addition, @t{~W} interacts correctly with depth
2210
abbreviation, by not resetting the depth counter to zero. @t{~W} does not
2211
accept parameters. If given the @i{colon} modifier, @t{~W} binds @b{*print-pretty*}
2212
to @i{true}. If given the @i{at-sign} modifier, @t{~W} binds @b{*print-level*}
2213
and @b{*print-length*} to @b{nil}.
2215
@t{~W} provides automatic support for the detection of circularity and
2216
sharing. If the @i{value} of @b{*print-circle*} is not @b{nil} and @t{~W} is applied
2217
to an argument that is a circular (or shared) reference, an appropriate
2218
@t{#@i{n}#} marker is inserted in the output instead of printing the argument.
2220
@node FORMAT Pretty Printer Operations, FORMAT Layout Control, FORMAT Printer Operations, Formatted Output
2221
@subsection FORMAT Pretty Printer Operations
2223
The following constructs provide access to the @i{pretty printer}:
2226
* Tilde Underscore-> Conditional Newline::
2227
* Tilde Less-Than-Sign-> Logical Block::
2228
* Tilde I-> Indent::
2229
* Tilde Slash-> Call Function::
2232
@node Tilde Underscore-> Conditional Newline, Tilde Less-Than-Sign-> Logical Block, FORMAT Pretty Printer Operations, FORMAT Pretty Printer Operations
2233
@subsubsection Tilde Underscore: Conditional Newline
2235
Without any modifiers, @t{~_} is the same as @t{(pprint-newline :linear)}.
2236
@t{~@@_} is the same as @t{(pprint-newline :miser)}.
2237
@t{~:_} is the same as @t{(pprint-newline :fill)}.
2238
@t{~:@@_} is the same as @t{(pprint-newline :mandatory)}.
2240
@node Tilde Less-Than-Sign-> Logical Block, Tilde I-> Indent, Tilde Underscore-> Conditional Newline, FORMAT Pretty Printer Operations
2241
@subsubsection Tilde Less-Than-Sign: Logical Block
2245
If @t{~:>} is used to terminate a @t{~<...~>},
2246
the directive is equivalent to a call to @b{pprint-logical-block}.
2247
The argument corresponding to the @t{~<...~:>} directive is treated in
2248
the same way as the @i{list} argument to @b{pprint-logical-block},
2249
thereby providing automatic support for non-@i{list} arguments and
2250
the detection of circularity, sharing, and depth abbreviation.
2251
The portion of the @i{control-string} nested within the @t{~<...~:>}
2252
specifies the @t{:prefix} (or @t{:per-line-prefix}), @t{:suffix},
2253
and body of the @b{pprint-logical-block}.
2255
The @i{control-string} portion enclosed by @t{~<...~:>} can be divided
2256
into segments @t{~<@i{prefix}~;@i{body}~;@i{suffix}~:>}
2257
by @t{~;} directives. If the first section is terminated by @t{~@@;},
2258
it specifies a per-line prefix rather than a simple prefix.
2259
The @i{prefix} and @i{suffix} cannot contain format directives.
2260
An error is signaled if either the prefix or suffix fails to be a
2261
constant string or if the enclosed portion is divided into more than three segments.
2263
If the enclosed portion is divided into only two segments, the @i{suffix}
2264
defaults to the null string. If the enclosed portion consists of only
2265
a single segment, both the @i{prefix} and the @i{suffix} default to
2266
the null string. If the @i{colon} modifier is used (@i{i.e.}, @t{~:<...~:>}),
2267
the @i{prefix} and @i{suffix} default to @t{"("} and @t{")"}
2268
(respectively) instead of the null string.
2270
The body segment can be any arbitrary @i{format string}.
2271
This @i{format string} is applied to the elements of the list
2272
corresponding to the @t{~<...~:>} directive as a whole.
2273
Elements are extracted from this list using @b{pprint-pop},
2274
thereby providing automatic support for malformed lists, and the detection
2275
of circularity, sharing, and length abbreviation.
2276
Within the body segment, @t{~@t{^}} acts like @b{pprint-exit-if-list-exhausted}.
2278
@t{~<...~:>} supports a feature not supported by @b{pprint-logical-block}.
2279
If @t{~:@@>} is used to terminate the directive (@i{i.e.}, @t{~<...~:@@>}),
2280
then a fill-style conditional newline is automatically inserted after each
2281
group of blanks immediately contained in the body (except for blanks
2282
after a ~<@i{Newline}> directive). This makes it easy to achieve the
2283
equivalent of paragraph filling.
2285
If the @i{at-sign} modifier is used with @t{~<...~:>}, the entire remaining argument
2286
list is passed to the directive as its argument. All of the remaining
2287
arguments are always consumed by @t{~@@<...~:>}, even if they are not all used
2288
by the @i{format string} nested in the directive. Other than the difference in
2289
its argument, @t{~@@<...~:>} is exactly the same as @t{~<...~:>} except that
2290
circularity detection is not applied if @t{~@@<...~:>} is encountered at top
2291
level in a @i{format string}. This ensures that circularity detection is
2292
applied only to data lists, not to @i{format argument} @i{lists}.
2294
@t{" . #@i{n}#"} is printed if circularity or sharing has to be indicated
2295
for its argument as a whole.
2297
To a considerable extent, the basic form of the directive @t{~<...~>} is
2298
incompatible with the dynamic control of the arrangement of output by
2299
@t{~W}, @t{~_}, @t{~<...~:>}, @t{~I}, and @t{~:T}. As a result, an error
2300
is signaled if any of these directives is nested within @t{~<...~>}.
2301
Beyond this, an error is also signaled if the @t{~<...~:;...~>} form of
2302
@t{~<...~>} is used in the same @i{format string} with
2303
@t{~W}, @t{~_}, @t{~<...~:>}, @t{~I}, or @t{~:T}.
2305
See also @ref{Tilde Less-Than-Sign-> Justification}.
2307
@node Tilde I-> Indent, Tilde Slash-> Call Function, Tilde Less-Than-Sign-> Logical Block, FORMAT Pretty Printer Operations
2308
@subsubsection Tilde I: Indent
2310
@t{~@i{n}I} is the same as @t{(pprint-indent :block n)}.
2312
@t{~@i{n}:I} is the same as @t{(pprint-indent :current n)}.
2313
In both cases, @i{n} defaults to zero, if it is omitted.
2315
@node Tilde Slash-> Call Function, , Tilde I-> Indent, FORMAT Pretty Printer Operations
2316
@subsubsection Tilde Slash: Call Function
2320
User defined functions can be called from within a format
2321
string by using the directive @t{~/@i{name}/}.
2322
The @i{colon} modifier, the @i{at-sign} modifier, and arbitrarily many parameters
2323
can be specified with the @t{~/@i{name}/} directive.
2324
@i{name} can be any arbitrary string that does not contain a "/".
2325
All of the characters in @i{name} are treated as if they were upper case.
2326
If @i{name} contains a single @i{colon} (@t{:}) or double @i{colon} (@t{::}),
2327
then everything up to but not including the first @t{":"} or @t{"::"}
2328
is taken to be a @i{string} that names a @i{package}.
2329
Everything after the first @t{":"} or @t{"::"} (if any) is taken to be a
2330
@i{string} that names a @t{symbol}. The function corresponding to a
2331
@t{~/name/} directive is obtained by looking up the @i{symbol}
2332
that has the indicated name in the indicated @i{package}.
2333
If @i{name} does not contain a @t{":"} or @t{"::"},
2334
then the whole @i{name} string is looked up in the @t{COMMON-LISP-USER} @i{package}.
2336
When a @t{~/name/} directive is encountered,
2337
the indicated function is called with four or more arguments.
2338
The first four arguments are:
2340
the @i{format argument} corresponding to the directive,
2341
a @i{generalized boolean} that is @i{true} if the @i{colon} modifier was used,
2342
and a @i{generalized boolean} that is @i{true} if the @i{at-sign} modifier was used.
2343
The remaining arguments consist of any parameters specified with the directive.
2344
The function should print the argument appropriately.
2345
Any values returned by the function are ignored.
2347
The three @i{functions}
2350
and @b{pprint-tabular}
2351
are specifically designed so that they can be called by @t{~/.../}
2352
(@i{i.e.}, @t{~/pprint-linear/}, @t{~/pprint-fill/}, and @t{~/pprint-tabular/}).
2353
In particular they take @i{colon} and @i{at-sign} arguments.
2355
@node FORMAT Layout Control, FORMAT Control-Flow Operations, FORMAT Pretty Printer Operations, Formatted Output
2356
@subsection FORMAT Layout Control
2359
* Tilde T-> Tabulate::
2360
* Tilde Less-Than-Sign-> Justification::
2361
* Tilde Greater-Than-Sign-> End of Justification::
2364
@node Tilde T-> Tabulate, Tilde Less-Than-Sign-> Justification, FORMAT Layout Control, FORMAT Layout Control
2365
@subsubsection Tilde T: Tabulate
2367
This spaces over to a given column.
2368
@t{~@i{colnum},@i{colinc}T} will output
2369
sufficient spaces to move the cursor to column @i{colnum}. If the cursor
2370
is already at or beyond column @i{colnum}, it will output spaces to move it to
2371
column @i{colnum}+@i{k}*@i{colinc} for the smallest positive integer
2372
@i{k} possible, unless @i{colinc} is zero, in which case no spaces
2373
are output if the cursor is already at or beyond column @i{colnum}.
2374
@i{colnum} and @i{colinc} default to @t{1}.
2376
If for some reason the current absolute column position cannot be determined
2379
may be able to deduce the current column position by noting
2380
that certain directives (such as @t{~%}, or @t{~&},
2382
with the argument being a string containing a newline) cause
2383
the column position to be reset to zero, and counting the number of characters
2384
emitted since that point. If that fails, @b{format}
2386
similar deduction on the riskier assumption that the destination was
2387
at column zero when @b{format}
2388
was invoked. If even this heuristic fails
2389
or is implementationally inconvenient, at worst
2390
the @t{~T} operation will simply output two spaces.
2392
@t{~@@T} performs relative tabulation.
2393
@t{~@i{colrel},@i{colinc}@@T} outputs @i{colrel} spaces
2394
and then outputs the smallest non-negative
2395
number of additional spaces necessary to move the cursor
2396
to a column that is a multiple
2397
of @i{colinc}. For example, the directive
2399
three spaces and then moves the cursor to a ``standard multiple-of-eight
2400
tab stop'' if not at one already.
2401
If the current output column cannot be determined, however,
2402
then @i{colinc} is ignored, and exactly @i{colrel} spaces are output.
2404
If the @i{colon} modifier is used with the @t{~T} directive,
2405
the tabbing computation is done relative to the horizontal position where the
2406
section immediately containing the directive begins, rather than with
2407
respect to a horizontal position of zero. The numerical parameters are
2408
both interpreted as being in units of @i{ems} and both default to @t{1}.
2409
@t{~@i{n},@i{m}:T} is the same as
2410
@t{(pprint-tab :section @i{n} @i{m})}.
2411
@t{~@i{n},@i{m}:@@T} is the same as
2412
@t{(pprint-tab :section-relative @i{n} @i{m})}.
2414
@node Tilde Less-Than-Sign-> Justification, Tilde Greater-Than-Sign-> End of Justification, Tilde T-> Tabulate, FORMAT Layout Control
2415
@subsubsection Tilde Less-Than-Sign: Justification
2417
@t{~@i{mincol},@i{colinc},@i{minpad},@i{padchar}<@i{str}~>}
2419
This justifies the text produced by processing @i{str}
2420
within a field at least @i{mincol} columns wide. @i{str}
2421
may be divided up into segments with @t{~;}, in which case the
2422
spacing is evenly divided between the text segments.
2424
With no modifiers, the leftmost text segment is left justified in the
2425
field, and the rightmost text segment is right justified. If there is
2426
only one text element, as a special case, it is right justified.
2427
The @t{:} modifier causes
2428
spacing to be introduced before the first text segment; the
2429
@t{@@} modifier causes spacing to be added after the last.
2430
The @i{minpad} parameter (default @t{0}) is the minimum number of
2431
padding characters to be output between each segment.
2432
The padding character is supplied by @i{padchar},
2433
which defaults to the space character.
2434
If the total width needed to satisfy these constraints is greater
2435
than @i{mincol}, then the width used is @i{mincol}+@i{k}*@i{colinc}
2436
for the smallest possible non-negative integer value @i{k}.
2437
@i{colinc} defaults to @t{1}, and @i{mincol} defaults to @t{0}.
2439
Note that @i{str} may include @b{format} directives.
2440
All the clauses in @i{str} are processed in order;
2441
it is the resulting pieces of text that are justified.
2443
The @t{~@t{^} } directive may be used to terminate processing of the
2444
clauses prematurely, in which case only the completely processed clauses
2447
If the first clause of a @t{~<}
2448
is terminated with @t{~:;} instead of
2449
@t{~;}, then it is used in a special way. All of the clauses are
2450
processed (subject to @t{~@t{^} }, of course), but the
2451
first one is not used
2452
in performing the spacing and padding. When the padded result has been
2453
determined, then if it will fit on the current line of output, it is
2454
output, and the text for the first clause is discarded. If, however, the
2455
padded text will not fit on the current line, then the text segment for
2456
the first clause is output before the padded text. The first clause
2457
ought to contain a newline (such as a @t{~%} directive). The first
2458
clause is always processed, and so any arguments it refers to will be
2459
used; the decision is whether to use the resulting segment of text, not
2460
whether to process the first clause. If the @t{~:;} has a prefix
2461
parameter @i{n}, then the padded text must fit on the current line with
2462
@i{n} character positions to spare to avoid outputting the first clause's
2463
text. For example, the control string
2469
can be used to print a list of items separated by commas without
2470
breaking items over line boundaries, beginning each line with
2471
@t{;; }. The prefix parameter
2472
@t{1} in @t{~1:;} accounts for the width of the
2473
comma that will follow the justified item if it is not the last
2474
element in the list, or the period
2475
if it is. If @t{~:;} has a second
2476
prefix parameter, then it is used as the width of the line,
2477
thus overriding the natural line width of the output stream. To make
2478
the preceding example use a line width of 50, one would write
2484
If the second argument is not supplied, then @b{format} uses the
2485
line width of the @i{destination} output stream.
2486
If this cannot be determined (for example, when producing a
2487
@i{string} result), then @b{format} uses @t{72} as the line length.
2489
See also @ref{Tilde Less-Than-Sign-> Logical Block}.
2491
@node Tilde Greater-Than-Sign-> End of Justification, , Tilde Less-Than-Sign-> Justification, FORMAT Layout Control
2492
@subsubsection Tilde Greater-Than-Sign: End of Justification
2494
@t{~>} terminates a @t{~<}.
2495
The consequences of using it elsewhere are undefined.
2497
@node FORMAT Control-Flow Operations, FORMAT Miscellaneous Operations, FORMAT Layout Control, Formatted Output
2498
@subsection FORMAT Control-Flow Operations
2501
* Tilde Asterisk-> Go-To::
2502
* Tilde Left-Bracket-> Conditional Expression::
2503
* Tilde Right-Bracket-> End of Conditional Expression::
2504
* Tilde Left-Brace-> Iteration::
2505
* Tilde Right-Brace-> End of Iteration::
2506
* Tilde Question-Mark-> Recursive Processing::
2509
@node Tilde Asterisk-> Go-To, Tilde Left-Bracket-> Conditional Expression, FORMAT Control-Flow Operations, FORMAT Control-Flow Operations
2510
@subsubsection Tilde Asterisk: Go-To
2512
The next @i{arg} is ignored.
2513
@t{~@i{n}*} ignores the next @i{n} arguments.
2515
@t{~:*} backs up in the list of
2516
arguments so that the argument last processed will be processed again.
2517
@t{~@i{n}:*} backs up @i{n} arguments.
2519
When within a @t{~@{} construct
2520
(see below), the ignoring (in either direction) is relative to the list
2521
of arguments being processed by the iteration.
2524
goes to the @i{n}th @i{arg}, where 0 means the first one;
2525
@i{n} defaults to 0, so @t{~@@*} goes back to the first @i{arg}.
2526
Directives after a @t{~@i{n}@@*}
2527
will take arguments in sequence beginning with the one gone to.
2528
When within a @t{~@{} construct, the ``goto''
2529
is relative to the list of arguments being processed by the iteration.
2531
@node Tilde Left-Bracket-> Conditional Expression, Tilde Right-Bracket-> End of Conditional Expression, Tilde Asterisk-> Go-To, FORMAT Control-Flow Operations
2532
@subsubsection Tilde Left-Bracket: Conditional Expression
2534
@t{~[@i{str0}~;@i{str1}~;@i{...}~;@i{strn}~]}
2536
This is a set of control strings, called @i{clauses}, one of which is
2537
chosen and used. The clauses are separated by @t{~;}
2538
and the construct is terminated by @t{~]}. For example,
2540
@t{"~[Siamese~;Manx~;Persian~] Cat"}
2543
clause is selected, where the first clause is number 0.
2544
If a prefix parameter is given (as @t{~@i{n}[}),
2545
then the parameter is used instead of an argument.
2546
If @i{arg} is out of range then no clause is selected
2547
and no error is signaled.
2548
After the selected alternative has been processed, the control string
2549
continues after the @t{~]}.
2551
@t{~[@i{str0}~;@i{str1}~;@i{...}~;@i{strn}~:;@i{default}~]}
2553
If the @i{last} @t{~;} used to separate clauses
2554
is @t{~:;} instead, then the last clause is an else clause
2555
that is performed if no other clause is selected.
2558
@t{"~[Siamese~;Manx~;Persian~:;Alley~] Cat"}
2560
@t{~:[@i{alternative}~;@i{consequent}~]}
2561
selects the @i{alternative} control string if @i{arg} is @i{false},
2562
and selects the @i{consequent} control string otherwise.
2564
@t{~@@[@i{consequent}~]}
2565
tests the argument. If it is @i{true},
2566
then the argument is not used up by the @t{~[} command
2567
but remains as the next one to be processed,
2568
and the one clause @i{consequent} is processed.
2569
If the @i{arg} is @i{false}, then the argument is used up,
2570
and the clause is not processed.
2571
The clause therefore should normally use exactly one argument,
2572
and may expect it to be @i{non-nil}.
2576
(setq *print-level* nil *print-length* 5)
2578
"~@@[ print level = ~D~]~@@[ print length = ~D~]"
2579
*print-level* *print-length*)
2580
@result{} " print length = 5"
2586
(format @i{stream} "...~@@[@i{str}~]..." ...)
2587
@equiv{} (format @i{stream} "...~:[~;~:*@i{str}~]..." ...)
2590
The combination of @t{~[} and @t{#} is useful, for
2591
example, for dealing with English conventions for printing lists:
2594
(setq foo "Items:~#[ none~; ~S~; ~S and ~S~
2595
~:;~@@@{~#[~; and~] ~S~@t{^} ,~@}~].")
2596
(format nil foo) @result{} "Items: none."
2597
(format nil foo 'foo) @result{} "Items: FOO."
2598
(format nil foo 'foo 'bar) @result{} "Items: FOO and BAR."
2599
(format nil foo 'foo 'bar 'baz) @result{} "Items: FOO, BAR, and BAZ."
2600
(format nil foo 'foo 'bar 'baz 'quux) @result{} "Items: FOO, BAR, BAZ, and QUUX."
2603
@node Tilde Right-Bracket-> End of Conditional Expression, Tilde Left-Brace-> Iteration, Tilde Left-Bracket-> Conditional Expression, FORMAT Control-Flow Operations
2604
@subsubsection Tilde Right-Bracket: End of Conditional Expression
2606
@t{~]} terminates a @t{~[}.
2607
The consequences of using it elsewhere are undefined.
2609
@node Tilde Left-Brace-> Iteration, Tilde Right-Brace-> End of Iteration, Tilde Right-Bracket-> End of Conditional Expression, FORMAT Control-Flow Operations
2610
@subsubsection Tilde Left-Brace: Iteration
2614
This is an iteration construct. The argument should be a @i{list},
2615
which is used as a set of arguments
2616
as if for a recursive call to @b{format}.
2617
The @i{string} @i{str} is used repeatedly as the control string.
2618
Each iteration can absorb as many elements of the @i{list} as it likes
2620
if @i{str} uses up two arguments by itself, then two elements of the
2621
@i{list} will get used up each time around the loop.
2622
If before any iteration step the @i{list}
2623
is empty, then the iteration is terminated.
2624
Also, if a prefix parameter @i{n} is given, then there will be at most @i{n}
2625
repetitions of processing of @i{str}.
2626
Finally, the @t{~@t{^} } directive can be
2627
used to terminate the iteration prematurely.
2632
(format nil "The winners are:~@{ ~S~@}."
2634
@result{} "The winners are: FRED HARRY JILL."
2635
(format nil "Pairs:~@{ <~S,~S>~@}."
2637
@result{} "Pairs: <A,1> <B,2> <C,3>."
2640
@t{~:@{ @i{str}~@} } is similar,
2641
but the argument should be a @i{list} of sublists.
2642
At each repetition step, one sublist
2643
is used as the set of arguments for
2644
processing @i{str}; on the next repetition, a new sublist
2646
or not all of the last sublist had been processed.
2650
(format nil "Pairs:~:@{ <~S,~S>~@} ."
2651
'((a 1) (b 2) (c 3)))
2652
@result{} "Pairs: <A,1> <B,2> <C,3>."
2655
@t{~@@@{ @i{str}~@} }
2656
is similar to @t{~@{ @i{str}~@} }, but instead of
2657
using one argument that is a list, all the remaining arguments
2658
are used as the list of arguments for the iteration.
2662
(format nil "Pairs:~@@@{ <~S,~S>~@} ." 'a 1 'b 2 'c 3)
2663
@result{} "Pairs: <A,1> <B,2> <C,3>."
2666
If the iteration is terminated before all the remaining arguments are
2667
consumed, then any arguments not processed by the iteration remain to be
2668
processed by any directives following the iteration construct.
2670
@t{~:@@@{ @i{str}~@} }
2671
combines the features
2672
of @t{~:@{ @i{str}~@} }
2673
and @t{~@@@{ @i{str}~@} }.
2674
All the remaining arguments
2675
are used, and each one must be a @i{list}.
2676
On each iteration, the next argument is
2677
used as a @i{list} of arguments to @i{str}.
2681
(format nil "Pairs:~:@@@{ <~S,~S>~@} ."
2682
'(a 1) '(b 2) '(c 3))
2683
@result{} "Pairs: <A,1> <B,2> <C,3>."
2686
Terminating the repetition construct with @t{~:@} }
2688
forces @i{str} to be processed at least once, even if the initial
2689
list of arguments is null. However, this will not override an explicit
2690
prefix parameter of zero.
2692
If @i{str} is empty, then an argument is used as @i{str}.
2693
It must be a @i{format control}
2694
and precede any arguments processed by the iteration. As an example,
2695
the following are equivalent:
2698
(apply #'format stream string arguments)
2699
@equiv{} (format stream "~1@{~:@}" string arguments)
2702
This will use @t{string} as a formatting string.
2703
The @t{~1@{ } says it will
2704
be processed at most once, and the @t{~:@} }
2705
says it will be processed at least once.
2706
Therefore it is processed exactly once, using @t{arguments} as the arguments.
2707
This case may be handled more clearly by the @t{~?} directive,
2708
but this general feature of @t{~@{ }
2709
is more powerful than @t{~?}.
2711
@node Tilde Right-Brace-> End of Iteration, Tilde Question-Mark-> Recursive Processing, Tilde Left-Brace-> Iteration, FORMAT Control-Flow Operations
2712
@subsubsection Tilde Right-Brace: End of Iteration
2714
@t{~@}} terminates a @t{~@{}.
2715
The consequences of using it elsewhere are undefined.
2717
@node Tilde Question-Mark-> Recursive Processing, , Tilde Right-Brace-> End of Iteration, FORMAT Control-Flow Operations
2718
@subsubsection Tilde Question-Mark: Recursive Processing
2720
The next @i{arg} must be a @i{format control}, and the one after it a @i{list};
2721
both are consumed by the @t{~?} directive.
2722
The two are processed as a @i{control-string}, with the elements of the @i{list}
2723
as the arguments. Once the recursive processing
2724
has been finished, the processing of the control
2725
string containing the @t{~?} directive is resumed.
2729
(format nil "~? ~D" "<~A ~D>" '("Foo" 5) 7) @result{} "<Foo 5> 7"
2730
(format nil "~? ~D" "<~A ~D>" '("Foo" 5 14) 7) @result{} "<Foo 5> 7"
2733
Note that in the second example three arguments are supplied
2734
to the @i{format string} @t{"<~A ~D>"}, but only two are processed
2735
and the third is therefore ignored.
2738
modifier, only one @i{arg} is directly consumed.
2739
The @i{arg} must be a @i{string};
2740
it is processed as part of the control
2741
string as if it had appeared in place of the @t{~@@?} construct,
2742
and any directives in the recursively processed control string may
2743
consume arguments of the control string containing the @t{~@@?}
2748
(format nil "~@@? ~D" "<~A ~D>" "Foo" 5 7) @result{} "<Foo 5> 7"
2749
(format nil "~@@? ~D" "<~A ~D>" "Foo" 5 14 7) @result{} "<Foo 5> 14"
2752
@node FORMAT Miscellaneous Operations, FORMAT Miscellaneous Pseudo-Operations, FORMAT Control-Flow Operations, Formatted Output
2753
@subsection FORMAT Miscellaneous Operations
2756
* Tilde Left-Paren-> Case Conversion::
2757
* Tilde Right-Paren-> End of Case Conversion::
2758
* Tilde P-> Plural::
2761
@node Tilde Left-Paren-> Case Conversion, Tilde Right-Paren-> End of Case Conversion, FORMAT Miscellaneous Operations, FORMAT Miscellaneous Operations
2762
@subsubsection Tilde Left-Paren: Case Conversion
2766
The contained control string @i{str} is processed, and what it produces
2767
is subject to case conversion.
2769
With no flags, every @i{uppercase} @i{character}
2770
is converted to the corresponding @i{lowercase} @i{character}.
2772
@t{~:(} capitalizes all words, as if by @b{string-capitalize}.
2775
capitalizes just the first word and forces the rest to lower
2778
@t{~:@@(} converts every lowercase character
2779
to the corresponding uppercase character.
2781
In this example @t{~@@(} is used to cause the first word
2782
produced by @t{~@@R} to be capitalized:
2785
(format nil "~@@R ~(~@@R~)" 14 14)
2787
(defun f (n) (format nil "~@@(~R~) error~:P detected." n)) @result{} F
2788
(f 0) @result{} "Zero errors detected."
2789
(f 1) @result{} "One error detected."
2790
(f 23) @result{} "Twenty-three errors detected."
2793
When case conversions appear nested, the outer conversion dominates,
2794
as illustrated in the following example:
2797
(format nil "~@@(how is ~:(BOB SMITH~)?~)")
2798
@result{} "How is bob smith?"
2799
@i{NOT}@result{} "How is Bob Smith?"
2802
@node Tilde Right-Paren-> End of Case Conversion, Tilde P-> Plural, Tilde Left-Paren-> Case Conversion, FORMAT Miscellaneous Operations
2803
@subsubsection Tilde Right-Paren: End of Case Conversion
2805
@t{~)} terminates a @t{~(}.
2806
The consequences of using it elsewhere are undefined.
2808
@node Tilde P-> Plural, , Tilde Right-Paren-> End of Case Conversion, FORMAT Miscellaneous Operations
2809
@subsubsection Tilde P: Plural
2811
If @i{arg} is not @b{eql}
2812
to the integer @t{1}, a lowercase @t{s} is
2813
printed; if @i{arg} is @b{eql} to @t{1}, nothing is printed.
2814
If @i{arg} is a floating-point @t{1.0}, the @t{s} is
2817
@t{~:P} does the same thing,
2818
after doing a @t{~:*} to back up one argument;
2819
that is, it prints a lowercase @t{s} if the previous argument was not
2823
prints @t{y} if the argument is @t{1}, or @t{ies} if it is
2824
not. @t{~:@@P} does the same thing, but backs up first.
2827
(format nil "~D tr~:@@P/~D win~:P" 7 1) @result{} "7 tries/1 win"
2828
(format nil "~D tr~:@@P/~D win~:P" 1 0) @result{} "1 try/0 wins"
2829
(format nil "~D tr~:@@P/~D win~:P" 1 3) @result{} "1 try/3 wins"
2832
@node FORMAT Miscellaneous Pseudo-Operations, Additional Information about FORMAT Operations, FORMAT Miscellaneous Operations, Formatted Output
2833
@subsection FORMAT Miscellaneous Pseudo-Operations
2836
* Tilde Semicolon-> Clause Separator::
2837
* Tilde Circumflex-> Escape Upward::
2838
* Tilde Newline-> Ignored Newline::
2841
@node Tilde Semicolon-> Clause Separator, Tilde Circumflex-> Escape Upward, FORMAT Miscellaneous Pseudo-Operations, FORMAT Miscellaneous Pseudo-Operations
2842
@subsubsection Tilde Semicolon: Clause Separator
2844
This separates clauses in @t{~[} and @t{~<} constructs.
2845
The consequences of using it elsewhere are undefined.
2847
@node Tilde Circumflex-> Escape Upward, Tilde Newline-> Ignored Newline, Tilde Semicolon-> Clause Separator, FORMAT Miscellaneous Pseudo-Operations
2848
@subsubsection Tilde Circumflex: Escape Upward
2852
This is an escape construct. If there are no more arguments remaining to
2853
be processed, then the immediately
2854
enclosing @t{~@{ } or @t{~<} construct
2855
is terminated. If there is no such enclosing construct, then the entire
2856
formatting operation is terminated.
2857
In the @t{~<} case, the formatting
2858
is performed, but no more segments are processed before doing the
2860
@t{~@t{^} } may appear anywhere in a @t{~@{ }
2864
(setq donestr "Done.~@t{^} ~D warning~:P.~@t{^} ~D error~:P.")
2865
@result{} "Done.~@t{^} ~D warning~:P.~@t{^} ~D error~:P."
2866
(format nil donestr) @result{} "Done."
2867
(format nil donestr 3) @result{} "Done. 3 warnings."
2868
(format nil donestr 1 5) @result{} "Done. 1 warning. 5 errors."
2871
If a prefix parameter is given, then termination occurs if the parameter
2872
is zero. (Hence @t{~@t{^}} is equivalent to
2873
@t{~#@t{^}}.) If two
2874
parameters are given, termination occurs if they are equal.
2876
[Reviewer Note by Barmar: Which equality predicate?] If three
2877
parameters are given, termination occurs if the first is less than or
2878
equal to the second and the second is less than or equal to the third.
2879
Of course, this is useless if all the prefix parameters are constants; at
2880
least one of them should be a @t{#} or a @t{V} parameter.
2882
If @t{~@t{^}} is used within a @t{~:@{ }
2883
construct, then it terminates
2884
the current iteration step because in the standard case it tests for
2885
remaining arguments of the current step only; the next iteration step
2886
commences immediately. @t{~:@t{^}} is used to terminate
2887
the iteration process.
2890
may be used only if the command it would terminate is
2891
@t{~:@{ } or @t{~:@@@{ }.
2892
The entire iteration process is terminated if and only if the sublist that is
2893
supplying the arguments for the current iteration step is the last sublist in
2894
the case of @t{~:@{ },
2895
or the last @b{format}
2896
argument in the case of @t{~:@@@{ }.
2898
equivalent to @t{~#:@t{^}};
2899
the latter terminates the entire iteration if and only if no
2900
arguments remain for the current iteration step.
2904
(format nil "~:@{ ~@@?~:@t{^} ...~@} " '(("a") ("b"))) @result{} "a...b"
2907
If @t{~@t{^}} appears within a control string being processed
2908
under the control of a @t{~?} directive, but not within
2909
any @t{~@{ } or @t{~<} construct within that string,
2910
then the string being
2911
processed will be terminated, thereby ending processing
2912
of the @t{~?} directive. Processing then
2913
continues within the string
2914
containing the @t{~?} directive at the point following that directive.
2917
appears within a @t{~[} or @t{~(} construct,
2918
then all the commands up to the @t{~@t{^}} are properly selected
2920
the @t{~[} or @t{~(} processing is terminated,
2921
and the outward search continues
2922
for a @t{~@{ } or @t{~<} construct
2923
to be terminated. For example:
2926
(setq tellstr "~@@(~@@[~R~]~@t{^} ~A!~)")
2927
@result{} "~@@(~@@[~R~]~@t{^} ~A!~)"
2928
(format nil tellstr 23) @result{} "Twenty-three!"
2929
(format nil tellstr nil "losers") @result{} " Losers!"
2930
(format nil tellstr 23 "losers") @result{} "Twenty-three losers!"
2933
Following are examples of the use of @t{~@t{^}}
2934
within a @t{~<} construct.
2937
(format nil "~15<~S~;~@t{^}~S~;~@t{^}~S~>" 'foo)
2939
(format nil "~15<~S~;~@t{^}~S~;~@t{^}~S~>" 'foo 'bar)
2941
(format nil "~15<~S~;~@t{^}~S~;~@t{^}~S~>" 'foo 'bar 'baz)
2942
@result{} "FOO BAR BAZ"
2945
@node Tilde Newline-> Ignored Newline, , Tilde Circumflex-> Escape Upward, FORMAT Miscellaneous Pseudo-Operations
2946
@subsubsection Tilde Newline: Ignored Newline
2948
@i{Tilde} immediately followed by a @i{newline} ignores the @i{newline}
2949
and any following non-newline @i{whitespace}_1 characters.
2951
the @i{newline} is ignored,
2952
but any following @i{whitespace}_1 is left in place.
2954
the @i{newline} is left in place,
2955
but any following @i{whitespace}_1 is ignored.
2959
(defun type-clash-error (fn nargs argnum right-type wrong-type)
2960
(format *error-output*
2961
"~&~S requires its ~:[~:R~;~*~]~
2962
argument to be of type ~S,~
2963
with an argument of type ~S.~
2964
fn (eql nargs 1) argnum right-type wrong-type))
2965
(type-clash-error 'aref nil 2 'integer 'vector) prints:
2966
AREF requires its second argument to be of type INTEGER,
2967
but it was called with an argument of type VECTOR.
2969
(type-clash-error 'car 1 1 'list 'short-float) prints:
2970
CAR requires its argument to be of type LIST,
2971
but it was called with an argument of type SHORT-FLOAT.
2975
Note that in this example newlines appear in the output only as specified
2976
by the @t{~&} and @t{~%} directives; the
2977
actual newline characters
2978
in the control string are suppressed because each is preceded by a tilde.
2980
@node Additional Information about FORMAT Operations, Examples of FORMAT, FORMAT Miscellaneous Pseudo-Operations, Formatted Output
2981
@subsection Additional Information about FORMAT Operations
2984
* Nesting of FORMAT Operations::
2985
* Missing and Additional FORMAT Arguments::
2986
* Additional FORMAT Parameters::
2987
* Undefined FORMAT Modifier Combinations::
2990
@node Nesting of FORMAT Operations, Missing and Additional FORMAT Arguments, Additional Information about FORMAT Operations, Additional Information about FORMAT Operations
2991
@subsubsection Nesting of FORMAT Operations
2993
The case-conversion, conditional, iteration, and justification
2994
constructs can contain other formatting constructs by bracketing them.
2995
These constructs must nest properly with respect to each other.
2996
For example, it is not legitimate to put the start of a case-conversion
2997
construct in each arm of a conditional and the
2998
end of the case-conversion construct outside the conditional:
3001
(format nil "~:[abc~:@@(def~;ghi~
3002
:@@(jkl~]mno~)" x) ;Invalid!
3005
This notation is invalid because the @t{~[...~;...~]}
3006
and @t{~(...~)} constructs are not properly nested.
3008
The processing indirection caused by the @t{~?} directive
3009
is also a kind of nesting for the purposes of this rule of proper nesting.
3010
It is not permitted to
3011
start a bracketing construct within a string processed
3012
under control of a @t{~?}
3013
directive and end the construct at some point after the @t{~?} construct
3014
in the string containing that construct, or vice versa.
3015
For example, this situation is invalid:
3018
(format nil "~@@?ghi~)" "abc~@@(def") ;Invalid!
3022
is invalid because the @t{~?}
3023
and @t{~(...~)} constructs are not properly nested.
3025
@node Missing and Additional FORMAT Arguments, Additional FORMAT Parameters, Nesting of FORMAT Operations, Additional Information about FORMAT Operations
3026
@subsubsection Missing and Additional FORMAT Arguments
3028
The consequences are undefined if no @i{arg} remains for a directive
3029
requiring an argument. However, it is permissible for one or more @i{args}
3030
to remain unprocessed by a directive; such @i{args} are ignored.
3032
@node Additional FORMAT Parameters, Undefined FORMAT Modifier Combinations, Missing and Additional FORMAT Arguments, Additional Information about FORMAT Operations
3033
@subsubsection Additional FORMAT Parameters
3035
The consequences are undefined if a format directive is given more parameters
3036
than it is described here as accepting.
3038
@node Undefined FORMAT Modifier Combinations, , Additional FORMAT Parameters, Additional Information about FORMAT Operations
3039
@subsubsection Undefined FORMAT Modifier Combinations
3041
The consequences are undefined if @i{colon} or @i{at-sign} modifiers
3042
are given to a directive in a combination not specifically described
3043
here as being meaningful.
3045
@node Examples of FORMAT, Notes about FORMAT, Additional Information about FORMAT Operations, Formatted Output
3046
@subsection Examples of FORMAT
3049
(format nil "foo") @result{} "foo"
3050
(setq x 5) @result{} 5
3051
(format nil "The answer is ~D." x) @result{} "The answer is 5."
3052
(format nil "The answer is ~3D." x) @result{} "The answer is 5."
3053
(format nil "The answer is ~3,'0D." x) @result{} "The answer is 005."
3054
(format nil "The answer is ~:D." (expt 47 x))
3055
@result{} "The answer is 229,345,007."
3056
(setq y "elephant") @result{} "elephant"
3057
(format nil "Look at the ~A!" y) @result{} "Look at the elephant!"
3058
(setq n 3) @result{} 3
3059
(format nil "~D item~:P found." n) @result{} "3 items found."
3060
(format nil "~R dog~:[s are~; is~] here." n (= n 1))
3061
@result{} "three dogs are here."
3062
(format nil "~R dog~:*~[s are~; is~:;s are~] here." n)
3063
@result{} "three dogs are here."
3064
(format nil "Here ~[are~;is~:;are~] ~:*~R pupp~:@@P." n)
3065
@result{} "Here are three puppies."
3070
(format nil "~6,2F|~6,2,1,'*F|~6,2,,'?F|~6F|~,2F|~F"
3071
x x x x x x)) @result{} FOO
3072
(foo 3.14159) @result{} " 3.14| 31.42| 3.14|3.1416|3.14|3.14159"
3073
(foo -3.14159) @result{} " -3.14|-31.42| -3.14|-3.142|-3.14|-3.14159"
3074
(foo 100.0) @result{} "100.00|******|100.00| 100.0|100.00|100.0"
3075
(foo 1234.0) @result{} "1234.00|******|??????|1234.0|1234.00|1234.0"
3076
(foo 0.006) @result{} " 0.01| 0.06| 0.01| 0.006|0.01|0.006"
3082
"~9,2,1,,'*E|~10,3,2,2,'?,,'$E|~
3085
(foo 3.14159) @result{} " 3.14E+0| 31.42$-01|+.003E+03| 3.14E+0"
3086
(foo -3.14159) @result{} " -3.14E+0|-31.42$-01|-.003E+03| -3.14E+0"
3087
(foo 1100.0) @result{} " 1.10E+3| 11.00$+02|+.001E+06| 1.10E+3"
3088
(foo 1100.0L0) @result{} " 1.10L+3| 11.00$+02|+.001L+06| 1.10L+3"
3089
(foo 1.1E13) @result{} "*********| 11.00$+12|+.001E+16| 1.10E+13"
3090
(foo 1.1L120) @result{} "*********|??????????|
3091
(foo 1.1L1200) @result{} "*********|??????????|
3094
As an example of the effects of varying the scale factor, the code
3099
(- k 5) (- k 5) 3.14159))
3102
produces the following output:
3105
Scale factor -5: | 0.000003E+06|
3106
Scale factor -4: | 0.000031E+05|
3107
Scale factor -3: | 0.000314E+04|
3108
Scale factor -2: | 0.003142E+03|
3109
Scale factor -1: | 0.031416E+02|
3110
Scale factor 0: | 0.314159E+01|
3111
Scale factor 1: | 3.141590E+00|
3112
Scale factor 2: | 31.41590E-01|
3113
Scale factor 3: | 314.1590E-02|
3114
Scale factor 4: | 3141.590E-03|
3115
Scale factor 5: | 31415.90E-04|
3116
Scale factor 6: | 314159.0E-05|
3117
Scale factor 7: | 3141590.E-06|
3122
(format nil "~9,2,1,,'*G|~9,3,2,3,'?,,'$G|~9,3,2,0,'
3124
(foo 0.0314159) @result{} " 3.14E-2|314.2$-04|0.314E-01| 3.14E-2"
3125
(foo 0.314159) @result{} " 0.31 |0.314 |0.314 | 0.31 "
3126
(foo 3.14159) @result{} " 3.1 | 3.14 | 3.14 | 3.1 "
3127
(foo 31.4159) @result{} " 31. | 31.4 | 31.4 | 31. "
3128
(foo 314.159) @result{} " 3.14E+2| 314. | 314. | 3.14E+2"
3129
(foo 3141.59) @result{} " 3.14E+3|314.2$+01|0.314E+04| 3.14E+3"
3130
(foo 3141.59L0) @result{} " 3.14L+3|314.2$+01|0.314L+04| 3.14L+3"
3131
(foo 3.14E12) @result{} "*********|314.0$+10|0.314E+13| 3.14E+12"
3132
(foo 3.14L120) @result{} "*********|?????????|
3133
(foo 3.14L1200) @result{} "*********|?????????|
3137
(format nil "~10<foo~;bar~>") @result{} "foo bar"
3138
(format nil "~10:<foo~;bar~>") @result{} " foo bar"
3139
(format nil "~10<foobar~>") @result{} " foobar"
3140
(format nil "~10:<foobar~>") @result{} " foobar"
3141
(format nil "~10:@@<foo~;bar~>") @result{} " foo bar "
3142
(format nil "~10@@<foobar~>") @result{} "foobar "
3143
(format nil "~10:@@<foobar~>") @result{} " foobar "
3147
(FORMAT NIL "Written to ~A." #P"foo.bin")
3148
@result{} "Written to foo.bin."
3151
@node Notes about FORMAT, , Examples of FORMAT, Formatted Output
3152
@subsection Notes about FORMAT
3154
Formatted output is performed not only by @b{format},
3155
but by certain other functions that accept a @i{format control}
3156
the way @b{format} does. For example, error-signaling functions
3157
such as @b{cerror} accept @i{format controls}.
3159
Note that the meaning of @b{nil} and @b{t} as destinations to @b{format}
3160
are different than those of @b{nil} and @b{t} as @i{stream designators}.
3162
The @t{~@t{^}} should appear only at the beginning of a @t{~<} clause,
3163
because it aborts the entire clause in which it appears (as well as
3164
all following clauses).
3166
@c end of including concept-format
3168
@node Printer Dictionary, , Formatted Output, Printer
3169
@section Printer Dictionary
3171
@c including dict-printer
3174
* copy-pprint-dispatch::
3177
* pprint-exit-if-list-exhausted::
3180
* pprint-logical-block::
3185
* print-unreadable-object::
3186
* set-pprint-dispatch::
3197
* *print-miser-width*::
3198
* *print-pprint-dispatch*::
3200
* *print-readably*::
3201
* *print-right-margin*::
3202
* print-not-readable::
3203
* print-not-readable-object::
3207
@node copy-pprint-dispatch, formatter, Printer Dictionary, Printer Dictionary
3208
@subsection copy-pprint-dispatch [Function]
3210
@code{copy-pprint-dispatch} @i{@r{&optional} table} @result{} @i{new-table}
3212
@subsubheading Arguments and Values::
3214
@i{table}---a @i{pprint dispatch table}, or @b{nil}.
3216
@i{new-table}---a @i{fresh} @i{pprint dispatch table}.
3218
@subsubheading Description::
3220
Creates and returns a copy of the specified @i{table},
3221
or of the @i{value} of @b{*print-pprint-dispatch*} if no @i{table} is specified,
3222
or of the initial @i{value} of @b{*print-pprint-dispatch*} if @b{nil} is specified.
3224
@subsubheading Exceptional Situations::
3226
Should signal an error of @i{type} @b{type-error} if @i{table}
3227
is not a @i{pprint dispatch table}.
3229
@node formatter, pprint-dispatch, copy-pprint-dispatch, Printer Dictionary
3230
@subsection formatter [Macro]
3232
@code{formatter} @i{control-string} @result{} @i{function}
3234
@subsubheading Arguments and Values::
3236
@i{control-string}---a @i{format string}; not evaluated.
3238
@i{function}---a @i{function}.
3240
@subsubheading Description::
3242
Returns a @i{function} which has behavior equivalent to:
3245
#'(lambda (*standard-output* &rest arguments)
3246
(apply #'format t @i{control-string} arguments)
3250
where @i{arguments-tail} is either the tail of @i{arguments}
3251
which has as its @i{car} the argument that would be processed next
3252
if there were more format directives in the @i{control-string},
3253
or else @b{nil} if no more @i{arguments} follow the most recently
3256
@subsubheading Examples::
3259
(funcall (formatter "~&~A~A") *standard-output* 'a 'b 'c)
3263
(format t (formatter "~&~A~A") 'a 'b 'c)
3268
@subsubheading Exceptional Situations::
3270
Might signal an error (at macro expansion time or at run time) if the argument
3271
is not a valid @i{format string}.
3273
@subsubheading See Also::
3277
@node pprint-dispatch, pprint-exit-if-list-exhausted, formatter, Printer Dictionary
3278
@subsection pprint-dispatch [Function]
3280
@code{pprint-dispatch} @i{object @r{&optional} table} @result{} @i{function, found-p}
3282
@subsubheading Arguments and Values::
3284
@i{object}---an @i{object}.
3286
@i{table}---a @i{pprint dispatch table}, or @b{nil}.
3287
The default is the @i{value} of @b{*print-pprint-dispatch*}.
3289
@i{function}---a @i{function designator}.
3291
@i{found-p}---a @i{generalized boolean}.
3293
@subsubheading Description::
3295
Retrieves the highest priority function in @i{table} that is
3296
associated with a @i{type specifier} that matches @i{object}.
3297
The function is chosen by finding all of the @i{type specifiers} in @i{table}
3298
that match the @i{object} and
3299
selecting the highest priority function associated with any of these
3300
@i{type specifiers}. If there is more than one highest priority function,
3301
an arbitrary choice is made. If no @i{type specifiers} match the
3302
@i{object}, a function is returned that prints @i{object}
3304
using @b{print-object}.
3306
The @i{secondary value}, @i{found-p}, is @i{true} if a matching
3307
@i{type specifier} was found in @i{table}, or @i{false} otherwise.
3309
If @i{table} is @b{nil},
3310
retrieval is done in the
3311
@i{initial pprint dispatch table}.
3313
@subsubheading Affected By::
3315
The state of the @i{table}.
3317
@subsubheading Exceptional Situations::
3319
Should signal an error of @i{type} @b{type-error} if @i{table} is neither a
3320
@i{pprint-dispatch-table} nor @b{nil}.
3322
@subsubheading Notes::
3325
(let ((*print-pretty* t))
3326
(write object :stream s))
3327
@equiv{} (funcall (pprint-dispatch object) s object)
3330
@node pprint-exit-if-list-exhausted, pprint-fill, pprint-dispatch, Printer Dictionary
3331
@subsection pprint-exit-if-list-exhausted [Local Macro]
3333
@subsubheading Syntax::
3335
@code{pprint-exit-if-list-exhausted} @i{<@i{no @i{arguments}}>} @result{} @i{@b{nil}}
3337
@subsubheading Description::
3339
Tests whether or not the @i{list} passed to
3340
the @i{lexically current logical block}
3341
has been exhausted; see @ref{Dynamic Control of the Arrangement of Output}.
3342
If this @i{list} has been
3343
reduced to @b{nil}, @b{pprint-exit-if-list-exhausted} terminates the execution
3344
of the @i{lexically current logical block} except for the printing
3345
of the suffix. Otherwise @b{pprint-exit-if-list-exhausted} returns @b{nil}.
3347
Whether or not @b{pprint-exit-if-list-exhausted} is @i{fbound} in the
3348
@i{global environment} is @i{implementation-dependent};
3349
however, the restrictions on redefinition and @i{shadowing} of
3350
@b{pprint-exit-if-list-exhausted} are the same as for @i{symbols} in the @t{COMMON-LISP} @i{package}
3351
which are @i{fbound} in the @i{global environment}.
3352
The consequences of attempting to use @b{pprint-exit-if-list-exhausted} outside
3353
of @b{pprint-logical-block} are undefined.
3355
@subsubheading Exceptional Situations::
3357
An error is signaled (at macro expansion time or at run time) if
3358
@b{pprint-exit-if-list-exhausted} is used anywhere other than
3359
lexically within a call on @b{pprint-logical-block}.
3360
Also, the consequences of executing @b{pprint-if-list-exhausted} outside
3361
of the dynamic extent of the @b{pprint-logical-block} which lexically
3362
contains it are undefined.
3364
@subsubheading See Also::
3366
@ref{pprint-logical-block}
3371
@node pprint-fill, pprint-indent, pprint-exit-if-list-exhausted, Printer Dictionary
3372
@subsection pprint-fill, pprint-linear, pprint-tabular [Function]
3374
@code{pprint-fill} @i{stream object @r{&optional} colon-p at-sign-p} @result{} @i{@b{nil}}
3376
@code{pprint-linear} @i{stream object @r{&optional} colon-p at-sign-p} @result{} @i{@b{nil}}
3378
@code{pprint-tabular} @i{stream object @r{&optional} colon-p at-sign-p tabsize} @result{} @i{@b{nil}}
3380
@subsubheading Arguments and Values::
3382
@i{stream}---an @i{output} @i{stream designator}.
3384
@i{object}---an @i{object}.
3386
@i{colon-p}---a @i{generalized boolean}.
3387
The default is @i{true}.
3389
@i{at-sign-p}---a @i{generalized boolean}.
3390
The default is @i{implementation-dependent}.
3392
@i{tabsize}---a non-negative @i{integer}.
3393
The default is @t{16}.
3395
@subsubheading Description::
3397
The functions @b{pprint-fill}, @b{pprint-linear}, and
3398
@b{pprint-tabular} specify particular ways of @i{pretty printing}
3399
a @i{list} to @i{stream}.
3400
Each function prints parentheses around the output if and only
3401
if @i{colon-p} is @i{true}.
3402
Each function ignores its @i{at-sign-p} argument.
3403
(Both arguments are included even though only one is needed
3404
so that these functions can be used via @t{~/.../}
3405
and as @b{set-pprint-dispatch} functions, as well as directly.)
3406
Each function handles abbreviation and the detection of circularity
3407
and sharing correctly, and uses @b{write} to print @i{object}
3408
when it is a @i{non-list}.
3410
If @i{object} is a @i{list} and
3411
if the @i{value} of @b{*print-pretty*} is @i{false},
3412
each of these functions prints @i{object}
3413
using a minimum of @i{whitespace},
3414
as described in @ref{Printing Lists and Conses}.
3415
Otherwise (if @i{object} is a @i{list} and
3416
if the @i{value} of @b{*print-pretty*} is @i{true}):
3421
The @i{function} @b{pprint-linear} prints a @i{list} either all on one line,
3422
or with each @i{element} on a separate line.
3425
The @i{function} @b{pprint-fill} prints a @i{list} with as many @i{elements}
3426
as possible on each line.
3429
The @i{function} @b{pprint-tabular} is the same as @b{pprint-fill}
3430
except that it prints the @i{elements} so that they line up in columns.
3431
The @i{tabsize} specifies the column spacing in @i{ems},
3432
which is the total spacing from the leading edge of one column to
3433
the leading edge of the next.
3436
@subsubheading Examples::
3438
Evaluating the following with a line length of @t{25} produces the output shown.
3441
(progn (princ "Roads ")
3442
(pprint-tabular *standard-output* '(elm main maple center) nil nil 8))
3447
@subsubheading Side Effects::
3449
Performs output to the indicated @i{stream}.
3451
@subsubheading Affected By::
3453
The cursor position on the indicated @i{stream}, if it can be determined.
3455
@subsubheading Notes::
3457
The @i{function} @b{pprint-tabular} could be defined as follows:
3460
(defun pprint-tabular (s list &optional (colon-p t) at-sign-p (tabsize nil))
3461
(declare (ignore at-sign-p))
3462
(when (null tabsize) (setq tabsize 16))
3463
(pprint-logical-block (s list :prefix (if colon-p "(" "")
3464
:suffix (if colon-p ")" ""))
3465
(pprint-exit-if-list-exhausted)
3466
(loop (write (pprint-pop) :stream s)
3467
(pprint-exit-if-list-exhausted)
3468
(write-char #\Space s)
3469
(pprint-tab :section-relative 0 tabsize s)
3470
(pprint-newline :fill s))))
3473
Note that it would have been inconvenient to specify this function
3474
using @b{format}, because of the need to pass its @i{tabsize} argument
3475
through to a @t{~:T} format directive nested within an iteration over a list.
3477
@node pprint-indent, pprint-logical-block, pprint-fill, Printer Dictionary
3478
@subsection pprint-indent [Function]
3480
@code{pprint-indent} @i{relative-to n @r{&optional} stream} @result{} @i{@b{nil}}
3482
@subsubheading Arguments and Values::
3484
@i{relative-to}---either @t{:block} or @t{:current}.
3488
@i{stream}---an @i{output} @i{stream designator}.
3489
The default is @i{standard output}.
3491
@subsubheading Description::
3493
@b{pprint-indent} specifies the indentation to use in a logical block on @i{stream}.
3495
If @i{stream} is a @i{pretty printing stream}
3496
and the @i{value} of @b{*print-pretty*} is @i{true},
3497
@b{pprint-indent} sets the indentation in the innermost
3498
dynamically enclosing logical block;
3499
otherwise, @b{pprint-indent} has no effect.
3501
@i{N} specifies the indentation in
3502
@i{ems}. If @i{relative-to} is @t{:block}, the indentation is set
3503
to the horizontal position of the first character in the @i{dynamically current logical block} plus @i{n}
3504
@i{ems}. If @i{relative-to} is @t{:current}, the indentation is set
3505
to the current output position plus @i{n} @i{ems}. (For robustness
3506
in the face of variable-width fonts, it is advisable to use @t{:current}
3507
with an @i{n} of zero whenever possible.)
3509
@i{N} can be negative;
3510
however, the total indentation cannot be moved
3511
left of the beginning of the line
3512
or left of the end of the rightmost per-line prefix---an attempt to move beyond
3513
one of these limits is treated
3514
the same as an attempt to move to that limit.
3515
Changes in indentation caused by @i{pprint-indent}
3516
do not take effect until after the next line break. In addition, in
3517
miser mode all calls to @b{pprint-indent} are ignored, forcing the lines
3518
corresponding to the logical block to line up under the first character in
3521
@subsubheading Exceptional Situations::
3523
An error is signaled if @i{relative-to} is any @i{object} other
3524
than @t{:block} or @t{:current}.
3526
@subsubheading See Also::
3528
@ref{Tilde I-> Indent}
3530
@node pprint-logical-block, pprint-newline, pprint-indent, Printer Dictionary
3531
@subsection pprint-logical-block [Macro]
3533
@code{pprint-logical-block} @i{@r{(}stream-symbol object
3534
@r{&key} prefix per-line-prefix suffix@r{)}
3535
@{@i{declaration}@}* @{@i{form}@}*}@*
3536
@result{} @i{@b{nil}}
3538
@subsubheading Arguments and Values::
3540
@i{stream-symbol}---a @i{stream variable designator}.
3542
@i{object}---an @i{object}; evaluated.
3544
@t{:prefix}---a @i{string}; evaluated.
3545
Complicated defaulting behavior; see below.
3547
@t{:per-line-prefix}---a @i{string}; evaluated.
3548
Complicated defaulting behavior; see below.
3550
@t{:suffix}---a @i{string}; evaluated.
3551
The default is the @i{null} @i{string}.
3553
@i{declaration}---a @b{declare} @i{expression}; not evaluated.
3555
@i{forms}---an @i{implicit progn}.
3557
@subsubheading Description::
3559
Causes printing to be grouped into a logical block.
3561
The logical block is printed to the @i{stream} that is the @i{value}
3562
of the @i{variable} denoted by @i{stream-symbol}.
3563
During the execution of the @i{forms},
3564
that @i{variable} is @i{bound} to a @i{pretty printing stream}
3565
that supports decisions about the arrangement of output
3566
and then forwards the output to the destination stream.
3568
All the standard printing functions
3569
(@i{e.g.}, @b{write},
3572
can be used to print output to the @i{pretty printing stream}.
3573
All and only the output sent to this @i{pretty printing stream}
3574
is treated as being in the logical block.
3576
The @i{prefix} specifies a prefix to be printed before the beginning of
3578
The @i{per-line-prefix} specifies a prefix that is printed before the block
3579
and at the beginning of each new line in the block.
3580
The @t{:prefix} and @t{:pre-line-prefix} @i{arguments} are mutually exclusive.
3581
If neither @t{:prefix} nor @t{:per-line-prefix} is specified,
3582
a @i{prefix} of the @i{null} @i{string} is assumed.
3584
The @i{suffix} specifies a suffix that is printed just after the logical block.
3588
a @i{list} that the body @i{forms} are responsible for printing.
3589
If @i{object} is not a @i{list},
3590
it is printed using @b{write}.
3591
(This makes it easier to write printing functions that are robust
3592
in the face of malformed arguments.)
3593
If @b{*print-circle*}
3594
is @i{non-nil} and @i{object} is a circular (or shared) reference to a @i{cons},
3595
then an appropriate ``@t{#@i{n}#}'' marker is printed. (This
3596
makes it easy to write printing functions that provide full support
3597
for circularity and sharing abbreviation.) If @b{*print-level*} is not
3598
@b{nil} and the logical block is at a dynamic nesting depth of greater
3599
than @b{*print-level*} in logical blocks, ``@t{#}'' is printed.
3600
(This makes easy to write printing functions that provide full support for depth
3603
If either of the three conditions above occurs, the indicated output is
3604
printed on @i{stream-symbol} and the body @i{forms} are skipped
3605
along with the printing of the @t{:prefix} and @t{:suffix}.
3606
(If the body @i{forms} are not to be responsible for printing a list,
3607
then the first two tests above can be turned off by supplying @b{nil} for
3608
the @i{object} argument.)
3610
In addition to the @i{object} argument of @b{pprint-logical-block},
3611
the arguments of the standard printing functions (such as @b{write},
3612
@b{print}, @b{prin1}, and @b{pprint}, as well as the arguments
3613
of the standard @i{format directives} such as @t{~A}, @t{~S},
3614
(and @t{~W}) are all checked (when necessary) for circularity and sharing.
3615
However, such checking is not applied to the arguments of the
3616
functions @b{write-line}, @b{write-string}, and @b{write-char}
3617
or to the literal text output by @b{format}. A consequence of this is
3618
that you must use one of the latter functions if you want to print some
3619
literal text in the output that is not supposed to be checked for circularity
3622
The body @i{forms} of a @b{pprint-logical-block} @i{form}
3623
must not perform any side-effects on the surrounding environment; for
3624
example, no @i{variables} must be assigned which have not been
3625
@i{bound} within its scope.
3627
The @b{pprint-logical-block} @i{macro} may be used regardless of the @i{value} of @b{*print-pretty*}.
3629
@subsubheading Affected By::
3631
@b{*print-circle*}, @b{*print-level*}.
3633
@subsubheading Exceptional Situations::
3635
An error of @i{type} @b{type-error} is signaled if any of the @t{:suffix},
3636
@t{:prefix}, or @t{:per-line-prefix} is supplied but does not evaluate
3639
An error is signaled if @t{:prefix} and @t{:pre-line-prefix} are both used.
3641
@b{pprint-logical-block} and the @i{pretty printing stream} it creates
3642
have @i{dynamic extent}. The consequences are undefined if, outside
3643
of this extent, output is attempted to the @i{pretty printing stream} it creates.
3645
It is also unspecified what happens if, within this extent, any output is
3646
sent directly to the underlying destination stream.
3648
@subsubheading See Also::
3652
@ref{pprint-exit-if-list-exhausted}
3654
@ref{Tilde Less-Than-Sign-> Logical Block}
3656
@subsubheading Notes::
3658
One reason for using the @b{pprint-logical-block} @i{macro} when the @i{value} of @b{*print-pretty*}
3659
is @b{nil} would be to allow it to perform checking for @i{dotted lists},
3660
as well as (in conjunction with @b{pprint-pop})
3661
checking for @b{*print-level*} or @b{*print-length*} being exceeded.
3663
Detection of circularity and sharing is supported by the @i{pretty printer}
3664
by in essence performing requested output twice. On the first pass,
3665
circularities and sharing are detected and the actual outputting of characters
3666
is suppressed. On the second pass, the appropriate ``@t{#@i{n}=}''
3667
and ``@t{#@i{n}#}'' markers are inserted and characters are output.
3668
This is why the restriction on side-effects is necessary.
3669
Obeying this restriction is facilitated by using @b{pprint-pop},
3670
instead of an ordinary @b{pop} when traversing a list being printed by
3671
the body @i{forms} of the @b{pprint-logical-block} @i{form}.)
3673
@node pprint-newline, pprint-pop, pprint-logical-block, Printer Dictionary
3674
@subsection pprint-newline [Function]
3676
@code{pprint-newline} @i{kind @r{&optional} stream} @result{} @i{@b{nil}}
3678
@subsubheading Arguments and Values::
3680
@i{kind}---one of @t{:linear}, @t{:fill}, @t{:miser}, or @t{:mandatory}.
3682
@i{stream}---a @i{stream designator}.
3683
The default is @i{standard output}.
3685
@subsubheading Description::
3687
If @i{stream} is a @i{pretty printing stream}
3688
and the @i{value} of @b{*print-pretty*} is @i{true},
3689
a line break is inserted in the output
3690
when the appropriate condition below is satisfied;
3691
otherwise, @b{pprint-newline} has no effect.
3693
@i{Kind} specifies the style of conditional newline.
3694
This @i{parameter} is treated as follows:
3700
``linear-style'' @i{conditional newline}.
3701
@ITindex{linear-style conditional newline}
3703
A line break is inserted
3704
if and only if the immediately containing @i{section}
3705
cannot be printed on one line.
3706
The effect of this is that line breaks are
3707
either inserted at every linear-style conditional newline in a logical block
3712
``miser-style'' @i{conditional newline}.
3713
@ITindex{miser-style conditional newline}
3715
A line break is inserted
3716
if and only if the immediately containing @i{section}
3717
cannot be printed on one line
3718
and miser style is in effect in the immediately containing logical block.
3719
The effect of this is that miser-style conditional newlines
3720
act like linear-style conditional newlines,
3721
but only when miser style is in effect.
3722
Miser style is in effect for a logical block if and only if
3723
the starting position of the logical block
3724
is less than or equal to
3725
@b{*print-miser-width*} @i{ems} from the right margin.
3729
``fill-style'' @i{conditional newline}.
3730
@ITindex{fill-style conditional newline}
3732
A line break is inserted if and only if
3733
either (a) the following @i{section} cannot be printed
3734
on the end of the current line,
3735
(b) the preceding @i{section} was not printed on a single line,
3736
or (c) the immediately containing @i{section} cannot
3737
be printed on one line and miser style is in effect
3738
in the immediately containing logical block.
3739
If a logical block is broken up into a number of subsections
3740
by fill-style conditional newlines,
3741
the basic effect is that the logical block
3742
is printed with as many subsections as possible on each line.
3743
However, if miser style is in effect,
3744
fill-style conditional newlines act like linear-style conditional newlines.
3746
@item @t{:mandatory}
3748
``mandatory-style'' @i{conditional newline}.
3749
@ITindex{mandatory-style conditional newline}
3751
A line break is always inserted.
3752
This implies that none of the containing @i{sections}
3753
can be printed on a single line and
3754
will therefore trigger the insertion of line breaks
3755
at linear-style conditional newlines in these @i{sections}.
3759
When a line break is inserted by any type of conditional newline,
3760
any blanks that immediately precede the conditional newline are omitted
3761
from the output and indentation is introduced at the beginning of the next line.
3762
By default, the indentation causes the following line to begin
3763
in the same horizontal position
3764
as the first character in the immediately containing logical block.
3765
(The indentation can be changed via @b{pprint-indent}.)
3767
There are a variety of ways unconditional newlines can be introduced into
3768
the output (@i{i.e.}, via @b{terpri} or by printing a string containing a newline
3769
character). As with mandatory conditional newlines, this prevents any of
3770
the containing @i{sections} from being printed on one line. In general, when
3771
an unconditional newline is encountered, it is printed out without
3772
suppression of the preceding blanks and without any indentation following
3773
it. However, if a per-line prefix has been specified (see
3774
@b{pprint-logical-block}), this prefix will always be printed no matter
3775
how a newline originates.
3777
@subsubheading Examples::
3779
See @ref{Examples of using the Pretty Printer}.
3781
@subsubheading Side Effects::
3783
Output to @i{stream}.
3785
@subsubheading Affected By::
3787
@b{*print-pretty*}, @b{*print-miser*}.
3788
The presence of containing logical blocks.
3789
The placement of newlines and conditional newlines.
3791
@subsubheading Exceptional Situations::
3793
An error of @i{type} @b{type-error} is signaled if @i{kind}
3794
is not one of @t{:linear}, @t{:fill}, @t{:miser}, or @t{:mandatory}.
3796
@subsubheading See Also::
3798
@ref{Tilde Underscore-> Conditional Newline},
3799
@ref{Examples of using the Pretty Printer}
3801
@node pprint-pop, pprint-tab, pprint-newline, Printer Dictionary
3802
@subsection pprint-pop [Local Macro]
3804
@subsubheading Syntax::
3806
@code{pprint-pop} @i{<@i{no @i{arguments}}>} @result{} @i{object}
3808
@subsubheading Arguments and Values::
3810
@i{object}---an @i{element} of the @i{list}
3811
being printed in the @i{lexically current logical block},
3814
@subsubheading Description::
3816
Pops one @i{element} from the @i{list} being printed
3817
in the @i{lexically current logical block}, obeying @b{*print-length*}
3818
and @b{*print-circle*} as described below.
3820
Each time @b{pprint-pop} is called, it pops the next value off the
3821
@i{list} passed to the @i{lexically current logical block} and returns it.
3822
However, before doing this, it performs three tests:
3827
If the remaining `list' is not a @i{list},
3828
``@t{. }'' is printed followed by the remaining `list.'
3829
(This makes it easier to write printing functions that
3830
are robust in the face of malformed arguments.)
3833
If @b{*print-length*} is @i{non-nil},
3834
and @b{pprint-pop} has already been called @b{*print-length*} times
3835
within the immediately containing logical block,
3836
``@t{...}'' is printed.
3837
(This makes it easy to write printing functions that properly handle
3838
@b{*print-length*}.)
3841
If @b{*print-circle*} is
3842
@i{non-nil}, and the remaining list is a circular (or shared) reference,
3843
then ``@t{. }'' is printed followed by an appropriate
3844
``@t{#@i{n}#}'' marker.
3845
(This catches instances of @i{cdr} circularity and sharing in lists.)
3848
If either of the three conditions above occurs, the indicated output is
3849
printed on the @i{pretty printing stream} created by the immediately containing
3850
@b{pprint-logical-block} and the execution of the immediately containing
3851
@b{pprint-logical-block} is terminated except for the printing of the suffix.
3853
If @b{pprint-logical-block} is given a `list' argument of @b{nil}---because
3854
it is not processing a list---@b{pprint-pop} can still be used to obtain
3855
support for @b{*print-length*}.
3856
In this situation, the first and third tests above are disabled and
3857
@b{pprint-pop} always returns @b{nil}.
3858
See @ref{Examples of using the Pretty Printer}---specifically, the @b{pprint-vector} example.
3860
Whether or not @b{pprint-pop} is @i{fbound} in the
3861
@i{global environment} is @i{implementation-dependent};
3862
however, the restrictions on redefinition and @i{shadowing} of
3863
@b{pprint-pop} are the same as for @i{symbols} in the @t{COMMON-LISP} @i{package}
3864
which are @i{fbound} in the @i{global environment}.
3865
The consequences of attempting to use @b{pprint-pop} outside
3866
of @b{pprint-logical-block} are undefined.
3868
@subsubheading Side Effects::
3871
to the @i{pretty printing stream} associated with the lexically current logical block.
3873
@subsubheading Affected By::
3875
@b{*print-length*}, @b{*print-circle*}.
3877
@subsubheading Exceptional Situations::
3879
An error is signaled (either at macro expansion time or at run time)
3880
if a usage of @b{pprint-pop} occurs where there is no lexically
3881
containing @b{pprint-logical-block} @i{form}.
3883
The consequences are undefined if @b{pprint-pop} is executed outside
3884
of the @i{dynamic extent} of this @b{pprint-logical-block}.
3886
@subsubheading See Also::
3888
@ref{pprint-exit-if-list-exhausted}
3890
@ref{pprint-logical-block}
3893
@subsubheading Notes::
3895
It is frequently a good idea to call @b{pprint-exit-if-list-exhausted}
3896
before calling @b{pprint-pop}.
3898
@node pprint-tab, print-object, pprint-pop, Printer Dictionary
3899
@subsection pprint-tab [Function]
3901
@code{pprint-tab} @i{kind colnum colinc @r{&optional} stream} @result{} @i{@b{nil}}
3903
@subsubheading Arguments and Values::
3905
@i{kind}---one of @t{:line}, @t{:section}, @t{:line-relative},
3906
or @t{:section-relative}.
3908
@i{colnum}---a non-negative @i{integer}.
3910
@i{colinc}---a non-negative @i{integer}.
3912
@i{stream}---an @i{output} @i{stream designator}.
3914
@subsubheading Description::
3916
Specifies tabbing to @i{stream} as performed by the standard @t{~T} format directive.
3918
If @i{stream} is a @i{pretty printing stream} and
3919
the @i{value} of @b{*print-pretty*} is @i{true},
3921
tabbing is performed;
3922
otherwise, @b{pprint-tab} has no effect.
3924
The arguments @i{colnum} and @i{colinc} correspond to the two
3925
@i{parameters} to @t{~T} and are in terms of @i{ems}.
3926
The @i{kind} argument specifies the style of tabbing. It must be one of
3927
@t{:line} (tab as by @t{~T}),
3928
@t{:section} (tab as by @t{~:T},
3929
but measuring horizontal positions relative to
3930
the start of the dynamically enclosing section),
3931
@t{:line-relative} (tab as by @t{~@@T}), or
3932
@t{:section-relative} (tab as by @t{~:@@T},
3933
but measuring horizontal positions relative to
3934
the start of the dynamically enclosing section).
3936
@subsubheading Exceptional Situations::
3938
An error is signaled if @i{kind} is not one of @t{:line},
3939
@t{:section}, @t{:line-relative}, or @t{:section-relative}.
3941
@subsubheading See Also::
3943
@ref{pprint-logical-block}
3945
@node print-object, print-unreadable-object, pprint-tab, Printer Dictionary
3946
@subsection print-object [Standard Generic Function]
3948
@subsubheading Syntax::
3950
@code{print-object} @i{object stream} @result{} @i{object}
3952
@subsubheading Method Signatures::
3954
@code{print-object} @i{@r{(}@i{object} standard-object@r{)} @i{stream}}
3956
@code{print-object} @i{@r{(}@i{object} structure-object@r{)} @i{stream}}
3958
@subsubheading Arguments and Values::
3960
@i{object}---an @i{object}.
3962
@i{stream}---a @i{stream}.
3964
@subsubheading Description::
3966
The @i{generic function} @b{print-object} writes the printed representation of @i{object}
3968
The @i{function} @b{print-object} is called by the @i{Lisp printer};
3969
it should not be called by the user.
3971
Each implementation is required to provide a @i{method} on
3972
the @i{class} @b{standard-object} and on the @i{class} @b{structure-object}.
3973
In addition, each @i{implementation} must provide
3974
@i{methods} on enough other @i{classes}
3975
so as to ensure that there is always an applicable @i{method}.
3976
Implementations are free to add @i{methods} for other @i{classes}.
3977
Users may write @i{methods} for @b{print-object} for their own
3978
@i{classes} if they do not wish to inherit an
3979
@i{implementation-dependent} @i{method}.
3981
The @i{method} on the @i{class} @b{structure-object} prints the object in the
3982
default @t{#S} notation; see @ref{Printing Structures}.
3984
@i{Methods} on @b{print-object} are responsible for implementing
3985
their part of the semantics of the @i{printer control variables}, as follows:
3989
@item @b{*print-readably*}
3990
All methods for @b{print-object} must obey @b{*print-readably*}.
3991
This includes both user-defined methods and @i{implementation-defined} methods.
3992
Readable printing of @i{structures} and @i{standard objects}
3993
is controlled by their @b{print-object} method,
3994
not by their @b{make-load-form} @i{method}.
3995
@i{Similarity} for these @i{objects} is application dependent
3996
and hence is defined to be whatever these @i{methods} do;
3997
see @ref{Similarity of Literal Objects}.
3999
@item @b{*print-escape*}
4000
Each @i{method} must implement @b{*print-escape*}.
4002
@item @b{*print-pretty*}
4004
The @i{method} may wish to perform specialized line breaking
4005
or other output conditional on the @i{value} of @b{*print-pretty*}.
4006
For further information,
4007
see (for example) the @i{macro} @b{pprint-fill}.
4008
See also @ref{Pretty Print Dispatch Tables} and @ref{Examples of using the Pretty Printer}.
4010
@item @b{*print-length*}
4011
@i{Methods} that produce output of indefinite length must obey
4014
For further information,
4015
see (for example) the @i{macros} @b{pprint-logical-block}
4017
See also @ref{Pretty Print Dispatch Tables} and @ref{Examples of using the Pretty Printer}.
4019
@item @b{*print-level*}
4020
The printer takes care of @b{*print-level*} automatically,
4021
provided that each @i{method} handles exactly one level of structure and
4022
calls @b{write} (or an equivalent @i{function}) recursively if
4023
there are more structural levels. The printer's decision of whether an
4024
@i{object} has components (and therefore should not be printed when the
4025
printing depth is not less than @b{*print-level*}) is
4026
@i{implementation-dependent}. In some implementations its
4027
@b{print-object} @i{method} is not called;
4028
in others the @i{method} is called,
4029
and the determination that the @i{object} has components is based on what
4030
it tries to write to the @i{stream}.
4032
@item @b{*print-circle*}
4034
When the @i{value} of @b{*print-circle*} is @i{true},
4037
@b{print-object} @i{method}
4039
can print @i{objects} to the supplied @i{stream}
4044
and expect circularities to be detected
4045
and printed using the @t{#@i{n}#} syntax.
4048
@b{print-object} @i{method}
4050
prints to a @i{stream} other than the one
4051
that was supplied, then circularity detection starts over for that
4052
@i{stream}. See @b{*print-circle*}.
4054
@item @b{*print-base*},
4058
and @b{*print-array*}
4059
These @i{printer control variables} apply to specific types of @i{objects}
4060
and are handled by the @i{methods} for those @i{objects}.
4064
If these rules are not obeyed, the results are undefined.
4066
In general, the printer and the @b{print-object} methods should not
4067
rebind the print control variables as they operate recursively through the
4068
structure, but this is @i{implementation-dependent}.
4070
In some implementations the @i{stream} argument passed to a
4071
@b{print-object} @i{method} is not the original @i{stream},
4072
but is an intermediate @i{stream} that implements part of the printer.
4073
@i{methods} should therefore not depend on the identity of this @i{stream}.
4075
@subsubheading See Also::
4079
@ref{pprint-logical-block}
4085
@b{*print-readably*},
4089
@ref{Default Print-Object Methods},
4091
@ref{Printing Structures},
4093
@ref{Pretty Print Dispatch Tables},
4094
@ref{Examples of using the Pretty Printer}
4096
@node print-unreadable-object, set-pprint-dispatch, print-object, Printer Dictionary
4097
@subsection print-unreadable-object [Macro]
4099
@code{print-unreadable-object} @i{@r{(}object stream @r{&key} type identity@r{)} @{@i{form}@}*} @result{} @i{@b{nil}}
4101
@subsubheading Arguments and Values::
4103
@i{object}---an @i{object}; evaluated.
4106
a @i{stream designator}; evaluated.
4108
@i{type}---a @i{generalized boolean}; evaluated.
4110
@i{identity}---a @i{generalized boolean}; evaluated.
4112
@i{forms}---an @i{implicit progn}.
4114
@subsubheading Description::
4116
Outputs a printed representation of @i{object} on @i{stream},
4117
beginning with ``@t{#<}'' and ending with ``@t{>}''.
4118
Everything output to @i{stream} by the body @i{forms}
4119
is enclosed in the the angle brackets.
4120
If @i{type} is @i{true}, the output from @i{forms}
4121
is preceded by a brief description of the @i{object}'s
4122
@i{type} and a space character.
4123
If @i{identity} is @i{true},
4124
the output from @i{forms} is followed by a space character
4125
and a representation of the @i{object}'s identity,
4126
typically a storage address.
4128
If either @i{type} or @i{identity} is not supplied,
4129
its value is @i{false}. It is valid to omit the body @i{forms}.
4130
If @i{type} and @i{identity} are both true and there are no
4131
body @i{forms}, only one space character separates the type
4134
@subsubheading Examples::
4136
;; Note that in this example, the precise form of the output
4137
;; is @i{implementation-dependent}.
4140
(defmethod print-object ((obj airplane) stream)
4141
(print-unreadable-object (obj stream :type t :identity t)
4142
(princ (tail-number obj) stream)))
4144
(prin1-to-string my-airplane)
4145
@result{} "#<Airplane NW0773 36000123135>"
4146
@i{OR}@result{} "#<FAA:AIRPLANE NW0773 17>"
4149
@subsubheading Exceptional Situations::
4151
If @b{*print-readably*} is @i{true}, @b{print-unreadable-object}
4152
signals an error of @i{type} @b{print-not-readable} without printing anything.
4154
@node set-pprint-dispatch, write, print-unreadable-object, Printer Dictionary
4155
@subsection set-pprint-dispatch [Function]
4157
@code{set-pprint-dispatch} @i{type-specifier function @r{&optional} priority table} @result{} @i{@b{nil}}
4159
@subsubheading Arguments and Values::
4161
@i{type-specifier}---a @i{type specifier}.
4163
@i{function}---a @i{function}, a @i{function name}, or @b{nil}.
4165
@i{priority}---a @i{real}.
4166
The default is @t{0}.
4168
@i{table}---a @i{pprint dispatch table}.
4169
The default is the @i{value} of @b{*print-pprint-dispatch*}.
4171
@subsubheading Description::
4173
Installs an entry into the @i{pprint dispatch table} which is @i{table}.
4177
of the entry. The first action of @b{set-pprint-dispatch} is to remove any
4178
pre-existing entry associated with @i{type-specifier}. This guarantees that
4179
there will never be two entries associated with the same @i{type specifier}
4180
in a given @i{pprint dispatch table}. Equality of @i{type specifiers} is
4181
tested by @b{equal}.
4183
Two values are associated with each @i{type specifier} in a
4184
@i{pprint dispatch table}: a @i{function} and a @i{priority}.
4185
The @i{function} must accept two arguments: the @i{stream} to which output
4186
is sent and the @i{object} to be printed. The @i{function} should
4187
@i{pretty print} the @i{object} to the @i{stream}. The @i{function}
4188
can assume that object satisfies the @i{type} given by @i{type-specifier}.
4189
The @i{function} must obey @b{*print-readably*}.
4190
Any values returned by the @i{function} are ignored.
4192
@i{Priority} is a priority to resolve conflicts
4193
when an object matches more than one entry.
4195
It is permissible for @i{function} to be @b{nil}. In this situation,
4196
there will be no @i{type-specifier} entry in @i{table} after
4197
@b{set-pprint-dispatch} returns.
4199
@subsubheading Exceptional Situations::
4201
An error is signaled if @i{priority} is not a @i{real}.
4203
@subsubheading Notes::
4205
Since @i{pprint dispatch tables} are often used to control the pretty
4206
printing of Lisp code, it is common for the @i{type-specifier} to be
4207
an @i{expression} of the form
4210
(cons @i{car-type} @i{cdr-type})
4213
This signifies that the corresponding object must be a cons cell
4214
whose @i{car} matches the @i{type specifier} @i{car-type}
4215
and whose @i{cdr} matches the @i{type specifier} @i{cdr-type}.
4216
The @i{cdr-type} can be omitted in which case it defaults to @b{t}.
4218
@node write, write-to-string, set-pprint-dispatch, Printer Dictionary
4219
@subsection write, prin1, print, pprint, princ [Function]
4221
@code{write} @i{@i{object} @r{&key} \writekeys@r{stream}}@*
4222
@result{} @i{object}
4224
@code{prin} @i{1} @result{} @i{object @r{&optional} output-stream}
4226
@code{princ} @i{object @r{&optional} output-stream} @result{} @i{object}
4228
@code{print} @i{object @r{&optional} output-stream} @result{} @i{object}
4230
@code{pprint} @i{object @r{&optional} output-stream} @result{} @i{<@i{no @i{values}}>}
4232
@subsubheading Arguments and Values::
4234
@i{object}---an @i{object}.
4236
@i{output-stream}---an @i{output} @i{stream designator}.
4237
The default is @i{standard output}.
4239
\writekeydescriptions@r{@i{stream}---an @i{output} @i{stream designator}.
4240
The default is @i{standard output}.}
4242
@subsubheading Description::
4244
@b{write}, @b{prin1}, @b{princ}, @b{print}, and @b{pprint}
4245
write the printed representation of @i{object} to @i{output-stream}.
4247
@b{write} is the general entry point to the @i{Lisp printer}.
4248
For each explicitly supplied @i{keyword parameter} named in Figure 22--6,
4249
the corresponding @i{printer control variable} is dynamically bound to its @i{value}
4250
while printing goes on;
4251
for each @i{keyword parameter} in Figure 22--6 that is not explicitly supplied,
4252
the value of the corresponding @i{printer control variable} is the same as it was
4253
at the time @b{write} was invoked.
4254
Once the appropriate @i{bindings} are @i{established},
4255
the @i{object} is output by the @i{Lisp printer}.
4260
@w{ Parameter Corresponding Dynamic Variable }
4261
@w{ @i{array} @b{*print-array*} }
4262
@w{ @i{base} @b{*print-base*} }
4263
@w{ @i{case} @b{*print-case*} }
4264
@w{ @i{circle} @b{*print-circle*} }
4265
@w{ @i{escape} @b{*print-escape*} }
4266
@w{ @i{gensym} @b{*print-gensym*} }
4267
@w{ @i{length} @b{*print-length*} }
4268
@w{ @i{level} @b{*print-level*} }
4269
@w{ @i{lines} @b{*print-lines*} }
4270
@w{ @i{miser-width} @b{*print-miser-width*} }
4271
@w{ @i{pprint-dispatch} @b{*print-pprint-dispatch*} }
4272
@w{ @i{pretty} @b{*print-pretty*} }
4273
@w{ @i{radix} @b{*print-radix*} }
4274
@w{ @i{readably} @b{*print-readably*} }
4275
@w{ @i{right-margin} @b{*print-right-margin*} }
4278
@w{ Figure 22--6: Argument correspondences for the WRITE function.}
4283
@b{prin1}, @b{princ}, @b{print}, and @b{pprint} implicitly
4284
@i{bind} certain print parameters to particular values. The remaining parameter
4285
values are taken from
4295
@b{*print-miser-width*},
4296
@b{*print-pprint-dispatch*},
4299
and @b{*print-right-margin*}.
4301
@b{prin1} produces output suitable for input to @b{read}.
4302
It binds @b{*print-escape*} to @i{true}.
4304
@b{princ} is just like @b{prin1} except that the
4305
output has no @i{escape} @i{characters}.
4306
It binds @b{*print-escape*} to @i{false}
4308
and @b{*print-readably*} to @i{false}.
4310
The general rule is that output from @b{princ} is intended to look
4311
good to people, while output from @b{prin1} is intended to
4312
be acceptable to @b{read}.
4314
@b{print} is just like @b{prin1}
4315
except that the printed representation
4316
of @i{object} is preceded by a newline
4317
and followed by a space.
4319
@b{pprint} is just like @b{print} except that the trailing
4320
space is omitted and
4321
@i{object} is printed with the @b{*print-pretty*} flag @i{non-nil}
4322
to produce pretty output.
4324
@i{Output-stream} specifies the @i{stream} to which
4325
output is to be sent.
4327
@subsubheading Affected By::
4329
@b{*standard-output*},
4341
@b{*read-default-float-format*}.
4343
@subsubheading See Also::
4345
@ref{readtable-case}
4347
@ref{FORMAT Printer Operations}
4349
@subsubheading Notes::
4351
The @i{functions} @b{prin1} and @b{print} do not bind @b{*print-readably*}.
4354
(prin1 object output-stream)
4355
@equiv{} (write object :stream output-stream :escape t)
4359
(princ object output-stream)
4360
@equiv{} (write object stream output-stream :escape nil :readably nil)
4364
(print object output-stream)
4365
@equiv{} (progn (terpri output-stream)
4366
(write object :stream output-stream
4368
(write-char #\space output-stream))
4372
(pprint object output-stream)
4373
@equiv{} (write object :stream output-stream :escape t :pretty t)
4376
@node write-to-string, *print-array*, write, Printer Dictionary
4377
@subsection write-to-string, prin1-to-string, princ-to-string [Function]
4379
@code{write-to-string} @i{object @r{&key} \writekeys}@*
4380
@result{} @i{string}
4382
@code{prin} @i{1} @result{} @i{-to-string}
4383
@r{object} @r{string}
4385
@code{princ-to-string} @i{object} @result{} @i{string}
4387
@subsubheading Arguments and Values::
4389
@i{object}---an @i{object}.
4391
\writekeydescriptions
4393
@i{string}---a @i{string}.
4395
@subsubheading Description::
4397
@b{write-to-string}, @b{prin1-to-string}, and @b{princ-to-string}
4398
are used to create a @i{string} consisting of the printed representation
4400
@i{Object} is effectively printed as if by @b{write},
4401
@b{prin1}, or @b{princ}, respectively,
4402
and the @i{characters} that would be output are made
4405
@b{write-to-string} is the general output function.
4406
It has the ability to specify all the parameters applicable
4407
to the printing of @i{object}.
4409
@b{prin1-to-string} acts like @b{write-to-string} with
4410
@t{:escape t}, that is, escape characters are written where appropriate.
4412
@b{princ-to-string} acts like @b{write-to-string} with
4414
@t{:escape nil :readably nil}.
4416
Thus no @i{escape} @i{characters} are written.
4418
All other keywords that would be specified to @b{write-to-string}
4419
are default values when @b{prin1-to-string}
4420
or @b{princ-to-string} is invoked.
4422
The meanings and defaults for the keyword arguments to @b{write-to-string}
4423
are the same as those for @b{write}.
4425
@subsubheading Examples::
4428
(prin1-to-string "abc") @result{} "\"abc\""
4429
(princ-to-string "abc") @result{} "abc"
4432
@subsubheading Affected By::
4444
@b{*read-default-float-format*}.
4446
@subsubheading See Also::
4450
@subsubheading Notes::
4453
(write-to-string @i{object} @{@i{key} @i{argument}@}*)
4454
@equiv{} (with-output-to-string (#1=#:string-stream)
4455
(write object :stream #1# @{@i{key} @i{argument}@}*))
4457
(princ-to-string @i{object})
4458
@equiv{} (with-output-to-string (string-stream)
4459
(princ @i{object} string-stream))
4461
(prin1-to-string @i{object})
4462
@equiv{} (with-output-to-string (string-stream)
4463
(prin1 @i{object} string-stream))
4466
@node *print-array*, *print-base*, write-to-string, Printer Dictionary
4467
@subsection *print-array* [Variable]
4469
@subsubheading Value Type::
4471
a @i{generalized boolean}.
4473
@subsubheading Initial Value::
4475
@i{implementation-dependent}.
4477
@subsubheading Description::
4479
Controls the format in which @i{arrays} are printed.
4480
If it is @i{false}, the contents of @i{arrays} other than @i{strings}
4481
are never printed. Instead, @i{arrays} are printed in a concise form using
4482
@t{#<} that gives enough information for the user to be able to identify the
4483
@i{array}, but does not include the entire @i{array} contents.
4484
If it is @i{true}, non-@i{string} @i{arrays} are printed using
4485
@t{#(...)}, @t{#*}, or @t{#nA} syntax.
4487
@subsubheading Affected By::
4489
The @i{implementation}.
4491
@subsubheading See Also::
4493
@ref{Sharpsign Left-Parenthesis},
4494
@ref{Sharpsign Less-Than-Sign}
4496
@node *print-base*, *print-case*, *print-array*, Printer Dictionary
4497
@subsection *print-base*, *print-radix* [Variable]
4499
@subsubheading Value Type::
4501
@b{*print-base*}---a @i{radix}.
4502
@b{*print-radix*}---a @i{generalized boolean}.
4504
@subsubheading Initial Value::
4506
The initial @i{value} of @b{*print-base*} is @t{10}.
4507
The initial @i{value} of @b{*print-radix*} is @i{false}.
4509
@subsubheading Description::
4511
@b{*print-base*} and @b{*print-radix*} control the printing
4513
The @i{value} of @b{*print-base*} is called the @i{current output base}
4514
@IGindex{current output base}
4517
The @i{value} of @b{*print-base*} is the @i{radix} in which the printer
4518
will print @i{rationals}. For radices above @t{10}, letters of
4519
the alphabet are used to represent digits above @t{9}.
4521
If the @i{value} of @b{*print-radix*} is @i{true},
4522
the printer will print a radix specifier to indicate the @i{radix}
4523
in which it is printing a @i{rational} number. The radix specifier
4524
is always printed using lowercase letters. If @b{*print-base*}
4525
is @t{2}, @t{8}, or @t{16}, then the radix specifier used is @t{#b},
4526
@t{#o}, or @t{#x}, respectively. For @i{integers}, base ten is
4527
indicated by a trailing decimal point instead of a leading radix
4528
specifier; for @i{ratios}, @t{#10r} is used.
4530
@subsubheading Examples::
4533
(let ((*print-base* 24.) (*print-radix* t))
4537
(setq *print-base* 10) @result{} 10
4538
(setq *print-radix* nil) @result{} NIL
4540
(let ((*print-base* (+ i 2))) ;print the decimal number 40
4541
(write 40) ;in each base from 2 to 36
4542
(if (zerop (mod i 10)) (terpri) (format t " "))))
4544
@t{ |> } 1111 220 130 104 55 50 44 40 37 34
4545
@t{ |> } 31 2C 2A 28 26 24 22 20 1J 1I
4546
@t{ |> } 1H 1G 1F 1E 1D 1C 1B 1A 19 18
4547
@t{ |> } 17 16 15 14
4549
(dolist (pb '(2 3 8 10 16))
4550
(let ((*print-radix* t) ;print the integer 10 and
4551
(*print-base* pb)) ;the ratio 1/10 in bases 2,
4553
@t{ |> } #b1010 #b1/1010
4554
@t{ |> } #3r101 #3r1/101
4555
@t{ |> } #o12 #o1/12
4556
@t{ |> } 10. #10r1/10
4561
@subsubheading Affected By::
4563
Might be @i{bound} by @b{format}, and @b{write}, @b{write-to-string}.
4565
@subsubheading See Also::
4571
@ref{write-to-string}
4573
@node *print-case*, *print-circle*, *print-base*, Printer Dictionary
4574
@subsection *print-case* [Variable]
4576
@subsubheading Value Type::
4578
One of the @i{symbols} @t{:upcase}, @t{:downcase}, or @t{:capitalize}.
4580
@subsubheading Initial Value::
4582
The @i{symbol} @t{:upcase}.
4584
@subsubheading Description::
4586
The @i{value} of @b{*print-case*} controls the case (upper, lower, or mixed) in
4587
which to print any uppercase characters in the names of @i{symbols}
4588
when vertical-bar syntax is not used.
4590
@b{*print-case*} has an effect at all times when the @i{value} of @b{*print-escape*}
4591
is @i{false}. @b{*print-case*} also has an effect when
4592
the @i{value} of @b{*print-escape*} is @i{true} unless inside an escape context
4593
(@i{i.e.}, unless between @i{vertical-bars} or after a @i{slash}).
4595
@subsubheading Examples::
4598
(defun test-print-case ()
4599
(dolist (*print-case* '(:upcase :downcase :capitalize))
4602
;; Although the choice of which characters to escape is specified by
4603
;; *PRINT-CASE*, the choice of how to escape those characters
4604
;; (i.e., whether single escapes or multiple escapes are used)
4605
;; is implementation-dependent. The examples here show two of the
4606
;; many valid ways in which escaping might appear.
4607
(test-print-case) ;Implementation A
4608
@t{ |> } THIS-AND-THAT |And-something-elSE|
4609
@t{ |> } this-and-that a\n\d-\s\o\m\e\t\h\i\n\g-\e\lse
4610
@t{ |> } This-And-That A\n\d-\s\o\m\e\t\h\i\n\g-\e\lse
4612
(test-print-case) ;Implementation B
4613
@t{ |> } THIS-AND-THAT |And-something-elSE|
4614
@t{ |> } this-and-that a|nd-something-el|se
4615
@t{ |> } This-And-That A|nd-something-el|se
4619
@subsubheading See Also::
4623
@subsubheading Notes::
4625
@b{read} normally converts lowercase characters appearing
4626
in @i{symbols} to corresponding uppercase characters,
4627
so that internally print names normally contain only uppercase characters.
4629
If @b{*print-escape*} is @i{true},
4630
lowercase characters in the @i{name} of a @i{symbol}
4631
are always printed in lowercase, and
4632
are preceded by a single escape character
4633
or enclosed by multiple escape characters;
4634
uppercase characters in the @i{name} of a @i{symbol}
4635
are printed in upper case, in lower case, or in mixed case
4636
so as to capitalize words, according to the value of
4637
@b{*print-case*}. The convention for what constitutes
4638
a ``word'' is the same as for @b{string-capitalize}.
4640
@node *print-circle*, *print-escape*, *print-case*, Printer Dictionary
4641
@subsection *print-circle* [Variable]
4643
@subsubheading Value Type::
4645
a @i{generalized boolean}.
4647
@subsubheading Initial Value::
4651
@subsubheading Description::
4653
Controls the attempt to detect circularity and sharing in an @i{object}
4657
the printing process merely proceeds by recursive descent without attempting
4658
to detect circularity and sharing.
4661
the printer will endeavor to detect cycles and sharing
4662
in the structure to be printed,
4663
and to use @t{#@i{n}=} and @t{#@i{n}#}
4664
syntax to indicate the circularities or shared components.
4666
If @i{true}, a user-defined
4668
@b{print-object} @i{method}
4671
@i{objects} to the supplied @i{stream} using @b{write}, @b{prin1},
4672
@b{princ}, or @b{format} and expect circularities and sharing
4673
to be detected and printed using the @t{#@i{n}#} syntax.
4677
@b{print-object} @i{method}
4679
prints to a @i{stream} other than the one
4680
that was supplied, then circularity detection starts over for that @i{stream}.
4682
Note that implementations should not use @t{#@i{n}#} notation
4683
when the @i{Lisp reader} would automatically assure sharing without it
4684
(@i{e.g.}, as happens with @i{interned} @i{symbols}).
4686
@subsubheading Examples::
4689
(let ((a (list 1 2 3)))
4691
(let ((*print-circle* t))
4694
@t{ |> } #1=(1 2 3 . #1#)
4698
@subsubheading See Also::
4702
@subsubheading Notes::
4704
An attempt to print a circular structure with @b{*print-circle*}
4705
set to @b{nil} may lead to looping behavior and failure to terminate.
4707
@node *print-escape*, *print-gensym*, *print-circle*, Printer Dictionary
4708
@subsection *print-escape* [Variable]
4710
@subsubheading Value Type::
4712
a @i{generalized boolean}.
4714
@subsubheading Initial Value::
4718
@subsubheading Description::
4721
escape characters and @i{package prefixes} are not output
4722
when an expression is printed.
4724
If @i{true}, an attempt is made to print an @i{expression}
4725
in such a way that it can be read again to produce an @b{equal} @i{expression}.
4726
(This is only a guideline; not a requirement. See @b{*print-readably*}.)
4728
For more specific details of how the @i{value} of @b{*print-escape*}
4729
affects the printing of certain @i{types},
4730
see @ref{Default Print-Object Methods}.
4732
@subsubheading Examples::
4734
(let ((*print-escape* t)) (write #\a))
4737
(let ((*print-escape* nil)) (write #\a))
4742
@subsubheading Affected By::
4744
@b{princ}, @b{prin1}, @b{format}
4746
@subsubheading See Also::
4750
@ref{readtable-case}
4752
@subsubheading Notes::
4754
@b{princ} effectively binds @b{*print-escape*} to @i{false}.
4755
@b{prin1} effectively binds @b{*print-escape*} to @i{true}.
4757
@node *print-gensym*, *print-level*, *print-escape*, Printer Dictionary
4758
@subsection *print-gensym* [Variable]
4760
@subsubheading Value Type::
4762
a @i{generalized boolean}.
4764
@subsubheading Initial Value::
4768
@subsubheading Description::
4770
Controls whether the prefix ``@t{#:}'' is printed before
4771
@i{apparently uninterned} @i{symbols}.
4772
The prefix is printed before such @i{symbols}
4773
if and only if the @i{value} of @b{*print-gensym*} is @i{true}.
4775
@subsubheading Examples::
4778
(let ((*print-gensym* nil))
4784
@subsubheading See Also::
4787
, @b{*print-escape*}
4789
@node *print-level*, *print-lines*, *print-gensym*, Printer Dictionary
4790
@subsection *print-level*, *print-length* [Variable]
4792
@subsubheading Value Type::
4794
a non-negative @i{integer}, or @b{nil}.
4796
@subsubheading Initial Value::
4800
@subsubheading Description::
4802
@b{*print-level*} controls how many levels deep a nested @i{object} will print.
4803
If it is @i{false}, then no control is exercised.
4804
Otherwise, it is an @i{integer} indicating the maximum level to be printed.
4805
An @i{object} to be printed is at level @t{0};
4806
its components (as of a @i{list} or @i{vector}) are at level @t{1};
4808
If an @i{object} to be recursively printed has components
4809
and is at a level equal to or greater than the @i{value} of @b{*print-level*},
4810
then the @i{object} is printed as ``@t{#}''.
4812
@b{*print-length*} controls how many elements at a given level are printed.
4813
If it is @i{false}, there is no limit to the number of components printed.
4814
Otherwise, it is an @i{integer} indicating the maximum number of @i{elements}
4815
of an @i{object} to be printed. If exceeded, the printer will print
4816
``@t{...}'' in place of the other @i{elements}. In the case of a @i{dotted list},
4817
if the @i{list} contains exactly as many @i{elements} as the @i{value} of @b{*print-length*},
4818
the terminating @i{atom} is printed rather than printing ``@t{...}''
4820
@b{*print-level*} and @b{*print-length*} affect the printing
4821
of an any @i{object} printed with a list-like syntax. They do not affect
4822
the printing of @i{symbols}, @i{strings}, and @i{bit vectors}.
4824
@subsubheading Examples::
4827
(setq a '(1 (2 (3 (4 (5 (6))))))) @result{} (1 (2 (3 (4 (5 (6))))))
4829
(let ((*print-level* i))
4830
(format t "~&~D -- ~S~
4833
@t{ |> } 2 -- (1 (2 #))
4834
@t{ |> } 3 -- (1 (2 (3 #)))
4835
@t{ |> } 4 -- (1 (2 (3 (4 #))))
4836
@t{ |> } 5 -- (1 (2 (3 (4 (5 #)))))
4837
@t{ |> } 6 -- (1 (2 (3 (4 (5 (6))))))
4838
@t{ |> } 7 -- (1 (2 (3 (4 (5 (6))))))
4841
(setq a '(1 2 3 4 5 6)) @result{} (1 2 3 4 5 6)
4843
(let ((*print-length* i))
4844
(format t "~&~D -- ~S~
4846
@t{ |> } 1 -- (1 ...)
4847
@t{ |> } 2 -- (1 2 ...)
4848
@t{ |> } 3 -- (1 2 3 ...)
4849
@t{ |> } 4 -- (1 2 3 4 ...)
4850
@t{ |> } 5 -- (1 2 3 4 5 6)
4851
@t{ |> } 6 -- (1 2 3 4 5 6)
4854
(dolist (level-length '((0 1) (1 1) (1 2) (1 3) (1 4)
4855
(2 1) (2 2) (2 3) (3 2) (3 3) (3 4)))
4856
(let ((*print-level* (first level-length))
4857
(*print-length* (second level-length)))
4858
(format t "~&~D ~D -- ~S~
4859
*print-level* *print-length*
4860
'(if (member x y) (+ (car x) 3) '(foo . #(a b c d "Baz"))))))
4862
@t{ |> } 1 1 -- (IF ...)
4863
@t{ |> } 1 2 -- (IF # ...)
4864
@t{ |> } 1 3 -- (IF # # ...)
4865
@t{ |> } 1 4 -- (IF # # #)
4866
@t{ |> } 2 1 -- (IF ...)
4867
@t{ |> } 2 2 -- (IF (MEMBER X ...) ...)
4868
@t{ |> } 2 3 -- (IF (MEMBER X Y) (+ # 3) ...)
4869
@t{ |> } 3 2 -- (IF (MEMBER X ...) ...)
4870
@t{ |> } 3 3 -- (IF (MEMBER X Y) (+ (CAR X) 3) ...)
4871
@t{ |> } 3 4 -- (IF (MEMBER X Y) (+ (CAR X) 3) '(FOO . #(A B C D ...)))
4875
@subsubheading See Also::
4879
@node *print-lines*, *print-miser-width*, *print-level*, Printer Dictionary
4880
@subsection *print-lines* [Variable]
4882
@subsubheading Value Type::
4884
a non-negative @i{integer}, or @b{nil}.
4886
@subsubheading Initial Value::
4890
@subsubheading Description::
4892
When the @i{value} of @b{*print-lines*} is other than @b{nil},
4893
it is a limit on the number of output lines produced when something is pretty
4894
printed. If an attempt is made to go beyond that many lines,
4895
``@t{..}'' is printed at the end of the last line followed by all of the
4896
suffixes (closing delimiters) that are pending to be printed.
4898
@subsubheading Examples::
4901
(let ((*print-right-margin* 25) (*print-lines* 3))
4902
(pprint '(progn (setq a 1 b 2 c 3 d 4))))
4903
@t{ |> } (PROGN (SETQ A 1
4906
@result{} <@i{no @i{values}}>
4909
@subsubheading Notes::
4911
The ``@t{..}'' notation is intentionally different than
4912
the ``@t{...}'' notation used for level abbreviation, so that the two
4913
different situations can be visually distinguished.
4915
This notation is used to increase the likelihood that the @i{Lisp reader}
4916
will signal an error if an attempt is later made to read the abbreviated output.
4917
Note however that if the truncation occurs in a @i{string},
4918
as in @t{"This string has been trunc.."}, the problem situation cannot be
4919
detected later and no such error will be signaled.
4921
@node *print-miser-width*, *print-pprint-dispatch*, *print-lines*, Printer Dictionary
4922
@subsection *print-miser-width* [Variable]
4924
@subsubheading Value Type::
4926
a non-negative @i{integer}, or @b{nil}.
4928
@subsubheading Initial Value::
4930
@i{implementation-dependent}
4932
@subsubheading Description::
4934
If it is not @b{nil}, the @i{pretty printer} switches to a compact
4935
style of output (called miser style) whenever the width available for
4936
printing a substructure is less than or equal to this many @i{ems}.
4938
@node *print-pprint-dispatch*, *print-pretty*, *print-miser-width*, Printer Dictionary
4939
@subsection *print-pprint-dispatch* [Variable]
4941
@subsubheading Value Type::
4943
a @i{pprint dispatch table}.
4945
@subsubheading Initial Value::
4947
@i{implementation-dependent}, but the initial entries all use a
4948
special class of priorities that have the property that they are less
4949
than every priority that can be specified using @b{set-pprint-dispatch},
4950
so that the initial contents of any entry can be overridden.
4952
@subsubheading Description::
4954
The @i{pprint dispatch table} which currently controls the @i{pretty printer}.
4956
@subsubheading See Also::
4959
@ref{Pretty Print Dispatch Tables}
4961
@subsubheading Notes::
4963
The intent is that the initial @i{value} of this @i{variable} should
4964
cause `traditional' @i{pretty printing} of @i{code}.
4965
In general, however, you can put a value in @b{*print-pprint-dispatch*}
4966
that makes pretty-printed output look exactly like non-pretty-printed output.
4968
Setting @b{*print-pretty*} to @i{true}
4969
just causes the functions contained in the @i{current pprint dispatch table}
4970
to have priority over normal @b{print-object} methods;
4971
it has no magic way of enforcing that those functions actually produce pretty
4972
output. For details, see @ref{Pretty Print Dispatch Tables}.
4974
@node *print-pretty*, *print-readably*, *print-pprint-dispatch*, Printer Dictionary
4975
@subsection *print-pretty* [Variable]
4977
@subsubheading Value Type::
4979
a @i{generalized boolean}.
4981
@subsubheading Initial Value::
4983
@i{implementation-dependent}.
4985
@subsubheading Description::
4987
Controls whether the @i{Lisp printer} calls the @i{pretty printer}.
4990
the @i{pretty printer} is not used and
4995
is output when printing an expression.
4998
the @i{pretty printer} is used, and the @i{Lisp printer} will endeavor
4999
to insert extra @i{whitespace}_1 where appropriate to make @i{expressions}
5002
@b{*print-pretty*} has an effect even when the @i{value} of @b{*print-escape*}
5005
@subsubheading Examples::
5008
(setq *print-pretty* 'nil) @result{} NIL
5009
(progn (write '(let ((a 1) (b 2) (c 3)) (+ a b c))) nil)
5010
@t{ |> } (LET ((A 1) (B 2) (C 3)) (+ A B C))
5012
(let ((*print-pretty* t))
5013
(progn (write '(let ((a 1) (b 2) (c 3)) (+ a b c))) nil))
5014
@t{ |> } (LET ((A 1)
5019
;; Note that the first two expressions printed by this next form
5020
;; differ from the second two only in whether escape characters are printed.
5021
;; In all four cases, extra whitespace is inserted by the pretty printer.
5023
(let ((*print-pretty* t))
5026
(terpri) (princ x) (princ " ")
5028
(test '#'(lambda () (list "a" #@b{'c} #'d))))
5029
@t{ |> } #'(LAMBDA ()
5030
@t{ |> } (LIST "a" #@b{'C} #'D))
5031
@t{ |> } #'(LAMBDA ()
5032
@t{ |> } (LIST "a" #@b{'C} #'D))
5033
@t{ |> } #'(LAMBDA ()
5034
@t{ |> } (LIST a b 'C #'D))
5035
@t{ |> } #'(LAMBDA ()
5036
@t{ |> } (LIST a b 'C #'D))
5040
@subsubheading See Also::
5044
@node *print-readably*, *print-right-margin*, *print-pretty*, Printer Dictionary
5045
@subsection *print-readably* [Variable]
5047
@subsubheading Value Type::
5049
a @i{generalized boolean}.
5051
@subsubheading Initial Value::
5055
@subsubheading Description::
5057
If @b{*print-readably*} is @i{true},
5058
some special rules for printing @i{objects} go into effect.
5059
Specifically, printing any @i{object} O_1 produces a printed
5060
representation that, when seen by the @i{Lisp reader}
5061
while the @i{standard readtable} is in effect,
5063
an @i{object} O_2 that is @i{similar} to O_1.
5064
The printed representation produced might or might not be the same as
5065
the printed representation produced when @b{*print-readably*} is @i{false}.
5066
If printing an @i{object} @i{readably} is not possible,
5067
an error of @i{type} @b{print-not-readable} is signaled rather than
5068
using a syntax (@i{e.g.}, the ``@t{#<}'' syntax) that would not be readable by
5069
the same @i{implementation}.
5070
If the @i{value} of some other @i{printer control variable} is such
5071
that these requirements would be violated, the @i{value} of that other
5072
@i{variable} is ignored.
5074
Specifically, if @b{*print-readably*} is @i{true},
5075
printing proceeds as if
5078
and @b{*print-gensym*} were also @i{true},
5082
and @b{*print-lines*} were @i{false}.
5084
If @b{*print-readably*} is @i{false},
5085
the normal rules for printing and the normal interpretations
5086
of other @i{printer control variables} are in effect.
5088
Individual @i{methods} for @b{print-object}, including user-defined
5089
@i{methods}, are responsible for implementing these requirements.
5091
If @b{*read-eval*} is @i{false} and @b{*print-readably*} is @i{true},
5092
any such method that would output a reference to the ``@t{#.}'' @i{reader macro}
5093
will either output something else or will signal an error (as described above).
5095
@subsubheading Examples::
5098
(let ((x (list "a" '\a (gensym) '((a (b (c))) d e f g)))
5099
(*print-escape* nil)
5100
(*print-gensym* nil)
5104
(let ((*print-readably* t))
5108
@t{ |> } (a a G4581 ((A #) D E ...))
5109
@t{ |> } ("a" |a| #:G4581 ((A (B (C))) D E F G))
5112
;; This is setup code is shared between the examples
5113
;; of three hypothetical implementations which follow.
5114
(setq table (make-hash-table)) @result{} #<HASH-TABLE EQL 0/120 32005763>
5115
(setf (gethash table 1) 'one) @result{} ONE
5116
(setf (gethash table 2) 'two) @result{} TWO
5119
(let ((*print-readably* t)) (print table))
5120
Error: Can't print #<HASH-TABLE EQL 0/120 32005763> readably.
5123
;; No standardized #S notation for hash tables is defined,
5124
;; but there might be an implementation-defined notation.
5125
(let ((*print-readably* t)) (print table))
5126
@t{ |> } #S(HASH-TABLE :TEST EQL :SIZE 120 :CONTENTS (1 ONE 2 TWO))
5127
@result{} #<HASH-TABLE EQL 0/120 32005763>
5130
;; Note that #. notation can only be used if *READ-EVAL* is true.
5131
;; If *READ-EVAL* were false, this same implementation might have to
5132
;; signal an error unless it had yet another printing strategy to fall
5134
(let ((*print-readably* t)) (print table))
5135
@t{ |> } #.(LET ((HASH-TABLE (MAKE-HASH-TABLE)))
5136
@t{ |> } (SETF (GETHASH 1 HASH-TABLE) ONE)
5137
@t{ |> } (SETF (GETHASH 2 HASH-TABLE) TWO)
5138
@t{ |> } HASH-TABLE)
5139
@result{} #<HASH-TABLE EQL 0/120 32005763>
5142
@subsubheading See Also::
5146
@ref{print-unreadable-object}
5148
@subsubheading Notes::
5150
The rules for ``@i{similarity}'' imply that
5152
syntax cannot be used for @i{arrays} of @i{element type}
5154
An implementation will have to use another syntax
5155
or signal an error of @i{type} @b{print-not-readable}.
5157
@node *print-right-margin*, print-not-readable, *print-readably*, Printer Dictionary
5158
@subsection *print-right-margin* [Variable]
5160
@subsubheading Value Type::
5162
a non-negative @i{integer}, or @b{nil}.
5164
@subsubheading Initial Value::
5168
@subsubheading Description::
5170
If it is @i{non-nil}, it specifies the right margin (as @i{integer}
5171
number of @i{ems}) to use when the @i{pretty printer} is making
5174
If it is @b{nil}, the right margin is taken to be the maximum line length
5175
such that output can be displayed without wraparound or truncation.
5176
If this cannot be determined, an @i{implementation-dependent} value is used.
5178
@subsubheading Notes::
5180
This measure is in units of @i{ems} in order to be compatible with
5181
@i{implementation-defined} variable-width fonts while still not
5182
requiring the language to provide support for fonts.
5184
@node print-not-readable, print-not-readable-object, *print-right-margin*, Printer Dictionary
5185
@subsection print-not-readable [Condition Type]
5187
@subsubheading Class Precedence List::
5188
@b{print-not-readable},
5190
@b{serious-condition},
5194
@subsubheading Description::
5196
The @i{type} @b{print-not-readable} consists of error conditions that occur during
5197
output while @b{*print-readably*} is @i{true}, as a result of attempting
5198
to write a printed representation with the @i{Lisp printer}
5199
that would not be correctly read back with the @i{Lisp reader}.
5200
The object which could not be printed is initialized by
5201
the @t{:object} initialization argument to @b{make-condition}, and is @i{accessed} by
5202
the @i{function} @b{print-not-readable-object}.
5204
@subsubheading See Also::
5206
@ref{print-not-readable-object}
5208
@node print-not-readable-object, format, print-not-readable, Printer Dictionary
5209
@subsection print-not-readable-object [Function]
5211
@code{print-not-readable-object} @i{condition} @result{} @i{object}
5213
@subsubheading Arguments and Values::
5215
@i{condition}---a @i{condition} of @i{type} @b{print-not-readable}.
5217
@i{object}---an @i{object}.
5219
@subsubheading Description::
5221
Returns the @i{object} that could not be printed readably
5222
in the situation represented by @i{condition}.
5224
@subsubheading See Also::
5226
@b{print-not-readable},
5229
@node format, , print-not-readable-object, Printer Dictionary
5230
@subsection format [Function]
5232
@code{format} @i{destination control-string @r{&rest} args} @result{} @i{result}
5234
@subsubheading Arguments and Values::
5236
@i{destination}---@b{nil},
5239
or a @i{string} with a @i{fill pointer}.
5241
@i{control-string}---a @i{format control}.
5243
@i{args}---@i{format arguments} for @i{control-string}.
5245
@i{result}---if @i{destination} is @i{non-nil}, then @b{nil};
5246
otherwise, a @i{string}.
5248
@subsubheading Description::
5250
@b{format} produces formatted output by outputting the characters
5251
of @i{control-string} and observing that a @i{tilde}
5252
introduces a directive. The character after the tilde, possibly preceded
5253
by prefix parameters and modifiers, specifies what kind of formatting
5254
is desired. Most directives use one or more elements of @i{args} to
5255
create their output.
5257
If @i{destination} is a @i{string}, a @i{stream}, or @b{t},
5258
then the @i{result} is @b{nil}. Otherwise, the @i{result} is
5259
a @i{string} containing the `output.'
5261
@b{format} is useful for producing nicely formatted text, producing
5262
good-looking messages, and so on. @b{format} can generate and return
5263
a @i{string} or output to @i{destination}.
5265
For details on how the @i{control-string} is interpreted,
5266
see @ref{Formatted Output}.
5268
@subsubheading Affected By::
5270
@b{*standard-output*},
5282
@subsubheading Exceptional Situations::
5284
If @i{destination} is a @i{string} with a @i{fill pointer},
5285
the consequences are undefined if destructive modifications are performed
5286
directly on the @i{string} during the @i{dynamic extent} of the call.
5288
@subsubheading See Also::
5292
@ref{Documentation of Implementation-Defined Scripts}
5294
@c end of including dict-printer
5296
@c %**end of chapter
added
removed
info/chap-22.texi
