streams.texi 25.3 KB
Newer Older
Richard M. Stallman's avatar
Richard M. Stallman committed
1 2
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
3 4
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2002, 2003, 2004,
@c   2005 Free Software Foundation, Inc.
Richard M. Stallman's avatar
Richard M. Stallman committed
5 6
@c See the file elisp.texi for copying conditions.
@setfilename ../info/streams
7
@node Read and Print, Minibuffers, Debugging, Top
Richard M. Stallman's avatar
Richard M. Stallman committed
8 9 10 11 12
@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
13
representations and read syntax described in @ref{Lisp Data Types}.
Richard M. Stallman's avatar
Richard M. Stallman committed
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

  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
42 43 44
object---converting the object to its @dfn{printed representation}
(@pxref{Printed Representation}).  Printing the cons cell described
above produces the text @samp{(a .@: 5)}.
Richard M. Stallman's avatar
Richard M. Stallman committed
45 46 47 48 49 50 51 52

  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
Richard M. Stallman's avatar
Richard M. Stallman committed
53
text produces a list (but not the same list) with elements @code{a}
Richard M. Stallman's avatar
Richard M. Stallman committed
54 55
and @code{b}.

Phillip Rulon's avatar
Phillip Rulon committed
56 57
  However, these two operations are not precisely inverse to each other.
There are three kinds of exceptions:
Richard M. Stallman's avatar
Richard M. Stallman committed
58 59 60 61

@itemize @bullet
@item
Printing can produce text that cannot be read.  For example, buffers,
62
windows, frames, subprocesses and markers print as text that starts
Richard M. Stallman's avatar
Richard M. Stallman committed
63 64 65 66 67 68 69 70
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.
Karl Heuer's avatar
Karl Heuer committed
71 72 73 74

@item
Comments can appear at certain points in the middle of an object's
read sequence without affecting the result of reading it.
Richard M. Stallman's avatar
Richard M. Stallman committed
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
@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
107 108 109 110 111 112 113 114 115 116 117 118 119 120 121
The input characters are generated by @var{function}, which must support
two kinds of calls:

@itemize @bullet
@item
When it is called with no arguments, it should return the next character.

@item
When it is called with one argument (always a character), @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''.  In this case, it makes no difference what value
@var{function} returns.
@end itemize
Richard M. Stallman's avatar
Richard M. Stallman committed
122 123 124 125 126 127

@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
Dave Love's avatar
Dave Love committed
128 129 130 131 132 133 134
input stream.  If Emacs is running in batch mode, standard input is used
instead of the minibuffer.  For example,
@example
(message "%s" (read t))
@end example
will read a Lisp expression from standard input and print the result
to standard output.
Richard M. Stallman's avatar
Richard M. Stallman committed
135 136 137 138 139 140 141 142 143 144 145 146

@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

Richard M. Stallman's avatar
Richard M. Stallman committed
147
  Here is an example of reading from a stream that is a buffer, showing
Richard M. Stallman's avatar
Richard M. Stallman committed
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
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
Richard M. Stallman's avatar
Richard M. Stallman committed
174 175
Note that the first read skips a space.  Reading skips any amount of
whitespace preceding the significant text.
Richard M. Stallman's avatar
Richard M. Stallman committed
176 177

  Here is an example of reading from a stream that is a marker,
Richard M. Stallman's avatar
Richard M. Stallman committed
178
initially positioned at the beginning of the buffer shown.  The value
Richard M. Stallman's avatar
Richard M. Stallman committed
179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198
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
Richard M. Stallman's avatar
Richard M. Stallman committed
199
     @result{} #<marker at 5 in foo>   ;; @r{Before the first space.}
Richard M. Stallman's avatar
Richard M. Stallman committed
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
@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
Richard M. Stallman's avatar
Richard M. Stallman committed
230
the function @code{useless-stream} obtains the next character in the list
Richard M. Stallman's avatar
Richard M. Stallman committed
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
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
Richard M. Stallman's avatar
Richard M. Stallman committed
260
     @result{} (40 41)
