annotate lispref/streams.texi @ 18647:72b27986e71d

(Finsert_file_contents): If enable-multibyte-characters is nil, decode character code by emacs-mule. (Fwrite_region): Use buffer-file-coding-system for encoding if enable-multibyte-characters is nil.
author Kenichi Handa <handa@m17n.org>
date Mon, 07 Jul 1997 00:59:44 +0000
parents 18c0e05d1bff
children 66d807bdc5b4
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4 @c See the file elisp.texi for copying conditions.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @setfilename ../info/streams
7115
9a9e88e65617 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6381
diff changeset
6 @node Read and Print, Minibuffers, Debugging, Top
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
7 @comment node-name, next, previous, up
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8 @chapter Reading and Printing Lisp Objects
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10 @dfn{Printing} and @dfn{reading} are the operations of converting Lisp
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11 objects to textual form and vice versa. They use the printed
7115
9a9e88e65617 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6381
diff changeset
12 representations and read syntax described in @ref{Lisp Data Types}.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 This chapter describes the Lisp functions for reading and printing.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15 It also describes @dfn{streams}, which specify where to get the text (if
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
16 reading) or where to put it (if printing).
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
17
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
18 @menu
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
19 * Streams Intro:: Overview of streams, reading and printing.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20 * Input Streams:: Various data types that can be used as input streams.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
21 * Input Functions:: Functions to read Lisp objects from text.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
22 * Output Streams:: Various data types that can be used as output streams.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
23 * Output Functions:: Functions to print Lisp objects as text.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
24 * Output Variables:: Variables that control what the printing functions do.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
25 @end menu
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
26
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
27 @node Streams Intro
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28 @section Introduction to Reading and Printing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29 @cindex Lisp reader
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30 @cindex printing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31 @cindex reading
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
33 @dfn{Reading} a Lisp object means parsing a Lisp expression in textual
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
34 form and producing a corresponding Lisp object. This is how Lisp
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
35 programs get into Lisp from files of Lisp code. We call the text the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
36 @dfn{read syntax} of the object. For example, the text @samp{(a .@: 5)}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37 is the read syntax for a cons cell whose @sc{car} is @code{a} and whose
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
38 @sc{cdr} is the number 5.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
39
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
40 @dfn{Printing} a Lisp object means producing text that represents that
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
41 object---converting the object to its printed representation. Printing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
42 the cons cell described above produces the text @samp{(a .@: 5)}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
43
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
44 Reading and printing are more or less inverse operations: printing the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
45 object that results from reading a given piece of text often produces
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
46 the same text, and reading the text that results from printing an object
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47 usually produces a similar-looking object. For example, printing the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
48 symbol @code{foo} produces the text @samp{foo}, and reading that text
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
49 returns the symbol @code{foo}. Printing a list whose elements are
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
50 @code{a} and @code{b} produces the text @samp{(a b)}, and reading that
7219
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
51 text produces a list (but not the same list) with elements @code{a}
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
52 and @code{b}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
53
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
54 However, these two operations are not precisely inverses. There are
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7219
diff changeset
55 three kinds of exceptions:
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
56
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
57 @itemize @bullet
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
58 @item
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59 Printing can produce text that cannot be read. For example, buffers,
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60 windows, frames, subprocesses and markers print into text that starts
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61 with @samp{#}; if you try to read this text, you get an error. There is
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62 no way to read those data types.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
64 @item
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65 One object can have multiple textual representations. For example,
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66 @samp{1} and @samp{01} represent the same integer, and @samp{(a b)} and
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67 @samp{(a .@: (b))} represent the same list. Reading will accept any of
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
68 the alternatives, but printing must choose one of them.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7219
diff changeset
69
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7219
diff changeset
70 @item
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7219
diff changeset
71 Comments can appear at certain points in the middle of an object's
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7219
diff changeset
72 read sequence without affecting the result of reading it.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
73 @end itemize
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
74
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
75 @node Input Streams
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
76 @section Input Streams
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
77 @cindex stream (for reading)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78 @cindex input stream
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
80 Most of the Lisp functions for reading text take an @dfn{input stream}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
81 as an argument. The input stream specifies where or how to get the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
82 characters of the text to be read. Here are the possible types of input
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
83 stream:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
84
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
85 @table @asis
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
86 @item @var{buffer}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87 @cindex buffer input stream
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
88 The input characters are read from @var{buffer}, starting with the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
89 character directly after point. Point advances as characters are read.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
90
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
91 @item @var{marker}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
92 @cindex marker input stream
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
93 The input characters are read from the buffer that @var{marker} is in,
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
94 starting with the character directly after the marker. The marker
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
95 position advances as characters are read. The value of point in the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
96 buffer has no effect when the stream is a marker.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
97
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
98 @item @var{string}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
99 @cindex string input stream
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
100 The input characters are taken from @var{string}, starting at the first
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
101 character in the string and using as many characters as required.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
102
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103 @item @var{function}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104 @cindex function input stream
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105 The input characters are generated by @var{function}, one character per
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
106 call. Normally @var{function} is called with no arguments, and should
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
107 return a character.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
108
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
109 @cindex unreading
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
110 Occasionally @var{function} is called with one argument (always a
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
111 character). When that happens, @var{function} should save the argument
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
112 and arrange to return it on the next call. This is called
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
113 @dfn{unreading} the character; it happens when the Lisp reader reads one
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
114 character too many and wants to ``put it back where it came from''.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
116 @item @code{t}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
117 @cindex @code{t} input stream
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118 @code{t} used as a stream means that the input is read from the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119 minibuffer. In fact, the minibuffer is invoked once and the text
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120 given by the user is made into a string that is then used as the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
121 input stream.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
122
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
123 @item @code{nil}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
124 @cindex @code{nil} input stream
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
125 @code{nil} supplied as an input stream means to use the value of
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
126 @code{standard-input} instead; that value is the @dfn{default input
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
127 stream}, and must be a non-@code{nil} input stream.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
128
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
129 @item @var{symbol}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
130 A symbol as input stream is equivalent to the symbol's function
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 definition (if any).
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132 @end table
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133
7219
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
134 Here is an example of reading from a stream that is a buffer, showing
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
135 where point is located before and after:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137 @example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
138 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139 ---------- Buffer: foo ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140 This@point{} is the contents of foo.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
141 ---------- Buffer: foo ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
142 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
143
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
144 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
145 (read (get-buffer "foo"))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
146 @result{} is
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
147 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
148 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
149 (read (get-buffer "foo"))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
150 @result{} the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
151 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
152
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
153 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
154 ---------- Buffer: foo ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
155 This is the@point{} contents of foo.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
156 ---------- Buffer: foo ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
157 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
158 @end example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
159
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
160 @noindent
7219
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
161 Note that the first read skips a space. Reading skips any amount of
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
162 whitespace preceding the significant text.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
163
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
164 In Emacs 18, reading a symbol discarded the delimiter terminating the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
165 symbol. Thus, point would end up at the beginning of @samp{contents}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
166 rather than after @samp{the}. The Emacs 19 behavior is superior because
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7219
diff changeset
167 it correctly handles input such as @samp{bar(foo)}, where the
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7219
diff changeset
168 open-parenthesis that ends one object is needed as the beginning of
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7219
diff changeset
169 another object.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
171 Here is an example of reading from a stream that is a marker,
7219
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
172 initially positioned at the beginning of the buffer shown. The value
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173 read is the symbol @code{This}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
175 @example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
177
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
178 ---------- Buffer: foo ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
179 This is the contents of foo.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
180 ---------- Buffer: foo ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
181 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
182
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
183 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
184 (setq m (set-marker (make-marker) 1 (get-buffer "foo")))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
185 @result{} #<marker at 1 in foo>
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
186 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
187 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
188 (read m)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
189 @result{} This
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
190 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
191 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
192 m
7219
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
193 @result{} #<marker at 5 in foo> ;; @r{Before the first space.}
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
194 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
195 @end example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
196
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
197 Here we read from the contents of a string:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
198
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
199 @example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
200 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
201 (read "(When in) the course")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
202 @result{} (When in)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
203 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
204 @end example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
205
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
206 The following example reads from the minibuffer. The
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
207 prompt is: @w{@samp{Lisp expression: }}. (That is always the prompt
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
208 used when you read from the stream @code{t}.) The user's input is shown
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
209 following the prompt.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
210
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
211 @example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
212 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
213 (read t)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214 @result{} 23
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
215 ---------- Buffer: Minibuffer ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
216 Lisp expression: @kbd{23 @key{RET}}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
217 ---------- Buffer: Minibuffer ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
219 @end example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
221 Finally, here is an example of a stream that is a function, named
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222 @code{useless-stream}. Before we use the stream, we initialize the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 variable @code{useless-list} to a list of characters. Then each call to
7219
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
224 the function @code{useless-stream} obtains the next character in the list
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225 or unreads a character by adding it to the front of the list.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
227 @example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
228 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
229 (setq useless-list (append "XY()" nil))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230 @result{} (88 89 40 41)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
232
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
233 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
234 (defun useless-stream (&optional unread)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
235 (if unread
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
236 (setq useless-list (cons unread useless-list))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
237 (prog1 (car useless-list)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
238 (setq useless-list (cdr useless-list)))))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
239 @result{} useless-stream
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
240 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
241 @end example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
242
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
243 @noindent
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
244 Now we read using the stream thus constructed:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246 @example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
247 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248 (read 'useless-stream)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249 @result{} XY
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
251
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
252 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
253 useless-list
7219
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
254 @result{} (40 41)
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
255 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
256 @end example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
257
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
258 @noindent
7219
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
259 Note that the open and close parentheses remains in the list. The Lisp
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
260 reader encountered the open parenthesis, decided that it ended the
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
261 input, and unread it. Another attempt to read from the stream at this
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
262 point would read @samp{()} and return @code{nil}.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
264 @defun get-file-char
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
265 This function is used internally as an input stream to read from the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
266 input file opened by the function @code{load}. Don't use this function
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
267 yourself.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
270 @node Input Functions
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271 @section Input Functions
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
272
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
273 This section describes the Lisp functions and variables that pertain
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274 to reading.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
275
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276 In the functions below, @var{stream} stands for an input stream (see
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
277 the previous section). If @var{stream} is @code{nil} or omitted, it
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278 defaults to the value of @code{standard-input}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280 @kindex end-of-file
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
281 An @code{end-of-file} error is signaled if reading encounters an
7219
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
282 unterminated list, vector, or string.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
283
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
284 @defun read &optional stream
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285 This function reads one textual Lisp expression from @var{stream},
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286 returning it as a Lisp object. This is the basic Lisp input function.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
288
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
289 @defun read-from-string string &optional start end
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
290 @cindex string to object
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
291 This function reads the first textual Lisp expression from the text in
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
292 @var{string}. It returns a cons cell whose @sc{car} is that expression,
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
293 and whose @sc{cdr} is an integer giving the position of the next
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294 remaining character in the string (i.e., the first one not read).
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295
7219
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
296 If @var{start} is supplied, then reading begins at index @var{start} in
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
297 the string (where the first character is at index 0). If @var{end} is
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
298 also supplied, then reading stops just before that index, as if the rest
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
299 of the string were not there.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
300
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
301 For example:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
302
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
303 @example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
305 (read-from-string "(setq x 55) (setq y 5)")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
306 @result{} ((setq x 55) . 11)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
307 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
308 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
309 (read-from-string "\"A short string\"")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310 @result{} ("A short string" . 16)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
311 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
312
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
313 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
314 ;; @r{Read starting at the first character.}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
315 (read-from-string "(list 112)" 0)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
316 @result{} ((list 112) . 10)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
318 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319 ;; @r{Read starting at the second character.}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
320 (read-from-string "(list 112)" 1)
7219
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
321 @result{} (list . 5)
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
322 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
323 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
324 ;; @r{Read starting at the seventh character,}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
325 ;; @r{and stopping at the ninth.}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
326 (read-from-string "(list 112)" 6 8)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
327 @result{} (11 . 8)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
328 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
329 @end example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
330 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
332 @defvar standard-input
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
333 This variable holds the default input stream---the stream that
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
334 @code{read} uses when the @var{stream} argument is @code{nil}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335 @end defvar
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
336
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
337 @node Output Streams
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
338 @section Output Streams
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
339 @cindex stream (for printing)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
340 @cindex output stream
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
341
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342 An output stream specifies what to do with the characters produced
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343 by printing. Most print functions accept an output stream as an
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
344 optional argument. Here are the possible types of output stream:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
345
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
346 @table @asis
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
347 @item @var{buffer}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348 @cindex buffer output stream
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
349 The output characters are inserted into @var{buffer} at point.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350 Point advances as characters are inserted.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
351
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
352 @item @var{marker}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
353 @cindex marker output stream
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
354 The output characters are inserted into the buffer that @var{marker}
7219
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
355 points into, at the marker position. The marker position advances as
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
356 characters are inserted. The value of point in the buffer has no effect
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357 on printing when the stream is a marker.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
359 @item @var{function}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360 @cindex function output stream
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
361 The output characters are passed to @var{function}, which is responsible
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
362 for storing them away. It is called with a single character as
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
363 argument, as many times as there are characters to be output, and is
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
364 free to do anything at all with the characters it receives.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
365
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
366 @item @code{t}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
367 @cindex @code{t} output stream
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
368 The output characters are displayed in the echo area.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
369
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
370 @item @code{nil}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
371 @cindex @code{nil} output stream
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
372 @code{nil} specified as an output stream means to the value of
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
373 @code{standard-output} instead; that value is the @dfn{default output
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
374 stream}, and must be a non-@code{nil} output stream.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
375
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
376 @item @var{symbol}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
377 A symbol as output stream is equivalent to the symbol's function
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
378 definition (if any).
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
379 @end table
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
380
7219
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
381 Many of the valid output streams are also valid as input streams. The
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
382 difference between input and output streams is therefore mostly one of
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
383 how you use a Lisp object, not a distinction of types of object.
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
384
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
385 Here is an example of a buffer used as an output stream. Point is
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
386 initially located as shown immediately before the @samp{h} in
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
387 @samp{the}. At the end, point is located directly before that same
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
388 @samp{h}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
389
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
390 @cindex print example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
391 @example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
392 @group
15800
18c0e05d1bff Make examples in Output Streams stand on their own.
Richard M. Stallman <rms@gnu.org>
parents: 15763
diff changeset
393 (setq m (set-marker (make-marker) 10 (get-buffer "foo")))
18c0e05d1bff Make examples in Output Streams stand on their own.
Richard M. Stallman <rms@gnu.org>
parents: 15763
diff changeset
394 @result{} #<marker at 10 in foo>
18c0e05d1bff Make examples in Output Streams stand on their own.
Richard M. Stallman <rms@gnu.org>
parents: 15763
diff changeset
395 @end group
18c0e05d1bff Make examples in Output Streams stand on their own.
Richard M. Stallman <rms@gnu.org>
parents: 15763
diff changeset
396
18c0e05d1bff Make examples in Output Streams stand on their own.
Richard M. Stallman <rms@gnu.org>
parents: 15763
diff changeset
397 @group
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398 ---------- Buffer: foo ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
399 This is t@point{}he contents of foo.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
400 ---------- Buffer: foo ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
402
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
403 (print "This is the output" (get-buffer "foo"))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
404 @result{} "This is the output"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
406 @group
15800
18c0e05d1bff Make examples in Output Streams stand on their own.
Richard M. Stallman <rms@gnu.org>
parents: 15763
diff changeset
407 m
18c0e05d1bff Make examples in Output Streams stand on their own.
Richard M. Stallman <rms@gnu.org>
parents: 15763
diff changeset
408 @result{} #<marker at 32 in foo>
18c0e05d1bff Make examples in Output Streams stand on their own.
Richard M. Stallman <rms@gnu.org>
parents: 15763
diff changeset
409 @end group
18c0e05d1bff Make examples in Output Streams stand on their own.
Richard M. Stallman <rms@gnu.org>
parents: 15763
diff changeset
410 @group
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
411 ---------- Buffer: foo ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
412 This is t
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
413 "This is the output"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414 @point{}he contents of foo.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 ---------- Buffer: foo ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
416 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
417 @end example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
419 Now we show a use of a marker as an output stream. Initially, the
7219
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
420 marker is in buffer @code{foo}, between the @samp{t} and the @samp{h} in
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
421 the word @samp{the}. At the end, the marker has advanced over the
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
422 inserted text so that it remains positioned before the same @samp{h}.
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
423 Note that the location of point, shown in the usual fashion, has no
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
424 effect.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
426 @example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
427 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
428 ---------- Buffer: foo ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
429 "This is the @point{}output"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
430 ---------- Buffer: foo ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
431 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
432
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
433 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
434 m
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
435 @result{} #<marker at 11 in foo>
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
436 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
437
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
438 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
439 (print "More output for foo." m)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
440 @result{} "More output for foo."
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
441 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444 ---------- Buffer: foo ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445 "This is t
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446 "More output for foo."
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447 he @point{}output"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448 ---------- Buffer: foo ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
452 m
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
453 @result{} #<marker at 35 in foo>
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
455 @end example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457 The following example shows output to the echo area:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459 @example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461 (print "Echo Area output" t)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462 @result{} "Echo Area output"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463 ---------- Echo Area ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464 "Echo Area output"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 ---------- Echo Area ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467 @end example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
469 Finally, we show the use of a function as an output stream. The
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470 function @code{eat-output} takes each character that it is given and
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
471 conses it onto the front of the list @code{last-output} (@pxref{Building
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
472 Lists}). At the end, the list contains all the characters output, but
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
473 in reverse order.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
474
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
475 @example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
476 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477 (setq last-output nil)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
478 @result{} nil
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
479 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
480
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
481 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
482 (defun eat-output (c)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483 (setq last-output (cons c last-output)))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
484 @result{} eat-output
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
485 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
486
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
487 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
488 (print "This is the output" 'eat-output)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
489 @result{} "This is the output"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
490 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
491
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
492 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
493 last-output
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
494 @result{} (10 34 116 117 112 116 117 111 32 101 104
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
495 116 32 115 105 32 115 105 104 84 34 10)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
496 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
497 @end example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
498
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
499 @noindent
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
500 Now we can put the output in the proper order by reversing the list:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
501
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
502 @example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
503 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
504 (concat (nreverse last-output))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
505 @result{} "
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
506 \"This is the output\"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
507 "
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
508 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
509 @end example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
510
7219
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
511 @noindent
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
512 Calling @code{concat} converts the list to a string so you can see its
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
513 contents more clearly.
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
514
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
515 @node Output Functions
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
516 @section Output Functions
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
517
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
518 This section describes the Lisp functions for printing Lisp objects.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
519
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
520 @cindex @samp{"} in printing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
521 @cindex @samp{\} in printing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
522 @cindex quoting characters in printing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
523 @cindex escape characters in printing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
524 Some of the Emacs printing functions add quoting characters to the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
525 output when necessary so that it can be read properly. The quoting
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526 characters used are @samp{"} and @samp{\}; they distinguish strings from
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
527 symbols, and prevent punctuation characters in strings and symbols from
7219
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
528 being taken as delimiters when reading. @xref{Printed Representation},
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
529 for full details. You specify quoting or no quoting by the choice of
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
530 printing function.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
531
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
532 If the text is to be read back into Lisp, then it is best to print
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
533 with quoting characters to avoid ambiguity. Likewise, if the purpose is
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
534 to describe a Lisp object clearly for a Lisp programmer. However, if
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
535 the purpose of the output is to look nice for humans, then it is better
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
536 to print without quoting.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
537
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
538 Printing a self-referent Lisp object requires an infinite amount of
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 text. In certain cases, trying to produce this text leads to a stack
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
540 overflow. Emacs detects such recursion and prints @samp{#@var{level}}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
541 instead of recursively printing an object already being printed. For
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
542 example, here @samp{#0} indicates a recursive reference to the object at
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
543 level 0 of the current print operation:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
544
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
545 @example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
546 (setq foo (list nil))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
547 @result{} (nil)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548 (setcar foo foo)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
549 @result{} (#0)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
550 @end example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
552 In the functions below, @var{stream} stands for an output stream.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
553 (See the previous section for a description of output streams.) If
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
554 @var{stream} is @code{nil} or omitted, it defaults to the value of
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
555 @code{standard-output}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
556
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
557 @defun print object &optional stream
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
558 @cindex Lisp printer
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
559 The @code{print} function is a convenient way of printing. It outputs
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
560 the printed representation of @var{object} to @var{stream}, printing in
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561 addition one newline before @var{object} and another after it. Quoting
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
562 characters are used. @code{print} returns @var{object}. For example:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
564 @example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
565 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
566 (progn (print 'The\ cat\ in)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
567 (print "the hat")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
568 (print " came back"))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
569 @print{}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
570 @print{} The\ cat\ in
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
571 @print{}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
572 @print{} "the hat"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
573 @print{}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
574 @print{} " came back"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
575 @print{}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
576 @result{} " came back"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
577 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
578 @end example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
579 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
580
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
581 @defun prin1 object &optional stream
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
582 This function outputs the printed representation of @var{object} to
7219
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
583 @var{stream}. It does not print newlines to separate output as
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
584 @code{print} does, but it does use quoting characters just like
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
585 @code{print}. It returns @var{object}.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
587 @example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
588 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
589 (progn (prin1 'The\ cat\ in)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
590 (prin1 "the hat")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
591 (prin1 " came back"))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
592 @print{} The\ cat\ in"the hat"" came back"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
593 @result{} " came back"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
594 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
595 @end example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
596 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
597
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
598 @defun princ object &optional stream
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
599 This function outputs the printed representation of @var{object} to
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
600 @var{stream}. It returns @var{object}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
601
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
602 This function is intended to produce output that is readable by people,
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
603 not by @code{read}, so it doesn't insert quoting characters and doesn't
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
604 put double-quotes around the contents of strings. It does not add any
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
605 spacing between calls.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
606
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
607 @example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
608 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
609 (progn
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
610 (princ 'The\ cat)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
611 (princ " in the \"hat\""))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
612 @print{} The cat in the "hat"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
613 @result{} " in the \"hat\""
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
614 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
615 @end example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
616 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
617
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
618 @defun terpri &optional stream
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
619 @cindex newline in print
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
620 This function outputs a newline to @var{stream}. The name stands
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
621 for ``terminate print''.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
622 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
623
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
624 @defun write-char character &optional stream
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
625 This function outputs @var{character} to @var{stream}. It returns
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
626 @var{character}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
627 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
628
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
629 @defun prin1-to-string object &optional noescape
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
630 @cindex object to string
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
631 This function returns a string containing the text that @code{prin1}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
632 would have printed for the same argument.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
633
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
634 @example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
635 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
636 (prin1-to-string 'foo)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
637 @result{} "foo"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
638 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
639 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
640 (prin1-to-string (mark-marker))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
641 @result{} "#<marker at 2773 in strings.texi>"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
642 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
643 @end example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
644
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
645 If @var{noescape} is non-@code{nil}, that inhibits use of quoting
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
646 characters in the output. (This argument is supported in Emacs versions
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
647 19 and later.)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
648
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
649 @example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
650 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
651 (prin1-to-string "foo")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
652 @result{} "\"foo\""
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
653 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
654 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
655 (prin1-to-string "foo" t)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
656 @result{} "foo"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
657 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
658 @end example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
659
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
660 See @code{format}, in @ref{String Conversion}, for other ways to obtain
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
661 the printed representation of a Lisp object as a string.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
662 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
663
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
664 @node Output Variables
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
665 @section Variables Affecting Output
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
666
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
667 @defvar standard-output
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
668 The value of this variable is the default output stream---the stream
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
669 that print functions use when the @var{stream} argument is @code{nil}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
670 @end defvar
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
671
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
672 @defvar print-escape-newlines
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
673 @cindex @samp{\n} in print
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
674 @cindex escape characters
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
675 If this variable is non-@code{nil}, then newline characters in strings
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
676 are printed as @samp{\n} and formfeeds are printed as @samp{\f}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
677 Normally these characters are printed as actual newlines and formfeeds.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
678
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
679 This variable affects the print functions @code{prin1} and @code{print},
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
680 as well as everything that uses them. It does not affect @code{princ}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
681 Here is an example using @code{prin1}:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
682
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
683 @example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
684 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
685 (prin1 "a\nb")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
686 @print{} "a
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
687 @print{} b"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
688 @result{} "a
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
689 b"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
690 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
691
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
692 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
693 (let ((print-escape-newlines t))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
694 (prin1 "a\nb"))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
695 @print{} "a\nb"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
696 @result{} "a
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
697 b"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
698 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
699 @end example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
700
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
701 @noindent
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
702 In the second expression, the local binding of
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
703 @code{print-escape-newlines} is in effect during the call to
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
704 @code{prin1}, but not during the printing of the result.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
705 @end defvar
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
706
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
707 @defvar print-length
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
708 @cindex printing limits
15763
4263612ea038 print-length applies to vectors.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
709 The value of this variable is the maximum number of elements of a list,
4263612ea038 print-length applies to vectors.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
710 vector or bitvector that will be printed. If an object being printed has
4263612ea038 print-length applies to vectors.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
711 more than this many elements, it is abbreviated with an ellipsis.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
712
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
713 If the value is @code{nil} (the default), then there is no limit.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
714
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
715 @example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
716 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
717 (setq print-length 2)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
718 @result{} 2
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
719 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
720 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
721 (print '(1 2 3 4 5))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
722 @print{} (1 2 ...)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
723 @result{} (1 2 ...)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
724 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
725 @end example
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
726 @end defvar
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
727
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
728 @defvar print-level
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
729 The value of this variable is the maximum depth of nesting of
7219
61202823bbb9 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7115
diff changeset
730 parentheses and brackets when printed. Any list or vector at a depth
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
731 exceeding this limit is abbreviated with an ellipsis. A value of
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
732 @code{nil} (which is the default) means no limit.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
733
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
734 This variable exists in version 19 and later versions.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
735 @end defvar