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