Common Lisp the Language, 2nd Edition

Next: Output to Binary Up: Output Functions Previous: Output Functions

## 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.

[Function]
`write object &key :stream :escape :radix :base :circle :pretty :level :length :case :gensym :array`

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*`, `*print-case*`, `*print-array*`, and `*print-gensym*`. (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.

X3J13 voted in June 1989 (DATA-IO) to add the keyword argument `:readably` to the function `write`, and voted in June 1989 (PRETTY-PRINT-INTERFACE) 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
print object &optional output-stream
pprint object &optional output-stream
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 (PRETTY-PRINT-INTERFACE) 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 (PRINC-CHARACTER) 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)

Compatibility note: In MacLisp, the functions `prin1`, `print`, and `princ` return `t`, not the argument object.

[Function]
`write-to-string object &key :escape :radix :base :circle :pretty :level :length :case :gensym :array
prin1-to-string object
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.

Compatibility note: The Interlisp function `mkstring` corresponds to the Common Lisp function `princ-to-string`.

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

X3J13 voted in June 1989 ((DATA-IO) and (PRETTY-PRINT-INTERFACE) ) to add keyword arguments to `write`; presumably they should also be added to `write-to-string`.

[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
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]
`terpri &optional output-stream
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
force-output &optional output-stream
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}*

X3J13 voted in June 1989 (DATA-IO) to add `print-unreadable-object`, which 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.

Next: Output to Binary Up: Output Functions Previous: Output Functions