52.1 Formatted output

A format string is generally more compact and easier than using just the standard procedures like display, write and newline. Parameters in the output string allow various output styles, and parameters can be taken from the arguments for runtime flexibility.

format is similar to the Common Lisp procedure of the same name, but it’s not identical and doesn’t have quite all the features found in Common Lisp²⁶.

C programmers will note the similarity between format and printf(), though escape sequences are marked with ~ instead of %, and are more powerful.

Function: format template-string

Function: format template-string args …

Function: format dest template-string

Function: format dest template-string arg …

Write output specified by the template-string string to dest; assume that the zero–based starting column number is the one specified by the parameter format-output-column.

dest can be:

• An output port.
• #t for current-output-port.
• A number for current-error-port.
• #f to return the output as a string.

If dest is not given (that is: the first argument is a string): the output is returned as if #f is used as dest argument.

template-string can contain literal text to be output, and ~ escapes. Each escape has the form:

~ [param [, param …] [:] [@] code

code is a character determining the escape sequence; the code letters are not case–sensitive, upper and lower case are the same. The : and @ characters are optional modifiers, one or both of which change the way various codes operate. Optional parameters are accepted by some codes too. Parameters have the following forms:

[+/-]number

An integer, with optional + or - sign in front of it.

'

The quote. The following character in the format string, for instance 'z for z.

v

The next function argument as the parameter. v stands for “variable”, a parameter can be calculated at runtime and included in the arguments. Upper case V can be used too.

#

The number of arguments remaining.

Parameters are separated by commas (,). A parameter can be left empty to keep its default value when supplying later parameters.

It’s an error if there are not enough arguments for the escapes in the format string, but any excess arguments are ignored.

Parameter: format-output-column

The zero–based starting column number for the next invocations of format. The value is initialised to 0 and must be a non–negative fixnum.

Iterations ~{ ~} and conditionals ~[ ~; ~] can be nested, but must be properly nested, meaning the inner form must be entirely within the outer form. So it’s not possible, for instance, to try to conditionalize the endpoint of an iteration.

(format "~{ ~[ ... ~] ~}" ...)       ;; good
(format "~{ ~[ ... ~} ... ~]" ...)   ;; bad

The same applies to case conversions ~( ~), they must properly nest with respect to iterations and conditionals (though currently a case conversion cannot nest within another case conversion).

When a sub–format (~?) is used, that sub–format string must be self-contained. It cannot for instance give a ~{ to begin an iteration form and have the ~} up in the originating format, or similar.