unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
blob 89046a682492d8037bb197e1f33f058c7aa63d45 34946 bytes (raw)
name: doc/lispref/streams.texi 	 # note: path name is non-authoritative(*)

   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
 
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990--1994, 1998--1999, 2001--2023 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Read and Print
@chapter Reading and Printing Lisp Objects

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

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

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

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

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

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

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

  However, these two operations are not precisely inverse to each other.
There are three kinds of exceptions:

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

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

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

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

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

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

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

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

@item @var{function}
@cindex function input stream
The input characters are generated by @var{function}, 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

@item @code{t}
@cindex @code{t} input stream
@code{t} used as a stream means that the input is read from the
minibuffer.  In fact, the minibuffer is invoked once and the text
given by the user is made into a string that is then used as the
input stream.  If Emacs is running in batch mode (@pxref{Batch Mode}),
standard input is used instead of the minibuffer.  For example,
@example
(message "%s" (read t))
@end example
will in batch mode read a Lisp expression from standard input and
print the result to standard output.

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

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

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

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

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

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

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

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

@example
@group

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

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

  Here we read from the contents of a string:

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

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

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

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

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

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

@noindent
Now we read using the stream thus constructed:

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

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

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

@node Input Functions
@section Input Functions

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

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

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

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

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

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

For example:

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

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

@defun read-positioning-symbols &optional stream
This function reads one textual expression from @var{stream}, like
@code{read} does, but additionally positions the read symbols to the
positions in @var{stream} where they occurred.  Only the symbol
@code{nil} is not positioned, this for efficiency reasons.
@xref{Symbols with Position}.  This function is used by the byte
compiler.
@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}.
The default is @code{t}, meaning use the minibuffer.
@end defvar

@defvar read-circle
If non-@code{nil}, this variable enables the reading of circular and
shared structures.  @xref{Circular Objects}.  Its default value is
@code{t}.
@end defvar

@cindex binary I/O in batch mode
When reading or writing from the standard input/output streams of the
Emacs process in batch mode, it is sometimes required to make sure any
arbitrary binary data will be read/written verbatim, and/or that no
translation of newlines to or from CR-LF pairs is performed.  This
issue does not exist on POSIX hosts, only on MS-Windows and MS-DOS@.
The following function allows you to control the I/O mode of any
standard stream of the Emacs process.

@defun set-binary-mode stream mode
Switch @var{stream} into binary or text I/O mode.  If @var{mode} is
non-@code{nil}, switch to binary mode, otherwise switch to text mode.
The value of @var{stream} can be one of @code{stdin}, @code{stdout},
or @code{stderr}.  This function flushes any pending output data of
@var{stream} as a side effect, and returns the previous value of I/O
mode for @var{stream}.  On POSIX hosts, it always returns a
non-@code{nil} value and does nothing except flushing pending output.
@end defun

@defun readablep object
@cindex readable syntax
This predicate says whether @var{object} has @dfn{readable syntax},
i.e., it can be written out and then read back by the Emacs Lisp
reader.  If it can't, this function returns @code{nil}; if it can,
this function returns a printed representation (via @code{prin1},
@pxref{Output Functions}) of @var{object}.
@end defun

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

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

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

@item @var{marker}
@cindex marker output stream
The output characters are inserted into the buffer that @var{marker}
points into, at the marker position.  The marker position advances as
characters are inserted.  The value of point in the buffer has no effect
on printing when the stream is a marker, and this kind of printing
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).

@item @var{function}
@cindex function output stream
The output characters are passed to @var{function}, which is responsible
for storing them away.  It is called with a single character as
argument, as many times as there are characters to be output, and
is responsible for storing the characters wherever you want to put them.

@item @code{t}
@cindex @code{t} output stream
The output characters are displayed in the echo area.  If Emacs is
running in batch mode (@pxref{Batch Mode}), the output is written to
the standard output descriptor instead.

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

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

  Many of the valid output streams are also valid as input streams.  The
difference between input and output streams is therefore more a matter
of how you use a Lisp object, than of different types of object.

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

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

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

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

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

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

@group
(setq m (copy-marker 10))
     @result{} #<marker at 10 in foo>
@end group

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

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

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

  The following example shows output to the echo area:

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

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

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

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

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

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

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

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

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

