ANSI Common Lisp   22 Printer   22.3 Formatted Output   22.3.9 FORMAT Miscellaneous Pseudo-Operations

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"