52.8 Escape sequences for special arguments handling

Format Escape Sequence: ~?

Format Escape Sequence: ~k

Sub–format. No parameters.

Take a format string argument and a second argument which is a list of arguments for that string, and output the result.

(format #t "~?" "~d ~d" '(1 2))    -| 1 2

~@? takes arguments for the sub-format directly rather than in a list.

(format #t "~@? ~s" "~d ~d" 1 2 "foo") -| 1 2 "foo"

~? and ~k are the same, ~k is provided for T-Scheme compatibility.

Format Escape Sequence: ~*

Argument jumping. Parameter: N.

Move forward N arguments (default 1) in the argument list. ~:* moves backwards. (N cannot be negative.)

(format #f "~d ~2*~d" 1 2 3 4) ⇒ "1 4"
(format #f "~d ~:*~d" 6)       ⇒ "6 6"

~@* moves to argument number N. The first argument is number 0 (and that’s the default for N).

(format #f "~d~d again ~@*~d~d" 1 2) ⇒ "12 again 12"
(format #f "~d~d~d ~1@*~d~d" 1 2 3)  ⇒ "123 23"

A # moves to the end; when followed by a : modifier it can be used to select an absolute position relative to the end of the argument list, a reverse of what the @ modifier does.

(format #t "~#*~2:*~a" 'a 'b 'c 'd)   -| c

At the end of the format string the current argument postion does not matter, any further arguments are ignored.

Format Escape Sequence: ~{ ~}

Iteration. Parameter: maxreps (for ~{).

The format between ~{ and ~} is iterated. The modifiers to ~{ determine how arguments are taken. The default is a list argument with each iteration successively consuming elements from it. This is a convenient way to output a whole list.

(format "~{~d~}" '(1 2 3))
⇒ "123"

(format "~{~s=~d ~}" '("x" 1 "y" 2))
⇒ "\"x\"=1 \"y\"=2 "

~:{ takes a single argument which is a list of lists, each of those contained lists gives the arguments for the iterated format.

(format "~:{~dx~d ~}" '((1 2) (3 4) (5 6)))
⇒ "1x2 3x4 5x6 "

~@{ takes arguments directly, with each iteration successively consuming arguments.

(format "~@{~d~}" 1 2 3)
⇒ "123"

(format "~@{~s=~d ~}" "x" 1 "y" 2)
⇒ "\"x\"=1 \"y\"=2 "

~:@{ takes list arguments, one argument for each iteration, using that list for the format.

(format "~:@{~dx~d ~}" '(1 2) '(3 4) '(5 6))
⇒ "1x2 3x4 5x6 "

Iterating stops when there are no more arguments or when the maxreps parameter to ~{ is reached (default no maximum).

(format "~2{~d~}" '(1 2 3 4))
⇒ 12

If the format between ~{ and ~} is empty, then a format string argument is taken (before iteration argument(s)) and used instead. This allows a sub–format (like ~? above) to be iterated.

(format "~{~}" "~d" '(1 2 3))
⇒ 123

Iterations can be nested, an inner iteration operates in the same way as described, but of course on the arguments the outer iteration provides it; this can be used to work into nested list structures. For example in the following the inner ~{~d~}x is applied to (1 2) then (3 4 5) etc.

(format "~{~{~d~}x~}" '((1 2) (3 4 5)))
⇒ "12x345x"

See also ~^ below for escaping from iteration.

Format Escape Sequence: ~[ ~; ~]

Conditional. Parameter: selector.

A conditional block is delimited by ~[ and ~], and ~; separates clauses within the block. ~[ takes an integer argument and that number clause is used. The first clause is number ‘0’.

(format "~[peach~;banana~;mango~]" 0)   ⇒ "peach"
(format "~[peach~;banana~;mango~]" 1)   ⇒ "banana"
(format "~[peach~;banana~;mango~]" 2)   ⇒ "mango"

The selector parameter can be used for the clause number, instead of taking an argument.

(format "~0[peach~;banana~;mango~]")    ⇒ "peach"
(format "~1[peach~;banana~;mango~]")    ⇒ "banana"
(format "~2[peach~;banana~;mango~]")    ⇒ "mango"

If the clause number is out of range then nothing is output. Or the last clause can be ~:; to use that for a number out of range.

(format "~[banana~;mango~]"         99) ⇒ ""
(format "~[banana~;mango~:;fruit~]" 99) ⇒ "fruit"

~:[ treats the argument as a flag, and expects two clauses. The first is used if the argument is #f or the second otherwise.

(format "~:[false~;not false~]" #f)   ⇒ "false"
(format "~:[false~;not false~]" 'abc) ⇒ "not false"

(let ((n 3))
  (format "~d gnu~:[s are~; is~] here" n (= 1 n)))
⇒ "3 gnus are here"

~@[ also treats the argument as a flag, and expects one clause. If the argument is #f then no output is produced and the argument is consumed, otherwise the clause is used and the argument is not consumed, it’s left for the clause. This can be used for instance to suppress output if #f means something not available.

(format "~@[temperature=~d~]" 27) ⇒ "temperature=27"
(format "~@[temperature=~d~]" #f) ⇒ ""

Format Escape Sequence: ~^

Escape. Parameters: val1, val2, val3.

Stop formatting if there are no more arguments. This can be used for instance to have a format string adapt to a variable number of arguments.

(format "~d~^ ~d" 1)            ⇒ "1"
(format "~d~^ ~d" 1 2)          ⇒ "1 2"

Within a ~{ ~} iteration, ~^ stops the current iteration step if there are no more arguments to that step, but continuing with possible further steps and the rest of the format. This can be used for instance to avoid a separator on the last iteration, or to adapt to variable length argument lists.

(format "~{~d~^/~} go"    '(1 2 3))
⇒ "1/2/3 go"

(format "~:{ ~d~^~d~} go" '((1) (2 3)))
⇒ " 1 23 go"

Within a ~? sub–format, ~^ operates just on that sub-format. If it terminates the sub–format then the originating format will still continue.

(format "~? items" "~d~^ ~d" '(1))
⇒ "1 items"

(format "~? items" "~d~^ ~d" '(1 2))
⇒ "1 2 items"

The parameters to ~^ (which are numbers) change the condition used to terminate. For a single parameter, termination is when that value is zero (notice this makes plain ~^ equivalent to ~#^). For two parameters, termination is when those two are equal. For three parameters, termination is when val1 <= val2 and val2 <= val3.