@cindex @code{stderr} stream, use for debugging
@anchor{external-debugging-output}
@defun external-debugging-output character
This function can be useful as an output stream when debugging.  It
writes @var{character} to the standard error stream.

For example
@example
@group
(print "This is the output" #'external-debugging-output)
@print{} This is the output
@result{} "This is the output"
@end group
@end example
@end defun

@node Output Functions
@section Output Functions

  This section describes the Lisp functions for printing Lisp
objects---converting objects into their printed representation.

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

  If the text is to be read back into Lisp, then 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.

  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:

@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.  Also
@xref{external-debugging-output}, a useful stream value for debugging.)
If @var{stream} is @code{nil} or omitted, it defaults to the value of
@code{standard-output}.

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

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

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

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

If @var{overrides} is non-@code{nil}, it should either be @code{t}
(which tells @code{prin1} to use the defaults for all printer related
variables), or a list of settings.  @xref{Output Overrides}, for details.
@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 ensure
@cindex newline in print
This function outputs a newline to @var{stream}.  The name stands for
``terminate print''.  If @var{ensure} is non-@code{nil} no newline is printed
if @var{stream} is already at the beginning of a line.  Note in this
case @var{stream} can not be a function and an error is signaled if
it is.  This function returns @code{t} if a newline is printed.
@end defun

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

@defun flush-standard-output
If you have Emacs-based batch scripts that send output to the
terminal, Emacs will automatically display the output whenever you
write a newline characters to @code{standard-output}.  This function
allows you to flush to @code{standard-output} without sending a
newline character first, which enables you to display incomplete
lines.
@end defun

@defun prin1-to-string object &optional noescape overrides
@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

If @var{overrides} is non-@code{nil}, it should either be @code{t}
(which tells @code{prin1} to use the defaults for all printer related
variables), or a list of settings.  @xref{Output Overrides}, for details.
@end example

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

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

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

@defmac with-output-to-string body@dots{}
This macro executes the @var{body} forms with @code{standard-output} set
up to feed output into a string.  Then it returns that string.

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

@cindex pretty-printer
@defun pp object &optional stream
This function outputs @var{object} to @var{stream}, just like
@code{prin1}, but does it in a prettier way.  That is, it'll
indent and fill the object to make it more readable for humans.
@end defun

If you need to use binary I/O in batch mode, e.g., use the functions
described in this section to write out arbitrary binary data or avoid
conversion of newlines on non-POSIX hosts, see @ref{Input Functions,
set-binary-mode}.

@node Output Variables
@section Variables Affecting Output
@cindex output-controlling variables

@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}.
The default is @code{t}, meaning display in the echo area.
@end defvar

@defvar print-quoted
If this is non-@code{nil}, that means to print quoted forms using
abbreviated reader syntax, e.g., @code{(quote foo)} prints as
@code{'foo}, and @code{(function foo)} as @code{#'foo}.  The default
is @code{t}.
@end defvar

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

This variable affects the print functions @code{prin1} and @code{print}
that print with quoting.  It does not affect @code{princ}.  Here is an
example using @code{prin1}:

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

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

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

@defvar print-escape-control-characters
If this variable is non-@code{nil}, control characters in strings are
printed as backslash sequences by the print functions @code{prin1} and
@code{print} that print with quoting.  If this variable and
@code{print-escape-newlines} are both non-@code{nil}, the latter takes
precedences for newlines and formfeeds.
@end defvar

@defvar print-escape-nonascii
If this variable is non-@code{nil}, then unibyte non-@acronym{ASCII}
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 unibyte non-@acronym{ASCII}
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
If this variable is non-@code{nil}, then multibyte non-@acronym{ASCII}
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
non-@acronym{ASCII} characters, regardless of the value of this variable,
when the output stream is a unibyte buffer or a marker pointing into
one.
@end defvar

