Format directives

Describes the general syntax of format directive invocations,
then details the syntax and semantics of each format directive.
(Well, not actually the case for now.)

⚠

This section is incomplete, unlike the CLHS summary table.

(All FORMAT directives are mentioned, but in quite insufficient depth.)

⚓ FORMAT reference » Format directives » Syntax

Within a FORMAT string, each FORMAT directive invocation is introduced by a literal tilde ("~") and followed by prefix arguments (if any), modifiers (if any) and finally the command name.

Field name Prefix arguments Modifiers Command name
Acceptable input ~ Comma-separated arguments : and/or @ or nothing One case-insensitive letter

⚓ FORMAT reference » Format directives » Syntax » Special selection mechanisms

("Special selection mechanism" is not a formal term, I just made it up for the purposes of this article.)

TODO

⚓ FORMAT reference » Format directives » ~C (Character)

Arguments

Prefix Modifiers (select) Consumed
∅ ∅ write-char (if simple character)
  1. character
: Pretty
@ Escape
:@ Modifiers

Bound printer variables

if @ (only) *print-escape*
t

⚓ FORMAT reference » Format directives » ~% (Newline) ~& ~| ~~

Arguments

Prefix Modifiers Consumed
  1. Number of newlines
 ∅ ∅

⚓ FORMAT reference » Format directives » ~% ~& (Fresh Line) ~| ~~

Arguments

Prefix Modifiers Consumed
  1. Number of fresh lines
 ∅ ∅

⚓ FORMAT reference » Format directives » ~% ~& ~| (Page) ~~

Arguments

Prefix Modifiers Consumed
  1. Number of pages
 ∅ ∅

⚓ FORMAT reference » Format directives » ~% ~& ~| ~~ (Tilde)

Arguments

Prefix Modifiers Consumed
  1. Number of tildes
 ∅ ∅

⚓ FORMAT reference » Format directives » ~R (Radix)

The ~R format directive supports two quite different sets of functionality depending on if any prefix arguments are supplied to it or not. This selection mechanism is unique to ~R.

⚓ FORMAT reference » Format directives » ~R (Radix) » Without prefix args

Arguments

Prefix Modifiers (select) Consumed
∅ ∅ Cardinal
  1. integer
: Ordinal
@ Roman
:@ Old roman

Bound printer variables

*print-base*
10

⚓ FORMAT reference » Format directives » ~R (Radix) » With prefix args

Arguments

Prefix Modifiers (Combine) Consumed
  1. radix
  2. mincol
  3. padchar
  4. comma-char
  5. comma-interval
 : Commas
  1. number
@ Sign

Bound printer variables

*print-escape* *print-radix* *print-base* *print-readably*
false false radix false

⚓ FORMAT reference » Format directives » ~D (Decimal), ~B (Binary), ~O (Octal), ~X (Hexadecimal)

Arguments

Same as ~R with prefix args,
but without the initial radix prefix argument.

Bound printer variables

Same as ~R with prefix args.
*print-base* is bound to the corresponding radix indicated in the table below.

These format directives are merely convenient aliases for invoking the ~R format directive with a specific radix argument, followed by any prefix arguments and modifiers given to the alias, which are forwarded directly to ~R.

Alias for ~R Name Radix passed to ~R
~D Decimal 10
~B Binary 2
~O Octal 8
~X Hexadecimal 16

⚓ FORMAT reference » Format directives » Floating Point

To be written.

⚓ FORMAT reference » Format directives » Floating Point » ~F (Fixed-Format)

Arguments

Prefix Modifiers Consumed
  1. width
  2. decimals
  3. scale
  4. overflow
  5. pad
 @ Sign
  1. number

Bound printer variables

*print-escape* *print-readably*
false false

⚓ FORMAT reference » Format directives » Floating Point » ~E (Exponential)

Arguments

Same as ~G:

Prefix Modifiers Consumed
  1. width
  2. decimals
  3. exponent-width
  4. scale
  5. overflow
  6. pad
  7. exponent-char
 @ Sign
  1. number

Bound printer variables

*print-escape* *print-readably*
false false

⚓ FORMAT reference » Format directives » Floating Point » ~G (General)

Arguments

Same as ~E:

Prefix Modifiers Consumed
  1. width
  2. decimals
  3. exponent-width
  4. scale
  5. overflow
  6. pad
  7. exponent-char
 @ Sign
  1. number

