22.3.9 FORMAT Miscellaneous Pseudo-Operations

22.3.9.1 Tilde Semicolon: Clause Separator

This separates clauses in ~[ and ~< constructs. The consequences of using it elsewhere are undefined.

22.3.9.2 Tilde Circumflex: Escape Upward

~^

This is an escape construct. If there are no more arguments remaining to be processed, then the immediately enclosing ~{ or ~< construct is terminated. If there is no such enclosing construct, then the entire formatting operation is terminated. In the ~< case, the formatting is performed, but no more segments are processed before doing the justification. ~^ may appear anywhere in a ~{ construct.

 (setq donestr "Done.~^ ~D warning~:P.~^ ~D error~:P.")
→ "Done.~^ ~D warning~:P.~^ ~D error~:P."
 (format nil donestr) → "Done."
 (format nil donestr 3) → "Done. 3 warnings."
 (format nil donestr 1 5) → "Done. 1 warning. 5 errors."

If a prefix parameter is given, then termination occurs if the parameter is zero. (Hence ~^ is equivalent to ~#^.) If two parameters are given, termination occurs if they are equal. If three parameters are given, termination occurs if the first is less than or equal to the second and the second is less than or equal to the third. Of course, this is useless if all the prefix parameters are constants; at least one of them should be a # or a V parameter.

If ~^ is used within a ~:{ construct, then it terminates the current iteration step because in the standard case it tests for remaining arguments of the current step only; the next iteration step commences immediately. ~:^ is used to terminate the iteration process. ~:^ may be used only if the command it would terminate is ~:{ or ~:@{ . The entire iteration process is terminated if and only if the sublist that is supplying the arguments for the current iteration step is the last sublist in the case of ~:{ , or the last format argument in the case of ~:@{ . ~:^ is not equivalent to ~#:^; the latter terminates the entire iteration if and only if no arguments remain for the current iteration step. For example:

 (format nil "~:{ ~@?~:^ ...~} " '(("a") ("b"))) → "a...b"

If ~^ appears within a control string being processed under the control of a ~? directive, but not within any ~{ or ~< construct within that string, then the string being processed will be terminated, thereby ending processing of the ~? directive. Processing then continues within the string containing the ~? directive at the point following that directive.

If ~^ appears within a ~[ or ~( construct, then all the commands up to the ~^ are properly selected or case-converted, the ~[ or ~( processing is terminated, and the outward search continues for a ~{ or ~< construct to be terminated. For example:

 (setq tellstr "~@(~@[~R~]~^ ~A!~)")
→ "~@(~@[~R~]~^ ~A!~)"
 (format nil tellstr 23) → "Twenty-three!"
 (format nil tellstr nil "losers") → " Losers!"
 (format nil tellstr 23 "losers") → "Twenty-three losers!"

Following are examples of the use of ~^ within a ~< construct.

 (format nil "~15<~S~;~^~S~;~^~S~>" 'foo)
→  "            FOO"
 (format nil "~15<~S~;~^~S~;~^~S~>" 'foo 'bar)
→  "FOO         BAR"
 (format nil "~15<~S~;~^~S~;~^~S~>" 'foo 'bar 'baz)
→  "FOO   BAR   BAZ"

22.3.9.3 Tilde Newline: Ignored Newline

Tilde immediately followed by a newline ignores the newline and any following non-newline whitespace₁ characters. With a :, the newline is ignored, but any following whitespace₁ is left in place. With an @, the newline is left in place, but any following whitespace₁ is ignored. For example:

 (defun type-clash-error (fn nargs argnum right-type wrong-type)
   (format *error-output*
           "~&~S requires its ~:[~:R~;~*~]~
           argument to be of type ~S,~%but it was called ~
           with an argument of type ~S.~%"
           fn (eql nargs 1) argnum right-type wrong-type))
 (type-clash-error 'aref nil 2 'integer 'vector)  prints:
AREF requires its second argument to be of type INTEGER,
but it was called with an argument of type VECTOR.
NIL
 (type-clash-error 'car 1 1 'list 'short-float)  prints:
CAR requires its argument to be of type LIST,
but it was called with an argument of type SHORT-FLOAT.
NIL

Note that in this example newlines appear in the output only as specified by the ~& and ~% directives; the actual newline characters in the control string are suppressed because each is preceded by a tilde.