Common Lisp the Language, 2nd Edition

Next: Pretty Printing Dispatch Up: Pretty Printing Previous: Format Directive Interface

# 27.5. Compiling Format Control Strings

The control strings used by `format` are essentially programs that perform printing. The macro `formatter` provides the efficiency of using a compiled function for printing without losing the visual compactness of `format` strings.

[Macro]
`formatter control-string`

The control-string must be a literal string. An error is signaled if control-string is not a valid `format` control string. The macro `formatter` expands into an expression of the form `(function (lambda (stream &rest args) ...))` that does the printing specified by control-string. The `lambda` created accepts an output stream as its first argument and zero or more data values as its remaining arguments. The value returned by the `lambda` is the tail (if any) of the data values that are not printed out by control-string. (For example, if the control-string is `"~A~A"`, the `cddr` (if any) of the data values is returned.) The form `(formatter "~%~2@{~S, ~}")` is equivalent to the following:

    #'(lambda (stream &rest args)
        (terpri stream)
        (dotimes (n 2)
          (if (null args) (return nil))
          (prin1 (pop args) stream)
          (write-string ", " stream))
        args)

In support of the above mechanism, `format` is extended so that it accepts functions as its second argument as well as strings. When a function is provided, it must be a function of the form created by `formatter`. The function is called with the appropriate output stream as its first argument and the data arguments to `format` as its remaining arguments. The function should perform whatever output is necessary and return the unused tail of the arguments (if any). The directives `` and `~{~}` with no body are also extended so that they accept functions as well as control strings. Every other standard function that takes a `format` string as an argument (for example, `error` and `warn`) is also extended so that it can accept functions of the form above instead.

Next: Pretty Printing Dispatch Up: Pretty Printing Previous: Format Directive Interface