22.3 Output Functions

The output functions are divided into two groups: those that operate on streams of characters and those that operate on streams of binary data. The function format operates on streams of characters but is described in a section separate from the other character-output functions because of its great complexity.

22.3.1 Output to Character Streams

These functions all take an optional argument called output-stream, which is where to send the output. If unsupplied or nil, output-stream defaults to the value of the variable *standard-output*. If it is t, the value of the variable *terminal-io* is used.

X3J13 voted in June 1989 to add the keyword argument :readably to the function write, and voted in June 1989 to add the keyword arguments :right-margin, :miser-width, :lines, and :pprint-dispatch. The revised description is as follows.

[Function] write object &key :stream :escape :radix :base :circle :pretty :level :length :case :gensym :array :readably :right-margin :miser-width :lines :pprint-dispatch

The printed representation of object is written to the output stream specified by :stream, which defaults to the value of *standard-output*.

The other keyword arguments specify values used to control the generation of the printed representation. Each defaults to the value of the corresponding global variable: see *print-escape*, *print-radix*, *print-base*, *print-circle*, *print-pretty*, *print-level*, *print-length*, and *print-case*, in addition to *print-array*, *print-gensym*, *print-readably*, *print-right-margin*, *print-miser-width*, *print-lines*, and *print-pprint-dispatch*. (This is the means by which these variables affect printing operations: supplying default values for the write function.) Note that the printing of symbols is also affected by the value of the variable *package*. write returns object.


[Function] prin1 object &optional output-stream
[Function] print object &optional output-stream
[Function] pprint object &optional output-stream
[Function] princ object &optional output-stream

prin1 outputs the printed representation of object to output-stream. Escape characters are used as appropriate. Roughly speaking, the output from prin1 is suitable for input to the function read. prin1 returns the object as its value.

(prin1 object output-stream)
    (write object :stream output-stream :escape t)

print is just like prin1 except that the printed representation of object is preceded by a newline (see terpri) and followed by a space. print returns object.

pprint is just like print except that the trailing space is omitted and the object is printed with the *print-pretty* flag non-nil to produce “pretty” output. pprint returns no values (that is, what the expression (values) returns: zero values).

X3J13 voted in January 1989 to adopt a facility for user-controlled pretty printing (see chapter 27).

princ is just like prin1 except that the output has no escape characters. A symbol is printed as simply the characters of its print name; a string is printed without surrounding double quotes; and there may be differences for other data types as well. The general rule is that output from princ is intended to look good to people, while output from prin1 is intended to be acceptable to the function read.

X3J13 voted in June 1987 to clarify that princ prints a character in exactly the same manner as write-char: the character is simply sent to the output stream. This was implied by the specification in section 22.1.6 in the first edition, but is worth pointing out explicitly here.
princ returns the object as its value.
(princ object output-stream)
    (write object :stream output-stream :escape nil)


[Function] write-to-string object &key :escape :radix :base :circle :pretty :level :length :case :gensym :array :readably :right-margin :miser-width :lines :pprint-dispatch
[Function] prin1-to-string object
[Function] princ-to-string object

The object is effectively printed as if by write, prin1, or princ, respectively, and the characters that would be output are made into a string, which is returned.


[Function] write-char character &optional output-stream

write-char outputs the character to output-stream, and returns character.


[Function] write-string string &optional output-stream &key :start :end
[Function] write-line string &optional output-stream &key :start :end

write-string writes the characters of the specified substring of string to the output-stream. The :start and :end parameters delimit a substring of string in the usual manner (see chapter 14). write-line does the same thing but then outputs a newline afterwards. (See read-line.) In either case, the string is returned (not the substring delimited by :start and :end). In some implementations these may be much more efficient than an explicit loop using write-char.


[Function] write-sequence sequence output-stream &key :start :end

write-sequence writes the elements of the subsequence of sequence bounded by start and end to output-stream.


[Function] terpri &optional output-stream
[Function] fresh-line &optional output-stream

