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