Bound printer variables

*print-escape* *print-readably*
false false

⚓ FORMAT reference » Format directives » Floating Point » ~$ (Monetary)

Arguments

Prefix Modifiers (Combine) Consumed
  1. decimals
  2. min-units
  3. min-width
  4. padchar
 : Sign before padding
  1. number
@ Sign

Bound printer variables

*print-escape* *print-readably*
false false

⚓ FORMAT reference » Format directives » ~A (Aesthetic)

Arguments

Prefix Modifiers (Combine) Consumed
Same as ~S and ~<~>:
  1. mincol
  2. colinc
  3. minpad
  4. padchar
 : Paren
  1. object
@ Padleft

Bound printer variables

*print-escape* *print-readably*
false false

⚓ FORMAT reference » Format directives » ~S (Standard)

Arguments

Prefix Modifiers (Combine) Consumed
Same as ~A and ~<~>:
  1. mincol
  2. colinc
  3. minpad
  4. padchar
 : Paren
  1. object
@ Padleft

Bound printer variables

*print-escape*
t

⚓ FORMAT reference » Format directives » ~W (Write)

Arguments

Prefix Modifiers (Combine) Consumed
∅ : Pretty
  1. object
@ Fully

Bound printer variables

if : *print-pretty*
true
if @ *print-level* *print-length*
nil nil

⚓ FORMAT reference » Format directives » ~_ (Conditional Newline)

Arguments

Prefix Modifiers (select) Consumed
∅ ∅ Linear ∅
: Fill
@ Miser
:@ Mandatory

⚓ FORMAT reference » Format directives » ~< ~:> (Logical Block) ~>

Arguments

Prefix Modifiers (Combine) Consumed
∅ : Paren
  1. (&rest) object
@ &rest

⚓ FORMAT reference » Format directives » ~I (Indent)

Arguments

Prefix Modifiers (select) Consumed
  1. n
 ∅ :block ∅
: :current

⚓ FORMAT reference » Format directives » ~/name/ (Call Function)

Arguments

All prefix arguments and modifiers
along with one consumed argument
are forwarded to the function.

⚓ FORMAT reference » Format directives » ~T (Tabulate)

Arguments

Prefix Modifiers (select) Consumed
  1. colnum
  2. colinc
 ∅ :line ∅
: :section
@ :line-relative
:@ :section-relative

⚓ FORMAT reference » Format directives » ~< ~:> ~> (Justification)

Arguments

Prefix Modifiers (Combine) Consumed
Same as ~A and ~S:
  1. mincol
  2. colinc
  3. minpad
  4. padchar
 : Padleft
  1. n
@ Padright

⚓ FORMAT reference » Format directives » ~* (Go-To)

Arguments

Prefix Modifiers (select) Consumed
  1. n
 ∅ Forward !
: Back
@ Absolute

⚓ FORMAT reference » Format directives » ~[~] (Conditional Expression)

⚓ FORMAT reference » Format directives » ~[~] » ~[ (case)

Arguments

Prefix Modifiers Consumed
  1. index (zero-based)
 : ✘
  1. index (unless prefix)
@ ✘

⚓ FORMAT reference » Format directives » ~[~] » ~:[ (if)

Arguments

Prefix Modifiers Consumed
∅ : ✔
  1. generalized-boolean
@ ✘

⚓ FORMAT reference » Format directives » ~[~] » ~@[ (when)

Arguments

Prefix Modifiers Consumed
∅ : ✔
  1. generalized-boolean
    (Not consumed if true.)
@ ✔

⚓ FORMAT reference » Format directives » ~{~} (Iteration)

Arguments

Prefix Modifiers (Combine) Consumed
  1. max-reps
 : Sublists
  1. (&rest) list
@ &rest

⚓ FORMAT reference » Format directives » ~? (Recursive Processing)

Arguments

Prefix Modifier Consumed
∅ @ &rest
  1. control-string
  2. (&rest) arguments

⚓ FORMAT reference » Format directives » ~(~) (Case Conversion)

Arguments

Prefix Modifiers (select) Consumed
∅ ∅ string-downcase

args consumed by interior
: string-capitalize
@ Capitalize downcase
:@ string-upcase

⚓ FORMAT reference » Format directives » ~P (Plural)

Arguments

Prefix Modifiers (Combine) Consumed
∅ : Previous
  1. quantity (unless :)
@ "...ies"