annotate doc/lispref/streams.texi @ 107754:c065a9e361c6

Explain how to re-throw a signal. control.texi (Handling Errors): How to re-throw a signal caught by condition-case.
author Eli Zaretskii <eliz@gnu.org>
date Wed, 31 Mar 2010 12:43:53 +0300
parents 1d1d5d9bd884
children 376148b31b5e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
84099
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2001, 2002,
106815
1d1d5d9bd884 Add 2010 to copyright years.
Glenn Morris <rgm@gnu.org>
parents: 103103
diff changeset
4 @c 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
84099
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
84116
0ba80d073e27 (setfilename): Go up one more level to ../../info.
Glenn Morris <rgm@gnu.org>
parents: 84099
diff changeset
6 @setfilename ../../info/streams
84099
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7 @node Read and Print, Minibuffers, Debugging, Top
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8 @comment node-name, next, previous, up
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9 @chapter Reading and Printing Lisp Objects
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11 @dfn{Printing} and @dfn{reading} are the operations of converting Lisp
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12 objects to textual form and vice versa. They use the printed
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13 representations and read syntax described in @ref{Lisp Data Types}.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15 This chapter describes the Lisp functions for reading and printing.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16 It also describes @dfn{streams}, which specify where to get the text (if
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17 reading) or where to put it (if printing).
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19 @menu
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20 * Streams Intro:: Overview of streams, reading and printing.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21 * Input Streams:: Various data types that can be used as input streams.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22 * Input Functions:: Functions to read Lisp objects from text.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
23 * Output Streams:: Various data types that can be used as output streams.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
24 * Output Functions:: Functions to print Lisp objects as text.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
25 * Output Variables:: Variables that control what the printing functions do.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
26 @end menu
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
27
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
28 @node Streams Intro
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
29 @section Introduction to Reading and Printing
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
30 @cindex Lisp reader
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
31 @cindex printing
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
32 @cindex reading
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
33
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
34 @dfn{Reading} a Lisp object means parsing a Lisp expression in textual
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
35 form and producing a corresponding Lisp object. This is how Lisp
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
36 programs get into Lisp from files of Lisp code. We call the text the
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
37 @dfn{read syntax} of the object. For example, the text @samp{(a .@: 5)}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
38 is the read syntax for a cons cell whose @sc{car} is @code{a} and whose
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
39 @sc{cdr} is the number 5.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
40
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
41 @dfn{Printing} a Lisp object means producing text that represents that
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
42 object---converting the object to its @dfn{printed representation}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
43 (@pxref{Printed Representation}). Printing the cons cell described
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
44 above produces the text @samp{(a .@: 5)}.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
45
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
46 Reading and printing are more or less inverse operations: printing the
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
47 object that results from reading a given piece of text often produces
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
48 the same text, and reading the text that results from printing an object
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
49 usually produces a similar-looking object. For example, printing the
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
50 symbol @code{foo} produces the text @samp{foo}, and reading that text
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
51 returns the symbol @code{foo}. Printing a list whose elements are
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
52 @code{a} and @code{b} produces the text @samp{(a b)}, and reading that
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
53 text produces a list (but not the same list) with elements @code{a}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
54 and @code{b}.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
55
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
56 However, these two operations are not precisely inverse to each other.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
57 There are three kinds of exceptions:
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
58
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
59 @itemize @bullet
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
60 @item
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
61 Printing can produce text that cannot be read. For example, buffers,
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
62 windows, frames, subprocesses and markers print as text that starts
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
63 with @samp{#}; if you try to read this text, you get an error. There is
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
64 no way to read those data types.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
65
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
66 @item
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
67 One object can have multiple textual representations. For example,
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
68 @samp{1} and @samp{01} represent the same integer, and @samp{(a b)} and
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
69 @samp{(a .@: (b))} represent the same list. Reading will accept any of
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
70 the alternatives, but printing must choose one of them.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
71
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
72 @item
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
73 Comments can appear at certain points in the middle of an object's
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
74 read sequence without affecting the result of reading it.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
75 @end itemize
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
76
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
77 @node Input Streams
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
78 @section Input Streams
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
79 @cindex stream (for reading)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
80 @cindex input stream
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
81
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
82 Most of the Lisp functions for reading text take an @dfn{input stream}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
83 as an argument. The input stream specifies where or how to get the
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
84 characters of the text to be read. Here are the possible types of input
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
85 stream:
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
86
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
87 @table @asis
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
88 @item @var{buffer}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
89 @cindex buffer input stream
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
90 The input characters are read from @var{buffer}, starting with the
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
91 character directly after point. Point advances as characters are read.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
92
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
93 @item @var{marker}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
94 @cindex marker input stream
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
95 The input characters are read from the buffer that @var{marker} is in,
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
96 starting with the character directly after the marker. The marker
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
97 position advances as characters are read. The value of point in the
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
98 buffer has no effect when the stream is a marker.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
99
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
100 @item @var{string}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
101 @cindex string input stream
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
102 The input characters are taken from @var{string}, starting at the first
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
103 character in the string and using as many characters as required.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
104
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
105 @item @var{function}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
106 @cindex function input stream
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
107 The input characters are generated by @var{function}, which must support
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
108 two kinds of calls:
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
109
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
110 @itemize @bullet
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
111 @item
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
112 When it is called with no arguments, it should return the next character.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
113
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
114 @item
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
115 When it is called with one argument (always a character), @var{function}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
116 should save the argument and arrange to return it on the next call.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
117 This is called @dfn{unreading} the character; it happens when the Lisp
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
118 reader reads one character too many and wants to ``put it back where it
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
119 came from.'' In this case, it makes no difference what value
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
120 @var{function} returns.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
121 @end itemize
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
122
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
123 @item @code{t}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
124 @cindex @code{t} input stream
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
125 @code{t} used as a stream means that the input is read from the
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
126 minibuffer. In fact, the minibuffer is invoked once and the text
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
127 given by the user is made into a string that is then used as the
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
128 input stream. If Emacs is running in batch mode, standard input is used
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
129 instead of the minibuffer. For example,
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
130 @example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
131 (message "%s" (read t))
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
132 @end example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
133 will read a Lisp expression from standard input and print the result
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
134 to standard output.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
135
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
136 @item @code{nil}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
137 @cindex @code{nil} input stream
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
138 @code{nil} supplied as an input stream means to use the value of
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
139 @code{standard-input} instead; that value is the @dfn{default input
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
140 stream}, and must be a non-@code{nil} input stream.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
141
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
142 @item @var{symbol}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
143 A symbol as input stream is equivalent to the symbol's function
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
144 definition (if any).
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
145 @end table
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
146
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
147 Here is an example of reading from a stream that is a buffer, showing
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
148 where point is located before and after:
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
149
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
150 @example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
151 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
152 ---------- Buffer: foo ----------
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
153 This@point{} is the contents of foo.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
154 ---------- Buffer: foo ----------
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
155 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
156
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
157 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
158 (read (get-buffer "foo"))
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
159 @result{} is
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
160 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
161 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
162 (read (get-buffer "foo"))
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
163 @result{} the
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
164 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
165
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
166 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
167 ---------- Buffer: foo ----------
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
168 This is the@point{} contents of foo.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
169 ---------- Buffer: foo ----------
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
170 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
171 @end example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
172
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
173 @noindent
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
174 Note that the first read skips a space. Reading skips any amount of
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
175 whitespace preceding the significant text.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
176
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
177 Here is an example of reading from a stream that is a marker,
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
178 initially positioned at the beginning of the buffer shown. The value
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
179 read is the symbol @code{This}.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
180
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
181 @example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
182 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
183
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
184 ---------- Buffer: foo ----------
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
185 This is the contents of foo.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
186 ---------- Buffer: foo ----------
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
187 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
188
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
189 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
190 (setq m (set-marker (make-marker) 1 (get-buffer "foo")))
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
191 @result{} #<marker at 1 in foo>
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
192 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
193 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
194 (read m)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
195 @result{} This
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
196 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
197 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
198 m
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
199 @result{} #<marker at 5 in foo> ;; @r{Before the first space.}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
200 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
201 @end example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
202
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
203 Here we read from the contents of a string:
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
204
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
205 @example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
206 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
207 (read "(When in) the course")
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
208 @result{} (When in)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
209 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
210 @end example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
211
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
212 The following example reads from the minibuffer. The
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
213 prompt is: @w{@samp{Lisp expression: }}. (That is always the prompt
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
214 used when you read from the stream @code{t}.) The user's input is shown
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
215 following the prompt.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
216
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
217 @example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
218 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
219 (read t)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
220 @result{} 23
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
221 ---------- Buffer: Minibuffer ----------
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
222 Lisp expression: @kbd{23 @key{RET}}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
223 ---------- Buffer: Minibuffer ----------
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
224 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
225 @end example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
226
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
227 Finally, here is an example of a stream that is a function, named
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
228 @code{useless-stream}. Before we use the stream, we initialize the
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
229 variable @code{useless-list} to a list of characters. Then each call to
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
230 the function @code{useless-stream} obtains the next character in the list
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
231 or unreads a character by adding it to the front of the list.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
232
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
233 @example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
234 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
235 (setq useless-list (append "XY()" nil))
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
236 @result{} (88 89 40 41)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
237 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
238
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
239 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
240 (defun useless-stream (&optional unread)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
241 (if unread
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
242 (setq useless-list (cons unread useless-list))
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
243 (prog1 (car useless-list)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
244 (setq useless-list (cdr useless-list)))))
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
245 @result{} useless-stream
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
246 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
247 @end example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
248
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
249 @noindent
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
250 Now we read using the stream thus constructed:
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
251
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
252 @example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
253 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
254 (read 'useless-stream)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
255 @result{} XY
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
256 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
257
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
258 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
259 useless-list
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
260 @result{} (40 41)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
261 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
262 @end example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
263
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
264 @noindent
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
265 Note that the open and close parentheses remain in the list. The Lisp
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
266 reader encountered the open parenthesis, decided that it ended the
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
267 input, and unread it. Another attempt to read from the stream at this
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
268 point would read @samp{()} and return @code{nil}.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
269
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
270 @defun get-file-char
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
271 This function is used internally as an input stream to read from the
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
272 input file opened by the function @code{load}. Don't use this function
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
273 yourself.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
274 @end defun
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
275
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
276 @node Input Functions
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
277 @section Input Functions
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
278
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
279 This section describes the Lisp functions and variables that pertain
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
280 to reading.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
281
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
282 In the functions below, @var{stream} stands for an input stream (see
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
283 the previous section). If @var{stream} is @code{nil} or omitted, it
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
284 defaults to the value of @code{standard-input}.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
285
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
286 @kindex end-of-file
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
287 An @code{end-of-file} error is signaled if reading encounters an
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
288 unterminated list, vector, or string.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
289
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
290 @defun read &optional stream
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
291 This function reads one textual Lisp expression from @var{stream},
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
292 returning it as a Lisp object. This is the basic Lisp input function.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
293 @end defun
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
294
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
295 @defun read-from-string string &optional start end
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
296 @cindex string to object
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
297 This function reads the first textual Lisp expression from the text in
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
298 @var{string}. It returns a cons cell whose @sc{car} is that expression,
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
299 and whose @sc{cdr} is an integer giving the position of the next
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
300 remaining character in the string (i.e., the first one not read).
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
301
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
302 If @var{start} is supplied, then reading begins at index @var{start} in
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
303 the string (where the first character is at index 0). If you specify
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
304 @var{end}, then reading is forced to stop just before that index, as if
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
305 the rest of the string were not there.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
306
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
307 For example:
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
308
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
309 @example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
310 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
311 (read-from-string "(setq x 55) (setq y 5)")
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
312 @result{} ((setq x 55) . 11)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
313 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
314 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
315 (read-from-string "\"A short string\"")
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
316 @result{} ("A short string" . 16)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
317 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
318
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
319 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
320 ;; @r{Read starting at the first character.}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
321 (read-from-string "(list 112)" 0)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
322 @result{} ((list 112) . 10)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
323 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
324 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
325 ;; @r{Read starting at the second character.}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
326 (read-from-string "(list 112)" 1)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
327 @result{} (list . 5)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
328 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
329 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
330 ;; @r{Read starting at the seventh character,}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
331 ;; @r{and stopping at the ninth.}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
332 (read-from-string "(list 112)" 6 8)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
333 @result{} (11 . 8)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
334 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
335 @end example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
336 @end defun
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
337
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
338 @defvar standard-input
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
339 This variable holds the default input stream---the stream that
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
340 @code{read} uses when the @var{stream} argument is @code{nil}.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
341 The default is @code{t}, meaning use the minibuffer.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
342 @end defvar
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
343
103102
789636652cc9 * variables.texi (File Local Variables): Note that read-circle is
Chong Yidong <cyd@stupidchicken.com>
parents: 100974
diff changeset
344 @defvar read-circle
789636652cc9 * variables.texi (File Local Variables): Note that read-circle is
Chong Yidong <cyd@stupidchicken.com>
parents: 100974
diff changeset
345 If non-@code{nil}, this variable enables the reading of circular and
789636652cc9 * variables.texi (File Local Variables): Note that read-circle is
Chong Yidong <cyd@stupidchicken.com>
parents: 100974
diff changeset
346 shared structures. @xref{Circular Objects}. Its default value is
789636652cc9 * variables.texi (File Local Variables): Note that read-circle is
Chong Yidong <cyd@stupidchicken.com>
parents: 100974
diff changeset
347 @code{t}.
789636652cc9 * variables.texi (File Local Variables): Note that read-circle is
Chong Yidong <cyd@stupidchicken.com>
parents: 100974
diff changeset
348 @end defvar
789636652cc9 * variables.texi (File Local Variables): Note that read-circle is
Chong Yidong <cyd@stupidchicken.com>
parents: 100974
diff changeset
349
84099
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
350 @node Output Streams
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
351 @section Output Streams
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
352 @cindex stream (for printing)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
353 @cindex output stream
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
354
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
355 An output stream specifies what to do with the characters produced
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
356 by printing. Most print functions accept an output stream as an
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
357 optional argument. Here are the possible types of output stream:
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
358
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
359 @table @asis
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
360 @item @var{buffer}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
361 @cindex buffer output stream
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
362 The output characters are inserted into @var{buffer} at point.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
363 Point advances as characters are inserted.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
364
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
365 @item @var{marker}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
366 @cindex marker output stream
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
367 The output characters are inserted into the buffer that @var{marker}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
368 points into, at the marker position. The marker position advances as
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
369 characters are inserted. The value of point in the buffer has no effect
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
370 on printing when the stream is a marker, and this kind of printing
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
371 does not move point (except that if the marker points at or before the
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
372 position of point, point advances with the surrounding text, as
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
373 usual).
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
374
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
375 @item @var{function}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
376 @cindex function output stream
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
377 The output characters are passed to @var{function}, which is responsible
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
378 for storing them away. It is called with a single character as
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
379 argument, as many times as there are characters to be output, and
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
380 is responsible for storing the characters wherever you want to put them.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
381
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
382 @item @code{t}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
383 @cindex @code{t} output stream
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
384 The output characters are displayed in the echo area.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
385
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
386 @item @code{nil}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
387 @cindex @code{nil} output stream
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
388 @code{nil} specified as an output stream means to use the value of
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
389 @code{standard-output} instead; that value is the @dfn{default output
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
390 stream}, and must not be @code{nil}.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
391
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
392 @item @var{symbol}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
393 A symbol as output stream is equivalent to the symbol's function
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
394 definition (if any).
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
395 @end table
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
396
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
397 Many of the valid output streams are also valid as input streams. The
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
398 difference between input and output streams is therefore more a matter
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
399 of how you use a Lisp object, than of different types of object.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
400
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
401 Here is an example of a buffer used as an output stream. Point is
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
402 initially located as shown immediately before the @samp{h} in
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
403 @samp{the}. At the end, point is located directly before that same
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
404 @samp{h}.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
405
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
406 @cindex print example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
407 @example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
408 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
409 ---------- Buffer: foo ----------
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
410 This is t@point{}he contents of foo.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
411 ---------- Buffer: foo ----------
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
412 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
413
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
414 (print "This is the output" (get-buffer "foo"))
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
415 @result{} "This is the output"
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
416
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
417 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
418 ---------- Buffer: foo ----------
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
419 This is t
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
420 "This is the output"
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
421 @point{}he contents of foo.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
422 ---------- Buffer: foo ----------
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
423 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
424 @end example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
425
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
426 Now we show a use of a marker as an output stream. Initially, the
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
427 marker is in buffer @code{foo}, between the @samp{t} and the @samp{h} in
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
428 the word @samp{the}. At the end, the marker has advanced over the
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
429 inserted text so that it remains positioned before the same @samp{h}.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
430 Note that the location of point, shown in the usual fashion, has no
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
431 effect.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
432
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
433 @example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
434 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
435 ---------- Buffer: foo ----------
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
436 This is the @point{}output
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
437 ---------- Buffer: foo ----------
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
438 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
439
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
440 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
441 (setq m (copy-marker 10))
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
442 @result{} #<marker at 10 in foo>
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
443 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
444
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
445 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
446 (print "More output for foo." m)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
447 @result{} "More output for foo."
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
448 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
449
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
450 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
451 ---------- Buffer: foo ----------
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
452 This is t
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
453 "More output for foo."
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
454 he @point{}output
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
455 ---------- Buffer: foo ----------
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
456 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
457
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
458 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
459 m
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
460 @result{} #<marker at 34 in foo>
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
461 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
462 @end example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
463
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
464 The following example shows output to the echo area:
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
465
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
466 @example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
467 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
468 (print "Echo Area output" t)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
469 @result{} "Echo Area output"
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
470 ---------- Echo Area ----------
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
471 "Echo Area output"
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
472 ---------- Echo Area ----------
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
473 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
474 @end example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
475
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
476 Finally, we show the use of a function as an output stream. The
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
477 function @code{eat-output} takes each character that it is given and
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
478 conses it onto the front of the list @code{last-output} (@pxref{Building
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
479 Lists}). At the end, the list contains all the characters output, but
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
480 in reverse order.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
481
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
482 @example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
483 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
484 (setq last-output nil)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
485 @result{} nil
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
486 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
487
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
488 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
489 (defun eat-output (c)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
490 (setq last-output (cons c last-output)))
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
491 @result{} eat-output
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
492 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
493
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
494 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
495 (print "This is the output" 'eat-output)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
496 @result{} "This is the output"
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
497 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
498
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
499 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
500 last-output
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
501 @result{} (10 34 116 117 112 116 117 111 32 101 104
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
502 116 32 115 105 32 115 105 104 84 34 10)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
503 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
504 @end example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
505
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
506 @noindent
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
507 Now we can put the output in the proper order by reversing the list:
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
508
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
509 @example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
510 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
511 (concat (nreverse last-output))
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
512 @result{} "
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
513 \"This is the output\"
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
514 "
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
515 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
516 @end example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
517
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
518 @noindent
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
519 Calling @code{concat} converts the list to a string so you can see its
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
520 contents more clearly.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
521
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
522 @node Output Functions
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
523 @section Output Functions
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
524
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
525 This section describes the Lisp functions for printing Lisp
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
526 objects---converting objects into their printed representation.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
527
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
528 @cindex @samp{"} in printing
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
529 @cindex @samp{\} in printing
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
530 @cindex quoting characters in printing
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
531 @cindex escape characters in printing
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
532 Some of the Emacs printing functions add quoting characters to the
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
533 output when necessary so that it can be read properly. The quoting
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
534 characters used are @samp{"} and @samp{\}; they distinguish strings from
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
535 symbols, and prevent punctuation characters in strings and symbols from
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
536 being taken as delimiters when reading. @xref{Printed Representation},
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
537 for full details. You specify quoting or no quoting by the choice of
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
538 printing function.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
539
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
540 If the text is to be read back into Lisp, then you should print with
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
541 quoting characters to avoid ambiguity. Likewise, if the purpose is to
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
542 describe a Lisp object clearly for a Lisp programmer. However, if the
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
543 purpose of the output is to look nice for humans, then it is usually
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
544 better to print without quoting.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
545
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
546 Lisp objects can refer to themselves. Printing a self-referential
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
547 object in the normal way would require an infinite amount of text, and
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
548 the attempt could cause infinite recursion. Emacs detects such
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
549 recursion and prints @samp{#@var{level}} instead of recursively printing
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
550 an object already being printed. For example, here @samp{#0} indicates
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
551 a recursive reference to the object at level 0 of the current print
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
552 operation:
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
553
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
554 @example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
555 (setq foo (list nil))
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
556 @result{} (nil)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
557 (setcar foo foo)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
558 @result{} (#0)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
559 @end example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
560
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
561 In the functions below, @var{stream} stands for an output stream.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
562 (See the previous section for a description of output streams.) If
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
563 @var{stream} is @code{nil} or omitted, it defaults to the value of
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
564 @code{standard-output}.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
565
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
566 @defun print object &optional stream
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
567 @cindex Lisp printer
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
568 The @code{print} function is a convenient way of printing. It outputs
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
569 the printed representation of @var{object} to @var{stream}, printing in
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
570 addition one newline before @var{object} and another after it. Quoting
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
571 characters are used. @code{print} returns @var{object}. For example:
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
572
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
573 @example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
574 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
575 (progn (print 'The\ cat\ in)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
576 (print "the hat")
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
577 (print " came back"))
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
578 @print{}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
579 @print{} The\ cat\ in
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
580 @print{}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
581 @print{} "the hat"
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
582 @print{}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
583 @print{} " came back"
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
584 @result{} " came back"
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
585 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
586 @end example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
587 @end defun
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
588
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
589 @defun prin1 object &optional stream
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
590 This function outputs the printed representation of @var{object} to
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
591 @var{stream}. It does not print newlines to separate output as
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
592 @code{print} does, but it does use quoting characters just like
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
593 @code{print}. It returns @var{object}.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
594
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
595 @example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
596 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
597 (progn (prin1 'The\ cat\ in)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
598 (prin1 "the hat")
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
599 (prin1 " came back"))
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
600 @print{} The\ cat\ in"the hat"" came back"
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
601 @result{} " came back"
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
602 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
603 @end example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
604 @end defun
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
605
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
606 @defun princ object &optional stream
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
607 This function outputs the printed representation of @var{object} to
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
608 @var{stream}. It returns @var{object}.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
609
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
610 This function is intended to produce output that is readable by people,
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
611 not by @code{read}, so it doesn't insert quoting characters and doesn't
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
612 put double-quotes around the contents of strings. It does not add any
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
613 spacing between calls.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
614
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
615 @example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
616 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
617 (progn
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
618 (princ 'The\ cat)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
619 (princ " in the \"hat\""))
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
620 @print{} The cat in the "hat"
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
621 @result{} " in the \"hat\""
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
622 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
623 @end example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
624 @end defun
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
625
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
626 @defun terpri &optional stream
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
627 @cindex newline in print
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
628 This function outputs a newline to @var{stream}. The name stands
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
629 for ``terminate print.''
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
630 @end defun
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
631
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
632 @defun write-char character &optional stream
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
633 This function outputs @var{character} to @var{stream}. It returns
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
634 @var{character}.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
635 @end defun
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
636
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
637 @defun prin1-to-string object &optional noescape
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
638 @cindex object to string
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
639 This function returns a string containing the text that @code{prin1}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
640 would have printed for the same argument.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
641
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
642 @example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
643 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
644 (prin1-to-string 'foo)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
645 @result{} "foo"
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
646 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
647 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
648 (prin1-to-string (mark-marker))
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
649 @result{} "#<marker at 2773 in strings.texi>"
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
650 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
651 @end example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
652
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
653 If @var{noescape} is non-@code{nil}, that inhibits use of quoting
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
654 characters in the output. (This argument is supported in Emacs versions
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
655 19 and later.)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
656
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
657 @example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
658 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
659 (prin1-to-string "foo")
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
660 @result{} "\"foo\""
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
661 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
662 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
663 (prin1-to-string "foo" t)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
664 @result{} "foo"
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
665 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
666 @end example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
667
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
668 See @code{format}, in @ref{Formatting Strings}, for other ways to obtain
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
669 the printed representation of a Lisp object as a string.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
670 @end defun
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
671
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
672 @defmac with-output-to-string body@dots{}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
673 This macro executes the @var{body} forms with @code{standard-output} set
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
674 up to feed output into a string. Then it returns that string.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
675
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
676 For example, if the current buffer name is @samp{foo},
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
677
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
678 @example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
679 (with-output-to-string
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
680 (princ "The buffer is ")
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
681 (princ (buffer-name)))
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
682 @end example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
683
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
684 @noindent
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
685 returns @code{"The buffer is foo"}.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
686 @end defmac
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
687
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
688 @node Output Variables
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
689 @section Variables Affecting Output
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
690 @cindex output-controlling variables
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
691
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
692 @defvar standard-output
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
693 The value of this variable is the default output stream---the stream
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
694 that print functions use when the @var{stream} argument is @code{nil}.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
695 The default is @code{t}, meaning display in the echo area.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
696 @end defvar
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
697
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
698 @defvar print-quoted
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
699 If this is non-@code{nil}, that means to print quoted forms using
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
700 abbreviated reader syntax. @code{(quote foo)} prints as @code{'foo},
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
701 @code{(function foo)} as @code{#'foo}, and backquoted forms print
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
702 using modern backquote syntax.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
703 @end defvar
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
704
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
705 @defvar print-escape-newlines
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
706 @cindex @samp{\n} in print
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
707 @cindex escape characters
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
708 If this variable is non-@code{nil}, then newline characters in strings
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
709 are printed as @samp{\n} and formfeeds are printed as @samp{\f}.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
710 Normally these characters are printed as actual newlines and formfeeds.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
711
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
712 This variable affects the print functions @code{prin1} and @code{print}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
713 that print with quoting. It does not affect @code{princ}. Here is an
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
714 example using @code{prin1}:
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
715
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
716 @example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
717 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
718 (prin1 "a\nb")
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
719 @print{} "a
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
720 @print{} b"
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
721 @result{} "a
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
722 b"
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
723 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
724
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
725 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
726 (let ((print-escape-newlines t))
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
727 (prin1 "a\nb"))
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
728 @print{} "a\nb"
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
729 @result{} "a
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
730 b"
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
731 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
732 @end example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
733
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
734 @noindent
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
735 In the second expression, the local binding of
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
736 @code{print-escape-newlines} is in effect during the call to
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
737 @code{prin1}, but not during the printing of the result.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
738 @end defvar
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
739
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
740 @defvar print-escape-nonascii
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
741 If this variable is non-@code{nil}, then unibyte non-@acronym{ASCII}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
742 characters in strings are unconditionally printed as backslash sequences
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
743 by the print functions @code{prin1} and @code{print} that print with
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
744 quoting.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
745
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
746 Those functions also use backslash sequences for unibyte non-@acronym{ASCII}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
747 characters, regardless of the value of this variable, when the output
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
748 stream is a multibyte buffer or a marker pointing into one.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
749 @end defvar
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
750
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
751 @defvar print-escape-multibyte
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
752 If this variable is non-@code{nil}, then multibyte non-@acronym{ASCII}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
753 characters in strings are unconditionally printed as backslash sequences
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
754 by the print functions @code{prin1} and @code{print} that print with
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
755 quoting.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
756
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
757 Those functions also use backslash sequences for multibyte
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
758 non-@acronym{ASCII} characters, regardless of the value of this variable,
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
759 when the output stream is a unibyte buffer or a marker pointing into
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
760 one.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
761 @end defvar
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
762
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
763 @defvar print-length
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
764 @cindex printing limits
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
765 The value of this variable is the maximum number of elements to print in
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
766 any list, vector or bool-vector. If an object being printed has more
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
767 than this many elements, it is abbreviated with an ellipsis.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
768
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
769 If the value is @code{nil} (the default), then there is no limit.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
770
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
771 @example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
772 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
773 (setq print-length 2)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
774 @result{} 2
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
775 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
776 @group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
777 (print '(1 2 3 4 5))
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
778 @print{} (1 2 ...)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
779 @result{} (1 2 ...)
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
780 @end group
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
781 @end example
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
782 @end defvar
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
783
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
784 @defvar print-level
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
785 The value of this variable is the maximum depth of nesting of
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
786 parentheses and brackets when printed. Any list or vector at a depth
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
787 exceeding this limit is abbreviated with an ellipsis. A value of
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
788 @code{nil} (which is the default) means no limit.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
789 @end defvar
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
790
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
791 @defopt eval-expression-print-length
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
792 @defoptx eval-expression-print-level
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
793 These are the values for @code{print-length} and @code{print-level}
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
794 used by @code{eval-expression}, and thus, indirectly, by many
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
795 interactive evaluation commands (@pxref{Lisp Eval,, Evaluating
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
796 Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}).
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
797 @end defopt
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
798
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
799 These variables are used for detecting and reporting circular
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
800 and shared structure:
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
801
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
802 @defvar print-circle
103102
789636652cc9 * variables.texi (File Local Variables): Note that read-circle is
Chong Yidong <cyd@stupidchicken.com>
parents: 100974
diff changeset
803 If non-@code{nil}, this variable enables detection of circular and
103103
4a7a1526ee6d Fix typo.
Chong Yidong <cyd@stupidchicken.com>
parents: 103102
diff changeset
804 shared structure in printing. @xref{Circular Objects}.
84099
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
805 @end defvar
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
806
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
807 @defvar print-gensym
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
808 If non-@code{nil}, this variable enables detection of uninterned symbols
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
809 (@pxref{Creating Symbols}) in printing. When this is enabled,
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
810 uninterned symbols print with the prefix @samp{#:}, which tells the Lisp
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
811 reader to produce an uninterned symbol.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
812 @end defvar
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
813
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
814 @defvar print-continuous-numbering
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
815 If non-@code{nil}, that means number continuously across print calls.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
816 This affects the numbers printed for @samp{#@var{n}=} labels and
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
817 @samp{#@var{m}#} references.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
818
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
819 Don't set this variable with @code{setq}; you should only bind it
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
820 temporarily to @code{t} with @code{let}. When you do that, you should
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
821 also bind @code{print-number-table} to @code{nil}.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
822 @end defvar
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
823
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
824 @defvar print-number-table
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
825 This variable holds a vector used internally by printing to implement
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
826 the @code{print-circle} feature. You should not use it except
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
827 to bind it to @code{nil} when you bind @code{print-continuous-numbering}.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
828 @end defvar
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
829
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
830 @defvar float-output-format
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
831 This variable specifies how to print floating point numbers. Its
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
832 default value is @code{nil}, meaning use the shortest output
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
833 that represents the number without losing information.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
834
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
835 To control output format more precisely, you can put a string in this
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
836 variable. The string should hold a @samp{%}-specification to be used
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
837 in the C function @code{sprintf}. For further restrictions on what
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
838 you can use, see the variable's documentation string.
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
839 @end defvar
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
840
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
841 @ignore
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
842 arch-tag: 07636b8c-c4e3-4735-9e06-2e864320b434
083e24ed6f4d Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
843 @end ignore