@defvar print-charset-text-property
This variable controls printing of `charset' text property on printing
a string.  The value should be @code{nil}, @code{t}, or
@code{default}.

If the value is @code{nil}, @code{charset} text properties are never
printed.  If @code{t}, they are always printed.

If the value is @code{default}, only print @code{charset} text
properties if there is an ``unexpected'' @code{charset} property.  For
ascii characters, all charsets are considered ``expected''.
Otherwise, the expected @code{charset} property of a character is
given by @code{char-charset}.
@end defvar

@defvar print-length
@cindex printing limits
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.

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

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

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

@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

  These variables are used for detecting and reporting circular
and shared structure:

@defvar print-circle
If non-@code{nil}, this variable enables detection of circular and
shared structure in printing.  @xref{Circular Objects}.
@end defvar

@defvar print-unreadable-function
By default, Emacs prints unreadable objects as @samp{#<...>"}.  For
instance:

@example
(prin1-to-string (make-marker))
     @result{} "#<marker in no buffer>"
@end example

If this variable is non-@code{nil}, it should be a function that will
be called to handle printing of these objects.  The function will be
called with two arguments: the object and the @var{noescape} flag used by
the printing functions (@pxref{Output Functions}).

The function should return either @code{nil} (print the object as
usual), or a string (which will be printed), or any other object
(don't print the object).  For instance:

@example
(let ((print-unreadable-function
       (lambda (object escape) "hello")))
  (prin1-to-string (make-marker)))
     @result{} "hello"
@end example
@end defvar

@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

@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

@defvar float-output-format
This variable specifies how to print floating-point numbers.  The
default 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

@defvar print-integers-as-characters
When this variable is non-@code{nil}, integers that represent
graphic base characters will be printed using Lisp character syntax
(@pxref{Basic Char Syntax}). Other numbers are printed the usual way.
For example, the list @code{(4 65 -1 10)} would be printed as
@samp{(4 ?A -1 ?\n)}.

More precisely, values printed in character syntax are those
representing characters belonging to the Unicode general categories
Letter, Number, Punctuation, Symbol and Private-use
(@pxref{Character Properties}), as well as the control characters
having their own escape syntax such as newline.
@end defvar

@node Output Overrides
@section Overriding Output Variables
@cindex overrides, in output functions
@cindex output variables, overriding

The previous section (@pxref{Output Functions}) lists the numerous
variables that control how the Emacs Lisp printer formats data for
outputs.  These are generally available for users to change, but
sometimes you want to output data in the default format, or override
the user settings in some other way.  For instance, if you're storing
Emacs Lisp data in a file, you don't want that data to be shortened by
a @code{print-length} setting.

The @code{prin1} and @code{prin1-to-string} functions therefore have
an optional @var{overrides} argument.  This argument can either be
@code{t} (which means that all printing variables should be reset to
the default values), or a list of settings for some of the variables.
Each element in the list can be either @code{t} (which means ``reset
to defaults'', and will usually be the first element of the list), or
a pair whose @code{car} is a symbol that stands for an output variable
and whose @code{cdr} is the value for that variable.

For instance, this prints using nothing but defaults:

@lisp
(prin1 object nil t)
@end lisp

This prints @var{object} using the current printing settings, but
overrides the value of @code{print-length} to be 5:

@lisp
(prin1 object nil '((length . 5)))
@end lisp

And finally, this prints @var{object} using only default settings, but
with @code{print-length} bound to 5:

@lisp
(prin1 object nil '(t (length . 5)))
@end lisp

Below is a list of symbols that can be used, and which variables they
map to:

@table @code
@item length
This overrides @code{print-length}.
@item level
This overrides @code{print-level}.
@item circle
This overrides @code{print-circle}.
@item quoted
This overrides @code{print-quoted}.
@item escape-newlines
This overrides @code{print-escape-newlines}.
@item escape-control-characters
This overrides @code{print-escape-control-characters}.
@item escape-nonascii
This overrides @code{print-escape-nonascii}.
@item escape-multibyte
This overrides @code{print-escape-multibyte}.
@item charset-text-property
This overrides @code{print-charset-text-property}.
@item unreadeable-function
This overrides @code{print-unreadable-function}.
@item gensym
This overrides @code{print-gensym}.
@item continuous-numbering
This overrides @code{print-continuous-numbering}.
@item number-table
This overrides @code{print-number-table}.
@item float-format
This overrides @code{float-output-format}.
@item integers-as-characters
This overrides @code{print-integers-as-characters}.
@end table

In the future, more overrides may be offered that do not map directly
to a variable, but can only be used via this parameter.

debug log:

solving 89046a68249 ...
found 89046a68249 in https://git.savannah.gnu.org/cgit/emacs.git

(*) Git path names are given by the tree(s) the blob belongs to.
    Blobs themselves have no identifier aside from the hash of its contents.^

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).