summaryrefslogtreecommitdiff
path: root/lispref/streams.texi
blob: db7e9aa38ea8e1ba38dd54ed2bd1cca42970452d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/streams
@node Read and Print, Minibuffers, Debugging, Top
@comment  node-name,  next,  previous,  up
@chapter Reading and Printing Lisp Objects

  @dfn{Printing} and @dfn{reading} are the operations of converting Lisp
objects to textual form and vice versa.  They use the printed
representations and read syntax described in @ref{Lisp Data Types}.

  This chapter describes the Lisp functions for reading and printing.
It also describes @dfn{streams}, which specify where to get the text (if
reading) or where to put it (if printing).

@menu
* Streams Intro::     Overview of streams, reading and printing.
* Input Streams::     Various data types that can be used as input streams.
* Input Functions::   Functions to read Lisp objects from text.
* Output Streams::    Various data types that can be used as output streams.
* Output Functions::  Functions to print Lisp objects as text.
* Output Variables::  Variables that control what the printing functions do.
@end menu

@node Streams Intro
@section Introduction to Reading and Printing
@cindex Lisp reader
@cindex printing
@cindex reading

  @dfn{Reading} a Lisp object means parsing a Lisp expression in textual
form and producing a corresponding Lisp object.  This is how Lisp
programs get into Lisp from files of Lisp code.  We call the text the
@dfn{read syntax} of the object.  For example, the text @samp{(a .@: 5)}
is the read syntax for a cons cell whose @sc{car} is @code{a} and whose
@sc{cdr} is the number 5.

  @dfn{Printing} a Lisp object means producing text that represents that
object---converting the object to its printed representation.  Printing
the cons cell described above produces the text @samp{(a .@: 5)}.

  Reading and printing are more or less inverse operations: printing the
object that results from reading a given piece of text often produces
the same text, and reading the text that results from printing an object
usually produces a similar-looking object.  For example, printing the
symbol @code{foo} produces the text @samp{foo}, and reading that text
returns the symbol @code{foo}.  Printing a list whose elements are
@code{a} and @code{b} produces the text @samp{(a b)}, and reading that
text produces a list (but not the same list) with elements @code{a}
and @code{b}.

  However, these two operations are not precisely inverses.  There are
three kinds of exceptions:

