CLHS summary
Summarizes each subsection of "CLHS 22.3 Formatted Output".
Includes a big table summarizing all format directive arguments.
The table is fairly complete and detailed, for a summary.
⚓
It's hard to produce a "value-added" summary for this section (excluding subsections).
You should probably just read it, it's fairly short and informative.
Some particular features that not everyone may know is that you can use V (dynamic argument) or # (number of parameters remaining) as a prefix parameter.
⚓
The following table is already fairly complete and detailed, for a summary. One notable todo would be to dynamically show some examples and other information such as bound printer variables (as appropriate) on the left when hovering over the cells of the table.
The first column ("~") links to the "full reference" part of this article (on another page), which for now is lacking quite a bit of depth.
Note that the following table is not intended to be "standalone". You'll need to complete with other sources of information such as the CLHS and practice a lot to make sense of it.
Most of this table's (insane) complexity directly reflects the accidental (due to packing a complex language into a string) yet unavoidable (you can't ignore it) complexity of FORMAT itself.
If you hate this table, then you hate FORMAT. (This isn't idle ranting either, I'm writing this article as a stepping stone to writing my own lispy FORMAT replacement. See a complex example.)
(This table has been called a monument to my sins
. I have developed a certain fondness for that assertion.)
| ⚓ | ~ | Name | Function | Prefix args | Colon | At-sign | Consume |
|---|---|---|---|---|---|---|---|
| ⚓ | CLHS 22.3.1 FORMAT Basic Output | ||||||
| ⚓ | ~C | Character | write-char | ∅ | write-char (if simple character) |
|
|
| Pretty | Escape | ||||||
| Modifiers | |||||||
| ⚓ | ~% | Newline | terpri | # of newlines | ∅ | ||
| ⚓ | ~& | Fresh-Line | fresh-line | # of fresh lines | |||
| ⚓ | ~| | Page | ∅ | # of pages | |||
| ⚓ | ~~ | Tilde | # of tildes | ||||
| ⚓ | CLHS 22.3.2 FORMAT Radix Control | ||||||
| ⚓ | ~R | Radix | ∅ | Without args | Cardinal |
|
|
| Ordinal | Roman | ||||||
| Old roman | |||||||
| write (:base) | Radix, ~D args | Commas | Sign |
|
|||
| ⚓ | ~D | Decimal |
|
||||
| ⚓ | ~B | Binary | |||||
| ⚓ | ~O | Octal | |||||
| ⚓ | ~X | Hexadecimal | |||||
| ⚓ | CLHS 22.3.3 FORMAT Floating-Point Printers | ||||||
| ⚓ | ~F | Fixed-Format Floating Point |
∅ |
|
∅ | Sign |
|
| ⚓ | ~E | Exponential Floating Point |
|
||||
| ⚓ | ~G | General Floating Point |
|||||
| ⚓ | ~$ | Monetary Floating Point |
|
Sign before padding |
Sign | ||
| ⚓ | CLHS 22.3.4 FORMAT Printer Operations | ||||||
| ⚓ | ~A | Aesthetic | princ |
|
Parentheses | Padleft | object |
| ⚓ | ~S | Standard | prin1 | ||||
| ⚓ | ~W | Write | write | ∅ | Pretty | Fully | |
| ⚓ | CLHS 22.3.5 FORMAT Pretty Printer Operations | ||||||
| ⚓ | ~_ | Conditional Newline |
pprint-newline | ∅ | :linear | 0 | |
| :fill | :miser | ||||||
| :mandatory | |||||||
| ⚓ | ~< | Logical Block |
pprint-logical- block |
Parentheses | &rest | object | |
| ⚓ | ~; | ∅ |
|
∅ | |||
| ⚓ | ~@; | First clause | ∅ | Per-line prefix | |||
| ⚓ | ~^ | pprint-exit- if-list- exhausted |
~^ prefix args | ∅ | |||
| ⚓ | ~:> | ∅ | ✔ | Fill | |||
| ⚓ | ~I | Indent | pprint-indent |
|
:block | ||
| :current | ∅ | ||||||
| ⚓ | ~/ | Call Function | ∅ | [Forwarded] | object | ||
| ⚓ | CLHS 22.3.6 FORMAT Layout Control | ||||||
| ⚓ | ~T | Tabulate | pprint-tab |
|
:line | ∅ | |
| :section | :line-relative | ||||||
| :section-relative | |||||||
| ⚓ | ~< | Justification | ∅ |
Like ~A |
Padleft | Padright | |
| ⚓ | ~; | ∅ |
Spacing is evenly divided |
||||
| ⚓ | ~:; | First segment |
|
(See prose.) |
∅ | ||
| ⚓ | ~^ | ∅ | ~^ prefix args |
Only the completely processed |
|||
| ⚓ | ~> | ∅ | ✘ | ∅ | |||
| ⚓ | CLHS 22.3.7 FORMAT Control Flow Operations | ||||||
| ⚓ | ~* | Go-To | ∅ |
|
Forward | ! | |
| Back | Absolute | ||||||
| ⚓ | ~[ | Conditional Expression |
case |
|
✘ | ✘ |
|
| ⚓ | ~; | ∅ |
indexth clause will be executed. |
∅ | |||
| ⚓ | ~:; | Last segment | Default clause | ∅ | |||
| ⚓ | ~] | ∅ | ∅ | ||||
| ⚓ | ~:[ | if (approx) | ✔ | ✘ |
|
||
| ⚓ | ~; |
|
∅ | ||||
| ⚓ | ~] | ∅ | |||||
| ⚓ | ~@[ | when (approx) | ✘ | ✔ |
|
||
| ⋮ |
|
||||||
| ⚓ | ~] | ∅ | |||||
| ⚓ | ~{ | Iteration | ∅ |
|
Sublists | &rest | list |
| ⋮ | ∅ |
Recursive call to |
Empty interior: |
||||
| ⚓ | ~^ | ~^ prefix args |
Finish entire (If sublists) |
∅ |
If using |
||
| ⚓ | ~} | ∅ | >0 iterations (unless 0 max-reps) |
∅ | |||
| ⚓ | ~? | Recursive Processing |
format | ∅ |
|
|
|
| ⚓ | CLHS 22.3.8 FORMAT Miscellaneous Operations | ||||||
| ⚓ | ~( ~) |
Case Conversion |
⇒ | ∅ | string-downcase |
args consumed |
|
| string-capitalize | Capitalize downcase |
||||||
| string-upcase | |||||||
| ⚓ | ~P | Plural | ∅ | Previous | "…ies" |
|
|
| ⚓ | CLHS 22.3.9 FORMAT Misc Pseudo-Operations | ||||||
| ⚓ | ~; | Clause Separator |
∅ | ∅ | |||
| ⚓ | ~^ | Escape Upward |
# prefix args | Terminate if |
Finish entire Usable only with |
∅ | |
| 0 | No args remain | ||||||
| 1 | (zerop a) | ||||||
| 2 | (= a b) | ||||||
| 3 | (<= a b c) | ||||||
| ⚓ | ~ | Ignored Newline |
∅ | Ignore newline and whitespace |
|||
| Ignore newline |
Ignore whitespace |
||||||
⚓
⚓
Format directive invocations must be properly nested.
⚓
Entire section: The consequences are undefined if no arg remains for a directive requiring an argument. However, it is permissible for one or more args to remain unprocessed by a directive; such args are ignored.
⚓
Entire section: The consequences are undefined if a format directive is given more parameters than it is described here as accepting.
(Here, "parameters" means "prefix arguments".)
⚓
Entire section: The consequences are undefined if colon or at-sign modifiers are given to a directive in a combination not specifically described here as being meaningful.