(format destination control-string argument*) writes text built from a control string, which holds plain text and directives that begin with a tilde. The destination is nil (return a string), t (*standard-output*), a stream, or a string with a fill pointer. formatter compiles a control string into a function. The control string is a language of its own, written inside a Lisp string, which the viewer colours separately when it is the control argument of format, formatter, error, warn, cerror, signal, break, y-or-n-p, yes-or-no-p, a :format-control keyword argument, or the format part of assert.
Directive syntax
A directive is ~, then optional prefix parameters separated by commas, then optional modifiers : and @ (in either order, both allowed), then one directive character, whose case does not matter. A parameter is a decimal integer with an optional sign (12, -3), a character written 'c (the apostrophe and the character), v or V (take the value from the next argument), # (the number of arguments left), or empty, which gives the default: ~10,,,'*A sets the first and fourth parameter. A comma after the last parameter is allowed but needed only to skip parameters.
(format nil "~5,'0d" 42) ; "00042"
(format nil "~:d" 1234567) ; "1,234,567"
(format nil "~@d" 7) ; "+7"
(format nil "~r" 21) ; "twenty-one"
(format nil "~:r" 3) ; "third"
(format nil "~@r" 1994) ; "MCMXCIV"
(format nil "~8,2f" 3.14159) ; " 3.14"
(format nil "~{~a~^, ~}" '(1 2 3)) ; "1, 2, 3"
(format nil "~a file~:p" 3) ; "3 files"Printing objects
| Directive | Parameters | Meaning |
|---|---|---|
~A | mincol, colinc, minpad, padchar | aesthetic: like princ, without escapes. Pads on the right to mincol; @ pads on the left; : prints nil as (). |
~S | as ~A | standard: like prin1, readable with escapes (strings keep quotes). |
~W | write: respects all the printer variables; : binds *print-pretty* true, @ disables length and level limits. | |
~C | a character; : spells names of non-printing characters (Space), @ prints in #\ syntax. | |
~P | plural: prints s unless the argument is 1; : reuses the previous argument (~:P), @ prints y or ies. | |
~/name/ | any | calls the function name (pkg:fn allowed) with the stream, the argument, the colon and at-sign flags, and the parameters. |
Numbers
| Directive | Parameters | Meaning |
|---|---|---|
~D | mincol, padchar, commachar, comma-interval | decimal integer. : adds commas every 3 digits (or comma-interval), @ always prints the sign. |
~B, ~O, ~X | as ~D | binary, octal, hexadecimal; same modifiers. |
~R | radix, mincol, padchar, commachar, comma-interval | with a radix, an integer in that base (2 to 36). With none: English cardinal; :R ordinal; @R Roman; :@R old-style Roman (IIII). |
~F | w, d, k, overflowchar, padchar | fixed-format float: width, digits after the point, scale factor 10k; @ prints the sign. Non-numbers are printed as with ~D. |
~E | w, d, e, k, overflowchar, padchar, exptchar | exponential: 1.5e+3; e is the exponent width; exptchar the marker. |
~G | as ~E | general: ~F or ~E, whichever suits the magnitude. |
~$ | d, n, w, padchar | monetary: d digits after the point (2), at least n before it; : puts the sign before padding, @ always shows the sign. |
Layout
| Directive | Parameters | Meaning |
|---|---|---|
~% | n | n newlines (default 1). |
~& | n | fresh-line: a newline unless already at the start of a line; with n, then n-1 more. |
~| | n | n page separators (form feeds). |
~~ | n | n tilde characters. |
~ then newline | ignores the newline and the whitespace that follows. : keeps the whitespace; @ keeps the newline and ignores the whitespace. | |
~T | colnum, colinc | tabulate to a column; @T moves relative (colrel, colinc); :T and :@T are section-relative in a pretty-printing block. |
~< … ~> | mincol, colinc, minpad, padchar | justification: text between ~; separators is padded to the width; : pads before the first segment, @ after the last; ~n:; sets a line-width wrap before the first segment. |
~< … ~:> | (none) | a pretty-printing logical block, as pprint-logical-block: the argument is a list, ~; separates prefix, body and suffix; ~@< uses the remaining arguments instead of a list; ending the block with ~:@> adds a fill-style conditional newline after every blank in the text. |
~_ | conditional newline: linear by default; :_ is fill, @_ miser, :@_ mandatory. | |
~I | n | sets the indentation of the logical block relative to its start; :I relative to the current column. |
Arguments, control and nesting
| Directive | Parameters | Meaning |
|---|---|---|
~* | n | skips n arguments (default 1); :* backs up n; @* goes to argument number n (from 0). |
~? | takes a control string and a list of arguments and processes them; @? takes only the string and uses the current arguments. | |
~( … ~) | case conversion of the text inside: ~( lower case, ~:( capitalise each word, ~@( capitalise the first word, ~:@( upper case. | |
~[ … ~; … ~] | n | conditional: with no modifier, the argument (or the parameter) is the index of the clause to use; ~:; introduces a default clause. ~:[ takes two clauses, false then true. ~@[ takes one clause that runs, keeping the argument, only if it is not nil. |
~{ … ~} | n | iteration over a list argument, at most n times; the body runs until the list is empty. ~:{ takes a list of lists, each element one pass. ~@{ uses the remaining arguments. ~:@{ both. A close ~:} makes the body run at least once. |
~^ | up to three | escape: leaves the nearest enclosing iteration, justification or ~< block if no arguments remain (or, with parameters, if they compare as described). ~:^ exits the whole ~:{. |
~; | separates clauses in ~[ and ~<; ~:; marks the default or the line-width clause. |
The brackets ~( ~) ~[ ~] ~{ ~} ~< ~> must pair, and nest. Text outside directives is copied. A format control that is a literal in the program is checked by a good compiler at compile time.
(defun show-table (rows)
(format t "~&~{~{~10a~^ | ~}~%~}" rows))
(format t "~{~a~^, ~}~%" '(a b c)) ; a, b, c
(format t "~:@(~a~)~%" "shout") ; SHOUT
(format t "~a file~:p~%" 3) ; 3 files
(format t "~[zero~;one~;two~:;many~]~%" 5) ; many
(format t "~@<~a ~_~a~:>~%" 1 2) ; a logical block over the argumentsWhere format strings live
Besides format, control strings are accepted by error, cerror, warn, signal, break, y-or-n-p, yes-or-no-p, assert and check-type (the optional message), with-simple-restart, simple-condition-format-control, the :report option of define-condition (through a function), formatter, and the invalid-method-error and method-combination-error functions. format itself also accepts a function made by formatter in place of a string. The pretty printer’s own tables (set-pprint-dispatch) use the same directives through pprint-logical-block.