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