Format is a function in Common Lisp that can produce formatted text using a format string similar to the printf format string. It provides more functionality than printf, 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 ioa_.
The format function is specified by the syntax[2]
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:
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 pattern
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.
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 whitespaces 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:
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.
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:
Even more fitting in those situations involving external input, a function argument may be passed into the format directive:
(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.
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:
An enumeration of the format directives, including their complete syntax and modifier effects, is adduced below.[3]
| Description | Full form | Modifier | |||||
|---|---|---|---|---|---|---|---|
: | @ | :@ | |||||
| Prints the literal character. | ~''repetitions'''''~'''. | Prints ''repetitions'' times the ~ character. | colspan="3" | ||||
| , | Prints a single character. | ~'''c'''. | Prints the format argument character without prefix. | Spells out non-printing characters. | Prepends the readable #\ prefix. | Spells out non-printing characters and mentions shift keys. | |
| Prints an unconditional newline. | ~''repetitions'''''%'''. | Prints ''repetitions'' line breaks. | colspan="3" | ||||
| Prints a conditional newline, or fresh-line. | ~''repetitions'''''&'''. | If the destination is not at the beginning of a fresh line, prints ''repetitions'' line breaks; otherwise, prints ''repetitions'' - 1 line breaks. | colspan="3" | ||||
| Prints a page separator. | ~''repetitions'''''{{pipe}}'''. | Prints ''repetitions'' times a page separator. | colspan="3" | ||||
| , | Either prints the number in the specified base (radix) or spells it out. | ~''radix'',''minColumns'',''padChar'',''commaChar'',''commaInterval'''''R'''.
| Prints the argument as an English number. | Spells the argument in English ordinal numbers. | Prints the argument in Roman numerals using the usual Roman format (e.g., 4 = IV). | Prints the argument in Roman numerals using the old Roman format (e.g., 4 = IIII). | |
| , | Prints the argument in decimal radix (base = 10). | ~''minColumns'',''padChar'',''commaChar'',''commaInterval'''''d'''. | Prints as decimal number without + (plus) sign or group separator. | Uses commas as group separator. | Prepends the sign. | Prepends the sign and uses commas as group separator. | |
| , | Prints the argument in binary radix (base = 2). | ~''minColumns'',''padChar'',''commaChar'',''commaInterval'''''b'''. | Prints as binary number without + (plus) sign or group separator. | Uses commas as group separator. | Prepends the sign. | Prepends the sign and uses commas as group separator. | |
| , | Prints the argument in octal radix (base = 8). | ~''minColumns'',''padChar'',''commaChar'',''commaInterval'''''o'''. | Prints as octal number without + (plus) sign or group separator. | Uses commas as group separator. | Prepends the sign. | Prepends the sign and uses commas as group separator. | |
| , | Prints the argument in hexadecimal radix (base = 16). | ~''minColumns'',''padChar'',''commaChar'',''commaInterval'''''x'''. | Prints as hexadecimal number without + (plus) sign or group separator. | Uses commas as group separator. | Prepends the sign. | Prepends the sign and uses commas as group separator. | |
| , | Prints the argument as a float in fixed-point notation. | ~''width'',''numDecimalPlaces'',''scaleFactor'',''overflowChar'',''padChar'''''f'''. | Prints as fixed-point without + (plus) sign. | Prepends the sign. | |||
| , | Prints the argument as a float in exponential notation. | ~''width'',''numDecimalPlaces'',''numDigits'',''scaleFactor'',''overflowChar'',''padChar'',''exponentChar'''''e'''. | Prints as exponential without + (plus) sign. | Prepends the sign. | |||
| , | Prints the argument either as a float in fixed-point or exponential notation, choosing automatically. | ~''width'',''numDecimalPlaces'',''numDigits'',''scaleFactor'',''overflowChar'',''padChar'',''exponentChar'''''g'''. | Prints as fixed-point or exponential without + (plus) sign. | Prepends the sign. | |||
| Prints the argument according to monetary conventions. | ~''width'',''numDigits'',''minWholeDigits'',''minTotalWidth'',''padChar'''''$'''. | Prints in monetary conventions without + (plus) sign or padding. | Prepends the sign before padding characters. | Prepends the sign. | |||
| , | Prints the argument in a human-friendly manner. | ~''minColumns'',''colInc'',''minPad'',''padChar'''''a'''. | Prints human-friendly output without justification. | Prints NIL as empty list NIL. | Pads on the left instead of the right side. | Pads on the left and prints NIL as | |
| , | Prints the argument in a manner compatible with the read function. | ~''minColumns'',''colInc'',''minPad'',''padChar'''''s'''. | Prints read-compatible without justification. | Prints NIL as empty list NIL. | Pads on the left instead of the right side. | Pads on the left and prints NIL as | |
| , | Prints the argument in accordance with the printer control variables. | ~'''w'''. | Prints in accordance with the currently set control variables. | Enables pretty printing. | Ignores print level and length constraints. | Ignores print level and length constraints and enables pretty printing. | |
| Prints a line break according to the pretty printer rules. | ~'''_'''. | Prints a line break if a single line is exceeded. | Prints a line break if no single line preceded. | Uses a compact (miser) style. | Always inserts a line break. | ||
| Justifies the output. | ~''minColumns'',''colInc'',''minPad'',''padChar''<b><</b>''expression''~<b>></b>. | Left-justifies the output. | Adds left padding (= right-justifies). | Adds right padding (= left-justifies). | Centers the text. | ||
| , | Indents a logical block. | ~'''i'''. | Starts indenting from the first character. | Indents starting from the current output position. | colspan="2" | ||
Dispatches the formatting operation to a user-defined function. The function must accept at least four parameters:
Additionally, zero or more arguments may be specified if the function shall also permit prefix parameters. | ~''prefixParams'''''/'''''function'''''/'''. | colspan="4" on the function implementation. | |||||
| , | Moves the output cursor to a given column or by a horizontal distance. | ~''columnNumber'',''columnIncrement'''''t'''. | Moves to the specified column. | Orients at section. | Moves the cursor relative to the current position. | Orients relative to section. | |
| Navigates across the format arguments. | ~''numberOfArgs'''''*'''. | Skips the ''numberOfArgs'' format arguments. | Moves ''numberOfArgs'' back. | Moves to the argument at index ''numberOfArgs''. | |||
Prints an expression based upon a condition. These expressions, or clauses, are separated by the ~; directive, and a default clause can be stated by using ~:; as its leading separator. The number of permitted clauses depends upon the concrete variety of this directive as stated by its modifier or modifiers. The whole conditional portion must be terminated with a ~]. |
# which equates the selected element with the number of format arguments left to process. A directive of this kind allows for a very concise modeling of multiple selections. | The format argument must be a zero-based integer index, its value being that of the clause to select and print. | Selects the first clause if the format argument is NIL, otherwise the second one. | Only processes the clause if the format argument is T, otherwise skips it. | |||
directive. If the directive ~^ is found inside of the enclosed portion, any content following it is only consumed if the current element is not the last one in the processed list. If the prefix parameter ''numberOfRepetitions'' is specified, its value defines the maximum number of elements to process; otherwise all of these are consumed. | ~''numberOfRepetitions'''''{'''''expression''~'''}'''. | A single format argument is expected to be a list, its elements are consumed in order by the enclosed directives. | Expects the format argument to be a list of lists, consuming its sublists. | Regards all remaining format arguments as a list and consumes these. | Regards all remaining format arguments as a list of sublists, consuming these sublists. | ||
| Substitutes the directive by the next argument, expected to be a format argument, using the subsequent format arguments in the new portion. | ~'''?'''. | Expects the subsequent format argument to be a list whose elements are associated with the inserted control string. | Expects separate format arguments instead of a list of these for the inserted portion, as one would specify in the usual manner. | ||||
| Modifies the case of the enclosed string. | ~'''('''expression~''')'''. | Converts all characters to lower case. | Capitalizes all words. | Capitalizes the first word only, converts the rest to lower case. | Converts all characters to upper case. | ||
| , | Prints a singular or plural suffix depending upon the numeric format argument. | ~'''p'''. | Prints nothing if the argument equals 1, otherwise prints s. | Moves back to the last consumed format argument, printing nothing if it was 1, otherwise printing s. | Prints a y if the argument equals 1, otherwise prints ies. | Moves back to the last consumed format argument, printing y if it was 1, otherwise printing ies. | |
Used in an iteration directive ~{''...''~} to terminate processing of the enclosed content if no further format arguments follow. | ~''p1'',''p2'',''p3'''''^'''.
| Operates as described. | colspan="3" | ||||
| Skips or retains line breaks and adjacent whitespaces in a multi-line control string. | ~''<b>Newline</b>''. | Skips the immediately following line break and adjacent whitespaces. | Skips the immediately following line break, but retains adjacent whitespaces. | Retains the immediately following line break, but skips adjacent whitespaces. | |||
An example of a C printf call is the following:
Using Common Lisp, this is equivalent to:
Another example would be to print every element of list delimited with commas, which can be done using the directives:[4]
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:
The ability to define a new directive through ~/<i>functionName/</i> 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.
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 specialised and common need.[4]
A Common Lisp FORMAT summary table is available.[5]