Format (Common Lisp)

Format is a function in Common Lisp that can produce formatted text using a format string similar to the print format string. It provides more functionality than print, allowing the user to output numbers in various formats (including, for instance: hex, binary, octal, roman numerals, and English), apply certain format specifiers only under certain conditions, iterate over data structures, output data tabularly, and even recurse, calling format internally to handle data structures that include their own preferred formatting strings. This functionally originates in MIT's Lisp Machine Lisp,^[1] where it was based on Multics.

The format function is specified by the syntax:^[2]

format destination controlString &rest formatArguments

Directives in the control string are interpolated using the format arguments, and the thus constructed character sequence is written to the destination.

The destination may either be a stream, a dynamic string, T, or the NIL constant; the latter of which presents a special case in that it creates, formats and returns a new string object, while T refers to the standard output, usually being equivalent to the console. Streams in Common Lisp comprehend, among others, string output and file streams; hence, being capable of writing to such a variety of destinations, this function unifies capabilities distributed among distinct commands in some other programming languages, such as C's printf for console output, sprintf for string formatting, and fprintf for file writing.

The multitude of destination types is exemplified in the following:

;; Prints "1 + 2 = 3" to the standard output and returns ``NIL''.
(format t "1 + 2 = ~D" 3)

;; Creates and returns a new string containing "1 + 2 = 3".
(format nil "1 + 2 = ~D" 3)

;; Creates and returns a new string containing "1 + 2 = 3".
(with-output-to-string (output)
  (format output "1 + 2 = ~D" 3))

;; Writes to the file "outputFile.txt" the string "1 + 2 = 3".
(with-open-file (output "outputFile.txt"
                  :direction         :output
                  :if-does-not-exist :create
                  :if-exists         :append)
  (format output "1 + 2 = ~D" 3))

;; Appends to the dynamic string the string "1 + 2 = 3".
(let ((output-string (make-array 0
                       :element-type 'character
                       :adjustable t
                       :fill-pointer 0)))
  (declare (type string output-string))
  (format output-string "1 + 2 = ~D" 3)
  (the string output-string))

The control string may contain literal characters as well as the meta character ~ (tilde), which demarcates format directives. While literals in the input are echoed verbatim, directives produce a special output, often consuming one or more format arguments.

A format directive, introduced by a ~, is followed by zero or more prefix parameters, zero or more modifiers, and the directive type. A directive definition, hence, must conform to the following pattern:

~[prefixParameters][modifiers]directiveType

