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
|
<h3 class="section">Output Functions</h3> <p>This section describes the Lisp functions for printing Lisp objects—converting objects into their printed representation. </p> <p>Some of the Emacs printing functions add quoting characters to the output when necessary so that it can be read properly. The quoting characters used are ‘<samp>"</samp>’ and ‘<samp>\</samp>’; they distinguish strings from symbols, and prevent punctuation characters in strings and symbols from being taken as delimiters when reading. See <a href="printed-representation">Printed Representation</a>, for full details. You specify quoting or no quoting by the choice of printing function. </p> <p>If the text is to be read back into Lisp, then you should print with quoting characters to avoid ambiguity. Likewise, if the purpose is to describe a Lisp object clearly for a Lisp programmer. However, if the purpose of the output is to look nice for humans, then it is usually better to print without quoting. </p> <p>Lisp objects can refer to themselves. Printing a self-referential object in the normal way would require an infinite amount of text, and the attempt could cause infinite recursion. Emacs detects such recursion and prints ‘<samp>#<var>level</var></samp>’ instead of recursively printing an object already being printed. For example, here ‘<samp>#0</samp>’ indicates a recursive reference to the object at level 0 of the current print operation: </p> <div class="example"> <pre class="example">(setq foo (list nil))
⇒ (nil)
(setcar foo foo)
⇒ (#0)
</pre>
</div> <p>In the functions below, <var>stream</var> stands for an output stream. (See the previous section for a description of output streams. Also See <a href="output-streams#external_002ddebugging_002doutput">external-debugging-output</a>, a useful stream value for debugging.) If <var>stream</var> is <code>nil</code> or omitted, it defaults to the value of <code>standard-output</code>. </p> <dl> <dt id="print">Function: <strong>print</strong> <em>object &optional stream</em>
</dt> <dd>
<p>The <code>print</code> function is a convenient way of printing. It outputs the printed representation of <var>object</var> to <var>stream</var>, printing in addition one newline before <var>object</var> and another after it. Quoting characters are used. <code>print</code> returns <var>object</var>. For example: </p> <div class="example"> <pre class="example">(progn (print 'The\ cat\ in)
(print "the hat")
(print " came back"))
-|
-| The\ cat\ in
-|
-| "the hat"
-|
-| " came back"
⇒ " came back"
</pre>
</div> </dd>
</dl> <dl> <dt id="prin1">Function: <strong>prin1</strong> <em>object &optional stream</em>
</dt> <dd>
<p>This function outputs the printed representation of <var>object</var> to <var>stream</var>. It does not print newlines to separate output as <code>print</code> does, but it does use quoting characters just like <code>print</code>. It returns <var>object</var>. </p> <div class="example"> <pre class="example">(progn (prin1 'The\ cat\ in)
(prin1 "the hat")
(prin1 " came back"))
-| The\ cat\ in"the hat"" came back"
⇒ " came back"
</pre>
</div> </dd>
</dl> <dl> <dt id="princ">Function: <strong>princ</strong> <em>object &optional stream</em>
</dt> <dd>
<p>This function outputs the printed representation of <var>object</var> to <var>stream</var>. It returns <var>object</var>. </p> <p>This function is intended to produce output that is readable by people, not by <code>read</code>, so it doesn’t insert quoting characters and doesn’t put double-quotes around the contents of strings. It does not add any spacing between calls. </p> <div class="example"> <pre class="example">(progn
(princ 'The\ cat)
(princ " in the \"hat\""))
-| The cat in the "hat"
⇒ " in the \"hat\""
</pre>
</div> </dd>
</dl> <dl> <dt id="terpri">Function: <strong>terpri</strong> <em>&optional stream ensure</em>
</dt> <dd>
<p>This function outputs a newline to <var>stream</var>. The name stands for “terminate print”. If <var>ensure</var> is non-<code>nil</code> no newline is printed if <var>stream</var> is already at the beginning of a line. Note in this case <var>stream</var> can not be a function and an error is signaled if it is. This function returns <code>t</code> if a newline is printed. </p>
</dd>
</dl> <dl> <dt id="write-char">Function: <strong>write-char</strong> <em>character &optional stream</em>
</dt> <dd><p>This function outputs <var>character</var> to <var>stream</var>. It returns <var>character</var>. </p></dd>
</dl> <dl> <dt id="prin1-to-string">Function: <strong>prin1-to-string</strong> <em>object &optional noescape</em>
</dt> <dd>
<p>This function returns a string containing the text that <code>prin1</code> would have printed for the same argument. </p> <div class="example"> <pre class="example">(prin1-to-string 'foo)
⇒ "foo"
</pre>
<pre class="example">(prin1-to-string (mark-marker))
⇒ "#<marker at 2773 in strings.texi>"
</pre>
</div> <p>If <var>noescape</var> is non-<code>nil</code>, that inhibits use of quoting characters in the output. (This argument is supported in Emacs versions 19 and later.) </p> <div class="example"> <pre class="example">(prin1-to-string "foo")
⇒ "\"foo\""
</pre>
<pre class="example">(prin1-to-string "foo" t)
⇒ "foo"
</pre>
</div> <p>See <code>format</code>, in <a href="formatting-strings">Formatting Strings</a>, for other ways to obtain the printed representation of a Lisp object as a string. </p>
</dd>
</dl> <dl> <dt id="with-output-to-string">Macro: <strong>with-output-to-string</strong> <em>body…</em>
</dt> <dd>
<p>This macro executes the <var>body</var> forms with <code>standard-output</code> set up to feed output into a string. Then it returns that string. </p> <p>For example, if the current buffer name is ‘<samp>foo</samp>’, </p> <div class="example"> <pre class="example">(with-output-to-string
(princ "The buffer is ")
(princ (buffer-name)))
</pre>
</div> <p>returns <code>"The buffer is foo"</code>. </p>
</dd>
</dl> <dl> <dt id="pp">Function: <strong>pp</strong> <em>object &optional stream</em>
</dt> <dd><p>This function outputs <var>object</var> to <var>stream</var>, just like <code>prin1</code>, but does it in a prettier way. That is, it’ll indent and fill the object to make it more readable for humans. </p></dd>
</dl> <p>If you need to use binary I/O in batch mode, e.g., use the functions described in this section to write out arbitrary binary data or avoid conversion of newlines on non-POSIX hosts, see <a href="input-functions">set-binary-mode</a>. </p><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-Functions.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Output-Functions.html</a>
</p>
</div>
|