Richard M. Stallman's avatar
Richard M. Stallman committed
261 262 263 264
@end group
@end example

@noindent
265
Note that the open and close parentheses remain in the list.  The Lisp
Richard M. Stallman's avatar
Richard M. Stallman committed
266 267 268
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}.
Richard M. Stallman's avatar
Richard M. Stallman committed
269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287

@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
Richard M. Stallman's avatar
Richard M. Stallman committed
288
unterminated list, vector, or string.
Richard M. Stallman's avatar
Richard M. Stallman committed
289 290 291 292 293 294 295 296 297 298 299 300 301

@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).

Richard M. Stallman's avatar
Richard M. Stallman committed
302
If @var{start} is supplied, then reading begins at index @var{start} in
303 304 305
the string (where the first character is at index 0).  If you specify
@var{end}, then reading is forced to stop just before that index, as if
the rest of the string were not there.
Richard M. Stallman's avatar
Richard M. Stallman committed
306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326

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)
Richard M. Stallman's avatar
Richard M. Stallman committed
327
     @result{} (list . 5)
Richard M. Stallman's avatar
Richard M. Stallman committed
328 329 330 331 332 333 334 335 336 337 338 339 340
@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}.
341
The default is @code{t}, meaning use the minibuffer.
Richard M. Stallman's avatar
Richard M. Stallman committed
342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361
@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}
Richard M. Stallman's avatar
Richard M. Stallman committed
362
points into, at the marker position.  The marker position advances as
Richard M. Stallman's avatar
Richard M. Stallman committed
363
characters are inserted.  The value of point in the buffer has no effect
364
on printing when the stream is a marker, and this kind of printing
365 366 367
does not move point (except that if the marker points at or before the
position of point, point advances with the surrounding text, as
usual).
Richard M. Stallman's avatar
Richard M. Stallman committed
368 369 370 371 372

@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
373 374
argument, as many times as there are characters to be output, and
is responsible for storing the characters wherever you want to put them.
Richard M. Stallman's avatar
Richard M. Stallman committed
375 376 377 378 379 380 381

@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
382
@code{nil} specified as an output stream means to use the value of
Richard M. Stallman's avatar
Richard M. Stallman committed
383
@code{standard-output} instead; that value is the @dfn{default output
384
stream}, and must not be @code{nil}.
Richard M. Stallman's avatar
Richard M. Stallman committed
385 386 387 388 389 390

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

Richard M. Stallman's avatar
Richard M. Stallman committed
391
  Many of the valid output streams are also valid as input streams.  The
392 393
difference between input and output streams is therefore more a matter
of how you use a Lisp object, than of different types of object.
Richard M. Stallman's avatar
Richard M. Stallman committed
394

Richard M. Stallman's avatar
Richard M. Stallman committed
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
  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
Richard M. Stallman's avatar
Richard M. Stallman committed
421 422 423 424 425
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.
Richard M. Stallman's avatar
Richard M. Stallman committed
426 427 428 429

@example
@group
---------- Buffer: foo ----------
430
This is the @point{}output
Richard M. Stallman's avatar
Richard M. Stallman committed
431 432 433 434
---------- Buffer: foo ----------
@end group

@group
435 436
(setq m (copy-marker 10))
     @result{} #<marker at 10 in foo>
Richard M. Stallman's avatar
Richard M. Stallman committed
437 438 439 440 441 442 443 444 445
@end group

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

@group
---------- Buffer: foo ----------
446
This is t
Richard M. Stallman's avatar
Richard M. Stallman committed
447
"More output for foo."
448
he @point{}output
Richard M. Stallman's avatar
Richard M. Stallman committed
449 450 451 452 453
---------- Buffer: foo ----------
@end group

@group
m
454
     @result{} #<marker at 34 in foo>
