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]
writeobject&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]
writeobject&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]
prin1object&optionaloutput-stream
printobject&optionaloutput-stream
pprintobject&optionaloutput-stream
princobject&optionaloutput-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-stringobject&key :escape :radix :base :circle :pretty :level :length :case :gensym :array
prin1-to-stringobject
princ-to-stringobject

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-stringobject&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-charcharacter&optionaloutput-stream

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

[Function]
write-stringstring&optionaloutput-stream&key :start :end
write-linestring&optionaloutput-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 &optionaloutput-stream
fresh-line &optionaloutput-stream

The function terpri outputs a newline to output-stream. It is identical in effect to (write-char #\Newlineoutput-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 &optionaloutput-stream
force-output &optionaloutput-stream
clear-output &optionaloutput-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

AI.Repository@cs.cmu.edu