*** empty log message ***
[emacs.git] / lispref / streams.texi
blob74f9e43e92c54634c285d4b95cf1a16a77b45000
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999
4 @c   Free Software Foundation, Inc. 
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/streams
7 @node Read and Print, Minibuffers, Debugging, Top
8 @comment  node-name,  next,  previous,  up
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).
19 @menu
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.
26 @end menu
28 @node Streams Intro
29 @section Introduction to Reading and Printing
30 @cindex Lisp reader
31 @cindex printing
32 @cindex reading
34   @dfn{Reading} a Lisp object means parsing a Lisp expression in textual
35 form and producing a corresponding Lisp object.  This is how Lisp
36 programs get into Lisp from files of Lisp code.  We call the text the
37 @dfn{read syntax} of the object.  For example, the text @samp{(a .@: 5)}
38 is the read syntax for a cons cell whose @sc{car} is @code{a} and whose
39 @sc{cdr} is the number 5.
41   @dfn{Printing} a Lisp object means producing text that represents that
42 object---converting the object to its @dfn{printed representation}
43 (@pxref{Printed Representation}).  Printing the cons cell described
44 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}
54 and @code{b}.
56   However, these two operations are not precisely inverse to each other.
57 There are three kinds of exceptions:
59 @itemize @bullet
60 @item
61 Printing can produce text that cannot be read.  For example, buffers,
62 windows, frames, subprocesses and markers print as 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.
66 @item
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.
72 @item
73 Comments can appear at certain points in the middle of an object's
74 read sequence without affecting the result of reading it.
75 @end itemize
77 @node Input Streams
78 @section Input Streams
79 @cindex stream (for reading)
80 @cindex input stream
82   Most of the Lisp functions for reading text take an @dfn{input stream}
83 as an argument.  The input stream specifies where or how to get the
84 characters of the text to be read.  Here are the possible types of input
85 stream:
87 @table @asis
88 @item @var{buffer}
89 @cindex buffer input stream
90 The input characters are read from @var{buffer}, starting with the
91 character directly after point.  Point advances as characters are read.
93 @item @var{marker}
94 @cindex marker input stream
95 The input characters are read from the buffer that @var{marker} is in,
96 starting with the character directly after the marker.  The marker
97 position advances as characters are read.  The value of point in the
98 buffer has no effect when the stream is a marker.
100 @item @var{string}
101 @cindex string input stream
102 The input characters are taken from @var{string}, starting at the first
103 character in the string and using as many characters as required.
105 @item @var{function}
106 @cindex function input stream
107 The input characters are generated by @var{function}, which must support
108 two kinds of calls:
110 @itemize @bullet
111 @item
112 When it is called with no arguments, it should return the next character.
114 @item
115 When it is called with one argument (always a character), @var{function}
116 should save the argument and arrange to return it on the next call.
117 This is called @dfn{unreading} the character; it happens when the Lisp
118 reader reads one character too many and wants to ``put it back where it
119 came from''.  In this case, it makes no difference what value
120 @var{function} returns.
121 @end itemize
123 @item @code{t}
124 @cindex @code{t} input stream
125 @code{t} used as a stream means that the input is read from the
126 minibuffer.  In fact, the minibuffer is invoked once and the text
127 given by the user is made into a string that is then used as the
128 input stream.  If Emacs is running in batch mode, standard input is used
129 instead of the minibuffer.  For example,
130 @example
131 (message "%s" (read t))
132 @end example
133 will read a Lisp expression from standard input and print the result
134 to standard output.
136 @item @code{nil}
137 @cindex @code{nil} input stream
138 @code{nil} supplied as an input stream means to use the value of
139 @code{standard-input} instead; that value is the @dfn{default input
140 stream}, and must be a non-@code{nil} input stream.
142 @item @var{symbol}
143 A symbol as input stream is equivalent to the symbol's function
144 definition (if any).
145 @end table
147   Here is an example of reading from a stream that is a buffer, showing
148 where point is located before and after:
150 @example
151 @group
152 ---------- Buffer: foo ----------
153 This@point{} is the contents of foo.
154 ---------- Buffer: foo ----------
155 @end group
157 @group
158 (read (get-buffer "foo"))
159      @result{} is
160 @end group
161 @group
162 (read (get-buffer "foo"))
163      @result{} the
164 @end group
166 @group
167 ---------- Buffer: foo ----------
168 This is the@point{} contents of foo.
169 ---------- Buffer: foo ----------
170 @end group
171 @end example
173 @noindent
174 Note that the first read skips a space.  Reading skips any amount of
175 whitespace preceding the significant text.
177   Here is an example of reading from a stream that is a marker,
178 initially positioned at the beginning of the buffer shown.  The value
179 read is the symbol @code{This}.
181 @example
182 @group
184 ---------- Buffer: foo ----------
185 This is the contents of foo.
186 ---------- Buffer: foo ----------
187 @end group
189 @group
190 (setq m (set-marker (make-marker) 1 (get-buffer "foo")))
191      @result{} #<marker at 1 in foo>
192 @end group
193 @group
194 (read m)
195      @result{} This
196 @end group
197 @group
199      @result{} #<marker at 5 in foo>   ;; @r{Before the first space.}
200 @end group
201 @end example
203   Here we read from the contents of a string:
205 @example
206 @group
207 (read "(When in) the course")
208      @result{} (When in)
209 @end group
210 @end example
212   The following example reads from the minibuffer.  The
213 prompt is: @w{@samp{Lisp expression: }}.  (That is always the prompt
214 used when you read from the stream @code{t}.)  The user's input is shown
215 following the prompt.
217 @example
218 @group
219 (read t)
220      @result{} 23
221 ---------- Buffer: Minibuffer ----------
222 Lisp expression: @kbd{23 @key{RET}}
223 ---------- Buffer: Minibuffer ----------
224 @end group
225 @end example
227   Finally, here is an example of a stream that is a function, named
228 @code{useless-stream}.  Before we use the stream, we initialize the
229 variable @code{useless-list} to a list of characters.  Then each call to
230 the function @code{useless-stream} obtains the next character in the list
231 or unreads a character by adding it to the front of the list.
233 @example
234 @group
235 (setq useless-list (append "XY()" nil))
236      @result{} (88 89 40 41)
237 @end group
239 @group
240 (defun useless-stream (&optional unread)
241   (if unread
242       (setq useless-list (cons unread useless-list))
243     (prog1 (car useless-list)
244            (setq useless-list (cdr useless-list)))))
245      @result{} useless-stream
246 @end group
247 @end example
249 @noindent
250 Now we read using the stream thus constructed:
252 @example
253 @group
254 (read 'useless-stream)
255      @result{} XY
256 @end group
258 @group
259 useless-list
260      @result{} (40 41)
261 @end group
262 @end example
264 @noindent
265 Note that the open and close parentheses remain in the list.  The Lisp
266 reader encountered the open parenthesis, decided that it ended the
267 input, and unread it.  Another attempt to read from the stream at this
268 point would read @samp{()} and return @code{nil}.
270 @defun get-file-char
271 This function is used internally as an input stream to read from the
272 input file opened by the function @code{load}.  Don't use this function
273 yourself.
274 @end defun
276 @node Input Functions
277 @section Input Functions
279   This section describes the Lisp functions and variables that pertain
280 to reading.
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}.
286 @kindex end-of-file
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.
293 @end defun
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 you specify
304 @var{end}, then reading is forced to stop just before that index, as if
305 the rest of the string were not there.
307 For example:
309 @example
310 @group
311 (read-from-string "(setq x 55) (setq y 5)")
312      @result{} ((setq x 55) . 11)
313 @end group
314 @group
315 (read-from-string "\"A short string\"")
316      @result{} ("A short string" . 16)
317 @end group
319 @group
320 ;; @r{Read starting at the first character.}
321 (read-from-string "(list 112)" 0)
322      @result{} ((list 112) . 10)
323 @end group
324 @group
325 ;; @r{Read starting at the second character.}
326 (read-from-string "(list 112)" 1)
327      @result{} (list . 5)
328 @end group
329 @group
330 ;; @r{Read starting at the seventh character,}
331 ;;   @r{and stopping at the ninth.}
332 (read-from-string "(list 112)" 6 8)
333      @result{} (11 . 8)
334 @end group
335 @end example
336 @end defun
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}.
341 @end defvar
343 @node Output Streams
344 @section Output Streams
345 @cindex stream (for printing)
346 @cindex output stream
348   An output stream specifies what to do with the characters produced
349 by printing.  Most print functions accept an output stream as an
350 optional argument.  Here are the possible types of output stream:
352 @table @asis
353 @item @var{buffer}
354 @cindex buffer output stream
355 The output characters are inserted into @var{buffer} at point.
356 Point advances as characters are inserted.
358 @item @var{marker}
359 @cindex marker output stream
360 The output characters are inserted into the buffer that @var{marker}
361 points into, at the marker position.  The marker position advances as
362 characters are inserted.  The value of point in the buffer has no effect
363 on printing when the stream is a marker, and this kind of printing
364 does not move point.
366 @item @var{function}
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
371 is responsible for storing the characters wherever you want to put them.
373 @item @code{t}
374 @cindex @code{t} output stream
375 The output characters are displayed in the echo area.
377 @item @code{nil}
378 @cindex @code{nil} output stream
379 @code{nil} specified as an output stream means to use the value of
380 @code{standard-output} instead; that value is the @dfn{default output
381 stream}, and must not be @code{nil}.
383 @item @var{symbol}
384 A symbol as output stream is equivalent to the symbol's function
385 definition (if any).
386 @end table
388   Many of the valid output streams are also valid as input streams.  The
389 difference between input and output streams is therefore more a matter
390 of how you use a Lisp object, than of different 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
395 @samp{h}.
397 @cindex print example
398 @example
399 @group
400 ---------- Buffer: foo ----------
401 This is t@point{}he contents of foo.
402 ---------- Buffer: foo ----------
403 @end group
405 (print "This is the output" (get-buffer "foo"))
406      @result{} "This is the output"
408 @group
409 ---------- Buffer: foo ----------
410 This is t
411 "This is the output"
412 @point{}he contents of foo.
413 ---------- Buffer: foo ----------
414 @end group
415 @end example
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
422 effect.
424 @example
425 @group
426 ---------- Buffer: foo ----------
427 This is the @point{}output
428 ---------- Buffer: foo ----------
429 @end group
431 @group
432 (setq m (copy-marker 10))
433      @result{} #<marker at 10 in foo>
434 @end group
436 @group
437 (print "More output for foo." m)
438      @result{} "More output for foo."
439 @end group
441 @group
442 ---------- Buffer: foo ----------
443 This is t
444 "More output for foo."
445 he @point{}output
446 ---------- Buffer: foo ----------
447 @end group
449 @group
451      @result{} #<marker at 34 in foo>
452 @end group
453 @end example
455   The following example shows output to the echo area:
457 @example
458 @group
459 (print "Echo Area output" t)
460      @result{} "Echo Area output"
461 ---------- Echo Area ----------
462 "Echo Area output"
463 ---------- Echo Area ----------
464 @end group
465 @end example
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
471 in reverse order.
473 @example
474 @group
475 (setq last-output nil)
476      @result{} nil
477 @end group
479 @group
480 (defun eat-output (c)
481   (setq last-output (cons c last-output)))
482      @result{} eat-output
483 @end group
485 @group
486 (print "This is the output" 'eat-output)
487      @result{} "This is the output"
488 @end group
490 @group
491 last-output
492      @result{} (10 34 116 117 112 116 117 111 32 101 104 
493     116 32 115 105 32 115 105 104 84 34 10)
494 @end group
495 @end example
497 @noindent
498 Now we can put the output in the proper order by reversing the list:
500 @example
501 @group
502 (concat (nreverse last-output))
503      @result{} "
504 \"This is the output\"
506 @end group
507 @end example
509 @noindent
510 Calling @code{concat} converts the list to a string so you can see its
511 contents more clearly.
513 @node Output Functions
514 @section Output Functions
516   This section describes the Lisp functions for printing Lisp
517 objects---converting objects into their printed representation.
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 Emacs 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
529 printing function.
531   If the text is to be read back into Lisp, then you should print with
532 quoting characters to avoid ambiguity.  Likewise, if the purpose is to
533 describe a Lisp object clearly for a Lisp programmer.  However, if the
534 purpose of the output is to look nice for humans, then it is usually
535 better to print without quoting.
537   Lisp objects can refer to themselves.  Printing a self-referential
538 object in the normal way would require an infinite amount of text, and
539 the attempt could cause infinite recursion.  Emacs detects such
540 recursion and prints @samp{#@var{level}} instead of recursively printing
541 an object already being printed.  For example, here @samp{#0} indicates
542 a recursive reference to the object at level 0 of the current print
543 operation:
545 @example
546 (setq foo (list nil))
547      @result{} (nil)
548 (setcar foo foo)
549      @result{} (#0)
550 @end example
552   In the functions below, @var{stream} stands for an output stream.
553 (See the previous section for a description of output streams.)  If
554 @var{stream} is @code{nil} or omitted, it defaults to the value of
555 @code{standard-output}.
557 @defun print object &optional stream
558 @cindex Lisp printer
559 The @code{print} function is a convenient way of printing.  It outputs
560 the printed representation of @var{object} to @var{stream}, printing in
561 addition one newline before @var{object} and another after it.  Quoting
562 characters are used.  @code{print} returns @var{object}.  For example:
564 @example
565 @group
566 (progn (print 'The\ cat\ in)
567        (print "the hat")
568        (print " came back"))
569      @print{} 
570      @print{} The\ cat\ in
571      @print{} 
572      @print{} "the hat"
573      @print{} 
574      @print{} " came back"
575      @print{} 
576      @result{} " came back"
577 @end group
578 @end example
579 @end defun
581 @defun prin1 object &optional stream
582 This function outputs the printed representation of @var{object} to
583 @var{stream}.  It does not print newlines to separate output as
584 @code{print} does, but it does use quoting characters just like
585 @code{print}.  It returns @var{object}.
587 @example
588 @group
589 (progn (prin1 'The\ cat\ in) 
590        (prin1 "the hat") 
591        (prin1 " came back"))
592      @print{} The\ cat\ in"the hat"" came back"
593      @result{} " came back"
594 @end group
595 @end example
596 @end defun
598 @defun princ object &optional stream
599 This function outputs the printed representation of @var{object} to
600 @var{stream}.  It returns @var{object}.
602 This function is intended to produce output that is readable by people,
603 not by @code{read}, so it doesn't insert quoting characters and doesn't
604 put double-quotes around the contents of strings.  It does not add any
605 spacing between calls.
607 @example
608 @group
609 (progn
610   (princ 'The\ cat)
611   (princ " in the \"hat\""))
612      @print{} The cat in the "hat"
613      @result{} " in the \"hat\""
614 @end group
615 @end example
616 @end defun
618 @defun terpri &optional stream
619 @cindex newline in print
620 This function outputs a newline to @var{stream}.  The name stands
621 for ``terminate print''.
622 @end defun
624 @defun write-char character &optional stream
625 This function outputs @var{character} to @var{stream}.  It returns
626 @var{character}.
627 @end defun
629 @defun prin1-to-string object &optional noescape
630 @cindex object to string
631 This function returns a string containing the text that @code{prin1}
632 would have printed for the same argument.
634 @example
635 @group
636 (prin1-to-string 'foo)
637      @result{} "foo"
638 @end group
639 @group
640 (prin1-to-string (mark-marker))
641      @result{} "#<marker at 2773 in strings.texi>"
642 @end group
643 @end example
645 If @var{noescape} is non-@code{nil}, that inhibits use of quoting
646 characters in the output.  (This argument is supported in Emacs versions
647 19 and later.)
649 @example
650 @group
651 (prin1-to-string "foo")
652      @result{} "\"foo\""
653 @end group
654 @group
655 (prin1-to-string "foo" t)
656      @result{} "foo"
657 @end group
658 @end example
660 See @code{format}, in @ref{String Conversion}, for other ways to obtain
661 the printed representation of a Lisp object as a string.
662 @end defun
664 @defmac with-output-to-string body...
665 This macro executes the @var{body} forms with @code{standard-output} set
666 up to feed output into a string.  Then it returns that string.
668 For example, if the current buffer name is @samp{foo},
670 @example
671 (with-output-to-string
672   (princ "The buffer is ")
673   (princ (buffer-name)))
674 @end example
676 @noindent
677 returns @code{"The buffer is foo"}.
678 @end defmac
680 @node Output Variables
681 @section Variables Affecting Output
683 @defvar standard-output
684 The value of this variable is the default output stream---the stream
685 that print functions use when the @var{stream} argument is @code{nil}.
686 @end defvar
688 @defvar print-escape-newlines
689 @cindex @samp{\n} in print
690 @cindex escape characters
691 If this variable is non-@code{nil}, then newline characters in strings
692 are printed as @samp{\n} and formfeeds are printed as @samp{\f}.
693 Normally these characters are printed as actual newlines and formfeeds.
695 This variable affects the print functions @code{prin1} and @code{print}
696 that print with quoting.  It does not affect @code{princ}.  Here is an
697 example using @code{prin1}:
699 @example
700 @group
701 (prin1 "a\nb")
702      @print{} "a
703      @print{} b"
704      @result{} "a
706 @end group
708 @group
709 (let ((print-escape-newlines t))
710   (prin1 "a\nb"))
711      @print{} "a\nb"
712      @result{} "a
714 @end group
715 @end example
717 @noindent
718 In the second expression, the local binding of
719 @code{print-escape-newlines} is in effect during the call to
720 @code{prin1}, but not during the printing of the result.
721 @end defvar
723 @defvar print-escape-nonascii
724 If this variable is non-@code{nil}, then unibyte non-@sc{ascii}
725 characters in strings are unconditionally printed as backslash sequences
726 by the print functions @code{prin1} and @code{print} that print with
727 quoting.
729 Those functions also use backslash sequences for unibyte non-@sc{ascii}
730 characters, regardless of the value of this variable, when the output
731 stream is a multibyte buffer or a marker pointing into one.
732 @end defvar
734 @defvar print-escape-multibyte
735 If this variable is non-@code{nil}, then multibyte non-@sc{ascii}
736 characters in strings are unconditionally printed as backslash sequences
737 by the print functions @code{prin1} and @code{print} that print with
738 quoting.
740 Those functions also use backslash sequences for multibyte
741 non-@sc{ascii} characters, regardless of the value of this variable,
742 when the output stream is a unibyte buffer or a marker pointing into
743 one.
744 @end defvar
746 @defvar print-length
747 @cindex printing limits
748 The value of this variable is the maximum number of elements to print in
749 any list, vector or bool-vector.  If an object being printed has more
750 than this many elements, it is abbreviated with an ellipsis.
752 If the value is @code{nil} (the default), then there is no limit.
754 @example
755 @group
756 (setq print-length 2)
757      @result{} 2
758 @end group
759 @group
760 (print '(1 2 3 4 5))
761      @print{} (1 2 ...)
762      @result{} (1 2 ...)
763 @end group
764 @end example
765 @end defvar
767 @defvar print-level
768 The value of this variable is the maximum depth of nesting of
769 parentheses and brackets when printed.  Any list or vector at a depth
770 exceeding this limit is abbreviated with an ellipsis.  A value of
771 @code{nil} (which is the default) means no limit.
772 @end defvar
774   These variables are used for detecting and reporting circular 
775 and shared structure---but they are only defined in Emacs 21.
777 @tindex print-circle
778 @defvar print-circle
779 If non-@code{nil}, this variable enables detection of circular 
780 and shared structure in printing.
781 @end defvar
783 @tindex print-gensym
784 @defvar print-gensym
785 If non-@code{nil}, this variable enables detection of uninterned symbols
786 (@pxref{Creating Symbols}) in printing.  When this is enabled,
787 uninterned symbols print with the prefix @samp{#:}, which tells the Lisp
788 reader to produce an uninterned symbol.
789 @end defvar