Richard M. Stallman's avatar
Richard M. Stallman committed
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
@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
495
     @result{} (10 34 116 117 112 116 117 111 32 101 104
Richard M. Stallman's avatar
Richard M. Stallman committed
496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511
    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

Richard M. Stallman's avatar
Richard M. Stallman committed
512 513 514 515
@noindent
Calling @code{concat} converts the list to a string so you can see its
contents more clearly.

Richard M. Stallman's avatar
Richard M. Stallman committed
516 517 518
@node Output Functions
@section Output Functions

519 520
  This section describes the Lisp functions for printing Lisp
objects---converting objects into their printed representation.
Richard M. Stallman's avatar
Richard M. Stallman committed
521 522 523 524 525 526 527 528 529

@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
Richard M. Stallman's avatar
Richard M. Stallman committed
530 531 532
being taken as delimiters when reading.  @xref{Printed Representation},
for full details.  You specify quoting or no quoting by the choice of
printing function.
Richard M. Stallman's avatar
Richard M. Stallman committed
533

534 535 536 537 538
  If the text is to be read back into Lisp, then you should 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 usually
better to print without quoting.
Richard M. Stallman's avatar
Richard M. Stallman committed
539

540 541 542 543 544 545 546
  Lisp objects can refer to themselves.  Printing a self-referential
object in the normal way would require an infinite amount of text, and
the attempt could cause infinite recursion.  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:
Richard M. Stallman's avatar
Richard M. Stallman committed
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

@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"))
572
     @print{}
Richard M. Stallman's avatar
Richard M. Stallman committed
573
     @print{} The\ cat\ in
574
     @print{}
Richard M. Stallman's avatar
Richard M. Stallman committed
575
     @print{} "the hat"
576
     @print{}
Richard M. Stallman's avatar
Richard M. Stallman committed
577 578 579 580 581 582 583 584
     @print{} " came back"
     @result{} " came back"
@end group
@end example
@end defun

@defun prin1 object &optional stream
This function outputs the printed representation of @var{object} to
Richard M. Stallman's avatar
Richard M. Stallman committed
585 586 587
@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}.
Richard M. Stallman's avatar
Richard M. Stallman committed
588 589 590

