Format (Common Lisp)
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, where it was based on Multics ioa_. Specification The format function is specified by the syntax Directives in the control string are interpolated using the format arguments, and the thus constructed character sequence is written to the destination. 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)) Control string and format arguments 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. Directives 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