The function terpri outputs a newline to output-stream. It is identical in effect to (write-char #\Newline output-stream); however, terpri always returns nil.

fresh-line is similar to terpri but outputs a newline only if the stream is not already at the start of a line. (If for some reason this cannot be determined, then a newline is output anyway.) This guarantees that the stream will be on a “fresh line” while consuming as little vertical distance as possible. fresh-line is a predicate that is true if it output a newline, and otherwise false.


[Function] finish-output &optional output-stream
[Function] force-output &optional output-stream
[Function] clear-output &optional output-stream

Some streams may be implemented in an asynchronous or buffered manner. The function finish-output attempts to ensure that all output sent to output-stream has reached its destination, and only then returns nil. force-output initiates the emptying of any internal buffers but returns nil without waiting for completion or acknowledgment.

The function clear-output, on the other hand, attempts to abort any outstanding output operation in progress in order to allow as little output as possible to continue to the destination. This is useful, for example, to abort a lengthy output to the terminal when an asynchronous error occurs. clear-output returns nil.

The precise actions of all three of these operations are implementation-dependent.


[Macro] print-unreadable-object (object stream[[:type type | :identity id]]){declaration}* {form}*

Function will output a printed representation of object on stream, beginning with #< and ending with >. Everything output to the stream during execution of the body forms is enclosed in the angle brackets. If type is true, the body output is preceded by a brief description of the object’s type and a space character. If id is true, the body output is followed by a space character and a representation of the object’s identity, typically a storage address.

If *print-readably* is true, print-unreadable-object signals an error of type print-not-readable without printing anything.

The object, stream, type, and id arguments are all evaluated normally. The type and id default to false. It is valid to provide no body forms. If type and id are both true and there are no body forms, only one space character separates the printed type and the printed identity.

The value returned by print-unreadable-object is nil.

(defmethod print-object ((obj airplane) stream)
  (print-unreadable-object (obj stream :type t :identity t)
    (princ (tail-number obj) stream)))
(print my-airplane)  prints
#<Airplane NW0773 777500123135>     ;In implementation A
                     or perhaps
#<FAA:AIRPLANE NW0773 17>           ;In implementation B

The big advantage of print-unreadable-object is that it allows a user to write print-object methods that adhere to implementation-specific style without requiring the user to write implementation-dependent code.

The X3J13 vote left it unclear whether print-unreadable-object permits declarations to appear before the body of the macro call. I believe that was the intent, and this is reflected in the syntax shown above; but this is only my interpretation.


22.3.2 Output to Binary Streams

Common Lisp currently specifies only a very simple facility for binary output: the writing of a single byte as an integer.

[Function] write-byte integer binary-output-stream

write-byte writes one byte, the value of integer. It is an error if integer is not of the type specified as the :element-type argument to open when the stream was created. The value integer is returned.


22.3.3 Formatted Output to Character Streams

The function format is very useful for producing nicely formatted text, producing good-looking messages, and so on. format can generate a string or output to a stream.

Formatted output is performed not only by the format function itself but by certain other functions that accept a control string “the way format does.” For example, error-signaling functions such as cerror accept format control strings.

[Function] format destination control-string &rest arguments

format is used to produce formatted output. format outputs the characters of control-string, except that a tilde (~) introduces a directive. The character after the tilde, possibly preceded by prefix parameters and modifiers, specifies what kind of formatting is desired. Most directives use one or more elements of arguments to create their output; the typical directive puts the next element of arguments into the output, formatted in some special way. It is an error if no argument remains for a directive requiring an argument, but it is not an error if one or more arguments remain unprocessed by a directive.

The output is sent to destination. If destination is nil, a string is created that contains the output; this string is returned as the value of the call to format.

When the first argument to format is nil, format creates a stream of type string-stream in much the same manner as with-output-to-string. (This stream may be visible to the user if, for example, the ~S directive is used to print a defstruct structure that has a user-supplied print function.)

In all other cases format returns nil, performing output to destination as a side effect. If destination is a stream, the output is sent to it. If destination is t, the output is sent to the stream that is the value of the variable *standard-output*. If destination is a string with a fill pointer, then in effect the output characters are added to the end of the string (as if by use of vector-push-extend).

The format function includes some extremely complicated and specialized features. It is not necessary to understand all or even most of its features to use format effectively. The beginner should skip over anything in the following documentation that is not immediately useful or clear. The more sophisticated features (such as conditionals and iteration) are there for the convenience of programs with especially complicated formatting requirements.

A format directive consists of a tilde (~), optional prefix parameters separated by commas, optional colon (:) and at-sign (@) modifiers, and a single character indicating what kind of directive this is. The alphabetic case of the directive character is ignored. The prefix parameters are generally integers, notated as optionally signed decimal numbers.

If both colon and at-sign modifiers are present, they may appear in either order; thus ~:@R and ~@:R mean the same thing. However, it is traditional to put the colon first, and all the examples in this book put colons before at-signs.

Examples of control strings:

"~S"           ;An ~S directive with no parameters or modifiers
"~3,-4:@s"     ;An ~S directive with two parameters, 3 and − 4,
               ; and both the colon and at-sign flags
"~,+4S"        ;First prefix parameter is omitted and takes
               ; on its default value; the second parameter is 4

Sometimes a prefix parameter is used to specify a character, for instance the padding character in a right- or left-justifying operation. In this case a single quote () followed by the desired character may be used as a prefix parameter, to mean the character object that is the character following the single quote. For example, you can use ~5,’0d to print an integer in decimal radix in five columns with leading zeros, or ~5,’*d to get leading asterisks.

In place of a prefix parameter to a directive, you can put the letter V (or v), which takes an argument from arguments for use as a parameter to the directive. Normally this should be an integer or character object, as appropriate. This feature allows variable-width fields and the like. If the argument used by a V parameter is nil, the effect is as if the parameter had been omitted. You may also use the character # in place of a parameter; it represents the number of arguments remaining to be processed.

It is an error to give a format directive more parameters than it is described here as accepting. It is also an error to give colon or at-sign modifiers to a directive in a combination not specifically described here as being meaningful.


X3J13 voted in January 1989 to clarify the interaction between format and the various printer control variables (those named *print-xxx*). This is important because many format operations are defined, directly or indirectly, in terms of prin1 or princ, which are affected by the printer control variables. The general rule is that format does not bind any of the standard printer control variables except as specified in the individual descriptions of directives. An implementation may not bind any standard printer control variable not specified in the description of a format directive, nor may an implementation fail to bind any standard printer control variables that is specified to be bound by such a description. (See these descriptions for specific changes voted by X3J13.)

One consequence of this change is that the user is guaranteed to be able to use the format ~A and ~S directives to do pretty printing, under control of the *print-pretty* variable. Implementations have differed on this point in their interpretations of the first edition. The new ~W directive may be more appropriate than either ~A and ~S for some purposes, whether for pretty printing or ordinary printing. See section 27.4 for a discussion of ~W and other new format directives related to pretty printing.

Here are some relatively simple examples to give you the general flavor of how format is used.

(format nil "foo")  "foo"

(setq x 5)

(format nil "The answer is ~D." x)  "The answer is 5."

(format nil "The answer is ~3D." x)  "The answer is   5."

(format nil "The answer is ~3,’0D." x)  "The answer is 005."

(format nil "The answer is ~:D." (expt 47 x))
                                 "The answer is 229,345,007."

(setq y "elephant")

(format nil "Look at the ~A!" y)  "Look at the elephant!"

(format nil "Type ~:C to ~A."
        (set-char-bit #\D :control t)
        "delete all your files")
    "Type Control-D to delete all your files."

(setq n 3)

(format nil "~D item~:P found." n)  "3 items found."

(format nil "~R dog~:[s are~; is~] here." n (= n 1))
       "three dogs are here."

(format nil "~R dog~:*~[s are~; is~:;s are~] here." n)
       "three dogs are here."

(format nil "Here ~[are~;is~:;are~] ~:*~R pupp~:@P." n)
       "Here are three puppies."

In the descriptions of the directives that follow, the term arg in general refers to the next item of the set of arguments to be processed. The word or phrase at the beginning of each description is a mnemonic (not necessarily an accurate one) for the directive.

X3J13 voted in June 1989 to introduce certain format directives to support the user interface to the pretty printer described in detail in chapter 27.

The format directives after this point are much more complicated than the foregoing; they constitute control structures that can perform case conversion, conditional selection, iteration, justification, and non-local exits. Used with restraint, they can perform powerful tasks. Used with abandon, they can produce completely unreadable and unmaintainable code.

The case-conversion, conditional, iteration, and justification constructs can contain other formatting constructs by bracketing them. These constructs must nest properly with respect to each other. For example, it is not legitimate to put the start of a case-conversion construct in each arm of a conditional and the end of the case-conversion construct outside the conditional:

(format nil "~:[abc~:@(def~;ghi~:@(jkl~]mno~)" x)     ;Illegal!

One might expect this to produce either "abcDEFMNO" or "ghiJKLMNO", depending on whether x is false or true; but in fact the construction is illegal because the ~[...~;...~] and ~(...~) constructs are not properly nested.

The processing indirection caused by the ~? directive is also a kind of nesting for the purposes of this rule of proper nesting. It is not permitted to start a bracketing construct within a string processed under control of a ~? directive and end the construct at some point after the ~? construct in the string containing that construct, or vice versa. For example, this situation is illegal:

(format nil "~?ghi~)" "abc~@(def")     ;Illegal!

One might expect it to produce "abcDEFGHI", but in fact the construction is illegal because the ~? and ~(...~) constructs are not properly nested.

X3J13 voted in June 1989 to introduce user-defined directives in the form of the ~/.../ directive. See section 27.4 for details.

The hairiest format control string I have ever seen in shown in table 22.10. It started innocently enough as part of the simulator for Connection Machine Lisp [4457]; the xapping data type, defined by defstruct, needed a :print-function option so that xappings would print properly. As this data type became more complicated, step by step, so did the format control string.


Table 22.10: Print Function for the Xapping Data Type
(defun print-xapping (xapping stream depth)
  (declare (ignore depth))
  (format stream
          ;; Are you ready for this one?
          "~:[{~;[~]~:{~S~:[~S~;~*~]~:̂ ~}~:[~; ~]~
           ~{~S~̂ ~}~:[~; ~]~[~*~;~S~;~*~]~:[}~;]~]"
          ;; Is that clear?
          (xectorp xapping)
          (do ((vp (xectorp xapping))
               (sp (finite-part-is-xetp xapping))
               (d (xapping-domain xapping) (cdr d))
               (r (xapping-range xapping) (cdr r))
               (z ’() (cons (list (if vp (car r) (car d))
                                  (or vp sp)
                                  (car r))
                            z)))
              ((null d) (reverse z)))
          (and (xapping-domain xapping)
               (or (xapping-exceptions xapping)
                   (xapping-infinite xapping)))
          (xapping-exceptions xapping)
          (and (xapping-exceptions xapping)
               (xapping-infinite xapping))
          (ecase (xapping-infinite xapping)
            ((nil) 0)
            (:constant 1)
            (:universal 2))
          (xapping-default xapping)
          (xectorp xapping)))