@example
@group
591 592
(progn (prin1 'The\ cat\ in)
       (prin1 "the hat")
Richard M. Stallman's avatar
Richard M. Stallman committed
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
       (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

662
See @code{format}, in @ref{Formatting Strings}, for other ways to obtain
Richard M. Stallman's avatar
Richard M. Stallman committed
663 664 665
the printed representation of a Lisp object as a string.
@end defun

666
@defmac with-output-to-string body@dots{}
667 668
This macro executes the @var{body} forms with @code{standard-output} set
up to feed output into a string.  Then it returns that string.
669 670 671 672 673 674 675 676 677 678 679 680 681

For example, if the current buffer name is @samp{foo},

@example
(with-output-to-string
  (princ "The buffer is ")
  (princ (buffer-name)))
@end example

@noindent
returns @code{"The buffer is foo"}.
@end defmac

Richard M. Stallman's avatar
Richard M. Stallman committed
682 683 684 685 686 687
@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}.
688
The default is @code{t}, meaning display in the echo area.
Richard M. Stallman's avatar
Richard M. Stallman committed
689 690
@end defvar

691 692 693 694 695 696 697
@defvar print-quoted
If this is non-@code{nil}, that means to print quoted forms using
abbreviated reader syntax.  @code{(quote foo)} prints as @code{'foo},
@code{(function foo)} as @code{#'foo}, and backquoted forms print
using modern backquote syntax.
@end defvar

Richard M. Stallman's avatar
Richard M. Stallman committed
698 699 700 701 702 703 704
@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.

705 706 707
This variable affects the print functions @code{prin1} and @code{print}
that print with quoting.  It does not affect @code{princ}.  Here is an
example using @code{prin1}:
Richard M. Stallman's avatar
Richard M. Stallman committed
708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732

@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

733
@defvar print-escape-nonascii
734
If this variable is non-@code{nil}, then unibyte non-@acronym{ASCII}
735 736 737
characters in strings are unconditionally printed as backslash sequences
by the print functions @code{prin1} and @code{print} that print with
quoting.
738

739
Those functions also use backslash sequences for unibyte non-@acronym{ASCII}
740 741 742 743 744
characters, regardless of the value of this variable, when the output
stream is a multibyte buffer or a marker pointing into one.
@end defvar

@defvar print-escape-multibyte
745
If this variable is non-@code{nil}, then multibyte non-@acronym{ASCII}
746 747 748 749 750
characters in strings are unconditionally printed as backslash sequences
by the print functions @code{prin1} and @code{print} that print with
quoting.

Those functions also use backslash sequences for multibyte
751
non-@acronym{ASCII} characters, regardless of the value of this variable,
752 753
when the output stream is a unibyte buffer or a marker pointing into
one.
754 755
@end defvar

Richard M. Stallman's avatar
Richard M. Stallman committed
756 757
@defvar print-length
@cindex printing limits
758 759 760
The value of this variable is the maximum number of elements to print in
any list, vector or bool-vector.  If an object being printed has more
than this many elements, it is abbreviated with an ellipsis.
Richard M. Stallman's avatar
Richard M. Stallman committed
761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778

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
Richard M. Stallman's avatar
Richard M. Stallman committed
779
parentheses and brackets when printed.  Any list or vector at a depth
Richard M. Stallman's avatar
Richard M. Stallman committed
780 781 782
exceeding this limit is abbreviated with an ellipsis.  A value of
@code{nil} (which is the default) means no limit.
@end defvar
783

784 785 786 787 788 789 790 791
@defopt eval-expression-print-length
@defoptx eval-expression-print-level
These are the values for @code{print-length} and @code{print-level}
used by @code{eval-expression}, and thus, indirectly, by many
interactive evaluation commands (@pxref{Lisp Eval,, Evaluating
Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}).
@end defopt

792
  These variables are used for detecting and reporting circular
793
and shared structure:
794 795 796

@tindex print-circle
@defvar print-circle
797
If non-@code{nil}, this variable enables detection of circular
798 799 800 801 802 803 804 805 806 807
and shared structure in printing.
@end defvar

@tindex print-gensym
@defvar print-gensym
If non-@code{nil}, this variable enables detection of uninterned symbols
(@pxref{Creating Symbols}) in printing.  When this is enabled,
uninterned symbols print with the prefix @samp{#:}, which tells the Lisp
reader to produce an uninterned symbol.
@end defvar
808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823

@defvar print-continuous-numbering
If non-@code{nil}, that means number continuously across print calls.
This affects the numbers printed for @samp{#@var{n}=} labels and
@samp{#@var{m}#} references.

Don't set this variable with @code{setq}; you should only bind it
temporarily to @code{t} with @code{let}.  When you do that, you should
also bind @code{print-number-table} to @code{nil}.
@end defvar

@defvar print-number-table
This variable holds a vector used internally by printing to implement
the @code{print-circle} feature.  You should not use it except
to bind it to @code{nil} when you bind @code{print-continuous-numbering}.
@end defvar
Miles Bader's avatar
Miles Bader committed
824

825 826 827 828 829 830 831 832 833 834 835
@defvar float-output-format
This variable specifies how to print floating point numbers.  Its
default value is @code{nil}, meaning use the shortest output
that represents the number without losing information.

To control output format more precisely, you can put a string in this
variable.  The string should hold a @samp{%}-specification to be used
in the C function @code{sprintf}.  For further restrictions on what
you can use, see the variable's documentation string.
@end defvar

Miles Bader's avatar
Miles Bader committed
836 837 838
@ignore
   arch-tag: 07636b8c-c4e3-4735-9e06-2e864320b434
@end ignore