2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/streams
6 @node Read and Print, Minibuffers, Debugging, Top
7 @comment node-name, next, previous, up
8 @chapter Reading and Printing Lisp Objects
10 @dfn{Printing} and @dfn{reading} are the operations of converting Lisp
11 objects to textual form and vice versa. They use the printed
12 representations and read syntax described in @ref{Lisp Data Types}.
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).
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.
28 @section Introduction to Reading and Printing
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.
40 @dfn{Printing} a Lisp object means producing text that represents that
41 object---converting the object to its @dfn{printed representation}
42 (@pxref{Printed Representation}). Printing the cons cell described
43 above produces the text @samp{(a .@: 5)}.
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
52 text produces a list (but not the same list) with elements @code{a}
55 However, these two operations are not precisely inverse to each other.
56 There are three kinds of exceptions:
60 Printing can produce text that cannot be read. For example, buffers,
61 windows, frames, subprocesses and markers print as text that starts
62 with @samp{#}; if you try to read this text, you get an error. There is
63 no way to read those data types.
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.
72 Comments can appear at certain points in the middle of an object's
73 read sequence without affecting the result of reading it.
77 @section Input Streams
78 @cindex stream (for reading)
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
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.
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.
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.
105 @cindex function input stream
106 The input characters are generated by @var{function}, which must support
111 When it is called with no arguments, it should return the next character.
114 When it is called with one argument (always a character), @var{function}
115 should save the argument and arrange to return it on the next call.
116 This is called @dfn{unreading} the character; it happens when the Lisp
117 reader reads one character too many and wants to ``put it back where it
118 came from''. In this case, it makes no difference what value
119 @var{function} returns.
123 @cindex @code{t} input stream
124 @code{t} used as a stream means that the input is read from the
125 minibuffer. In fact, the minibuffer is invoked once and the text
126 given by the user is made into a string that is then used as the
130 @cindex @code{nil} input stream
131 @code{nil} supplied as an input stream means to use the value of
132 @code{standard-input} instead; that value is the @dfn{default input
133 stream}, and must be a non-@code{nil} input stream.
136 A symbol as input stream is equivalent to the symbol's function
140 Here is an example of reading from a stream that is a buffer, showing
141 where point is located before and after:
145 ---------- Buffer: foo ----------
146 This@point{} is the contents of foo.
147 ---------- Buffer: foo ----------
151 (read (get-buffer "foo"))
155 (read (get-buffer "foo"))
160 ---------- Buffer: foo ----------
161 This is the@point{} contents of foo.
162 ---------- Buffer: foo ----------
167 Note that the first read skips a space. Reading skips any amount of
168 whitespace preceding the significant text.
170 Here is an example of reading from a stream that is a marker,
171 initially positioned at the beginning of the buffer shown. The value
172 read is the symbol @code{This}.
177 ---------- Buffer: foo ----------
178 This is the contents of foo.
179 ---------- Buffer: foo ----------
183 (setq m (set-marker (make-marker) 1 (get-buffer "foo")))
184 @result{} #<marker at 1 in foo>
192 @result{} #<marker at 5 in foo> ;; @r{Before the first space.}
196 Here we read from the contents of a string:
200 (read "(When in) the course")
205 The following example reads from the minibuffer. The
206 prompt is: @w{@samp{Lisp expression: }}. (That is always the prompt
207 used when you read from the stream @code{t}.) The user's input is shown
208 following the prompt.
214 ---------- Buffer: Minibuffer ----------
215 Lisp expression: @kbd{23 @key{RET}}
216 ---------- Buffer: Minibuffer ----------
220 Finally, here is an example of a stream that is a function, named
221 @code{useless-stream}. Before we use the stream, we initialize the
222 variable @code{useless-list} to a list of characters. Then each call to
223 the function @code{useless-stream} obtains the next character in the list
224 or unreads a character by adding it to the front of the list.
228 (setq useless-list (append "XY()" nil))
229 @result{} (88 89 40 41)
233 (defun useless-stream (&optional unread)
235 (setq useless-list (cons unread useless-list))
236 (prog1 (car useless-list)
237 (setq useless-list (cdr useless-list)))))
238 @result{} useless-stream
243 Now we read using the stream thus constructed:
247 (read 'useless-stream)
258 Note that the open and close parentheses remain in the list. The Lisp
259 reader encountered the open parenthesis, decided that it ended the
260 input, and unread it. Another attempt to read from the stream at this
261 point would read @samp{()} and return @code{nil}.
264 This function is used internally as an input stream to read from the
265 input file opened by the function @code{load}. Don't use this function
269 @node Input Functions
270 @section Input Functions
272 This section describes the Lisp functions and variables that pertain
275 In the functions below, @var{stream} stands for an input stream (see
276 the previous section). If @var{stream} is @code{nil} or omitted, it
277 defaults to the value of @code{standard-input}.
280 An @code{end-of-file} error is signaled if reading encounters an
281 unterminated list, vector, or string.
283 @defun read &optional stream
284 This function reads one textual Lisp expression from @var{stream},
285 returning it as a Lisp object. This is the basic Lisp input function.
288 @defun read-from-string string &optional start end
289 @cindex string to object
290 This function reads the first textual Lisp expression from the text in
291 @var{string}. It returns a cons cell whose @sc{car} is that expression,
292 and whose @sc{cdr} is an integer giving the position of the next
293 remaining character in the string (i.e., the first one not read).
295 If @var{start} is supplied, then reading begins at index @var{start} in
296 the string (where the first character is at index 0). If you specify
297 @var{end}, then reading is forced to stop just before that index, as if
298 the rest of the string were not there.
304 (read-from-string "(setq x 55) (setq y 5)")
305 @result{} ((setq x 55) . 11)
308 (read-from-string "\"A short string\"")
309 @result{} ("A short string" . 16)
313 ;; @r{Read starting at the first character.}
314 (read-from-string "(list 112)" 0)
315 @result{} ((list 112) . 10)
318 ;; @r{Read starting at the second character.}
319 (read-from-string "(list 112)" 1)
323 ;; @r{Read starting at the seventh character,}
324 ;; @r{and stopping at the ninth.}
325 (read-from-string "(list 112)" 6 8)
331 @defvar standard-input
332 This variable holds the default input stream---the stream that
333 @code{read} uses when the @var{stream} argument is @code{nil}.
337 @section Output Streams
338 @cindex stream (for printing)
339 @cindex output stream
341 An output stream specifies what to do with the characters produced
342 by printing. Most print functions accept an output stream as an
343 optional argument. Here are the possible types of output stream:
347 @cindex buffer output stream
348 The output characters are inserted into @var{buffer} at point.
349 Point advances as characters are inserted.
352 @cindex marker output stream
353 The output characters are inserted into the buffer that @var{marker}
354 points into, at the marker position. The marker position advances as
355 characters are inserted. The value of point in the buffer has no effect
356 on printing when the stream is a marker, and this kind of printing
360 @cindex function output stream
361 The output characters are passed to @var{function}, which is responsible
362 for storing them away. It is called with a single character as
363 argument, as many times as there are characters to be output, and
364 is responsible for storing the characters wherever you want to put them.
367 @cindex @code{t} output stream
368 The output characters are displayed in the echo area.
371 @cindex @code{nil} output stream
372 @code{nil} specified as an output stream means to use the value of
373 @code{standard-output} instead; that value is the @dfn{default output
374 stream}, and must not be @code{nil}.
377 A symbol as output stream is equivalent to the symbol's function
381 Many of the valid output streams are also valid as input streams. The
382 difference between input and output streams is therefore more a matter
383 of how you use a Lisp object, than of different types of object.
385 Here is an example of a buffer used as an output stream. Point is
386 initially located as shown immediately before the @samp{h} in
387 @samp{the}. At the end, point is located directly before that same
390 @cindex print example
393 ---------- Buffer: foo ----------
394 This is t@point{}he contents of foo.
395 ---------- Buffer: foo ----------
398 (print "This is the output" (get-buffer "foo"))
399 @result{} "This is the output"
402 ---------- Buffer: foo ----------
405 @point{}he contents of foo.
406 ---------- Buffer: foo ----------
410 Now we show a use of a marker as an output stream. Initially, the
411 marker is in buffer @code{foo}, between the @samp{t} and the @samp{h} in
412 the word @samp{the}. At the end, the marker has advanced over the
413 inserted text so that it remains positioned before the same @samp{h}.
414 Note that the location of point, shown in the usual fashion, has no
419 ---------- Buffer: foo ----------
420 This is the @point{}output
421 ---------- Buffer: foo ----------
425 (setq m (copy-marker 10))
426 @result{} #<marker at 10 in foo>
430 (print "More output for foo." m)
431 @result{} "More output for foo."
435 ---------- Buffer: foo ----------
437 "More output for foo."
439 ---------- Buffer: foo ----------
444 @result{} #<marker at 34 in foo>
448 The following example shows output to the echo area:
452 (print "Echo Area output" t)
453 @result{} "Echo Area output"
454 ---------- Echo Area ----------
456 ---------- Echo Area ----------
460 Finally, we show the use of a function as an output stream. The
461 function @code{eat-output} takes each character that it is given and
462 conses it onto the front of the list @code{last-output} (@pxref{Building
463 Lists}). At the end, the list contains all the characters output, but
468 (setq last-output nil)
473 (defun eat-output (c)
474 (setq last-output (cons c last-output)))
479 (print "This is the output" 'eat-output)
480 @result{} "This is the output"
485 @result{} (10 34 116 117 112 116 117 111 32 101 104
486 116 32 115 105 32 115 105 104 84 34 10)
491 Now we can put the output in the proper order by reversing the list:
495 (concat (nreverse last-output))
497 \"This is the output\"
503 Calling @code{concat} converts the list to a string so you can see its
504 contents more clearly.
506 @node Output Functions
507 @section Output Functions
509 This section describes the Lisp functions for printing Lisp
510 objects---converting objects into their printed representation.
512 @cindex @samp{"} in printing
513 @cindex @samp{\} in printing
514 @cindex quoting characters in printing
515 @cindex escape characters in printing
516 Some of the Emacs printing functions add quoting characters to the
517 output when necessary so that it can be read properly. The quoting
518 characters used are @samp{"} and @samp{\}; they distinguish strings from
519 symbols, and prevent punctuation characters in strings and symbols from
520 being taken as delimiters when reading. @xref{Printed Representation},
521 for full details. You specify quoting or no quoting by the choice of
524 If the text is to be read back into Lisp, then you should print with
525 quoting characters to avoid ambiguity. Likewise, if the purpose is to
526 describe a Lisp object clearly for a Lisp programmer. However, if the
527 purpose of the output is to look nice for humans, then it is usually
528 better to print without quoting.
530 Lisp objects can refer to themselves. Printing a self-referential
531 object in the normal way would require an infinite amount of text, and
532 the attempt could cause infinite recursion. Emacs detects such
533 recursion and prints @samp{#@var{level}} instead of recursively printing
534 an object already being printed. For example, here @samp{#0} indicates
535 a recursive reference to the object at level 0 of the current print
539 (setq foo (list nil))
545 In the functions below, @var{stream} stands for an output stream.
546 (See the previous section for a description of output streams.) If
547 @var{stream} is @code{nil} or omitted, it defaults to the value of
548 @code{standard-output}.
550 @defun print object &optional stream
552 The @code{print} function is a convenient way of printing. It outputs
553 the printed representation of @var{object} to @var{stream}, printing in
554 addition one newline before @var{object} and another after it. Quoting
555 characters are used. @code{print} returns @var{object}. For example:
559 (progn (print 'The\ cat\ in)
561 (print " came back"))
563 @print{} The\ cat\ in
567 @print{} " came back"
569 @result{} " came back"
574 @defun prin1 object &optional stream
575 This function outputs the printed representation of @var{object} to
576 @var{stream}. It does not print newlines to separate output as
577 @code{print} does, but it does use quoting characters just like
578 @code{print}. It returns @var{object}.
582 (progn (prin1 'The\ cat\ in)
584 (prin1 " came back"))
585 @print{} The\ cat\ in"the hat"" came back"
586 @result{} " came back"
591 @defun princ object &optional stream
592 This function outputs the printed representation of @var{object} to
593 @var{stream}. It returns @var{object}.
595 This function is intended to produce output that is readable by people,
596 not by @code{read}, so it doesn't insert quoting characters and doesn't
597 put double-quotes around the contents of strings. It does not add any
598 spacing between calls.
604 (princ " in the \"hat\""))
605 @print{} The cat in the "hat"
606 @result{} " in the \"hat\""
611 @defun terpri &optional stream
612 @cindex newline in print
613 This function outputs a newline to @var{stream}. The name stands
614 for ``terminate print''.
617 @defun write-char character &optional stream
618 This function outputs @var{character} to @var{stream}. It returns
622 @defun prin1-to-string object &optional noescape
623 @cindex object to string
624 This function returns a string containing the text that @code{prin1}
625 would have printed for the same argument.
629 (prin1-to-string 'foo)
633 (prin1-to-string (mark-marker))
634 @result{} "#<marker at 2773 in strings.texi>"
638 If @var{noescape} is non-@code{nil}, that inhibits use of quoting
639 characters in the output. (This argument is supported in Emacs versions
644 (prin1-to-string "foo")
648 (prin1-to-string "foo" t)
653 See @code{format}, in @ref{String Conversion}, for other ways to obtain
654 the printed representation of a Lisp object as a string.
657 @defmac with-output-to-string body...
658 @tindex with-output-to-string
659 This macro executes the @var{body} forms with @code{standard-output} set
660 up to feed output into a string. Then it returns that string.
662 For example, if the current buffer name is @samp{foo},
665 (with-output-to-string
666 (princ "The buffer is ")
667 (princ (buffer-name)))
671 returns @code{"The buffer is foo"}.
674 @node Output Variables
675 @section Variables Affecting Output
677 @defvar standard-output
678 The value of this variable is the default output stream---the stream
679 that print functions use when the @var{stream} argument is @code{nil}.
682 @defvar print-escape-newlines
683 @cindex @samp{\n} in print
684 @cindex escape characters
685 If this variable is non-@code{nil}, then newline characters in strings
686 are printed as @samp{\n} and formfeeds are printed as @samp{\f}.
687 Normally these characters are printed as actual newlines and formfeeds.
689 This variable affects the print functions @code{prin1} and @code{print}
690 that print with quoting. It does not affect @code{princ}. Here is an
691 example using @code{prin1}:
703 (let ((print-escape-newlines t))
712 In the second expression, the local binding of
713 @code{print-escape-newlines} is in effect during the call to
714 @code{prin1}, but not during the printing of the result.
717 @tindex print-escape-nonascii
718 @defvar print-escape-nonascii
719 If this variable is non-@code{nil}, then unibyte non-@sc{ascii}
720 characters in strings are unconditionally printed as backslash sequences
721 by the print functions @code{prin1} and @code{print} that print with
724 Those functions also use backslash sequences for unibyte non-@sc{ascii}
725 characters, regardless of the value of this variable, when the output
726 stream is a multibyte buffer or a marker pointing into one.
729 @tindex print-escape-multibyte
730 @defvar print-escape-multibyte
731 If this variable is non-@code{nil}, then multibyte non-@sc{ascii}
732 characters in strings are unconditionally printed as backslash sequences
733 by the print functions @code{prin1} and @code{print} that print with
736 Those functions also use backslash sequences for multibyte
737 non-@sc{ascii} characters, regardless of the value of this variable,
738 when the output stream is a unibyte buffer or a marker pointing into
743 @cindex printing limits
744 The value of this variable is the maximum number of elements to print in
745 any list, vector or bool-vector. If an object being printed has more
746 than this many elements, it is abbreviated with an ellipsis.
748 If the value is @code{nil} (the default), then there is no limit.
752 (setq print-length 2)
764 The value of this variable is the maximum depth of nesting of
765 parentheses and brackets when printed. Any list or vector at a depth
766 exceeding this limit is abbreviated with an ellipsis. A value of
767 @code{nil} (which is the default) means no limit.
770 These variables are used for detecting and reporting circular
771 and shared structure---but they are only defined in Emacs 21.
775 If non-@code{nil}, this variable enables detection of circular
776 and shared structure in printing.
781 If non-@code{nil}, this variable enables detection of uninterned symbols
782 (@pxref{Creating Symbols}) in printing. When this is enabled,
783 uninterned symbols print with the prefix @samp{#:}, which tells the Lisp
784 reader to produce an uninterned symbol.