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 inverses. There are
56 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}, one character per
107 call. Normally @var{function} is called with no arguments, and should
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''.
116 In this case, it makes no difference what value @var{function} returns.
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
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.
132 A symbol as input stream is equivalent to the symbol's function
136 Here is an example of reading from a stream that is a buffer, showing
137 where point is located before and after:
141 ---------- Buffer: foo ----------
142 This@point{} is the contents of foo.
143 ---------- Buffer: foo ----------
147 (read (get-buffer "foo"))
151 (read (get-buffer "foo"))
156 ---------- Buffer: foo ----------
157 This is the@point{} contents of foo.
158 ---------- Buffer: foo ----------
163 Note that the first read skips a space. Reading skips any amount of
164 whitespace preceding the significant text.
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}
168 rather than after @samp{the}. The current behavior is superior because
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
173 Here is an example of reading from a stream that is a marker,
174 initially positioned at the beginning of the buffer shown. The value
175 read is the symbol @code{This}.
180 ---------- Buffer: foo ----------
181 This is the contents of foo.
182 ---------- Buffer: foo ----------
186 (setq m (set-marker (make-marker) 1 (get-buffer "foo")))
187 @result{} #<marker at 1 in foo>
195 @result{} #<marker at 5 in foo> ;; @r{Before the first space.}
199 Here we read from the contents of a string:
203 (read "(When in) the course")
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.
217 ---------- Buffer: Minibuffer ----------
218 Lisp expression: @kbd{23 @key{RET}}
219 ---------- Buffer: Minibuffer ----------
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
226 the function @code{useless-stream} obtains the next character in the list
227 or unreads a character by adding it to the front of the list.
231 (setq useless-list (append "XY()" nil))
232 @result{} (88 89 40 41)
236 (defun useless-stream (&optional 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
246 Now we read using the stream thus constructed:
250 (read 'useless-stream)
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}.
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
272 @node Input Functions
273 @section Input Functions
275 This section describes the Lisp functions and variables that pertain
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}.
283 An @code{end-of-file} error is signaled if reading encounters an
284 unterminated list, vector, or string.
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.
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).
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.
307 (read-from-string "(setq x 55) (setq y 5)")
308 @result{} ((setq x 55) . 11)
311 (read-from-string "\"A short string\"")
312 @result{} ("A short string" . 16)
316 ;; @r{Read starting at the first character.}
317 (read-from-string "(list 112)" 0)
318 @result{} ((list 112) . 10)
321 ;; @r{Read starting at the second character.}
322 (read-from-string "(list 112)" 1)
326 ;; @r{Read starting at the seventh character,}
327 ;; @r{and stopping at the ninth.}
328 (read-from-string "(list 112)" 6 8)
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}.
340 @section Output Streams
341 @cindex stream (for printing)
342 @cindex output stream
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:
350 @cindex buffer output stream
351 The output characters are inserted into @var{buffer} at point.
352 Point advances as characters are inserted.
355 @cindex marker output stream
356 The output characters are inserted into the buffer that @var{marker}
357 points into, at the marker position. The marker position advances as
358 characters are inserted. The value of point in the buffer has no effect
359 on printing when the stream is a marker.
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.
369 @cindex @code{t} output stream
370 The output characters are displayed in the echo area.
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.
379 A symbol as output stream is equivalent to the symbol's function
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.
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
392 @cindex print example
395 (setq m (set-marker (make-marker) 10 (get-buffer "foo")))
396 @result{} #<marker at 10 in foo>
400 ---------- Buffer: foo ----------
401 This is t@point{}he contents of foo.
402 ---------- Buffer: foo ----------
405 (print "This is the output" (get-buffer "foo"))
406 @result{} "This is the output"
410 @result{} #<marker at 32 in foo>
413 ---------- Buffer: foo ----------
416 @point{}he contents of foo.
417 ---------- Buffer: foo ----------
421 Now we show a use of a marker as an output stream. Initially, the
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
430 ---------- Buffer: foo ----------
431 "This is the @point{}output"
432 ---------- Buffer: foo ----------
437 @result{} #<marker at 11 in foo>
441 (print "More output for foo." m)
442 @result{} "More output for foo."
446 ---------- Buffer: foo ----------
448 "More output for foo."
450 ---------- Buffer: foo ----------
455 @result{} #<marker at 35 in foo>
459 The following example shows output to the echo area:
463 (print "Echo Area output" t)
464 @result{} "Echo Area output"
465 ---------- Echo Area ----------
467 ---------- Echo Area ----------
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
479 (setq last-output nil)
484 (defun eat-output (c)
485 (setq last-output (cons c last-output)))
490 (print "This is the output" 'eat-output)
491 @result{} "This is the 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)
502 Now we can put the output in the proper order by reversing the list:
506 (concat (nreverse last-output))
508 \"This is the output\"
514 Calling @code{concat} converts the list to a string so you can see its
515 contents more clearly.
517 @node Output Functions
518 @section Output Functions
520 This section describes the Lisp functions for printing Lisp
521 objects---converting objects into their printed representation.
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
531 being taken as delimiters when reading. @xref{Printed Representation},
532 for full details. You specify quoting or no quoting by the choice of
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.
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:
549 (setq foo (list nil))
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}.
560 @defun print object &optional stream
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:
569 (progn (print 'The\ cat\ in)
571 (print " came back"))
573 @print{} The\ cat\ in
577 @print{} " came back"
579 @result{} " came back"
584 @defun prin1 object &optional stream
585 This function outputs the printed representation of @var{object} to
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}.
592 (progn (prin1 'The\ cat\ in)
594 (prin1 " came back"))
595 @print{} The\ cat\ in"the hat"" came back"
596 @result{} " came back"
601 @defun princ object &optional stream
602 This function outputs the printed representation of @var{object} to
603 @var{stream}. It returns @var{object}.
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.
614 (princ " in the \"hat\""))
615 @print{} The cat in the "hat"
616 @result{} " in the \"hat\""
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''.
627 @defun write-char character &optional stream
628 This function outputs @var{character} to @var{stream}. It returns
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.
639 (prin1-to-string 'foo)
643 (prin1-to-string (mark-marker))
644 @result{} "#<marker at 2773 in strings.texi>"
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
654 (prin1-to-string "foo")
658 (prin1-to-string "foo" t)
663 See @code{format}, in @ref{String Conversion}, for other ways to obtain
664 the printed representation of a Lisp object as a string.
667 @tindex with-output-to-string
668 @defmac with-output-to-string body...
669 This macro executes the @var{body} forms with standard-output set up so
670 that all output feeds into a string. Then it returns that string.
672 For example, if the current buffer name is @samp{foo},
675 (with-output-to-string
676 (princ "The buffer is ")
677 (princ (buffer-name)))
681 returns @code{"The buffer is foo"}.
684 @node Output Variables
685 @section Variables Affecting Output
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}.
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.
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}:
713 (let ((print-escape-newlines t))
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.
728 @cindex printing limits
729 The value of this variable is the maximum number of elements to print in
730 any list, vector or bool-vector. If an object being printed has more
731 than this many elements, it is abbreviated with an ellipsis.
733 If the value is @code{nil} (the default), then there is no limit.
737 (setq print-length 2)
749 The value of this variable is the maximum depth of nesting of
750 parentheses and brackets when printed. Any list or vector at a depth
751 exceeding this limit is abbreviated with an ellipsis. A value of
752 @code{nil} (which is the default) means no limit.