2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/streams.info
8 @node Read and Print, Minibuffers, Debugging, Top
9 @chapter Reading and Printing Lisp Objects
11 @dfn{Printing} and @dfn{reading} are the operations of converting Lisp
12 objects to textual form and vice versa. They use the printed
13 representations and read syntax described in @ref{Lisp Data Types}.
15 This chapter describes the Lisp functions for reading and printing.
16 It also describes @dfn{streams}, which specify where to get the text (if
17 reading) or where to put it (if printing).
20 * Streams Intro:: Overview of streams, reading and printing.
21 * Input Streams:: Various data types that can be used as input streams.
22 * Input Functions:: Functions to read Lisp objects from text.
23 * Output Streams:: Various data types that can be used as output streams.
24 * Output Functions:: Functions to print Lisp objects as text.
25 * Output Variables:: Variables that control what the printing functions do.
29 @node Streams Intro, Input Streams, Read and Print, Read and Print
30 @section Introduction to Reading and Printing
35 @dfn{Reading} a Lisp object means parsing a Lisp expression in textual
36 form and producing a corresponding Lisp object. This is how Lisp
37 programs get into Lisp from files of Lisp code. We call the text the
38 @dfn{read syntax} of the object. For example, the text @samp{(a .@: 5)}
39 is the read syntax for a cons cell whose @sc{car} is @code{a} and whose
40 @sc{cdr} is the number 5.
42 @dfn{Printing} a Lisp object means producing text that represents that
43 object---converting the object to its printed representation. Printing
44 the cons cell described above produces the text @samp{(a .@: 5)}.
46 Reading and printing are more or less inverse operations: printing the
47 object that results from reading a given piece of text often produces
48 the same text, and reading the text that results from printing an object
49 usually produces a similar-looking object. For example, printing the
50 symbol @code{foo} produces the text @samp{foo}, and reading that text
51 returns the symbol @code{foo}. Printing a list whose elements are
52 @code{a} and @code{b} produces the text @samp{(a b)}, and reading that
53 text produces a list (but not the same list) with elements @code{a}
56 However, these two operations are not precisely inverses. There are
57 three kinds of exceptions:
61 Printing can produce text that cannot be read. For example, buffers,
62 windows, frames, subprocesses and markers print into text that starts
63 with @samp{#}; if you try to read this text, you get an error. There is
64 no way to read those data types.
67 One object can have multiple textual representations. For example,
68 @samp{1} and @samp{01} represent the same integer, and @samp{(a b)} and
69 @samp{(a .@: (b))} represent the same list. Reading will accept any of
70 the alternatives, but printing must choose one of them.
73 Comments can appear at certain points in the middle of an object's
74 read sequence without affecting the result of reading it.
79 @section Input Streams
80 @cindex stream (for reading)
83 Most of the Lisp functions for reading text take an @dfn{input stream}
84 as an argument. The input stream specifies where or how to get the
85 characters of the text to be read. Here are the possible types of input
90 @cindex buffer input stream
91 The input characters are read from @var{buffer}, starting with the
92 character directly after point. Point advances as characters are read.
95 @cindex marker input stream
96 The input characters are read from the buffer that @var{marker} is in,
97 starting with the character directly after the marker. The marker
98 position advances as characters are read. The value of point in the
99 buffer has no effect when the stream is a marker.
102 @cindex string input stream
103 The input characters are taken from @var{string}, starting at the first
104 character in the string and using as many characters as required.
107 @cindex function input stream
108 The input characters are generated by @var{function}, one character per
109 call. Normally @var{function} is called with no arguments, and should
113 Occasionally @var{function} is called with one argument (always a
114 character). When that happens, @var{function} should save the argument
115 and arrange to return it on the next call. This is called
116 @dfn{unreading} the character; it happens when the Lisp reader reads one
117 character too many and wants to ``put it back where it came from''.
120 @cindex @code{t} input stream
121 @code{t} used as a stream means that the input is read from the
122 minibuffer. In fact, the minibuffer is invoked once and the text
123 given by the user is made into a string that is then used as the
127 @cindex @code{nil} input stream
128 @code{nil} supplied as an input stream means to use the value of
129 @code{standard-input} instead; that value is the @dfn{default input
130 stream}, and must be a non-@code{nil} input stream.
133 A symbol as input stream is equivalent to the symbol's function
137 Here is an example of reading from a stream that is a buffer, showing
138 where point is located before and after:
142 ---------- Buffer: foo ----------
143 This@point{} is the contents of foo.
144 ---------- Buffer: foo ----------
148 (read (get-buffer "foo"))
152 (read (get-buffer "foo"))
157 ---------- Buffer: foo ----------
158 This is the@point{} contents of foo.
159 ---------- Buffer: foo ----------
164 Note that the first read skips a space. Reading skips any amount of
165 whitespace preceding the significant text.
167 In Emacs 18, reading a symbol discarded the delimiter terminating the
168 symbol. Thus, point would end up at the beginning of @samp{contents}
169 rather than after @samp{the}. The Emacs 19 behavior is superior because
170 it correctly handles input such as @samp{bar(foo)}, where the
171 open-parenthesis that ends one object is needed as the beginning of
174 Here is an example of reading from a stream that is a marker,
175 initially positioned at the beginning of the buffer shown. The value
176 read is the symbol @code{This}.
181 ---------- Buffer: foo ----------
182 This is the contents of foo.
183 ---------- Buffer: foo ----------
187 (setq m (set-marker (make-marker) 1 (get-buffer "foo")))
188 @result{} #<marker at 1 in foo>
196 @result{} #<marker at 5 in foo> ;; @r{Before the first space.}
200 Here we read from the contents of a string:
204 (read "(When in) the course")
209 The following example reads from the minibuffer. The
210 prompt is: @w{@samp{Lisp expression: }}. (That is always the prompt
211 used when you read from the stream @code{t}.) The user's input is shown
212 following the prompt.
218 ---------- Buffer: Minibuffer ----------
219 Lisp expression: @kbd{23 @key{RET}}
220 ---------- Buffer: Minibuffer ----------
224 Finally, here is an example of a stream that is a function, named
225 @code{useless-stream}. Before we use the stream, we initialize the
226 variable @code{useless-list} to a list of characters. Then each call to
227 the function @code{useless-stream} obtains the next character in the list
228 or unreads a character by adding it to the front of the list.
232 (setq useless-list (append "XY()" nil))
233 @result{} (88 89 40 41)
237 (defun useless-stream (&optional unread)
239 (setq useless-list (cons unread useless-list))
240 (prog1 (car useless-list)
241 (setq useless-list (cdr useless-list)))))
242 @result{} useless-stream
247 Now we read using the stream thus constructed:
251 (read 'useless-stream)
262 Note that the open and close parentheses remains in the list. The Lisp
263 reader encountered the open parenthesis, decided that it ended the
264 input, and unread it. Another attempt to read from the stream at this
265 point would read @samp{()} and return @code{nil}.
267 @ignore @c Not in SXEmacs+XEmacs
269 This function is used internally as an input stream to read from the
270 input file opened by the function @code{load}. Don't use this function
276 @node Input Functions
277 @section Input Functions
279 This section describes the Lisp functions and variables that pertain
282 In the functions below, @var{stream} stands for an input stream (see
283 the previous section). If @var{stream} is @code{nil} or omitted, it
284 defaults to the value of @code{standard-input}.
287 An @code{end-of-file} error is signaled if reading encounters an
288 unterminated list, vector, or string.
290 @defun read &optional stream
291 This function reads one textual Lisp expression from @var{stream},
292 returning it as a Lisp object. This is the basic Lisp input function.
295 @defun read-from-string string &optional start end
296 @cindex string to object
297 This function reads the first textual Lisp expression from the text in
298 @var{string}. It returns a cons cell whose @sc{car} is that expression,
299 and whose @sc{cdr} is an integer giving the position of the next
300 remaining character in the string (i.e., the first one not read).
302 If @var{start} is supplied, then reading begins at index @var{start} in
303 the string (where the first character is at index 0). If @var{end} is
304 also supplied, then reading stops just before that index, as if the rest
305 of the string were not there.
311 (read-from-string "(setq x 55) (setq y 5)")
312 @result{} ((setq x 55) . 11)
315 (read-from-string "\"A short string\"")
316 @result{} ("A short string" . 16)
320 ;; @r{Read starting at the first character.}
321 (read-from-string "(list 112)" 0)
322 @result{} ((list 112) . 10)
325 ;; @r{Read starting at the second character.}
326 (read-from-string "(list 112)" 1)
330 ;; @r{Read starting at the seventh character,}
331 ;; @r{and stopping at the ninth.}
332 (read-from-string "(list 112)" 6 8)
338 @defvar standard-input
339 This variable holds the default input stream---the stream that
340 @code{read} uses when the @var{stream} argument is @code{nil}.
345 @section Output Streams
346 @cindex stream (for printing)
347 @cindex output stream
349 An output stream specifies what to do with the characters produced
350 by printing. Most print functions accept an output stream as an
351 optional argument. Here are the possible types of output stream:
355 @cindex buffer output stream
356 The output characters are inserted into @var{buffer} at point.
357 Point advances as characters are inserted.
360 @cindex marker output stream
361 The output characters are inserted into the buffer that @var{marker}
362 points into, at the marker position. The marker position advances as
363 characters are inserted. The value of point in the buffer has no effect
364 on printing when the stream is a marker.
367 @cindex function output stream
368 The output characters are passed to @var{function}, which is responsible
369 for storing them away. It is called with a single character as
370 argument, as many times as there are characters to be output, and is
371 free to do anything at all with the characters it receives.
374 @cindex @code{t} output stream
375 The output characters are displayed in the echo area.
378 @cindex @code{nil} output stream
379 @code{nil} specified as an output stream means to the value of
380 @code{standard-output} instead; that value is the @dfn{default output
381 stream}, and must be a non-@code{nil} output stream.
384 A symbol as output stream is equivalent to the symbol's function
388 Many of the valid output streams are also valid as input streams. The
389 difference between input and output streams is therefore mostly one of
390 how you use a Lisp object, not a distinction of types of object.
392 Here is an example of a buffer used as an output stream. Point is
393 initially located as shown immediately before the @samp{h} in
394 @samp{the}. At the end, point is located directly before that same
397 @cindex print example
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"
409 ---------- Buffer: foo ----------
412 @point{}he contents of foo.
413 ---------- Buffer: foo ----------
417 Now we show a use of a marker as an output stream. Initially, the
418 marker is in buffer @code{foo}, between the @samp{t} and the @samp{h} in
419 the word @samp{the}. At the end, the marker has advanced over the
420 inserted text so that it remains positioned before the same @samp{h}.
421 Note that the location of point, shown in the usual fashion, has no
426 ---------- Buffer: foo ----------
427 "This is the @point{}output"
428 ---------- Buffer: foo ----------
433 @result{} #<marker at 11 in foo>
437 (print "More output for foo." m)
438 @result{} "More output for foo."
442 ---------- Buffer: foo ----------
444 "More output for foo."
446 ---------- Buffer: foo ----------
451 @result{} #<marker at 35 in foo>
455 The following example shows output to the echo area:
459 (print "Echo Area output" t)
460 @result{} "Echo Area output"
461 ---------- Echo Area ----------
463 ---------- Echo Area ----------
467 Finally, we show the use of a function as an output stream. The
468 function @code{eat-output} takes each character that it is given and
469 conses it onto the front of the list @code{last-output} (@pxref{Building
470 Lists}). At the end, the list contains all the characters output, but
475 (setq last-output nil)
480 (defun eat-output (c)
481 (setq last-output (cons c last-output)))
486 (print "This is the output" 'eat-output)
487 @result{} "This is the output"
492 @result{} (?\n ?\" ?t ?u ?p ?t ?u ?o ?\ ?e ?h ?t
493 ?\ ?s ?i ?\ ?s ?i ?h ?T ?\" ?\n)
498 Now we can put the output in the proper order by reversing the list:
502 (concat (nreverse last-output))
504 \"This is the output\"
510 Calling @code{concat} converts the list to a string so you can see its
511 contents more clearly.
514 @node Output Functions
515 @section Output Functions
517 This section describes the Lisp functions for printing Lisp objects.
519 @cindex @samp{"} in printing
520 @cindex @samp{\} in printing
521 @cindex quoting characters in printing
522 @cindex escape characters in printing
523 Some of the SXEmacs printing functions add quoting characters to the
524 output when necessary so that it can be read properly. The quoting
525 characters used are @samp{"} and @samp{\}; they distinguish strings from
526 symbols, and prevent punctuation characters in strings and symbols from
527 being taken as delimiters when reading. @xref{Printed Representation},
528 for full details. You specify quoting or no quoting by the choice of
531 If the text is to be read back into Lisp, then it is best to print
532 with quoting characters to avoid ambiguity. Likewise, if the purpose is
533 to describe a Lisp object clearly for a Lisp programmer. However, if
534 the purpose of the output is to look nice for humans, then it is better
535 to print without quoting.
537 Printing a self-referent Lisp object requires an infinite amount of
538 text. In certain cases, trying to produce this text leads to a stack
539 overflow. SXEmacs detects such recursion and prints @samp{#@var{level}}
540 instead of recursively printing an object already being printed. For
541 example, here @samp{#0} indicates a recursive reference to the object at
542 level 0 of the current print operation:
545 (setq foo (list nil))
551 In the functions below, @var{stream} stands for an output stream.
552 (See the previous section for a description of output streams.) If
553 @var{stream} is @code{nil} or omitted, it defaults to the value of
554 @code{standard-output}.
556 @defun print object &optional stream
558 The @code{print} function is a convenient way of printing. It outputs
559 the printed representation of @var{object} to @var{stream}, printing in
560 addition one newline before @var{object} and another after it. Quoting
561 characters are used. @code{print} returns @var{object}. For example:
565 (progn (print 'The\ cat\ in)
567 (print " came back"))
569 @print{} The\ cat\ in
573 @print{} " came back"
575 @result{} " came back"
580 @defun prin1 object &optional stream
581 This function outputs the printed representation of @var{object} to
582 @var{stream}. It does not print newlines to separate output as
583 @code{print} does, but it does use quoting characters just like
584 @code{print}. It returns @var{object}.
588 (progn (prin1 'The\ cat\ in)
590 (prin1 " came back"))
591 @print{} The\ cat\ in"the hat"" came back"
592 @result{} " came back"
597 @defun princ object &optional stream
598 This function outputs the printed representation of @var{object} to
599 @var{stream}. It returns @var{object}.
601 This function is intended to produce output that is readable by people,
602 not by @code{read}, so it doesn't insert quoting characters and doesn't
603 put double-quotes around the contents of strings. It does not add any
604 spacing between calls.
610 (princ " in the \"hat\""))
611 @print{} The cat in the "hat"
612 @result{} " in the \"hat\""
617 @defun terpri &optional stream
618 @cindex newline in print
619 This function outputs a newline to @var{stream}. The name stands
620 for ``terminate print''.
623 @defun write-char character &optional stream
624 This function outputs @var{character} to @var{stream}. It returns
628 @defun prin1-to-string object &optional noescape
629 @cindex object to string
630 This function returns a string containing the text that @code{prin1}
631 would have printed for the same argument.
635 (prin1-to-string 'foo)
639 (prin1-to-string (mark-marker))
640 @result{} "#<marker at 2773 in strings.texi>"
644 If @var{noescape} is non-@code{nil}, that inhibits use of quoting
645 characters in the output. (This argument is supported in Emacs versions
650 (prin1-to-string "foo")
654 (prin1-to-string "foo" t)
659 See @code{format}, in @ref{String Conversion}, for other ways to obtain
660 the printed representation of a Lisp object as a string.
664 @node Output Variables
665 @section Variables Affecting Output
667 @defvar standard-output
668 The value of this variable is the default output stream---the stream
669 that print functions use when the @var{stream} argument is @code{nil}.
672 @defvar print-escape-newlines
673 @cindex @samp{\n} in print
674 @cindex escape characters
675 If this variable is non-@code{nil}, then newline characters in strings
676 are printed as @samp{\n} and formfeeds are printed as @samp{\f}.
677 Normally these characters are printed as actual newlines and formfeeds.
679 This variable affects the print functions @code{prin1} and @code{print},
680 as well as everything that uses them. It does not affect @code{princ}.
681 Here is an example using @code{prin1}:
693 (let ((print-escape-newlines t))
702 In the second expression, the local binding of
703 @code{print-escape-newlines} is in effect during the call to
704 @code{prin1}, but not during the printing of the result.
707 @defvar print-readably
708 @cindex printing readably
709 If non-@code{nil}, then all objects will be printed in a readable form.
710 If an object has no readable representation, then an error is signalled.
711 When @code{print-readably} is true, compiled-function objects will be
712 written in @samp{#[...]} form instead of in @samp{#<compiled-function
713 [...]>} form, and two-element lists of the form @samp{(quote object)}
714 will be written as the equivalent @samp{'object}. Do not @emph{set}
715 this variable; bind it instead.
719 @cindex printing limits
720 The value of this variable is the maximum number of elements of a list
721 that will be printed. If a list being printed has more than this many
722 elements, it is abbreviated with an ellipsis.
724 If the value is @code{nil} (the default), then there is no limit.
728 (setq print-length 2)
740 The value of this variable is the maximum depth of nesting of
741 parentheses and brackets when printed. Any list or vector at a depth
742 exceeding this limit is abbreviated with an ellipsis. A value of
743 @code{nil} (which is the default) means no limit.
745 This variable exists in version 19 and later versions.
748 @defvar print-string-length
749 @cindex string length, maximum when printing
750 The value of this variable is the maximum number of characters of a string
751 that will be printed. If a string being printed has more than this many
752 characters, it is abbreviated with an ellipsis.
756 @cindex printing uninterned symbols
757 @cindex uninterned symbols, printing
758 If non-@code{nil}, then uninterned symbols will be printed specially.
759 Uninterned symbols are those which are not present in @code{obarray},
760 that is, those which were made with @code{make-symbol} or by calling
761 @code{intern} with a second argument.
763 When @code{print-gensym} is true, such symbols will be preceded by
764 @samp{#:}, which causes the reader to create a new symbol instead of
765 interning and returning an existing one. Beware: The @samp{#:} syntax
766 creates a new symbol each time it is seen, so if you print an object
767 which contains two pointers to the same uninterned symbol, @code{read}
768 will not duplicate that structure.
770 Also, since SXEmacs has no real notion of packages, there is no way for
771 the printer to distinguish between symbols interned in no obarray, and
772 symbols interned in an alternate obarray.
775 @defvar float-output-format
776 @cindex printing floating-point numbers
777 @cindex floating-point numbers, printing
778 This variable holds the format descriptor string that Lisp uses to print
779 floats. This is a @samp{%}-spec like those accepted by @code{printf} in
780 C, but with some restrictions. It must start with the two characters
781 @samp{%.}. After that comes an integer precision specification, and
782 then a letter which controls the format. The letters allowed are
783 @samp{e}, @samp{f} and @samp{g}.
787 Use @samp{e} for exponential notation
788 @samp{@var{dig}.@var{digits}e@var{expt}}.
790 Use @samp{f} for decimal point notation @samp{DIGITS.DIGITS}.
792 Use @samp{g} to choose the shorter of those two formats for the number
796 The precision in any of these cases is the number of digits following
797 the decimal point. With @samp{f}, a precision of 0 means to omit the
798 decimal point. 0 is not allowed with @samp{f} or @samp{g}.
800 A value of @code{nil} means to use @samp{%.16g}.
802 Regardless of the value of @code{float-output-format}, a floating point
803 number will never be printed in such a way that it is ambiguous with an
804 integer; that is, a floating-point number will always be printed with a
805 decimal point and/or an exponent, even if the digits following the
806 decimal point are all zero. This is to preserve read-equivalence.