Commit | Line | Data |
---|---|---|
5e8db0c6 RS |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Emacs Lisp Reference Manual. | |
fd897522 | 3 | @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999 |
177c0ea7 | 4 | @c Free Software Foundation, Inc. |
5e8db0c6 RS |
5 | @c See the file elisp.texi for copying conditions. |
6 | @setfilename ../info/streams | |
05fd2b65 | 7 | @node Read and Print, Minibuffers, Debugging, Top |
5e8db0c6 RS |
8 | @comment node-name, next, previous, up |
9 | @chapter Reading and Printing Lisp Objects | |
10 | ||
11 | @dfn{Printing} and @dfn{reading} are the operations of converting Lisp | |
12 | objects to textual form and vice versa. They use the printed | |
05fd2b65 | 13 | representations and read syntax described in @ref{Lisp Data Types}. |
5e8db0c6 RS |
14 | |
15 | This chapter describes the Lisp functions for reading and printing. | |
16 | It also describes @dfn{streams}, which specify where to get the text (if | |
17 | reading) or where to put it (if printing). | |
18 | ||
19 | @menu | |
20 | * Streams Intro:: Overview of streams, reading and printing. | |
21 | * Input Streams:: Various data types that can be used as input streams. | |
22 | * Input Functions:: Functions to read Lisp objects from text. | |
23 | * Output Streams:: Various data types that can be used as output streams. | |
24 | * Output Functions:: Functions to print Lisp objects as text. | |
25 | * Output Variables:: Variables that control what the printing functions do. | |
26 | @end menu | |
27 | ||
28 | @node Streams Intro | |
29 | @section Introduction to Reading and Printing | |
30 | @cindex Lisp reader | |
31 | @cindex printing | |
32 | @cindex reading | |
33 | ||
34 | @dfn{Reading} a Lisp object means parsing a Lisp expression in textual | |
35 | form and producing a corresponding Lisp object. This is how Lisp | |
36 | programs get into Lisp from files of Lisp code. We call the text the | |
37 | @dfn{read syntax} of the object. For example, the text @samp{(a .@: 5)} | |
38 | is the read syntax for a cons cell whose @sc{car} is @code{a} and whose | |
39 | @sc{cdr} is the number 5. | |
40 | ||
41 | @dfn{Printing} a Lisp object means producing text that represents that | |
f9f59935 RS |
42 | object---converting the object to its @dfn{printed representation} |
43 | (@pxref{Printed Representation}). Printing the cons cell described | |
44 | above produces the text @samp{(a .@: 5)}. | |
5e8db0c6 RS |
45 | |
46 | Reading and printing are more or less inverse operations: printing the | |
47 | object that results from reading a given piece of text often produces | |
48 | the same text, and reading the text that results from printing an object | |
49 | usually produces a similar-looking object. For example, printing the | |
50 | symbol @code{foo} produces the text @samp{foo}, and reading that text | |
51 | returns the symbol @code{foo}. Printing a list whose elements are | |
52 | @code{a} and @code{b} produces the text @samp{(a b)}, and reading that | |
b664e483 | 53 | text produces a list (but not the same list) with elements @code{a} |
5e8db0c6 RS |
54 | and @code{b}. |
55 | ||
a40d4712 PR |
56 | However, these two operations are not precisely inverse to each other. |
57 | There are three kinds of exceptions: | |
5e8db0c6 RS |
58 | |
59 | @itemize @bullet | |
60 | @item | |
61 | Printing can produce text that cannot be read. For example, buffers, | |
f9f59935 | 62 | windows, frames, subprocesses and markers print as text that starts |
5e8db0c6 RS |
63 | with @samp{#}; if you try to read this text, you get an error. There is |
64 | no way to read those data types. | |
65 | ||
66 | @item | |
67 | One object can have multiple textual representations. For example, | |
68 | @samp{1} and @samp{01} represent the same integer, and @samp{(a b)} and | |
69 | @samp{(a .@: (b))} represent the same list. Reading will accept any of | |
70 | the alternatives, but printing must choose one of them. | |
bfe721d1 KH |
71 | |
72 | @item | |
73 | Comments can appear at certain points in the middle of an object's | |
74 | read sequence without affecting the result of reading it. | |
5e8db0c6 RS |
75 | @end itemize |
76 | ||
77 | @node Input Streams | |
78 | @section Input Streams | |
79 | @cindex stream (for reading) | |
80 | @cindex input stream | |
81 | ||
82 | Most of the Lisp functions for reading text take an @dfn{input stream} | |
83 | as an argument. The input stream specifies where or how to get the | |
84 | characters of the text to be read. Here are the possible types of input | |
85 | stream: | |
86 | ||
87 | @table @asis | |
88 | @item @var{buffer} | |
89 | @cindex buffer input stream | |
90 | The input characters are read from @var{buffer}, starting with the | |
91 | character directly after point. Point advances as characters are read. | |
92 | ||
93 | @item @var{marker} | |
94 | @cindex marker input stream | |
95 | The input characters are read from the buffer that @var{marker} is in, | |
96 | starting with the character directly after the marker. The marker | |
97 | position advances as characters are read. The value of point in the | |
98 | buffer has no effect when the stream is a marker. | |
99 | ||
100 | @item @var{string} | |
101 | @cindex string input stream | |
102 | The input characters are taken from @var{string}, starting at the first | |
103 | character in the string and using as many characters as required. | |
104 | ||
105 | @item @var{function} | |
106 | @cindex function input stream | |
969fe9b5 RS |
107 | The input characters are generated by @var{function}, which must support |
108 | two kinds of calls: | |
109 | ||
110 | @itemize @bullet | |
111 | @item | |
112 | When it is called with no arguments, it should return the next character. | |
113 | ||
114 | @item | |
115 | When it is called with one argument (always a character), @var{function} | |
116 | should save the argument and arrange to return it on the next call. | |
117 | This is called @dfn{unreading} the character; it happens when the Lisp | |
118 | reader reads one character too many and wants to ``put it back where it | |
119 | came from''. In this case, it makes no difference what value | |
120 | @var{function} returns. | |
121 | @end itemize | |
5e8db0c6 RS |
122 | |
123 | @item @code{t} | |
124 | @cindex @code{t} input stream | |
125 | @code{t} used as a stream means that the input is read from the | |
126 | minibuffer. In fact, the minibuffer is invoked once and the text | |
127 | given by the user is made into a string that is then used as the | |
e2b1c016 DL |
128 | input stream. If Emacs is running in batch mode, standard input is used |
129 | instead of the minibuffer. For example, | |
130 | @example | |
131 | (message "%s" (read t)) | |
132 | @end example | |
133 | will read a Lisp expression from standard input and print the result | |
134 | to standard output. | |
5e8db0c6 RS |
135 | |
136 | @item @code{nil} | |
137 | @cindex @code{nil} input stream | |
138 | @code{nil} supplied as an input stream means to use the value of | |
139 | @code{standard-input} instead; that value is the @dfn{default input | |
140 | stream}, and must be a non-@code{nil} input stream. | |
141 | ||
142 | @item @var{symbol} | |
143 | A symbol as input stream is equivalent to the symbol's function | |
144 | definition (if any). | |
145 | @end table | |
146 | ||
b664e483 | 147 | Here is an example of reading from a stream that is a buffer, showing |
5e8db0c6 RS |
148 | where point is located before and after: |
149 | ||
150 | @example | |
151 | @group | |
152 | ---------- Buffer: foo ---------- | |
153 | This@point{} is the contents of foo. | |
154 | ---------- Buffer: foo ---------- | |
155 | @end group | |
156 | ||
157 | @group | |
158 | (read (get-buffer "foo")) | |
159 | @result{} is | |
160 | @end group | |
161 | @group | |
162 | (read (get-buffer "foo")) | |
163 | @result{} the | |
164 | @end group | |
165 | ||
166 | @group | |
167 | ---------- Buffer: foo ---------- | |
168 | This is the@point{} contents of foo. | |
169 | ---------- Buffer: foo ---------- | |
170 | @end group | |
171 | @end example | |
172 | ||
173 | @noindent | |
b664e483 RS |
174 | Note that the first read skips a space. Reading skips any amount of |
175 | whitespace preceding the significant text. | |
5e8db0c6 | 176 | |
5e8db0c6 | 177 | Here is an example of reading from a stream that is a marker, |
b664e483 | 178 | initially positioned at the beginning of the buffer shown. The value |
5e8db0c6 RS |
179 | read is the symbol @code{This}. |
180 | ||
181 | @example | |
182 | @group | |
183 | ||
184 | ---------- Buffer: foo ---------- | |
185 | This is the contents of foo. | |
186 | ---------- Buffer: foo ---------- | |
187 | @end group | |
188 | ||
189 | @group | |
190 | (setq m (set-marker (make-marker) 1 (get-buffer "foo"))) | |
191 | @result{} #<marker at 1 in foo> | |
192 | @end group | |
193 | @group | |
194 | (read m) | |
195 | @result{} This | |
196 | @end group | |
197 | @group | |
198 | m | |
b664e483 | 199 | @result{} #<marker at 5 in foo> ;; @r{Before the first space.} |
5e8db0c6 RS |
200 | @end group |
201 | @end example | |
202 | ||
203 | Here we read from the contents of a string: | |
204 | ||
205 | @example | |
206 | @group | |
207 | (read "(When in) the course") | |
208 | @result{} (When in) | |
209 | @end group | |
210 | @end example | |
211 | ||
212 | The following example reads from the minibuffer. The | |
213 | prompt is: @w{@samp{Lisp expression: }}. (That is always the prompt | |
214 | used when you read from the stream @code{t}.) The user's input is shown | |
215 | following the prompt. | |
216 | ||
217 | @example | |
218 | @group | |
219 | (read t) | |
220 | @result{} 23 | |
221 | ---------- Buffer: Minibuffer ---------- | |
222 | Lisp expression: @kbd{23 @key{RET}} | |
223 | ---------- Buffer: Minibuffer ---------- | |
224 | @end group | |
225 | @end example | |
226 | ||
227 | Finally, here is an example of a stream that is a function, named | |
228 | @code{useless-stream}. Before we use the stream, we initialize the | |
229 | variable @code{useless-list} to a list of characters. Then each call to | |
b664e483 | 230 | the function @code{useless-stream} obtains the next character in the list |
5e8db0c6 RS |
231 | or unreads a character by adding it to the front of the list. |
232 | ||
233 | @example | |
234 | @group | |
235 | (setq useless-list (append "XY()" nil)) | |
236 | @result{} (88 89 40 41) | |
237 | @end group | |
238 | ||
239 | @group | |
240 | (defun useless-stream (&optional unread) | |
241 | (if unread | |
242 | (setq useless-list (cons unread useless-list)) | |
243 | (prog1 (car useless-list) | |
244 | (setq useless-list (cdr useless-list))))) | |
245 | @result{} useless-stream | |
246 | @end group | |
247 | @end example | |
248 | ||
249 | @noindent | |
250 | Now we read using the stream thus constructed: | |
251 | ||
252 | @example | |
253 | @group | |
254 | (read 'useless-stream) | |
255 | @result{} XY | |
256 | @end group | |
257 | ||
258 | @group | |
259 | useless-list | |
b664e483 | 260 | @result{} (40 41) |
5e8db0c6 RS |
261 | @end group |
262 | @end example | |
263 | ||
264 | @noindent | |
a9f0a989 | 265 | Note that the open and close parentheses remain in the list. The Lisp |
b664e483 RS |
266 | reader encountered the open parenthesis, decided that it ended the |
267 | input, and unread it. Another attempt to read from the stream at this | |
268 | point would read @samp{()} and return @code{nil}. | |
5e8db0c6 RS |
269 | |
270 | @defun get-file-char | |
271 | This function is used internally as an input stream to read from the | |
272 | input file opened by the function @code{load}. Don't use this function | |
273 | yourself. | |
274 | @end defun | |
275 | ||
276 | @node Input Functions | |
277 | @section Input Functions | |
278 | ||
279 | This section describes the Lisp functions and variables that pertain | |
280 | to reading. | |
281 | ||
282 | In the functions below, @var{stream} stands for an input stream (see | |
283 | the previous section). If @var{stream} is @code{nil} or omitted, it | |
284 | defaults to the value of @code{standard-input}. | |
285 | ||
286 | @kindex end-of-file | |
287 | An @code{end-of-file} error is signaled if reading encounters an | |
b664e483 | 288 | unterminated list, vector, or string. |
5e8db0c6 RS |
289 | |
290 | @defun read &optional stream | |
291 | This function reads one textual Lisp expression from @var{stream}, | |
292 | returning it as a Lisp object. This is the basic Lisp input function. | |
293 | @end defun | |
294 | ||
295 | @defun read-from-string string &optional start end | |
296 | @cindex string to object | |
297 | This function reads the first textual Lisp expression from the text in | |
298 | @var{string}. It returns a cons cell whose @sc{car} is that expression, | |
299 | and whose @sc{cdr} is an integer giving the position of the next | |
300 | remaining character in the string (i.e., the first one not read). | |
301 | ||
b664e483 | 302 | If @var{start} is supplied, then reading begins at index @var{start} in |
969fe9b5 RS |
303 | the string (where the first character is at index 0). If you specify |
304 | @var{end}, then reading is forced to stop just before that index, as if | |
305 | the rest of the string were not there. | |
5e8db0c6 RS |
306 | |
307 | For example: | |
308 | ||
309 | @example | |
310 | @group | |
311 | (read-from-string "(setq x 55) (setq y 5)") | |
312 | @result{} ((setq x 55) . 11) | |
313 | @end group | |
314 | @group | |
315 | (read-from-string "\"A short string\"") | |
316 | @result{} ("A short string" . 16) | |
317 | @end group | |
318 | ||
319 | @group | |
320 | ;; @r{Read starting at the first character.} | |
321 | (read-from-string "(list 112)" 0) | |
322 | @result{} ((list 112) . 10) | |
323 | @end group | |
324 | @group | |
325 | ;; @r{Read starting at the second character.} | |
326 | (read-from-string "(list 112)" 1) | |
b664e483 | 327 | @result{} (list . 5) |
5e8db0c6 RS |
328 | @end group |
329 | @group | |
330 | ;; @r{Read starting at the seventh character,} | |
331 | ;; @r{and stopping at the ninth.} | |
332 | (read-from-string "(list 112)" 6 8) | |
333 | @result{} (11 . 8) | |
334 | @end group | |
335 | @end example | |
336 | @end defun | |
337 | ||
338 | @defvar standard-input | |
339 | This variable holds the default input stream---the stream that | |
340 | @code{read} uses when the @var{stream} argument is @code{nil}. | |
53325195 | 341 | The default is @code{t}, meaning use the minibuffer. |
5e8db0c6 RS |
342 | @end defvar |
343 | ||
344 | @node Output Streams | |
345 | @section Output Streams | |
346 | @cindex stream (for printing) | |
347 | @cindex output stream | |
348 | ||
349 | An output stream specifies what to do with the characters produced | |
350 | by printing. Most print functions accept an output stream as an | |
351 | optional argument. Here are the possible types of output stream: | |
352 | ||
353 | @table @asis | |
354 | @item @var{buffer} | |
355 | @cindex buffer output stream | |
356 | The output characters are inserted into @var{buffer} at point. | |
357 | Point advances as characters are inserted. | |
358 | ||
359 | @item @var{marker} | |
360 | @cindex marker output stream | |
361 | The output characters are inserted into the buffer that @var{marker} | |
b664e483 | 362 | points into, at the marker position. The marker position advances as |
5e8db0c6 | 363 | characters are inserted. The value of point in the buffer has no effect |
a9f0a989 | 364 | on printing when the stream is a marker, and this kind of printing |
9f6a7e77 LT |
365 | does not move point (except that if the marker points at or before the |
366 | position of point, point advances with the surrounding text, as | |
367 | usual). | |
5e8db0c6 RS |
368 | |
369 | @item @var{function} | |
370 | @cindex function output stream | |
371 | The output characters are passed to @var{function}, which is responsible | |
372 | for storing them away. It is called with a single character as | |
a9f0a989 RS |
373 | argument, as many times as there are characters to be output, and |
374 | is responsible for storing the characters wherever you want to put them. | |
5e8db0c6 RS |
375 | |
376 | @item @code{t} | |
377 | @cindex @code{t} output stream | |
378 | The output characters are displayed in the echo area. | |
379 | ||
380 | @item @code{nil} | |
381 | @cindex @code{nil} output stream | |
a9f0a989 | 382 | @code{nil} specified as an output stream means to use the value of |
5e8db0c6 | 383 | @code{standard-output} instead; that value is the @dfn{default output |
a9f0a989 | 384 | stream}, and must not be @code{nil}. |
5e8db0c6 RS |
385 | |
386 | @item @var{symbol} | |
387 | A symbol as output stream is equivalent to the symbol's function | |
388 | definition (if any). | |
389 | @end table | |
390 | ||
b664e483 | 391 | Many of the valid output streams are also valid as input streams. The |
969fe9b5 RS |
392 | difference between input and output streams is therefore more a matter |
393 | of how you use a Lisp object, than of different types of object. | |
b664e483 | 394 | |
5e8db0c6 RS |
395 | Here is an example of a buffer used as an output stream. Point is |
396 | initially located as shown immediately before the @samp{h} in | |
397 | @samp{the}. At the end, point is located directly before that same | |
398 | @samp{h}. | |
399 | ||
400 | @cindex print example | |
401 | @example | |
402 | @group | |
403 | ---------- Buffer: foo ---------- | |
404 | This is t@point{}he contents of foo. | |
405 | ---------- Buffer: foo ---------- | |
406 | @end group | |
407 | ||
408 | (print "This is the output" (get-buffer "foo")) | |
409 | @result{} "This is the output" | |
410 | ||
411 | @group | |
412 | ---------- Buffer: foo ---------- | |
413 | This is t | |
414 | "This is the output" | |
415 | @point{}he contents of foo. | |
416 | ---------- Buffer: foo ---------- | |
417 | @end group | |
418 | @end example | |
419 | ||
420 | Now we show a use of a marker as an output stream. Initially, the | |
b664e483 RS |
421 | marker is in buffer @code{foo}, between the @samp{t} and the @samp{h} in |
422 | the word @samp{the}. At the end, the marker has advanced over the | |
423 | inserted text so that it remains positioned before the same @samp{h}. | |
424 | Note that the location of point, shown in the usual fashion, has no | |
425 | effect. | |
5e8db0c6 RS |
426 | |
427 | @example | |
428 | @group | |
429 | ---------- Buffer: foo ---------- | |
a9f0a989 | 430 | This is the @point{}output |
5e8db0c6 RS |
431 | ---------- Buffer: foo ---------- |
432 | @end group | |
433 | ||
434 | @group | |
1911e6e5 RS |
435 | (setq m (copy-marker 10)) |
436 | @result{} #<marker at 10 in foo> | |
5e8db0c6 RS |
437 | @end group |
438 | ||
439 | @group | |
440 | (print "More output for foo." m) | |
441 | @result{} "More output for foo." | |
442 | @end group | |
443 | ||
444 | @group | |
445 | ---------- Buffer: foo ---------- | |
a9f0a989 | 446 | This is t |
5e8db0c6 | 447 | "More output for foo." |
a9f0a989 | 448 | he @point{}output |
5e8db0c6 RS |
449 | ---------- Buffer: foo ---------- |
450 | @end group | |
451 | ||
452 | @group | |
453 | m | |
1911e6e5 | 454 | @result{} #<marker at 34 in foo> |
5e8db0c6 RS |
455 | @end group |
456 | @end example | |
457 | ||
458 | The following example shows output to the echo area: | |
459 | ||
460 | @example | |
461 | @group | |
462 | (print "Echo Area output" t) | |
463 | @result{} "Echo Area output" | |
464 | ---------- Echo Area ---------- | |
465 | "Echo Area output" | |
466 | ---------- Echo Area ---------- | |
467 | @end group | |
468 | @end example | |
469 | ||
470 | Finally, we show the use of a function as an output stream. The | |
471 | function @code{eat-output} takes each character that it is given and | |
472 | conses it onto the front of the list @code{last-output} (@pxref{Building | |
473 | Lists}). At the end, the list contains all the characters output, but | |
474 | in reverse order. | |
475 | ||
476 | @example | |
477 | @group | |
478 | (setq last-output nil) | |
479 | @result{} nil | |
480 | @end group | |
481 | ||
482 | @group | |
483 | (defun eat-output (c) | |
484 | (setq last-output (cons c last-output))) | |
485 | @result{} eat-output | |
486 | @end group | |
487 | ||
488 | @group | |
489 | (print "This is the output" 'eat-output) | |
490 | @result{} "This is the output" | |
491 | @end group | |
492 | ||
493 | @group | |
494 | last-output | |
177c0ea7 | 495 | @result{} (10 34 116 117 112 116 117 111 32 101 104 |
5e8db0c6 RS |
496 | 116 32 115 105 32 115 105 104 84 34 10) |
497 | @end group | |
498 | @end example | |
499 | ||
500 | @noindent | |
501 | Now we can put the output in the proper order by reversing the list: | |
502 | ||
503 | @example | |
504 | @group | |
505 | (concat (nreverse last-output)) | |
506 | @result{} " | |
507 | \"This is the output\" | |
508 | " | |
509 | @end group | |
510 | @end example | |
511 | ||
b664e483 RS |
512 | @noindent |
513 | Calling @code{concat} converts the list to a string so you can see its | |
514 | contents more clearly. | |
515 | ||
5e8db0c6 RS |
516 | @node Output Functions |
517 | @section Output Functions | |
518 | ||
f9f59935 RS |
519 | This section describes the Lisp functions for printing Lisp |
520 | objects---converting objects into their printed representation. | |
5e8db0c6 RS |
521 | |
522 | @cindex @samp{"} in printing | |
523 | @cindex @samp{\} in printing | |
524 | @cindex quoting characters in printing | |
525 | @cindex escape characters in printing | |
526 | Some of the Emacs printing functions add quoting characters to the | |
527 | output when necessary so that it can be read properly. The quoting | |
528 | characters used are @samp{"} and @samp{\}; they distinguish strings from | |
529 | symbols, and prevent punctuation characters in strings and symbols from | |
b664e483 RS |
530 | being taken as delimiters when reading. @xref{Printed Representation}, |
531 | for full details. You specify quoting or no quoting by the choice of | |
532 | printing function. | |
5e8db0c6 | 533 | |
969fe9b5 RS |
534 | If the text is to be read back into Lisp, then you should print with |
535 | quoting characters to avoid ambiguity. Likewise, if the purpose is to | |
536 | describe a Lisp object clearly for a Lisp programmer. However, if the | |
537 | purpose of the output is to look nice for humans, then it is usually | |
538 | better to print without quoting. | |
5e8db0c6 | 539 | |
a9f0a989 RS |
540 | Lisp objects can refer to themselves. Printing a self-referential |
541 | object in the normal way would require an infinite amount of text, and | |
542 | the attempt could cause infinite recursion. Emacs detects such | |
543 | recursion and prints @samp{#@var{level}} instead of recursively printing | |
544 | an object already being printed. For example, here @samp{#0} indicates | |
545 | a recursive reference to the object at level 0 of the current print | |
546 | operation: | |
5e8db0c6 RS |
547 | |
548 | @example | |
549 | (setq foo (list nil)) | |
550 | @result{} (nil) | |
551 | (setcar foo foo) | |
552 | @result{} (#0) | |
553 | @end example | |
554 | ||
555 | In the functions below, @var{stream} stands for an output stream. | |
556 | (See the previous section for a description of output streams.) If | |
557 | @var{stream} is @code{nil} or omitted, it defaults to the value of | |
558 | @code{standard-output}. | |
559 | ||
560 | @defun print object &optional stream | |
561 | @cindex Lisp printer | |
562 | The @code{print} function is a convenient way of printing. It outputs | |
563 | the printed representation of @var{object} to @var{stream}, printing in | |
564 | addition one newline before @var{object} and another after it. Quoting | |
565 | characters are used. @code{print} returns @var{object}. For example: | |
566 | ||
567 | @example | |
568 | @group | |
569 | (progn (print 'The\ cat\ in) | |
570 | (print "the hat") | |
571 | (print " came back")) | |
177c0ea7 | 572 | @print{} |
5e8db0c6 | 573 | @print{} The\ cat\ in |
177c0ea7 | 574 | @print{} |
5e8db0c6 | 575 | @print{} "the hat" |
177c0ea7 | 576 | @print{} |
5e8db0c6 | 577 | @print{} " came back" |
5e8db0c6 RS |
578 | @result{} " came back" |
579 | @end group | |
580 | @end example | |
581 | @end defun | |
582 | ||
583 | @defun prin1 object &optional stream | |
584 | This function outputs the printed representation of @var{object} to | |
b664e483 RS |
585 | @var{stream}. It does not print newlines to separate output as |
586 | @code{print} does, but it does use quoting characters just like | |
587 | @code{print}. It returns @var{object}. | |
5e8db0c6 RS |
588 | |
589 | @example | |
590 | @group | |
177c0ea7 JB |
591 | (progn (prin1 'The\ cat\ in) |
592 | (prin1 "the hat") | |
5e8db0c6 RS |
593 | (prin1 " came back")) |
594 | @print{} The\ cat\ in"the hat"" came back" | |
595 | @result{} " came back" | |
596 | @end group | |
597 | @end example | |
598 | @end defun | |
599 | ||
600 | @defun princ object &optional stream | |
601 | This function outputs the printed representation of @var{object} to | |
602 | @var{stream}. It returns @var{object}. | |
603 | ||
604 | This function is intended to produce output that is readable by people, | |
605 | not by @code{read}, so it doesn't insert quoting characters and doesn't | |
606 | put double-quotes around the contents of strings. It does not add any | |
607 | spacing between calls. | |
608 | ||
609 | @example | |
610 | @group | |
611 | (progn | |
612 | (princ 'The\ cat) | |
613 | (princ " in the \"hat\"")) | |
614 | @print{} The cat in the "hat" | |
615 | @result{} " in the \"hat\"" | |
616 | @end group | |
617 | @end example | |
618 | @end defun | |
619 | ||
620 | @defun terpri &optional stream | |
621 | @cindex newline in print | |
622 | This function outputs a newline to @var{stream}. The name stands | |
623 | for ``terminate print''. | |
624 | @end defun | |
625 | ||
626 | @defun write-char character &optional stream | |
627 | This function outputs @var{character} to @var{stream}. It returns | |
628 | @var{character}. | |
629 | @end defun | |
630 | ||
631 | @defun prin1-to-string object &optional noescape | |
632 | @cindex object to string | |
633 | This function returns a string containing the text that @code{prin1} | |
634 | would have printed for the same argument. | |
635 | ||
636 | @example | |
637 | @group | |
638 | (prin1-to-string 'foo) | |
639 | @result{} "foo" | |
640 | @end group | |
641 | @group | |
642 | (prin1-to-string (mark-marker)) | |
643 | @result{} "#<marker at 2773 in strings.texi>" | |
644 | @end group | |
645 | @end example | |
646 | ||
647 | If @var{noescape} is non-@code{nil}, that inhibits use of quoting | |
648 | characters in the output. (This argument is supported in Emacs versions | |
649 | 19 and later.) | |
650 | ||
651 | @example | |
652 | @group | |
653 | (prin1-to-string "foo") | |
654 | @result{} "\"foo\"" | |
655 | @end group | |
656 | @group | |
657 | (prin1-to-string "foo" t) | |
658 | @result{} "foo" | |
659 | @end group | |
660 | @end example | |
661 | ||
662 | See @code{format}, in @ref{String Conversion}, for other ways to obtain | |
663 | the printed representation of a Lisp object as a string. | |
664 | @end defun | |
665 | ||
f9f59935 | 666 | @defmac with-output-to-string body... |
a9f0a989 RS |
667 | This macro executes the @var{body} forms with @code{standard-output} set |
668 | up to feed output into a string. Then it returns that string. | |
f9f59935 RS |
669 | |
670 | For example, if the current buffer name is @samp{foo}, | |
671 | ||
672 | @example | |
673 | (with-output-to-string | |
674 | (princ "The buffer is ") | |
675 | (princ (buffer-name))) | |
676 | @end example | |
677 | ||
678 | @noindent | |
679 | returns @code{"The buffer is foo"}. | |
680 | @end defmac | |
681 | ||
5e8db0c6 RS |
682 | @node Output Variables |
683 | @section Variables Affecting Output | |
684 | ||
685 | @defvar standard-output | |
686 | The value of this variable is the default output stream---the stream | |
687 | that print functions use when the @var{stream} argument is @code{nil}. | |
53325195 | 688 | The default is @code{t}, meaning display in the echo area. |
5e8db0c6 RS |
689 | @end defvar |
690 | ||
0fa0135a RS |
691 | @defvar print-quoted |
692 | If this is non-@code{nil}, that means to print quoted forms using | |
693 | abbreviated reader syntax. @code{(quote foo)} prints as @code{'foo}, | |
694 | @code{(function foo)} as @code{#'foo}, and backquoted forms print | |
695 | using modern backquote syntax. | |
696 | @end defvar | |
697 | ||
5e8db0c6 RS |
698 | @defvar print-escape-newlines |
699 | @cindex @samp{\n} in print | |
700 | @cindex escape characters | |
701 | If this variable is non-@code{nil}, then newline characters in strings | |
702 | are printed as @samp{\n} and formfeeds are printed as @samp{\f}. | |
703 | Normally these characters are printed as actual newlines and formfeeds. | |
704 | ||
969fe9b5 RS |
705 | This variable affects the print functions @code{prin1} and @code{print} |
706 | that print with quoting. It does not affect @code{princ}. Here is an | |
707 | example using @code{prin1}: | |
5e8db0c6 RS |
708 | |
709 | @example | |
710 | @group | |
711 | (prin1 "a\nb") | |
712 | @print{} "a | |
713 | @print{} b" | |
714 | @result{} "a | |
715 | b" | |
716 | @end group | |
717 | ||
718 | @group | |
719 | (let ((print-escape-newlines t)) | |
720 | (prin1 "a\nb")) | |
721 | @print{} "a\nb" | |
722 | @result{} "a | |
723 | b" | |
724 | @end group | |
725 | @end example | |
726 | ||
727 | @noindent | |
728 | In the second expression, the local binding of | |
729 | @code{print-escape-newlines} is in effect during the call to | |
730 | @code{prin1}, but not during the printing of the result. | |
731 | @end defvar | |
732 | ||
1911e6e5 | 733 | @defvar print-escape-nonascii |
ad800164 | 734 | If this variable is non-@code{nil}, then unibyte non-@acronym{ASCII} |
1911e6e5 RS |
735 | characters in strings are unconditionally printed as backslash sequences |
736 | by the print functions @code{prin1} and @code{print} that print with | |
737 | quoting. | |
5074194e | 738 | |
ad800164 | 739 | Those functions also use backslash sequences for unibyte non-@acronym{ASCII} |
5074194e RS |
740 | characters, regardless of the value of this variable, when the output |
741 | stream is a multibyte buffer or a marker pointing into one. | |
742 | @end defvar | |
743 | ||
5074194e | 744 | @defvar print-escape-multibyte |
ad800164 | 745 | If this variable is non-@code{nil}, then multibyte non-@acronym{ASCII} |
5074194e RS |
746 | characters in strings are unconditionally printed as backslash sequences |
747 | by the print functions @code{prin1} and @code{print} that print with | |
748 | quoting. | |
749 | ||
750 | Those functions also use backslash sequences for multibyte | |
ad800164 | 751 | non-@acronym{ASCII} characters, regardless of the value of this variable, |
5074194e RS |
752 | when the output stream is a unibyte buffer or a marker pointing into |
753 | one. | |
1911e6e5 RS |
754 | @end defvar |
755 | ||
5e8db0c6 RS |
756 | @defvar print-length |
757 | @cindex printing limits | |
f9f59935 RS |
758 | The value of this variable is the maximum number of elements to print in |
759 | any list, vector or bool-vector. If an object being printed has more | |
760 | than this many elements, it is abbreviated with an ellipsis. | |
5e8db0c6 RS |
761 | |
762 | If the value is @code{nil} (the default), then there is no limit. | |
763 | ||
764 | @example | |
765 | @group | |
766 | (setq print-length 2) | |
767 | @result{} 2 | |
768 | @end group | |
769 | @group | |
770 | (print '(1 2 3 4 5)) | |
771 | @print{} (1 2 ...) | |
772 | @result{} (1 2 ...) | |
773 | @end group | |
774 | @end example | |
775 | @end defvar | |
776 | ||
777 | @defvar print-level | |
778 | The value of this variable is the maximum depth of nesting of | |
b664e483 | 779 | parentheses and brackets when printed. Any list or vector at a depth |
5e8db0c6 RS |
780 | exceeding this limit is abbreviated with an ellipsis. A value of |
781 | @code{nil} (which is the default) means no limit. | |
5e8db0c6 | 782 | @end defvar |
8241495d | 783 | |
2683ea73 RS |
784 | @defopt eval-expression-print-length |
785 | @defoptx eval-expression-print-level | |
786 | These are the values for @code{print-length} and @code{print-level} | |
787 | used by @code{eval-expression}, and thus, indirectly, by many | |
788 | interactive evaluation commands (@pxref{Lisp Eval,, Evaluating | |
789 | Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}). | |
790 | @end defopt | |
791 | ||
177c0ea7 | 792 | These variables are used for detecting and reporting circular |
b5881fef | 793 | and shared structure: |
8241495d RS |
794 | |
795 | @tindex print-circle | |
796 | @defvar print-circle | |
177c0ea7 | 797 | If non-@code{nil}, this variable enables detection of circular |
8241495d RS |
798 | and shared structure in printing. |
799 | @end defvar | |
800 | ||
801 | @tindex print-gensym | |
802 | @defvar print-gensym | |
803 | If non-@code{nil}, this variable enables detection of uninterned symbols | |
804 | (@pxref{Creating Symbols}) in printing. When this is enabled, | |
805 | uninterned symbols print with the prefix @samp{#:}, which tells the Lisp | |
806 | reader to produce an uninterned symbol. | |
807 | @end defvar | |
58c96291 RS |
808 | |
809 | @defvar print-continuous-numbering | |
810 | If non-@code{nil}, that means number continuously across print calls. | |
811 | This affects the numbers printed for @samp{#@var{n}=} labels and | |
812 | @samp{#@var{m}#} references. | |
813 | ||
814 | Don't set this variable with @code{setq}; you should only bind it | |
815 | temporarily to @code{t} with @code{let}. When you do that, you should | |
816 | also bind @code{print-number-table} to @code{nil}. | |
817 | @end defvar | |
818 | ||
819 | @defvar print-number-table | |
820 | This variable holds a vector used internally by printing to implement | |
821 | the @code{print-circle} feature. You should not use it except | |
822 | to bind it to @code{nil} when you bind @code{print-continuous-numbering}. | |
823 | @end defvar | |
ab5796a9 | 824 | |
70fc62f1 RS |
825 | @defvar float-output-format |
826 | This variable specifies how to print floating point numbers. Its | |
827 | default value is @code{nil}, meaning use the shortest output | |
828 | that represents the number without losing information. | |
829 | ||
830 | To control output format more precisely, you can put a string in this | |
831 | variable. The string should hold a @samp{%}-specification to be used | |
832 | in the C function @code{sprintf}. For further restrictions on what | |
833 | you can use, see the variable's documentation string. | |
834 | @end defvar | |
835 | ||
ab5796a9 MB |
836 | @ignore |
837 | arch-tag: 07636b8c-c4e3-4735-9e06-2e864320b434 | |
838 | @end ignore |