The directive type is always specified by a single character, case-insensitive in the case of letters. The data to be processed by a format directive, if at all necessary, is called its format argument and may be zero or more objects of any type compatible. Whether and in which quantity such data is accepted depends on the directive and potential modifiers applied unto it. The directive type ~%, for instance, abstains from the consumption of any format arguments, whereas ~D expects exactly one integer number to print, and ~@{, a directive influenced by the at-sign modifier, processes all remaining arguments.

The following directive, ~B, expects one number object from the format arguments and writes its binary (radix 2) equivalent to the standard output.

(format t "~B" 5)

Where configurations are permissive, prefix parameters may be specified.

Prefix parameters enable an injection of additional information into a directive to operate upon, similar to the operation of parameters when provided to a function. Prefix parameters are always optional, and, if provided, must be located between the introducing ~ and either the modifiers or, if none present, the directive type. The values are separated by commas, but do not tolerate white spaces on either side. The number and type of these parameters depends on the directive and the influence of potential modifiers.

Two particular characters may be utilized as prefix parameter values with distinctive interpretation: v or V acts as a placeholder for an integer number or character from the format arguments which is consumed and placed into its stead. The second special character, #, is substituted by the tally of format arguments yet abiding their consumption. Both V and # enable behavior defined by dynamic content injected into the prefix parameter list.

The V parameter value introduces a functionality equivalent to a variable in the context of general programming. Given this simple scenario, in order to left-pad a binary representation of the integer number 5 to at least eight digits with zeros, the literal solution is as follows:

(format t "~8,'0b" 5)

The first prefix parameter controlling the output width may, however, be defined in terms of the V character, delegating the parameter value specification to the next format argument, in our case 8.

(format t "~v,'0b" 8 5)

Solutions of this kind are particularly a benefit if parts of the prefix parameter list shall be described by variables or function arguments instead of literals, as is the case in the following piece of code:

(let ((number-of-digits 8))
  (declare (type (integer 0 *) number-of-digits))
  (format t "~V,'0b" number-of-digits 5))

Even more fitting in those situations involving external input, a function argument may be passed into the format directive:

(defun print-as-hexadecimal (number-to-format number-of-digits)
  "Prints the NUMBER-TO-FORMAT in the hexadecimal system (radix 16),
   left-padded with zeros to at least NUMBER-OF-DIGITS."
  (declare (type number        number-to-format))
  (declare (type (integer 0 *) number-of-digits))
  (format t "~V,'0x" number-of-digits number-to-format))

(print-as-hexadecimal 12 2)

# as a prefix parameter tallies those format arguments not yet processed by preceding directives, doing so without actually consuming anything from this list. The utility of such a dynamically inserted value is preponderantly restricted to use cases pertaining to conditional processing. As the argument number can only be an integer number greater than or equal to zero, its significance coincides with that of an index into the clauses of a conditional ~[ directive.

The interplay of the special # prefix parameter value with the conditional selection directive ~[ is illustrated in the following example. The condition states four clauses, accessible via the indices 0, 1, 2, and 3 respectively. The number of format arguments is employed as the means for the clause index retrieval; to do so, we insert # into the conditional directive which permits the index to be a prefix parameter. # computes the tally of format arguments and suggests this number as the selection index. The arguments, not consumed by this act, are then available to and processed by the selected clause's directives.

;; Prints "none selected".
(format t "~#[none selected~;one selected: ~A~;two selected: ~A and ~A~:;more selected: ~@{~A~^, ~}~]")

;; Prints "one selected: BUNNY".
(format t "~#[none selected~;one selected: ~A~;two selected: ~A and ~A~:;more selected: ~@{~A~^, ~}~]" 'bunny)

;; Prints "two selected: BUNNY and PIGEON".
(format t "~#[none selected~;one selected: ~A~;two selected: ~A and ~A~:;more selected: ~@{~A~^, ~}~]" 'bunny 'pigeon)

;; Prints "more selected: BUNNY, PIGEON, MOUSE".
(format t "~#[none selected~;one selected: ~A~;two selected: ~A and ~A~:;more selected: ~@{~A~^, ~}~]" 'bunny 'pigeon 'mouse)

Modifiers act in the capacity of flags intending to influence the behavior of a directive. The admission, magnitude of behavioral modification and effect, as with prefix parameters, depends upon the directive. In some severe cases, the syntax of a directive may be varied to a degree as to invalidate certain prefix parameters; this power especially distinguishes modifiers from most parameters. The two valid modifier characters are @ (at-sign) and : (colon), possibly in combination as either :@ or @:.

The following example illustrates a rather mild case of influence exerted upon a directive by the @ modifier: It merely ensures that the binary representation of a formatted number is always preceded by the number's sign:

(format t "~@B" 5)

An enumeration of the format directives, including their complete syntax and modifier effects, is adduced below.^[3]

An example of a C printf call is the following:

 printf("Color %s, number1 %d, number2 %05d, hex %x, float %5.2f, unsigned value %u.\n",
             "red", 123456, 89, 255, 3.14, 250);

Using Common Lisp, this is equivalent to:

 (format t "Color ~A, number1 ~D, number2 ~5,'0D, hex ~X, float ~5,2F, unsigned value ~D.~%"
             "red" 123456 89 255 3.14 250)
 ;; prints: Color red, number1 123456, number2 00089, hex FF, float  3.14, unsigned value 250.

Another example would be to print every element of list delimited with commas, which can be done using the ~{, ~^ and ~} directives:^[4]

 (let ((groceries '(eggs bread butter carrots)))
   (format t "~{~A~^, ~}.~%" groceries)         ; Prints in uppercase
   (format t "~:(~{~A~^, ~}~).~%" groceries))   ; Capitalizes output
 ;; prints: EGGS, BREAD, BUTTER, CARROTS.
 ;; prints: Eggs, Bread, Butter, Carrots.

Note that not only is the list of values iterated over directly by format, but the commas correctly are printed between items, not after them. A yet more complex example would be printing out a list using customary English phrasing:

(let ((template "The lucky winners were:~#[ none~; ~S~; ~S and ~S~
           ~:;~@{~#[~; and~] ~S~^,~}~]."))
  (format nil template)
  ;; ⇒   "The lucky winners were: none."
  (format nil template 'foo)
  ;; ⇒   "The lucky winners were: FOO."
  (format nil template 'foo 'bar)
  ;; ⇒   "The lucky winners were: FOO and BAR."
  (format nil template 'foo 'bar 'baz)
  ;; ⇒   "The lucky winners were: FOO, BAR, and BAZ."
  (format nil template 'foo 'bar 'baz 'quux)
  ;; ⇒   "The lucky winners were: FOO, BAR, BAZ, and QUUX."
  )

The ability to define a new directive through ~/functionName/ provides the means for customization. The next example implements a function which prints an input string either in lowercase, uppercase or reverse style, permitting a configuration of the number of repetitions, too.

(defun mydirective (destination
                    format-argument
                    colon-modifier-supplied-p
                    at-sign-modifier-supplied-p
                    &optional (repetitions 1))
  "This function represents a callback suitable as a directive in a
   ``format'' invocation, expecting a string as its FORMAT-ARGUMENT
   to print REPETITIONS number of times to the DESTINATION.
   ---
   The COLON-MODIFIER-SUPPLIED-P and AT-SIGN-MODIFIER-SUPPLIED-P flags
   expect a generalized Boolean each, being the representatives of the
   ``:'' and ``@'' modifiers respectively. Their influence is defined
   as follows:
     - If no modifier is set, the FORMAT-ARGUMENT is printed without
       further modifications.
     - If the colon modifier is set, but not the at-sign modifier, the
       FORMAT-ARGUMENT is converted into lowercase before printing.
     - If the at-modifier is set, but not the colon-modifier, the
       FORMAT-ARGUMENT is converted into uppercase before printing.
     - If both modifiers are set, the FORMAT-ARGUMENT is reversed before
       printing.
   ---
   The number of times the FORMAT-ARGUMENT string is to be printed is
   determined by the prefix parameter REPETITIONS, which must be a
   non-negative integer number and defaults to one."
  (declare (type (or null (eql t) stream string) destination))
  (declare (type t                               format-argument))
  (declare (type t                               colon-modifier-supplied-p))
  (declare (type t                               at-sign-modifier-supplied-p))
  (declare (type (integer 0 *)                   repetitions))
  
  (let ((string-to-print format-argument))
    (declare (type string string-to-print))
    
    ;; Adjust the STRING-TO-PRINT based upon the modifiers.
    (cond
      ((and colon-modifier-supplied-p at-sign-modifier-supplied-p)
        (setf string-to-print (reverse string-to-print)))
      (colon-modifier-supplied-p
        (setf string-to-print (string-downcase string-to-print)))
      (at-sign-modifier-supplied-p
        (setf string-to-print (string-upcase string-to-print)))
      (t
        nil))
    
    (loop repeat repetitions do
      (format destination "~A" string-to-print))))

;; Print "Hello" a single time.
(format t "~/mydirective/" "Hello")

;; Print "Hello" three times.
(format t "~3/mydirective/" "Hello")

;; Print a lowercase "Hello" (= "hello") three times.
(format t "~3:/mydirective/" "Hello")

;; Print an uppercase "Hello" (= "HELLO") three times.
(format t "~3@/mydirective/" "Hello")

;; Print a reversed "Hello" (= "olleH") three times.
(format t "~3:@/mydirective/" "Hello")

Whilst format is somewhat infamous for its tendency to become opaque and hard to read, it provides a remarkably concise yet powerful syntax for a specialized and common need.^[4]

A Common Lisp FORMAT summary table is available.^[5]

• Common Lisp
• Common Lisp the Language
• Practical Common Lisp
• On Lisp

• Common Lisp HyperSpec Section 22.3 Formatted Output
• Practical Common Lisp Chapter 18. A Few FORMAT Recipes

This article needs additional or more specific categories. Please help out by adding categories to it so that it can be listed with similar articles. (June 2024)