1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
|
<h3 class="section">Output Streams</h3> <p>An output stream specifies what to do with the characters produced by printing. Most print functions accept an output stream as an optional argument. Here are the possible types of output stream: </p> <dl compact> <dt><var>buffer</var></dt> <dd>
<p>The output characters are inserted into <var>buffer</var> at point. Point advances as characters are inserted. </p> </dd> <dt><var>marker</var></dt> <dd>
<p>The output characters are inserted into the buffer that <var>marker</var> points into, at the marker position. The marker position advances as characters are inserted. The value of point in the buffer has no effect on printing when the stream is a marker, and this kind of printing does not move point (except that if the marker points at or before the position of point, point advances with the surrounding text, as usual). </p> </dd> <dt><var>function</var></dt> <dd>
<p>The output characters are passed to <var>function</var>, which is responsible for storing them away. It is called with a single character as argument, as many times as there are characters to be output, and is responsible for storing the characters wherever you want to put them. </p> </dd> <dt><code>t</code></dt> <dd>
<p>The output characters are displayed in the echo area. If Emacs is running in batch mode (see <a href="batch-mode">Batch Mode</a>), the output is written to the standard output descriptor instead. </p> </dd> <dt><code>nil</code></dt> <dd>
<p><code>nil</code> specified as an output stream means to use the value of the <code>standard-output</code> variable instead; that value is the <em>default output stream</em>, and must not be <code>nil</code>. </p> </dd> <dt><var>symbol</var></dt> <dd><p>A symbol as output stream is equivalent to the symbol’s function definition (if any). </p></dd> </dl> <p>Many of the valid output streams are also valid as input streams. The difference between input and output streams is therefore more a matter of how you use a Lisp object, than of different types of object. </p> <p>Here is an example of a buffer used as an output stream. Point is initially located as shown immediately before the ‘<samp>h</samp>’ in ‘<samp>the</samp>’. At the end, point is located directly before that same ‘<samp>h</samp>’. </p> <div class="example"> <pre class="example">---------- Buffer: foo ----------
This is t∗he contents of foo.
---------- Buffer: foo ----------
</pre>
<pre class="example">
(print "This is the output" (get-buffer "foo"))
⇒ "This is the output"
</pre>
<pre class="example">---------- Buffer: foo ----------
This is t
"This is the output"
∗he contents of foo.
---------- Buffer: foo ----------
</pre>
</div> <p>Now we show a use of a marker as an output stream. Initially, the marker is in buffer <code>foo</code>, between the ‘<samp>t</samp>’ and the ‘<samp>h</samp>’ in the word ‘<samp>the</samp>’. At the end, the marker has advanced over the inserted text so that it remains positioned before the same ‘<samp>h</samp>’. Note that the location of point, shown in the usual fashion, has no effect. </p> <div class="example"> <pre class="example">---------- Buffer: foo ----------
This is the ∗output
---------- Buffer: foo ----------
</pre>
<pre class="example">(setq m (copy-marker 10))
⇒ #<marker at 10 in foo>
</pre>
<pre class="example">(print "More output for foo." m)
⇒ "More output for foo."
</pre>
<pre class="example">---------- Buffer: foo ----------
This is t
"More output for foo."
he ∗output
---------- Buffer: foo ----------
</pre>
<pre class="example">m
⇒ #<marker at 34 in foo>
</pre>
</div> <p>The following example shows output to the echo area: </p> <div class="example"> <pre class="example">(print "Echo Area output" t)
⇒ "Echo Area output"
---------- Echo Area ----------
"Echo Area output"
---------- Echo Area ----------
</pre>
</div> <p>Finally, we show the use of a function as an output stream. The function <code>eat-output</code> takes each character that it is given and conses it onto the front of the list <code>last-output</code> (see <a href="building-lists">Building Lists</a>). At the end, the list contains all the characters output, but in reverse order. </p> <div class="example"> <pre class="example">(setq last-output nil)
⇒ nil
</pre>
<pre class="example">(defun eat-output (c)
(setq last-output (cons c last-output)))
⇒ eat-output
</pre>
<pre class="example">(print "This is the output" #'eat-output)
⇒ "This is the output"
</pre>
<pre class="example">last-output
⇒ (10 34 116 117 112 116 117 111 32 101 104
116 32 115 105 32 115 105 104 84 34 10)
</pre>
</div> <p>Now we can put the output in the proper order by reversing the list: </p> <div class="example"> <pre class="example">(concat (nreverse last-output))
⇒ "
\"This is the output\"
"
</pre>
</div> <p>Calling <code>concat</code> converts the list to a string so you can see its contents more clearly. </p> <dl> <dt id="external-debugging-output">Function: <strong>external-debugging-output</strong> <em>character</em>
</dt> <dd>
<p>This function can be useful as an output stream when debugging. It writes <var>character</var> to the standard error stream. </p> <p>For example </p>
<div class="example"> <pre class="example">(print "This is the output" #'external-debugging-output)
-| This is the output
⇒ "This is the output"
</pre>
</div> </dd>
</dl><div class="_attribution">
<p class="_attribution-p">
Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
<a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Output-Streams.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Output-Streams.html</a>
</p>
</div>
|