See section 22.1.5 for the defstruct definition of the xapping data type, whose accessor functions are used in this code.

See the description of set-macro-character for a discussion of xappings and the defstruct definition. Assume that the predicate xectorp is true of a xapping if it is a xector, and that the predicate finite-part-is-xetp is true if every value in the range is the same as its corresponding index.

Here is a blow-by-blow description of the parts of this format string:

~:[{~;[~]  

Print “[” for a xector, and “{” otherwise.

~:{~S~:[~S~;~*~]~:̂ ~} 

Given a list of lists, print the pairs. Each sublist has three elements: the index (or the value if we’re printing a xector); a flag that is true for either a xector or xet (in which case no arrow is printed); and the value. Note the use of ~:{ to iterate, and the use of ~:̂ to avoid printing a separating space after the final pair (or at all, if there are no pairs).

~:[~; ~]  

If there were pairs and there are exceptions or an infinite part, print a separating space.

~newline  

Do nothing. This merely allows the format control string to be broken across two lines.

~{~S~̂ ~}  

Given a list of exception indices, print them. Note the use of ~{ to iterate, and the use of to avoid printing a separating space after the final exception (or at all, if there are no exceptions).

~:[~; ~]  

If there were exceptions and there is an infinite part, print a separating space.

~[~*~;~S~;~*~]  

Use ~[ to choose one of three cases for printing the infinite part.

~:[}~;]~]  

Print “]” for a xector, and “}” otherwise.