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