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