The next arg is ignored.
~n* ignores the next n arguments.
~:* backs up in the list of
arguments so that the argument last processed will be processed again.
~n:* backs up n arguments.
When within a ~{ construct
(see below), the ignoring (in either direction) is relative to the list
of arguments being processed by the iteration.
~n@*
goes to the nth arg, where 0 means the first one;
n defaults to 0, so ~@* goes back to the first arg.
Directives after a ~n@*
will take arguments in sequence beginning with the one gone to.
When within a ~{ construct, the “goto”
is relative to the list of arguments being processed by the iteration.
This is a set of control strings, called clauses, one of which is
chosen and used. The clauses are separated by ~;
and the construct is terminated by ~]. For example,
"~[Siamese~;Manx~;Persian~] Cat"
The argth
clause is selected, where the first clause is number 0.
If a prefix parameter is given (as ~n[),
then the parameter is used instead of an argument.
If arg is out of range then no clause is selected
and no error is signaled.
After the selected alternative has been processed, the control string
continues after the ~].
~[str0~;str1~;...~;strn~:;default~]
has a default case.
If the last ~; used to separate clauses
is ~:; instead, then the last clause is an else clause
that is performed if no other clause is selected.
For example:
"~[Siamese~;Manx~;Persian~:;Alley~] Cat"
~:[alternative~;consequent~]
selects the alternative control string if arg is false,
and selects the consequent control string otherwise.
~@[consequent~]
tests the argument. If it is true,
then the argument is not used up by the ~[ command
but remains as the next one to be processed,
and the one clause consequent is processed.
If the arg is false, then the argument is used up,
and the clause is not processed.
The clause therefore should normally use exactly one argument,
and may expect it to be non-nil.
For example:
(setq *print-level* nil *print-length* 5)
(format nil
"~@[ print level = ~D~]~@[ print length = ~D~]"
*print-level* *print-length*)
→ " print length = 5"
Note also that
(format stream "...~@[str~]..." ...) ≡ (format stream "...~:[~;~:*str~]..." ...)
The combination of ~[ and # is useful, for
example, for dealing with English conventions for printing lists:
(setq foo "Items:~#[ none~; ~S~; ~S and ~S~
~:;~@{~#[~; and~] ~S~^ ,~}~].")
(format nil foo) → "Items: none."
(format nil foo 'foo) → "Items: FOO."
(format nil foo 'foo 'bar) → "Items: FOO and BAR."
(format nil foo 'foo 'bar 'baz) → "Items: FOO, BAR, and BAZ."
(format nil foo 'foo 'bar 'baz 'quux) → "Items: FOO, BAR, BAZ, and QUUX."
~] terminates a ~[.
The consequences of using it elsewhere are undefined.
This is an iteration construct. The argument should be a list,
which is used as a set of arguments
as if for a recursive call to format.
The string str is used repeatedly as the control string.
Each iteration can absorb as many elements of the list as it likes
as arguments;
if str uses up two arguments by itself, then two elements of the
list will get used up each time around the loop.
If before any iteration step the list
is empty, then the iteration is terminated.
Also, if a prefix parameter n is given, then there will be at most n
repetitions of processing of str.
Finally, the ~^ directive can be
used to terminate the iteration prematurely.
For example:
(format nil "The winners are:~{ ~S~}."
'(fred harry jill))
→ "The winners are: FRED HARRY JILL."
(format nil "Pairs:~{ <~S,~S>~}."
'(a 1 b 2 c 3))
→ "Pairs: <A,1> <B,2> <C,3>."
~:{ str~} is similar,
but the argument should be a list of sublists.
At each repetition step, one sublist
is used as the set of arguments for
processing str; on the next repetition, a new sublist
is used, whether
or not all of the last sublist had been processed.
For example:
(format nil "Pairs:~:{ <~S,~S>~} ."
'((a 1) (b 2) (c 3)))
→ "Pairs: <A,1> <B,2> <C,3>."
~@{ str~}
is similar to ~{ str~} , but instead of
using one argument that is a list, all the remaining arguments
are used as the list of arguments for the iteration.
Example:
(format nil "Pairs:~@{ <~S,~S>~} ." 'a 1 'b 2 'c 3)
→ "Pairs: <A,1> <B,2> <C,3>."
If the iteration is terminated before all the remaining arguments are consumed, then any arguments not processed by the iteration remain to be processed by any directives following the iteration construct.
~:@{ str~}
combines the features
of ~:{ str~}
and ~@{ str~} .
All the remaining arguments
are used, and each one must be a list.
On each iteration, the next argument is
used as a list of arguments to str.
Example:
(format nil "Pairs:~:@{ <~S,~S>~} ."
'(a 1) '(b 2) '(c 3))
→ "Pairs: <A,1> <B,2> <C,3>."
Terminating the repetition construct with ~:}
instead of ~}
forces str to be processed at least once, even if the initial
list of arguments is null. However, this will not override an explicit
prefix parameter of zero.
If str is empty, then an argument is used as str. It must be a format control and precede any arguments processed by the iteration. As an example, the following are equivalent:
(apply #'format stream string arguments)
≡ (format stream "~1{~:}" string arguments)
This will use string as a formatting string.
The ~1{ says it will
be processed at most once, and the ~:}
says it will be processed at least once.
Therefore it is processed exactly once, using arguments as the arguments.
This case may be handled more clearly by the ~? directive,
but this general feature of ~{
is more powerful than ~?.
~} terminates a ~{.
The consequences of using it elsewhere are undefined.
The next arg must be a format control, and the one after it a list;
both are consumed by the ~? directive.
The two are processed as a control-string, with the elements of the list
as the arguments. Once the recursive processing
has been finished, the processing of the control
string containing the ~? directive is resumed.
Example:
(format nil "~? ~D" "<~A ~D>" '("Foo" 5) 7) → "<Foo 5> 7"
(format nil "~? ~D" "<~A ~D>" '("Foo" 5 14) 7) → "<Foo 5> 7"
Note that in the second example three arguments are supplied
to the format string "<~A ~D>", but only two are processed
and the third is therefore ignored.
With the @
modifier, only one arg is directly consumed.
The arg must be a string;
it is processed as part of the control
string as if it had appeared in place of the ~@? construct,
and any directives in the recursively processed control string may
consume arguments of the control string containing the ~@?
directive.
Example:
(format nil "~@? ~D" "<~A ~D>" "Foo" 5 7) → "<Foo 5> 7" (format nil "~@? ~D" "<~A ~D>" "Foo" 5 14 7) → "<Foo 5> 14"