261 lines
14 KiB
HTML
261 lines
14 KiB
HTML
|
<!DOCTYPE HTML PUBLIC "-//W3O//DTD W3 HTML 2.0//EN">
|
||
|
|
<!Converted with LaTeX2HTML 0.6.5 (Tue Nov 15 1994) by Nikos Drakos (nikos@cbl.leeds.ac.uk), CBLU, University of Leeds >
|
||
|
|
<HEAD>
|
||
|
|
<TITLE>22.3.1. Output to Character Streams</TITLE>
|
||
|
|
</HEAD>
|
||
|
|
<BODY>
|
||
|
|
<meta name="description" value=" Output to Character Streams">
|
||
|
|
<meta name="keywords" value="clm">
|
||
|
|
<meta name="resource-type" value="document">
|
||
|
|
<meta name="distribution" value="global">
|
||
|
|
<P>
|
||
|
|
<b>Common Lisp the Language, 2nd Edition</b>
|
||
|
|
<BR> <HR><A NAME=tex2html4012 HREF="node199.html"><IMG ALIGN=BOTTOM ALT="next" SRC="icons/next_motif.gif"></A> <A NAME=tex2html4010 HREF="node197.html"><IMG ALIGN=BOTTOM ALT="up" SRC="icons/up_motif.gif"></A> <A NAME=tex2html4004 HREF="node197.html"><IMG ALIGN=BOTTOM ALT="previous" SRC="icons/previous_motif.gif"></A> <A NAME=tex2html4014 HREF="node1.html"><IMG ALIGN=BOTTOM ALT="contents" SRC="icons/contents_motif.gif"></A> <A NAME=tex2html4015 HREF="index.html"><IMG ALIGN=BOTTOM ALT="index" SRC="icons/index_motif.gif"></A> <BR>
|
||
|
|
<B> Next:</B> <A NAME=tex2html4013 HREF="node199.html"> Output to Binary </A>
|
||
|
|
<B>Up:</B> <A NAME=tex2html4011 HREF="node197.html"> Output Functions</A>
|
||
|
|
<B> Previous:</B> <A NAME=tex2html4005 HREF="node197.html"> Output Functions</A>
|
||
|
|
<HR> <P>
|
||
|
|
<H2><A NAME=SECTION002631000000000000000>22.3.1. Output to Character Streams</A></H2>
|
||
|
|
<P>
|
||
|
|
These functions all take an optional argument called <i>output-stream</i>,
|
||
|
|
which is where to send the output. If unsupplied or <tt>nil</tt>, <i>output-stream</i>
|
||
|
|
defaults to the value of the variable
|
||
|
|
<tt>*standard-output*</tt>. If it is <tt>t</tt>, the value of the variable
|
||
|
|
<tt>*terminal-io*</tt> is used.
|
||
|
|
<P>
|
||
|
|
<img align=bottom alt="old_change_begin" src="gif/old_change_begin.gif"><br>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>write <i>object</i> &key :stream :escape :radix :base :circle :pretty :level :length :case :gensym :array</tt><P>The printed representation of <i>object</i> is written to the output stream
|
||
|
|
specified by <tt>:stream</tt>, which defaults to the value of <tt>*standard-output*</tt>.
|
||
|
|
<P>
|
||
|
|
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 <tt>*print-escape*</tt>,
|
||
|
|
<tt>*print-radix*</tt>, <tt>*print-base*</tt>, <tt>*print-circle*</tt>, <tt>*print-pretty*</tt>,
|
||
|
|
<tt>*print-level*</tt>, <tt>*print-length*</tt>,
|
||
|
|
<tt>*print-case*</tt>,
|
||
|
|
<tt>*print-array*</tt>,
|
||
|
|
and <tt>*print-gensym*</tt>.
|
||
|
|
(This is the means by which these variables affect printing operations:
|
||
|
|
supplying default values for the <tt>write</tt> function.)
|
||
|
|
Note that the printing of symbols is also affected by the value
|
||
|
|
of the variable <tt>*package*</tt>.
|
||
|
|
<tt>write</tt> returns <i>object</i>.
|
||
|
|
<br><img align=bottom alt="old_change_end" src="gif/old_change_end.gif">
|
||
|
|
<P>
|
||
|
|
<img align=bottom alt="change_begin" src="gif/change_begin.gif"><br>
|
||
|
|
X3J13 voted in June 1989 (DATA-IO) <A NAME=23218> </A> to add the keyword argument
|
||
|
|
<tt>:readably</tt> to the function <tt>write</tt>, and voted in June 1989 (PRETTY-PRINT-INTERFACE) <A NAME=23221> </A>
|
||
|
|
to add the keyword arguments <tt>:right-margin</tt>, <tt>:miser-width</tt>, <tt>:lines</tt>,
|
||
|
|
and <tt>:pprint-dispatch</tt>.
|
||
|
|
The revised description
|
||
|
|
is as follows.
|
||
|
|
<P>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>write <i>object</i> &key :stream :escape :radix :base :circle :pretty :level :length :case :gensym :array :readably :right-margin :miser-width :lines :pprint-dispatch</tt><P>The printed representation of <i>object</i> is written to the output stream
|
||
|
|
specified by <tt>:stream</tt>, which defaults to the value of <tt>*standard-output*</tt>.
|
||
|
|
<P>
|
||
|
|
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 <tt>*print-escape*</tt>,
|
||
|
|
<tt>*print-radix*</tt>, <tt>*print-base*</tt>, <tt>*print-circle*</tt>, <tt>*print-pretty*</tt>,
|
||
|
|
<tt>*print-level*</tt>, <tt>*print-length*</tt>, and <tt>*print-case*</tt>, in addition to
|
||
|
|
<tt>*print-array*</tt>,
|
||
|
|
<tt>*print-gensym*</tt>,
|
||
|
|
<tt>*print-readably*</tt>,
|
||
|
|
<tt>*print-right-margin*</tt>,
|
||
|
|
<tt>*print-miser-width*</tt>,
|
||
|
|
<tt>*print-lines*</tt>,
|
||
|
|
and <tt>*print-pprint-dispatch*</tt>.
|
||
|
|
(This is the means by which these variables affect printing operations:
|
||
|
|
supplying default values for the <tt>write</tt> function.)
|
||
|
|
Note that the printing of symbols is also affected by the value
|
||
|
|
of the variable <tt>*package*</tt>.
|
||
|
|
<tt>write</tt> returns <i>object</i>.
|
||
|
|
<br><img align=bottom alt="change_end" src="gif/change_end.gif">
|
||
|
|
<P>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>prin1 <i>object</i> &optional <i>output-stream</i> <BR>print <i>object</i> &optional <i>output-stream</i> <BR>pprint <i>object</i> &optional <i>output-stream</i> <BR>princ <i>object</i> &optional <i>output-stream</i></tt><P><tt>prin1</tt> outputs the printed representation of <i>object</i> to
|
||
|
|
<i>output-stream</i>. Escape characters are used as appropriate.
|
||
|
|
Roughly speaking, the output from <tt>prin1</tt> is suitable for input to
|
||
|
|
the function <tt>read</tt>. <tt>prin1</tt> returns the <i>object</i> as its value.
|
||
|
|
<P><pre>
|
||
|
|
(prin1 <i>object</i> <i>output-stream</i>)
|
||
|
|
== (write <i>object</i> :stream <i>output-stream</i> :escape t)
|
||
|
|
</pre><P>
|
||
|
|
<P>
|
||
|
|
<tt>print</tt> is just like <tt>prin1</tt> except that the printed representation
|
||
|
|
of <i>object</i> is preceded by a newline (see <tt>terpri</tt>)
|
||
|
|
and followed by a space.
|
||
|
|
<tt>print</tt> returns <i>object</i>.
|
||
|
|
<P>
|
||
|
|
<tt>pprint</tt> is just like <tt>print</tt> except that the trailing
|
||
|
|
space is omitted and the
|
||
|
|
<i>object</i> is printed with the <tt>*print-pretty*</tt> flag non-<tt>nil</tt>
|
||
|
|
to produce ``pretty'' output.
|
||
|
|
<tt>pprint</tt> returns no values (that is, what the expression
|
||
|
|
<tt>(values)</tt> returns: zero values).
|
||
|
|
<P>
|
||
|
|
<img align=bottom alt="change_begin" src="gif/change_begin.gif"><br>
|
||
|
|
X3J13 voted in January 1989
|
||
|
|
(PRETTY-PRINT-INTERFACE) <A NAME=23302> </A>
|
||
|
|
to adopt a facility for user-controlled pretty printing
|
||
|
|
(see chapter <A HREF="node253.html#PPRINT">27</A>).
|
||
|
|
<br><img align=bottom alt="change_end" src="gif/change_end.gif">
|
||
|
|
<P>
|
||
|
|
<tt>princ</tt> is just like <tt>prin1</tt> 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 <tt>princ</tt> is intended to look
|
||
|
|
good to people, while output from <tt>prin1</tt> is intended to
|
||
|
|
be acceptable to the function <tt>read</tt>.
|
||
|
|
<p>
|
||
|
|
<img align=bottom alt="change_begin" src="gif/change_begin.gif"><br>
|
||
|
|
X3J13 voted in June 1987 (PRINC-CHARACTER) <A NAME=23311> </A>
|
||
|
|
to clarify that <tt>princ</tt> prints a character in exactly
|
||
|
|
the same manner as <tt>write-char</tt>: the character is simply sent to the output <i>stream</i>.
|
||
|
|
This was implied by the specification in section <A HREF="node193.html#PRINTER">22.1.6</A> in the first edition,
|
||
|
|
but is worth pointing out explicitly here.
|
||
|
|
<br><img align=bottom alt="change_end" src="gif/change_end.gif">
|
||
|
|
<P>
|
||
|
|
<tt>princ</tt> returns the <i>object</i> as its value.
|
||
|
|
<P><pre>
|
||
|
|
(princ <i>object</i> <i>output-stream</i>)
|
||
|
|
== (write <i>object</i> :stream <i>output-stream</i> :escape <tt>nil</tt>)
|
||
|
|
</pre><P>
|
||
|
|
<P>
|
||
|
|
<hr>
|
||
|
|
<b>Compatibility note:</b> In MacLisp, the functions <tt>prin1</tt>, <tt>print</tt>,
|
||
|
|
and <tt>princ</tt> return <tt>t</tt>, not the argument <i>object</i>.
|
||
|
|
<hr>
|
||
|
|
<P>
|
||
|
|
<img align=bottom alt="old_change_begin" src="gif/old_change_begin.gif"><br>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>write-to-string <i>object</i> &key :escape :radix :base :circle :pretty :level :length :case :gensym :array <BR>prin1-to-string <i>object</i> <BR>princ-to-string <i>object</i></tt><P>The object is effectively printed as if by <tt>write</tt>,
|
||
|
|
<tt>prin1</tt>, or <tt>princ</tt>, respectively,
|
||
|
|
and the characters that would be output are made into a string,
|
||
|
|
which is returned.
|
||
|
|
<br><img align=bottom alt="old_change_end" src="gif/old_change_end.gif">
|
||
|
|
<P>
|
||
|
|
<hr>
|
||
|
|
<b>Compatibility note:</b> The Interlisp function <tt>mkstring</tt> corresponds
|
||
|
|
to the Common Lisp function <tt>princ-to-string</tt>.
|
||
|
|
<hr>
|
||
|
|
<P>
|
||
|
|
<img align=bottom alt="change_begin" src="gif/change_begin.gif"><br>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>write-to-string <i>object</i> &key :escape :radix :base :circle :pretty :level :length :case :gensym :array :readably :right-margin :miser-width :lines :pprint-dispatch</tt><P>X3J13 voted in June 1989 ((DATA-IO) <A NAME=23347> </A> and (PRETTY-PRINT-INTERFACE) <A NAME=23348> </A> )
|
||
|
|
to add keyword arguments to <tt>write</tt>; presumably they should also be added
|
||
|
|
to <tt>write-to-string</tt>.
|
||
|
|
<br><img align=bottom alt="change_end" src="gif/change_end.gif">
|
||
|
|
<P>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>write-char <i>character</i> &optional <i>output-stream</i></tt><P><tt>write-char</tt> outputs the <i>character</i> to <i>output-stream</i>,
|
||
|
|
and returns <i>character</i>.
|
||
|
|
<P>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>write-string <i>string</i> &optional <i>output-stream</i> &key :start :end <BR>write-line <i>string</i> &optional <i>output-stream</i> &key :start :end</tt><P><tt>write-string</tt> writes the characters of the specified
|
||
|
|
substring of <i>string</i> to
|
||
|
|
the <i>output-stream</i>. The <tt>:start</tt> and <tt>:end</tt> parameters
|
||
|
|
delimit a substring of <i>string</i> in the usual manner
|
||
|
|
(see chapter <A HREF="node141.html#KSEQUE">14</A>).
|
||
|
|
<tt>write-line</tt> does the same thing but then
|
||
|
|
outputs a newline afterwards. (See <tt>read-line</tt>.)
|
||
|
|
In either case, the <i>string</i> is returned (<i>not</i> the substring
|
||
|
|
delimited by <tt>:start</tt> and <tt>:end</tt>).
|
||
|
|
In some implementations these may be much
|
||
|
|
more efficient than an explicit loop using <tt>write-char</tt>.
|
||
|
|
<P>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>terpri &optional <i>output-stream</i> <BR>fresh-line &optional <i>output-stream</i></tt><P>The function <tt>terpri</tt> outputs a newline to <i>output-stream</i>.
|
||
|
|
It is identical in effect to
|
||
|
|
<tt>(write-char #\Newline <i>output-stream</i>)</tt>; however,
|
||
|
|
<tt>terpri</tt> always returns <tt>nil</tt>.
|
||
|
|
<P>
|
||
|
|
<tt>fresh-line</tt> is similar to <tt>terpri</tt> 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.
|
||
|
|
<tt>fresh-line</tt> is a predicate that is true if it output a
|
||
|
|
newline, and otherwise false.
|
||
|
|
<P>
|
||
|
|
<BR><b>[Function]</b><BR>
|
||
|
|
<tt>finish-output &optional <i>output-stream</i> <BR>force-output &optional <i>output-stream</i> <BR>clear-output &optional <i>output-stream</i></tt><P>Some streams may be implemented in an asynchronous or buffered manner.
|
||
|
|
The function <tt>finish-output</tt> attempts to ensure that all output
|
||
|
|
sent to <i>output-stream</i> has reached its destination, and only then
|
||
|
|
returns <tt>nil</tt>. <tt>force-output</tt> initiates the emptying of any
|
||
|
|
internal buffers but returns <tt>nil</tt> without waiting for completion
|
||
|
|
or acknowledgment.
|
||
|
|
<P>
|
||
|
|
The function <tt>clear-output</tt>, 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.
|
||
|
|
<tt>clear-output</tt> returns <tt>nil</tt>.
|
||
|
|
<P>
|
||
|
|
The precise actions of all three of these operations are
|
||
|
|
implementation-dependent.
|
||
|
|
<P>
|
||
|
|
<img align=bottom alt="change_begin" src="gif/change_begin.gif"><br>
|
||
|
|
<BR><b>[Macro]</b><BR>
|
||
|
|
<pre>
|
||
|
|
print-unreadable-object (<i>object</i> <i>stream</i>
|
||
|
|
<b>[[</b> :type <i>type</i> | :identity <i>id</i> <b>]]</b>)
|
||
|
|
{<i>declaration</i>}* {<i>form</i>}*
|
||
|
|
</pre>
|
||
|
|
X3J13 voted in June 1989 (DATA-IO) <A NAME=23401> </A> to add
|
||
|
|
<tt>print-unreadable-object</tt>,
|
||
|
|
which will output a printed representation of <i>object</i> on <i>stream</i>,
|
||
|
|
beginning with
|
||
|
|
<tt>#<</tt> and ending with <tt>></tt>. Everything output to the <i>stream</i> during
|
||
|
|
execution of the body
|
||
|
|
forms is enclosed in the angle brackets. If <i>type</i> is true, the body
|
||
|
|
output is preceded by a brief description of the object's type and a
|
||
|
|
space character. If <i>id</i> is true, the body output is followed by
|
||
|
|
a space character and a representation of the object's identity,
|
||
|
|
typically a storage address.
|
||
|
|
<P>
|
||
|
|
If <tt>*print-readably*</tt> is true, <tt>print-unreadable-object</tt> signals an error
|
||
|
|
of type <tt>print-not-readable</tt> without printing anything.
|
||
|
|
<P>
|
||
|
|
The <i>object</i>, <i>stream</i>, <i>type</i>, and <i>id</i> arguments are all evaluated
|
||
|
|
normally. The <i>type</i> and <i>id</i> default to false. It is valid to provide
|
||
|
|
no body forms. If <i>type</i> and <i>id</i> are both true and there are no
|
||
|
|
body forms, only one space character separates the printed type and the printed identity.
|
||
|
|
<P>
|
||
|
|
The value returned by <tt>print-unreadable-object</tt> is <tt>nil</tt>.
|
||
|
|
<P><pre>
|
||
|
|
(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
|
||
|
|
</pre><P>
|
||
|
|
The big advantage of
|
||
|
|
<tt>print-unreadable-object</tt> is that it allows a user to write <tt>print-object</tt> methods that
|
||
|
|
adhere to implementation-specific style without requiring the user to write
|
||
|
|
implementation-dependent code.
|
||
|
|
<P>
|
||
|
|
The X3J13 vote left it unclear whether <tt>print-unreadable-object</tt>
|
||
|
|
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.
|
||
|
|
<br><img align=bottom alt="change_end" src="gif/change_end.gif">
|
||
|
|
<P>
|
||
|
|
<BR> <HR><A NAME=tex2html4012 HREF="node199.html"><IMG ALIGN=BOTTOM ALT="next" SRC="icons/next_motif.gif"></A> <A NAME=tex2html4010 HREF="node197.html"><IMG ALIGN=BOTTOM ALT="up" SRC="icons/up_motif.gif"></A> <A NAME=tex2html4004 HREF="node197.html"><IMG ALIGN=BOTTOM ALT="previous" SRC="icons/previous_motif.gif"></A> <A NAME=tex2html4014 HREF="node1.html"><IMG ALIGN=BOTTOM ALT="contents" SRC="icons/contents_motif.gif"></A> <A NAME=tex2html4015 HREF="index.html"><IMG ALIGN=BOTTOM ALT="index" SRC="icons/index_motif.gif"></A> <BR>
|
||
|
|
<B> Next:</B> <A NAME=tex2html4013 HREF="node199.html"> Output to Binary </A>
|
||
|
|
<B>Up:</B> <A NAME=tex2html4011 HREF="node197.html"> Output Functions</A>
|
||
|
|
<B> Previous:</B> <A NAME=tex2html4005 HREF="node197.html"> Output Functions</A>
|
||
|
|
<HR> <P>
|
||
|
|
<HR>
|
||
|
|
<P><ADDRESS>
|
||
|
|
AI.Repository@cs.cmu.edu
|
||
|
|
</ADDRESS>
|
||
|
|
</BODY>
|