@itemize @bullet
@item
Printing can produce text that cannot be read.  For example, buffers,
windows, frames, subprocesses and markers print into text that starts
with @samp{#}; if you try to read this text, you get an error.  There is
no way to read those data types.

@item
One object can have multiple textual representations.  For example,
@samp{1} and @samp{01} represent the same integer, and @samp{(a b)} and
@samp{(a .@: (b))} represent the same list.  Reading will accept any of
the alternatives, but printing must choose one of them.

@item
Comments can appear at certain points in the middle of an object's
read sequence without affecting the result of reading it.
@end itemize

@node Input Streams
@section Input Streams
@cindex stream (for reading)
@cindex input stream

  Most of the Lisp functions for reading text take an @dfn{input stream}
as an argument.  The input stream specifies where or how to get the
characters of the text to be read.  Here are the possible types of input
stream:

@table @asis
@item @var{buffer}
@cindex buffer input stream
The input characters are read from @var{buffer}, starting with the
character directly after point.  Point advances as characters are read.

@item @var{marker}
@cindex marker input stream
The input characters are read from the buffer that @var{marker} is in,
starting with the character directly after the marker.  The marker
position advances as characters are read.  The value of point in the
buffer has no effect when the stream is a marker.

@item @var{string}
@cindex string input stream
The input characters are taken from @var{string}, starting at the first
character in the string and using as many characters as required.

@item @var{function}
@cindex function input stream
The input characters are generated by @var{function}, one character per
call.  Normally @var{function} is called with no arguments, and should
return a character.

@cindex unreading
Occasionally @var{function} is called with one argument (always a
character).  When that happens, @var{function} should save the argument
and arrange to return it on the next call.  This is called
@dfn{unreading} the character; it happens when the Lisp reader reads one
character too many and wants to ``put it back where it came from''.

@item @code{t}
@cindex @code{t} input stream
@code{t} used as a stream means that the input is read from the
minibuffer.  In fact, the minibuffer is invoked once and the text
given by the user is made into a string that is then used as the
input stream.

@item @code{nil}
@cindex @code{nil} input stream
@code{nil} supplied as an input stream means to use the value of
@code{standard-input} instead; that value is the @dfn{default input
stream}, and must be a non-@code{nil} input stream.

@item @var{symbol}
A symbol as input stream is equivalent to the symbol's function
definition (if any).
@end table

  Here is an example of reading from a stream that is a buffer, showing
where point is located before and after:

@example
@group
---------- Buffer: foo ----------
This@point{} is the contents of foo.
---------- Buffer: foo ----------
@end group

@group
(read (get-buffer "foo"))
     @result{} is
@end group
@group
(read (get-buffer "foo"))
     @result{} the
@end group

@group
---------- Buffer: foo ----------
This is the@point{} contents of foo.
---------- Buffer: foo ----------
@end group
@end example

@noindent
Note that the first read skips a space.  Reading skips any amount of
whitespace preceding the significant text.

  In Emacs 18, reading a symbol discarded the delimiter terminating the
symbol.  Thus, point would end up at the beginning of @samp{contents}
rather than after @samp{the}.  The Emacs 19 behavior is superior because
it correctly handles input such as @samp{bar(foo)}, where the
open-parenthesis that ends one object is needed as the beginning of
another object.

  Here is an example of reading from a stream that is a marker,
initially positioned at the beginning of the buffer shown.  The value
read is the symbol @code{This}.

@example
@group

---------- Buffer: foo ----------
This is the contents of foo.
---------- Buffer: foo ----------
@end group

@group
(setq m (set-marker (make-marker) 1 (get-buffer "foo")))
     @result{} #<marker at 1 in foo>
@end group
@group
(read m)
     @result{} This
@end group
@group
m
     @result{} #<marker at 5 in foo>   ;; @r{Before the first space.}
@end group
@end example

  Here we read from the contents of a string:

@example
@group
(read "(When in) the course")
     @result{} (When in)
@end group
@end example

  The following example reads from the minibuffer.  The
prompt is: @w{@samp{Lisp expression: }}.  (That is always the prompt
used when you read from the stream @code{t}.)  The user's input is shown
following the prompt.

@example
@group
(read t)
     @result{} 23
---------- Buffer: Minibuffer ----------
Lisp expression: @kbd{23 @key{RET}}
---------- Buffer: Minibuffer ----------
@end group
@end example

  Finally, here is an example of a stream that is a function, named
@code{useless-stream}.  Before we use the stream, we initialize the
variable @code{useless-list} to a list of characters.  Then each call to
the function @code{useless-stream} obtains the next character in the list
or unreads a character by adding it to the front of the list.

@example
@group
(setq useless-list (append "XY()" nil))
     @result{} (88 89 40 41)
@end group

@group
(defun useless-stream (&optional unread)
  (if unread
      (setq useless-list (cons unread useless-list))
    (prog1 (car useless-list)
           (setq useless-list (cdr useless-list)))))
     @result{} useless-stream
@end group
@end example

@noindent
Now we read using the stream thus constructed:

@example
@group
(read 'useless-stream)
     @result{} XY
@end group

@group
useless-list
     @result{} (40 41)
@end group
@end example

@noindent
Note that the open and close parentheses remains in the list.  The Lisp
reader encountered the open parenthesis, decided that it ended the
input, and unread it.  Another attempt to read from the stream at this
point would read @samp{()} and return @code{nil}.

@defun get-file-char
This function is used internally as an input stream to read from the
input file opened by the function @code{load}.  Don't use this function
yourself.
@end defun

@node Input Functions
@section Input Functions

  This section describes the Lisp functions and variables that pertain
to reading.

  In the functions below, @var{stream} stands for an input stream (see
the previous section).  If @var{stream} is @code{nil} or omitted, it
defaults to the value of @code{standard-input}.

@kindex end-of-file
  An @code{end-of-file} error is signaled if reading encounters an
unterminated list, vector, or string.

@defun read &optional stream
This function reads one textual Lisp expression from @var{stream},
returning it as a Lisp object.  This is the basic Lisp input function.
@end defun

@defun read-from-string string &optional start end
@cindex string to object
This function reads the first textual Lisp expression from the text in
@var{string}.  It returns a cons cell whose @sc{car} is that expression,
and whose @sc{cdr} is an integer giving the position of the next
remaining character in the string (i.e., the first one not read).

If @var{start} is supplied, then reading begins at index @var{start} in
the string (where the first character is at index 0).  If @var{end} is
also supplied, then reading stops just before that index, as if the rest
of the string were not there.

For example:

@example
@group
(read-from-string "(setq x 55) (setq y 5)")
     @result{} ((setq x 55) . 11)
@end group
@group
(read-from-string "\"A short string\"")
     @result{} ("A short string" . 16)
@end group

@group
;; @r{Read starting at the first character.}
(read-from-string "(list 112)" 0)
     @result{} ((list 112) . 10)
@end group
@group
;; @r{Read starting at the second character.}
(read-from-string "(list 112)" 1)
     @result{} (list . 5)
@end group
@group
;; @r{Read starting at the seventh character,}
;;   @r{and stopping at the ninth.}
(read-from-string "(list 112)" 6 8)
     @result{} (11 . 8)
@end group
@end example
@end defun

@defvar standard-input
This variable holds the default input stream---the stream that
@code{read} uses when the @var{stream} argument is @code{nil}.
@end defvar

@node Output Streams
@section Output Streams
@cindex stream (for printing)
@cindex output stream

  An output stream specifies what to do with the characters produced
by printing.  Most print functions accept an output stream as an
optional argument.  Here are the possible types of output stream:

@table @asis
@item @var{buffer}
@cindex buffer output stream
The output characters are inserted into @var{buffer} at point.
Point advances as characters are inserted.

@item @var{marker}
@cindex marker output stream
The output characters are inserted into the buffer that @var{marker}
points into, at the marker position.  The marker position advances as
characters are inserted.  The value of point in the buffer has no effect
on printing when the stream is a marker.

@item @var{function}
@cindex function output stream
The output characters are passed to @var{function}, which is responsible
for storing them away.  It is called with a single character as
argument, as many times as there are characters to be output, and is
free to do anything at all with the characters it receives.

@item @code{t}
@cindex @code{t} output stream
The output characters are displayed in the echo area.

@item @code{nil}
@cindex @code{nil} output stream
@code{nil} specified as an output stream means to the value of
@code{standard-output} instead; that value is the @dfn{default output
stream}, and must be a non-@code{nil} output stream.

@item @var{symbol}
A symbol as output stream is equivalent to the symbol's function
definition (if any).
@end table

  Many of the valid output streams are also valid as input streams.  The
difference between input and output streams is therefore mostly one of
how you use a Lisp object, not a distinction of types of object.

  Here is an example of a buffer used as an output stream.  Point is
initially located as shown immediately before the @samp{h} in
@samp{the}.  At the end, point is located directly before that same
@samp{h}.

@cindex print example
@example
@group
---------- Buffer: foo ----------
This is t@point{}he contents of foo.
---------- Buffer: foo ----------
@end group

(print "This is the output" (get-buffer "foo"))
     @result{} "This is the output"

@group
---------- Buffer: foo ----------
This is t
"This is the output"
@point{}he contents of foo.
---------- Buffer: foo ----------
@end group
@end example

  Now we show a use of a marker as an output stream.  Initially, the
marker is in buffer @code{foo}, between the @samp{t} and the @samp{h} in
the word @samp{the}.  At the end, the marker has advanced over the
inserted text so that it remains positioned before the same @samp{h}.
Note that the location of point, shown in the usual fashion, has no
effect.

@example
@group
---------- Buffer: foo ----------
"This is the @point{}output"
---------- Buffer: foo ----------
@end group

@group
m
     @result{} #<marker at 11 in foo>
@end group

@group
(print "More output for foo." m)
     @result{} "More output for foo."
@end group

@group
---------- Buffer: foo ----------
"This is t
"More output for foo."
he @point{}output"
---------- Buffer: foo ----------
@end group

@group
m
     @result{} #<marker at 35 in foo>
@end group
@end example

  The following example shows output to the echo area:

@example
@group
(print "Echo Area output" t)
     @result{} "Echo Area output"
---------- Echo Area ----------
"Echo Area output"
---------- Echo Area ----------
@end group
@end example

  Finally, we show the use of a function as an output stream.  The
function @code{eat-output} takes each character that it is given and
conses it onto the front of the list @code{last-output} (@pxref{Building
Lists}).  At the end, the list contains all the characters output, but
in reverse order.

@example
@group
(setq last-output nil)
     @result{} nil
@end group

@group
(defun eat-output (c)
  (setq last-output (cons c last-output)))
     @result{} eat-output
@end group

@group
(print "This is the output" 'eat-output)
     @result{} "This is the output"
@end group

@group
last-output
     @result{} (10 34 116 117 112 116 117 111 32 101 104 
    116 32 115 105 32 115 105 104 84 34 10)
@end group
@end example

@noindent
Now we can put the output in the proper order by reversing the list:

@example
@group
(concat (nreverse last-output))
     @result{} "
\"This is the output\"
"
@end group
@end example

@noindent
Calling @code{concat} converts the list to a string so you can see its
contents more clearly.

@node Output Functions
@section Output Functions

  This section describes the Lisp functions for printing Lisp objects.

@cindex @samp{"} in printing
@cindex @samp{\} in printing
@cindex quoting characters in printing
@cindex escape characters in printing
  Some of the Emacs printing functions add quoting characters to the
output when necessary so that it can be read properly.  The quoting
characters used are @samp{"} and @samp{\}; they distinguish strings from
symbols, and prevent punctuation characters in strings and symbols from
being taken as delimiters when reading.  @xref{Printed Representation},
for full details.  You specify quoting or no quoting by the choice of
printing function.

  If the text is to be read back into Lisp, then it is best to print
with quoting characters to avoid ambiguity.  Likewise, if the purpose is
to describe a Lisp object clearly for a Lisp programmer.  However, if
the purpose of the output is to look nice for humans, then it is better
to print without quoting.

  Printing a self-referent Lisp object requires an infinite amount of
text.  In certain cases, trying to produce this text leads to a stack
overflow.  Emacs detects such recursion and prints @samp{#@var{level}}
instead of recursively printing an object already being printed.  For
example, here @samp{#0} indicates a recursive reference to the object at
level 0 of the current print operation:

@example
(setq foo (list nil))
     @result{} (nil)
(setcar foo foo)
     @result{} (#0)
@end example

  In the functions below, @var{stream} stands for an output stream.
(See the previous section for a description of output streams.)  If
@var{stream} is @code{nil} or omitted, it defaults to the value of
@code{standard-output}.

@defun print object &optional stream
@cindex Lisp printer
The @code{print} function is a convenient way of printing.  It outputs
the printed representation of @var{object} to @var{stream}, printing in
addition one newline before @var{object} and another after it.  Quoting
characters are used.  @code{print} returns @var{object}.  For example:

@example
@group
(progn (print 'The\ cat\ in)
       (print "the hat")
       (print " came back"))
     @print{} 
     @print{} The\ cat\ in
     @print{} 
     @print{} "the hat"
     @print{} 
     @print{} " came back"
     @print{} 
     @result{} " came back"
@end group
@end example
@end defun

@defun prin1 object &optional stream
This function outputs the printed representation of @var{object} to
@var{stream}.  It does not print newlines to separate output as
@code{print} does, but it does use quoting characters just like
@code{print}.  It returns @var{object}.

@example
@group
(progn (prin1 'The\ cat\ in) 
       (prin1 "the hat") 
       (prin1 " came back"))
     @print{} The\ cat\ in"the hat"" came back"
     @result{} " came back"
@end group
@end example
@end defun

@defun princ object &optional stream
This function outputs the printed representation of @var{object} to
@var{stream}.  It returns @var{object}.

This function is intended to produce output that is readable by people,
not by @code{read}, so it doesn't insert quoting characters and doesn't
put double-quotes around the contents of strings.  It does not add any
spacing between calls.

@example
@group
(progn
  (princ 'The\ cat)
  (princ " in the \"hat\""))
     @print{} The cat in the "hat"
     @result{} " in the \"hat\""
@end group
@end example
@end defun

@defun terpri &optional stream
@cindex newline in print
This function outputs a newline to @var{stream}.  The name stands
for ``terminate print''.
@end defun

@defun write-char character &optional stream
This function outputs @var{character} to @var{stream}.  It returns
@var{character}.
@end defun

@defun prin1-to-string object &optional noescape
@cindex object to string
This function returns a string containing the text that @code{prin1}
would have printed for the same argument.

@example
@group
(prin1-to-string 'foo)
     @result{} "foo"
@end group
@group
(prin1-to-string (mark-marker))
     @result{} "#<marker at 2773 in strings.texi>"
@end group
@end example

If @var{noescape} is non-@code{nil}, that inhibits use of quoting
characters in the output.  (This argument is supported in Emacs versions
19 and later.)

@example
@group
(prin1-to-string "foo")
     @result{} "\"foo\""
@end group
@group
(prin1-to-string "foo" t)
     @result{} "foo"
@end group
@end example

See @code{format}, in @ref{String Conversion}, for other ways to obtain
the printed representation of a Lisp object as a string.
@end defun

@node Output Variables
@section Variables Affecting Output

@defvar standard-output
The value of this variable is the default output stream---the stream
that print functions use when the @var{stream} argument is @code{nil}.
@end defvar

@defvar print-escape-newlines
@cindex @samp{\n} in print
@cindex escape characters
If this variable is non-@code{nil}, then newline characters in strings
are printed as @samp{\n} and formfeeds are printed as @samp{\f}.
Normally these characters are printed as actual newlines and formfeeds.

This variable affects the print functions @code{prin1} and @code{print},
as well as everything that uses them.  It does not affect @code{princ}.
Here is an example using @code{prin1}:

@example
@group
(prin1 "a\nb")
     @print{} "a
     @print{} b"
     @result{} "a
b"
@end group

@group
(let ((print-escape-newlines t))
  (prin1 "a\nb"))
     @print{} "a\nb"
     @result{} "a
b"
@end group
@end example

@noindent
In the second expression, the local binding of
@code{print-escape-newlines} is in effect during the call to
@code{prin1}, but not during the printing of the result.
@end defvar

@defvar print-length
@cindex printing limits
The value of this variable is the maximum number of elements of a list
that will be printed.  If a list being printed has more than this many
elements, it is abbreviated with an ellipsis.

If the value is @code{nil} (the default), then there is no limit.

@example
@group
(setq print-length 2)
     @result{} 2
@end group
@group
(print '(1 2 3 4 5))
     @print{} (1 2 ...)
     @result{} (1 2 ...)
@end group
@end example
@end defvar

@defvar print-level
The value of this variable is the maximum depth of nesting of
parentheses and brackets when printed.  Any list or vector at a depth
exceeding this limit is abbreviated with an ellipsis.  A value of
@code{nil} (which is the default) means no limit.

This variable exists in version 19 and later versions.
@end defvar