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 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455
|
@node Reader, System Construction, Printer, Top
@chapter Reader
@menu
* Reader Concepts::
* Reader Dictionary::
@end menu
@node Reader Concepts, Reader Dictionary, Reader, Reader
@section Reader Concepts
@c including concept-reader
@menu
* Dynamic Control of the Lisp Reader::
* Effect of Readtable Case on the Lisp Reader::
* Argument Conventions of Some Reader Functions::
@end menu
@node Dynamic Control of the Lisp Reader, Effect of Readtable Case on the Lisp Reader, Reader Concepts, Reader Concepts
@subsection Dynamic Control of the Lisp Reader
Various aspects of the @i{Lisp reader} can be controlled dynamically.
See @ref{Readtables} and @ref{Variables that affect the Lisp Reader}.
@node Effect of Readtable Case on the Lisp Reader, Argument Conventions of Some Reader Functions, Dynamic Control of the Lisp Reader, Reader Concepts
@subsection Effect of Readtable Case on the Lisp Reader
The @i{readtable case} of the @i{current readtable} affects the @i{Lisp reader}
in the following ways:
@table @asis
@item @t{:upcase}
When the @i{readtable case} is @t{:upcase},
unescaped constituent @i{characters} are converted to @i{uppercase},
as specified in @ref{Reader Algorithm}.
@item @t{:downcase}
When the @i{readtable case} is @t{:downcase},
unescaped constituent @i{characters} are converted to @i{lowercase}.
@item @t{:preserve}
When the @i{readtable case} is @t{:preserve},
the case of all @i{characters} remains unchanged.
@item @t{:invert}
When the @i{readtable case} is @t{:invert},
then if all of the unescaped letters in the extended token are of the same @i{case},
those (unescaped) letters are converted to the opposite @i{case}.
@end table
@menu
* Examples of Effect of Readtable Case on the Lisp Reader::
@end menu
@node Examples of Effect of Readtable Case on the Lisp Reader, , Effect of Readtable Case on the Lisp Reader, Effect of Readtable Case on the Lisp Reader
@subsubsection Examples of Effect of Readtable Case on the Lisp Reader
@example
(defun test-readtable-case-reading ()
(let ((*readtable* (copy-readtable nil)))
(format t "READTABLE-CASE Input Symbol-name~
~
~
(dolist (readtable-case '(:upcase :downcase :preserve :invert))
(setf (readtable-case *readtable*) readtable-case)
(dolist (input '("ZEBRA" "Zebra" "zebra"))
(format t "~&:~A~16T~A~24T~A"
(string-upcase readtable-case)
input
(symbol-name (read-from-string input)))))))
@end example
The output from @t{(test-readtable-case-reading)} should be as follows:
@example
READTABLE-CASE Input Symbol-name
-------------------------------------
:UPCASE ZEBRA ZEBRA
:UPCASE Zebra ZEBRA
:UPCASE zebra ZEBRA
:DOWNCASE ZEBRA zebra
:DOWNCASE Zebra zebra
:DOWNCASE zebra zebra
:PRESERVE ZEBRA ZEBRA
:PRESERVE Zebra Zebra
:PRESERVE zebra zebra
:INVERT ZEBRA zebra
:INVERT Zebra Zebra
:INVERT zebra ZEBRA
@end example
@node Argument Conventions of Some Reader Functions, , Effect of Readtable Case on the Lisp Reader, Reader Concepts
@subsection Argument Conventions of Some Reader Functions
@menu
* The EOF-ERROR-P argument::
* The RECURSIVE-P argument::
@end menu
@node The EOF-ERROR-P argument, The RECURSIVE-P argument, Argument Conventions of Some Reader Functions, Argument Conventions of Some Reader Functions
@subsubsection The EOF-ERROR-P argument
@i{Eof-error-p} in input function calls
controls what happens if input is from a file (or any other
input source that has a definite end) and the end of the file is reached.
If @i{eof-error-p} is @i{true} (the default),
an error of @i{type} @b{end-of-file} is signaled
at end of file. If it is @i{false}, then no error is signaled, and instead
the function returns @i{eof-value}.
Functions such as @b{read} that read the representation
of an @i{object} rather than a single
character always signals an error, regardless of @i{eof-error-p}, if
the file ends in the middle of an object representation.
For example, if a file does
not contain enough right parentheses to balance the left parentheses in
it, @b{read} signals an error. If a file ends in a
@i{symbol} or a @i{number}
immediately followed by end-of-file, @b{read} reads the
@i{symbol} or
@i{number}
successfully and when called again will
act according to @i{eof-error-p}.
Similarly, the @i{function} @b{read-line}
successfully reads the last line of a file even if that line
is terminated by end-of-file rather than the newline character.
Ignorable text, such as lines containing only @i{whitespace}_2 or comments,
are not considered to begin an @i{object};
if @b{read} begins to read an @i{expression} but sees only such
ignorable text, it does not consider the file to end in the middle of an @i{object}.
Thus an @i{eof-error-p} argument controls what happens
when the file ends between @i{objects}.
@node The RECURSIVE-P argument, , The EOF-ERROR-P argument, Argument Conventions of Some Reader Functions
@subsubsection The RECURSIVE-P argument
If @i{recursive-p} is supplied and not @b{nil}, it specifies that
this function call is not an outermost call to @b{read} but an
embedded call, typically from a @i{reader macro function}.
It is important to distinguish such recursive calls for three reasons.
@table @asis
@item 1.
An outermost call establishes the context within which the
@t{#@i{n}=} and @t{#@i{n}#} syntax is scoped. Consider, for example,
the expression
@example
(cons '#3=(p q r) '(x y . #3#))
@end example
If the @i{single-quote} @i{reader macro} were defined in this way:
@example
(set-macro-character #\' ;incorrect
#'(lambda (stream char)
(declare (ignore char))
(list 'quote (read stream))))
@end example
then each call to the @i{single-quote} @i{reader macro function} would establish
independent contexts for the scope of @b{read} information, including the scope of
identifications between markers like ``@t{#3=}'' and ``@t{#3#}''. However, for
this expression, the scope was clearly intended to be determined by the outer set
of parentheses, so such a definition would be incorrect.
The correct way to define the @i{single-quote}
@i{reader macro} uses @i{recursive-p}:
@example
(set-macro-character #\' ;correct
#'(lambda (stream char)
(declare (ignore char))
(list 'quote (read stream t nil t))))
@end example
@item 2.
A recursive call does not alter whether the reading process
is to preserve @i{whitespace}_2 or not (as determined by whether the
outermost call was to @b{read} or @b{read-preserving-whitespace}).
Suppose again that @i{single-quote}
were to be defined as shown above in the incorrect definition.
Then a call to @b{read-preserving-whitespace}
that read the expression @t{'foo<@i{Space}>} would fail to preserve the space
character following the symbol @t{foo} because the @i{single-quote}
@i{reader macro function} calls @b{read},
not @b{read-preserving-whitespace},
to read the following expression (in this case @t{foo}).
The correct definition, which passes the value @i{true} for @i{recursive-p}
to @b{read}, allows the outermost call to determine
whether @i{whitespace}_2 is preserved.
@item 3.
When end-of-file is encountered and the @i{eof-error-p} argument
is not @b{nil}, the kind of error that is signaled may depend on the value
of @i{recursive-p}. If @i{recursive-p}
is @i{true}, then the end-of-file
is deemed to have occurred within the middle of a printed representation;
if @i{recursive-p} is @i{false}, then the end-of-file may be deemed to have
occurred between @i{objects} rather than within the middle of one.
@end table
@c end of including concept-reader
@node Reader Dictionary, , Reader Concepts, Reader
@section Reader Dictionary
@c including dict-reader
@menu
* readtable::
* copy-readtable::
* make-dispatch-macro-character::
* read::
* read-delimited-list::
* read-from-string::
* readtable-case::
* readtablep::
* set-dispatch-macro-character::
* set-macro-character::
* set-syntax-from-char::
* with-standard-io-syntax::
* *read-base*::
* *read-default-float-format*::
* *read-eval*::
* *read-suppress*::
* *readtable*::
* reader-error::
@end menu
@node readtable, copy-readtable, Reader Dictionary, Reader Dictionary
@subsection readtable [System Class]
@subsubheading Class Precedence List::
@b{readtable},
@b{t}
@subsubheading Description::
A @i{readtable} maps @i{characters} into @i{syntax types} for
the @i{Lisp reader}; see @ref{Syntax}.
A @i{readtable} also
contains associations between @i{macro characters}
and their @i{reader macro functions},
and records information about the case conversion rules
to be used by the @i{Lisp reader} when parsing @i{symbols}.
Each @i{simple} @i{character} must be representable in the @i{readtable}.
It is @i{implementation-defined} whether @i{non-simple} @i{characters}
can have syntax descriptions in the @i{readtable}.
@subsubheading See Also::
@ref{Readtables},
@ref{Printing Other Objects}
@node copy-readtable, make-dispatch-macro-character, readtable, Reader Dictionary
@subsection copy-readtable [Function]
@code{copy-readtable} @i{{&optional} from-readtable to-readtable} @result{} @i{readtable}
@subsubheading Arguments and Values::
@i{from-readtable}---a @i{readtable designator}.
The default is the @i{current readtable}.
@i{to-readtable}---a @i{readtable} or @b{nil}.
The default is @b{nil}.
@i{readtable}---the @i{to-readtable} if it is @i{non-nil},
or else a @i{fresh} @i{readtable}.
@subsubheading Description::
@b{copy-readtable} copies @i{from-readtable}.
If @i{to-readtable} is @b{nil}, a new @i{readtable} is created and returned.
Otherwise the @i{readtable} specified by @i{to-readtable} is modified and returned.
@b{copy-readtable} copies the setting of @b{readtable-case}.
@subsubheading Examples::
@example
(setq zvar 123) @result{} 123
(set-syntax-from-char #\z #\' (setq table2 (copy-readtable))) @result{} T
zvar @result{} 123
(copy-readtable table2 *readtable*) @result{} #<READTABLE 614000277>
zvar @result{} VAR
(setq *readtable* (copy-readtable)) @result{} #<READTABLE 46210223>
zvar @result{} VAR
(setq *readtable* (copy-readtable nil)) @result{} #<READTABLE 46302670>
zvar @result{} 123
@end example
@subsubheading See Also::
@b{readtable},
@ref{readtable}
@subsubheading Notes::
@example
(setq *readtable* (copy-readtable nil))
@end example
restores the input syntax to standard @r{Common Lisp} syntax, even if
the @i{initial readtable} has been clobbered
(assuming it is not so badly clobbered that you cannot type in the above expression).
On the other hand,
@example
(setq *readtable* (copy-readtable))
@end example
replaces the current @i{readtable} with a copy of itself.
This is useful if you want to save a copy of a readtable for later use,
protected from alteration in the meantime. It is also useful if you want to
locally bind the readtable to a copy of itself, as in:
@example
(let ((*readtable* (copy-readtable))) ...)
@end example
@node make-dispatch-macro-character, read, copy-readtable, Reader Dictionary
@subsection make-dispatch-macro-character [Function]
@code{make-dispatch-macro-character} @i{char {&optional} non-terminating-p readtable} @result{} @i{@b{t}}
@subsubheading Arguments and Values::
@i{char}---a @i{character}.
@i{non-terminating-p}---a @i{generalized boolean}.
The default is @i{false}.
@i{readtable}---a @i{readtable}.
The default is the @i{current readtable}.
@subsubheading Description::
@b{make-dispatch-macro-character} makes @i{char}
be a @i{dispatching macro character} in @i{readtable}.
Initially, every @i{character} in the dispatch table
associated with the @i{char} has an associated function
that signals an error of @i{type} @b{reader-error}.
If @i{non-terminating-p} is @i{true},
the @i{dispatching macro character}
is made a @i{non-terminating} @i{macro character};
if @i{non-terminating-p} is @i{false},
the @i{dispatching macro character}
is made a @i{terminating} @i{macro character}.
@subsubheading Examples::
@example
(get-macro-character #\@{) @result{} NIL, @i{false}
(make-dispatch-macro-character #\@{) @result{} T
(not (get-macro-character #\@{)) @result{} @i{false}
@end example
The @i{readtable} is altered.
@subsubheading See Also::
@ref{readtable}
,
@ref{set-dispatch-macro-character; get-dispatch-macro-character}
@node read, read-delimited-list, make-dispatch-macro-character, Reader Dictionary
@subsection read, read-preserving-whitespace [Function]
@code{read} @i{{&optional} input-stream eof-error-p eof-value recursive-p} @result{} @i{object}
@code{read-preserving-whitespace} @i{{&optional} input-stream eof-error-p
eof-value recursive-p}@*
@result{} @i{object}
@subsubheading Arguments and Values::
@i{input-stream}---an @i{input} @i{stream designator}.
@i{eof-error-p}---a @i{generalized boolean}.
The default is @i{true}.
@i{eof-value}---an @i{object}.
The default is @b{nil}.
@i{recursive-p}---a @i{generalized boolean}.
The default is @i{false}.
@i{object}---an @i{object} (parsed by the @i{Lisp reader})
or the @i{eof-value}.
@subsubheading Description::
@b{read} parses the printed representation of an @i{object}
from @i{input-stream} and builds such an @i{object}.
@b{read-preserving-whitespace} is like @b{read} but preserves
any @i{whitespace}_2 @i{character}
that delimits the printed representation of the @i{object}.
@b{read-preserving-whitespace} is exactly like @b{read}
when the @i{recursive-p} @i{argument} to @b{read-preserving-whitespace}
is @i{true}.
When @b{*read-suppress*} is @i{false},
@b{read} throws away the delimiting @i{character} required by
certain printed representations if it is a
@i{whitespace}_2 @i{character};
but @b{read} preserves the character
(using @b{unread-char}) if it is
syntactically meaningful, because it could be the start of the next expression.
If a file ends in a @i{symbol} or a @i{number}
immediately followed by an @i{end of file}_1,
@b{read} reads the @i{symbol} or @i{number} successfully;
when called again, it sees the @i{end of file}_1 and
only then acts according to @i{eof-error-p}.
If a file contains ignorable text at the end, such
as blank lines and comments, @b{read}
does not consider it to end in the
middle of an @i{object}.
If @i{recursive-p} is @i{true}, the call to @b{read} is
expected to be made
from within some function that itself
has been called from @b{read} or from a similar input function, rather
than from the top level.
Both functions return the @i{object} read from @i{input-stream}.
@i{Eof-value} is returned if @i{eof-error-p} is @i{false} and end of file
is reached before the beginning of an @i{object}.
@subsubheading Examples::
@example
(read)
@t{ |> } @b{|>>}@t{'a}@b{<<|}
@result{} (QUOTE A)
(with-input-from-string (is " ") (read is nil 'the-end)) @result{} THE-END
(defun skip-then-read-char (s c n)
(if (char= c #\@{) (read s t nil t) (read-preserving-whitespace s))
(read-char-no-hang s)) @result{} SKIP-THEN-READ-CHAR
(let ((*readtable* (copy-readtable nil)))
(set-dispatch-macro-character #\# #\@{ #'skip-then-read-char)
(set-dispatch-macro-character #\# #\@} #'skip-then-read-char)
(with-input-from-string (is "#@{123 x #@}123 y")
(format t "~S ~S" (read is) (read is)))) @result{} #\x, #\Space, NIL
@end example
As an example, consider this @i{reader macro} definition:
@example
(defun slash-reader (stream char)
(declare (ignore char))
`(path . ,(loop for dir = (read-preserving-whitespace stream t nil t)
then (progn (read-char stream t nil t)
(read-preserving-whitespace stream t nil t))
collect dir
while (eql (peek-char nil stream nil nil t) #\/))))
(set-macro-character #\/ #'slash-reader)
@end example
Consider now calling @b{read} on this expression:
@example
(zyedh /usr/games/zork /usr/games/boggle)
@end example
The @t{/} macro reads objects separated by more @t{/} characters;
thus @t{/usr/games/zork} is intended to read as @t{(path usr games zork)}.
The entire example expression should therefore be read as
@example
(zyedh (path usr games zork) (path usr games boggle))
@end example
However, if @b{read} had been used instead of
@b{read-preserving-whitespace}, then after the reading of the symbol
@t{zork}, the following space would be discarded; the next call
to @b{peek-char} would see the following @t{/}, and the loop would
continue, producing this interpretation:
@example
(zyedh (path usr games zork usr games boggle))
@end example
There are times when @i{whitespace}_2 should be discarded.
If a command interpreter takes single-character commands,
but occasionally reads an @i{object} then if the @i{whitespace}_2
after a @i{symbol}
is not discarded it might be interpreted as a command
some time later after the @i{symbol} had been read.
@subsubheading Affected By::
@b{*standard-input*},
@b{*terminal-io*},
@b{*readtable*},
@b{*read-default-float-format*},
@b{*read-base*},
@b{*read-suppress*},
@b{*package*},
@b{*read-eval*}.
@subsubheading Exceptional Situations::
@b{read} signals an error of @i{type} @b{end-of-file},
regardless of @i{eof-error-p}, if
the file ends in the middle of an @i{object} representation.
For example, if a file does
not contain enough right parentheses to balance the left parentheses in
it, @b{read} signals an error.
This is detected when @b{read} or @b{read-preserving-whitespace}
is called with @i{recursive-p} and @i{eof-error-p} @i{non-nil},
and end-of-file is reached before the beginning of an @i{object}.
If @i{eof-error-p} is @i{true}, an error of @i{type} @b{end-of-file}
is signaled at the end of file.
@subsubheading See Also::
@ref{peek-char}
,
@ref{read-char}
,
@ref{unread-char}
,
@ref{read-from-string}
,
@ref{read-delimited-list}
,
@ref{parse-integer}
,
{@ref{Syntax}},
{@ref{Reader Concepts}}
@node read-delimited-list, read-from-string, read, Reader Dictionary
@subsection read-delimited-list [Function]
@code{read-delimited-list} @i{char {&optional} input-stream recursive-p} @result{} @i{list}
@subsubheading Arguments and Values::
@i{char}---a @i{character}.
@i{input-stream}---an @i{input} @i{stream designator}.
The default is @i{standard input}.
@i{recursive-p}---a @i{generalized boolean}.
The default is @i{false}.
@i{list}---a @i{list} of the @i{objects} read.
@subsubheading Description::
@b{read-delimited-list} reads @i{objects} from @i{input-stream}
until the next character after an @i{object}'s
representation (ignoring @i{whitespace}_2 characters and comments) is @i{char}.
@b{read-delimited-list} looks ahead at each step
for the next non-@i{whitespace}_2 @i{character}
and peeks at it as if with @b{peek-char}.
If it is @i{char},
then the @i{character} is consumed and the @i{list} of @i{objects} is returned.
If it is a @i{constituent} or @i{escape} @i{character},
then @b{read} is used to read an @i{object},
which is added to the end of the @i{list}.
If it is a @i{macro character},
its @i{reader macro function} is called;
if the function returns a @i{value},
that @i{value} is added to the @i{list}.
The peek-ahead process is then repeated.
If @i{recursive-p} is @i{true},
this call is expected to be embedded in a higher-level call to @b{read}
or a similar function.
It is an error to reach end-of-file during the operation of
@b{read-delimited-list}.
The consequences are undefined
if @i{char} has a @i{syntax type} of @i{whitespace}_2
in the @i{current readtable}.
@subsubheading Examples::
@example
(read-delimited-list #\{]}) 1 2 3 4 5 6 {]}
@result{} (1 2 3 4 5 6)
@end example
Suppose you wanted @t{#@{{@i{a}} @i{b} @i{c} ... @i{z}@}}
to read as a list of all pairs of the elements @i{a}, @i{b}, @i{c},
..., @i{z}, for example.
@example
#@{p q z a@} reads as ((p q) (p z) (p a) (q z) (q a) (z a))
@end example
This can be done by specifying a macro-character definition for @t{#@{}
that does two things: reads in all the items up to the @t{@}},
and constructs the pairs. @b{read-delimited-list} performs
the first task.
@example
(defun |#@{-reader| (stream char arg)
(declare (ignore char arg))
(mapcon #'(lambda (x)
(mapcar #'(lambda (y) (list (car x) y)) (cdr x)))
(read-delimited-list #\@} stream t))) @result{} |#@{-reader|
(set-dispatch-macro-character #\# #\@{ #'|#@{-reader|) @result{} T
(set-macro-character #\@} (get-macro-character #\) @b{nil}))
@end example
Note that @i{true} is supplied for the @i{recursive-p} argument.
It is necessary here to give a definition to the character @t{@}} as
well to prevent it from being a constituent.
If the line
@example
(set-macro-character #\@} (get-macro-character #\) @b{nil}))
@end example
shown above were not included, then the @t{@}} in
@example
#@{ p q z a@}
@end example
would be considered a constituent character, part of the symbol named
@t{a@}}. This could be corrected by putting a space before
the @t{@}}, but it is better to call
@b{set-macro-character}.
Giving @t{@}} the same
definition as the standard definition of the character @t{)} has the
twin benefit of making it terminate tokens for use with
@b{read-delimited-list} and also making it invalid for use in any
other context. Attempting to read a stray @t{@}} will signal an error.
@subsubheading Affected By::
@b{*standard-input*},
@b{*readtable*},
@b{*terminal-io*}.
@subsubheading See Also::
@ref{read; read-preserving-whitespace}
,
@ref{peek-char}
,
@ref{read-char}
,
@ref{unread-char}
.
@subsubheading Notes::
@b{read-delimited-list} is intended for use in implementing @i{reader macros}.
Usually it is desirable for @i{char} to be a @i{terminating} @i{macro character}
so that it can be used to delimit tokens; however, @b{read-delimited-list}
makes no attempt to alter the syntax specified for @i{char} by the current
readtable. The caller must make any necessary changes to the readtable syntax
explicitly.
@node read-from-string, readtable-case, read-delimited-list, Reader Dictionary
@subsection read-from-string [Function]
@code{read-from-string} @i{string {&optional} eof-error-p eof-value
{&key} start end preserve-whitespace}@*
@result{} @i{object, position}
@subsubheading Arguments and Values::
@i{string}---a @i{string}.
@i{eof-error-p}---a @i{generalized boolean}.
The default is @i{true}.
@i{eof-value}---an @i{object}.
The default is @b{nil}.
@i{start}, @i{end}---@i{bounding index designators} of @i{string}.
The defaults for @i{start} and @i{end} are @t{0} and @b{nil}, respectively.
@i{preserve-whitespace}---a @i{generalized boolean}.
The default is @i{false}.
@i{object}---an @i{object} (parsed by the @i{Lisp reader})
or the @i{eof-value}.
@i{position}---an @i{integer} greater than or equal to zero,
and less than or equal to
one more than the @i{length} of the @i{string}.
@subsubheading Description::
Parses the printed representation of an @i{object}
from the subsequence of @i{string} @i{bounded} by @i{start} and @i{end},
as if @b{read} had been called on an @i{input} @i{stream}
containing those same @i{characters}.
If @i{preserve-whitespace} is @i{true},
the operation will preserve @i{whitespace}_2
as @b{read-preserving-whitespace} would do.
If an @i{object} is successfully parsed, the @i{primary value}, @i{object},
is the @i{object} that was parsed.
If @i{eof-error-p} is @i{false} and if the end of the @i{substring} is reached,
@i{eof-value} is returned.
The @i{secondary value}, @i{position}, is the index of the first @i{character}
in the @i{bounded} @i{string} that was not read.
The @i{position} may depend upon the value of @i{preserve-whitespace}.
If the entire @i{string} was read,
the @i{position} returned is either the @i{length} of the @i{string}
or one greater than the @i{length} of the @i{string}.
@subsubheading Examples::
@example
(read-from-string " 1 3 5" t nil :start 2) @result{} 3, 5
(read-from-string "(a b c)") @result{} (A B C), 7
@end example
@subsubheading Exceptional Situations::
If the end of the supplied substring
occurs before an @i{object} can be read, an
error is signaled if @i{eof-error-p} is @i{true}.
An error is signaled if the end of the @i{substring} occurs
in the middle of an incomplete @i{object}.
@subsubheading See Also::
@ref{read; read-preserving-whitespace}
,
@b{read-preserving-whitespace}
@subsubheading Notes::
The reason that @i{position} is allowed to be beyond the
@i{length} of the @i{string} is to permit (but not require)
the @i{implementation} to work by simulating the effect of a
trailing delimiter at the end of the @i{bounded} @i{string}.
When @i{preserve-whitespace} is @i{true},
the @i{position} might count the simulated delimiter.
@node readtable-case, readtablep, read-from-string, Reader Dictionary
@subsection readtable-case [Accessor]
@code{readtable-case} @i{readtable} @result{} @i{mode}
(setf (@code{ readtable-case} @i{readtable}) mode)@*
@subsubheading Arguments and Values::
@i{readtable}---a @i{readtable}.
@i{mode}---a @i{case sensitivity mode}.
@subsubheading Description::
@i{Accesses} the @i{readtable case} of @i{readtable},
which affects the way in which the @i{Lisp Reader} reads @i{symbols}
and the way in which the @i{Lisp Printer} writes @i{symbols}.
@subsubheading Examples::
See @ref{Examples of Effect of Readtable Case on the Lisp Reader} and @ref{Examples of Effect of Readtable Case on the Lisp Printer}.
@subsubheading Exceptional Situations::
Should signal an error of @i{type} @b{type-error}
if @i{readtable} is not a @i{readtable}.
Should signal an error of @i{type} @b{type-error}
if @i{mode} is not a @i{case sensitivity mode}.
@subsubheading See Also::
@ref{readtable}
,
@b{*print-escape*},
@ref{Reader Algorithm},
@ref{Effect of Readtable Case on the Lisp Reader},
@ref{Effect of Readtable Case on the Lisp Printer}
@subsubheading Notes::
@b{copy-readtable} copies the @i{readtable case} of the @i{readtable}.
@node readtablep, set-dispatch-macro-character, readtable-case, Reader Dictionary
@subsection readtablep [Function]
@code{readtablep} @i{object} @result{} @i{generalized-boolean}
@subsubheading Arguments and Values::
@i{object}---an @i{object}.
@i{generalized-boolean}---a @i{generalized boolean}.
@subsubheading Description::
Returns @i{true} if @i{object} is of @i{type} @b{readtable};
otherwise, returns @i{false}.
@subsubheading Examples::
@example
(readtablep *readtable*) @result{} @i{true}
(readtablep (copy-readtable)) @result{} @i{true}
(readtablep '*readtable*) @result{} @i{false}
@end example
@subsubheading Notes::
@example
(readtablep @i{object}) @equiv{} (typep @i{object} 'readtable)
@end example
@node set-dispatch-macro-character, set-macro-character, readtablep, Reader Dictionary
@subsection set-dispatch-macro-character, get-dispatch-macro-character
@flushright
@i{[Function]}
@end flushright
@code{get-dispatch-macro-character} @i{disp-char sub-char {&optional} readtable} @result{} @i{function}
@code{set-dispatch-macro-character} @i{disp-char sub-char new-function {&optional} readtable} @result{} @i{@b{t}}
@subsubheading Arguments and Values::
@i{disp-char}---a @i{character}.
@i{sub-char}---a @i{character}.
@i{readtable}---a @i{readtable designator}.
The default is the @i{current readtable}.
@i{function}---a @i{function designator} or @b{nil}.
@i{new-function}---a @i{function designator}.
@subsubheading Description::
@b{set-dispatch-macro-character} causes @i{new-function} to be called
when @i{disp-char} followed by @i{sub-char} is read.
If @i{sub-char} is a lowercase letter,
it is converted to its uppercase equivalent.
It is an error if @i{sub-char} is one of the ten decimal digits.
@b{set-dispatch-macro-character} installs a @i{new-function} to be called
when a particular @i{dispatching macro character} pair is read.
@i{New-function} is installed as the dispatch function to be
called when @i{readtable} is in use and when @i{disp-char} is followed by
@i{sub-char}.
For more information about how the @i{new-function} is invoked,
see @ref{Macro Characters}.
@b{get-dispatch-macro-character} retrieves
the dispatch function associated with @i{disp-char} and @i{sub-char}
in @i{readtable}.
@b{get-dispatch-macro-character} returns the macro-character function
for @i{sub-char} under @i{disp-char}, or @b{nil} if there is no
function associated with @i{sub-char}.
If @i{sub-char} is a decimal digit, @b{get-dispatch-macro-character}
returns @b{nil}.
@subsubheading Examples::
@example
(get-dispatch-macro-character #\# #\@{) @result{} NIL
(set-dispatch-macro-character #\# #\@{ ;dispatch on #@{
#'(lambda(s c n)
(let ((list (read s nil (values) t))) ;list is object after #n@{
(when (consp list) ;return nth element of list
(unless (and n (< 0 n (length list))) (setq n 0))
(setq list (nth n list)))
list))) @result{} T
#@{(1 2 3 4) @result{} 1
#3@{(0 1 2 3) @result{} 3
#@{123 @result{} 123
@end example
If it is desired that @t{#$@i{foo}} :
as if it were @t{(dollars @i{foo})}.
@example
(defun |#$-reader| (stream subchar arg)
(declare (ignore subchar arg))
(list 'dollars (read stream t nil t))) @result{} |#$-reader|
(set-dispatch-macro-character #\# #\$ #'|#$-reader|) @result{} T
@end example
@subsubheading See Also::
@ref{Macro Characters}
@subsubheading Side Effects::
The @i{readtable} is modified.
@subsubheading Affected By::
@b{*readtable*}.
@subsubheading Exceptional Situations::
For either function, an error is signaled if @i{disp-char} is not
a @i{dispatching macro character} in @i{readtable}.
@subsubheading See Also::
@ref{readtable}
@subsubheading Notes::
It is necessary
to use @b{make-dispatch-macro-character} to set up the
dispatch character before specifying its sub-characters.
@node set-macro-character, set-syntax-from-char, set-dispatch-macro-character, Reader Dictionary
@subsection set-macro-character, get-macro-character [Function]
@code{get-macro-character} @i{char {&optional} readtable} @result{} @i{function, non-terminating-p}
@code{set-macro-character} @i{char new-function {&optional} non-terminating-p readtable} @result{} @i{@b{t}}
@subsubheading Arguments and Values::
@i{char}---a @i{character}.
@i{non-terminating-p}---a @i{generalized boolean}.
The default is @i{false}.
@i{readtable}---a @i{readtable designator}.
The default is the @i{current readtable}.
@i{function}---@b{nil},
or a @i{designator} for a @i{function} of two @i{arguments}.
@i{new-function}---a @i{function designator}.
@subsubheading Description::
@b{get-macro-character} returns as its @i{primary value}, @i{function},
the @i{reader macro function} associated with @i{char} in @i{readtable} (if any),
or else @b{nil} if @i{char} is not a @i{macro character} in @i{readtable}.
The @i{secondary value}, @i{non-terminating-p}, is @i{true}
if @i{char} is a @i{non-terminating} @i{macro character};
otherwise, it is @i{false}.
@b{set-macro-character} causes @i{char} to be a @i{macro character}
associated with the @i{reader macro function} @i{new-function}
(or the @i{designator} for @i{new-function}) in @i{readtable}.
If @i{non-terminating-p} is @i{true},
@i{char} becomes a @i{non-terminating} @i{macro character};
otherwise it becomes a @i{terminating} @i{macro character}.
@subsubheading Examples::
@example
(get-macro-character #\@{) @result{} NIL, @i{false}
(not (get-macro-character #\;)) @result{} @i{false}
@end example
The following is a possible definition for the @i{single-quote} @i{reader macro}
in @i{standard syntax}:
@example
(defun single-quote-reader (stream char)
(declare (ignore char))
(list 'quote (read stream t nil t))) @result{} SINGLE-QUOTE-READER
(set-macro-character #\' #'single-quote-reader) @result{} T
@end example
Here @t{single-quote-reader} reads an @i{object} following the @i{single-quote}
and returns a @i{list} of @b{quote} and that @i{object}.
The @i{char} argument is ignored.
The following is a possible definition for the @i{semicolon} @i{reader macro}
in @i{standard syntax}:
@example
(defun semicolon-reader (stream char)
(declare (ignore char))
;; First swallow the rest of the current input line.
;; End-of-file is acceptable for terminating the comment.
(do () ((char= (read-char stream nil #\Newline t) #\Newline)))
;; Return zero values.
(values)) @result{} SEMICOLON-READER
(set-macro-character #\; #'semicolon-reader) @result{} T
@end example
@subsubheading Side Effects::
The @i{readtable} is modified.
@subsubheading See Also::
@ref{readtable}
@node set-syntax-from-char, with-standard-io-syntax, set-macro-character, Reader Dictionary
@subsection set-syntax-from-char [Function]
@code{set-syntax-from-char} @i{to-char from-char {&optional} to-readtable from-readtable} @result{} @i{@b{t}}
@subsubheading Arguments and Values::
@i{to-char}---a @i{character}.
@i{from-char}---a @i{character}.
@i{to-readtable}---a @i{readtable}.
The default is the @i{current readtable}.
@i{from-readtable}---a @i{readtable designator}.
The default is the @i{standard readtable}.
@subsubheading Description::
@b{set-syntax-from-char} makes
the syntax of @i{to-char} in @i{to-readtable} be the same as
the syntax of @i{from-char} in @i{from-readtable}.
@b{set-syntax-from-char} copies the @i{syntax types} of @i{from-char}.
If @i{from-char} is a @i{macro character},
its @i{reader macro function} is copied also.
If the character is a @i{dispatching macro character},
its entire dispatch table of @i{reader macro functions} is copied.
The @i{constituent traits} of @i{from-char} are not copied.
A macro definition from a character such as
@t{"} can be copied to another character; the standard definition for @t{"}
looks for another character that is the same as the character that
invoked it. The definition of @t{(} can not be meaningfully copied
to @t{@{}, on the other hand.
The result is that @i{lists} are of the form
@t{@{a b c)}, not @t{@{a b c@}},
because the definition
always looks for a closing parenthesis, not a closing brace.
@subsubheading Examples::
@example
(set-syntax-from-char #\7 #\;) @result{} T
123579 @result{} 1235
@end example
@subsubheading Side Effects::
The @i{to-readtable} is modified.
@subsubheading Affected By::
The existing values in the @i{from-readtable}.
@subsubheading See Also::
@ref{set-macro-character; get-macro-character}
,
@ref{make-dispatch-macro-character}
,
@ref{Character Syntax Types}
@subsubheading Notes::
The @i{constituent traits} of a @i{character} are ``hard wired''
into the parser for extended @i{tokens}. For example, if the definition
of @t{S} is copied to @t{*}, then @t{*} will become a @i{constituent}
that is @i{alphabetic}_2 but that cannot be used as a
@i{short float} @i{exponent marker}.
For further information, see @ref{Constituent Traits}.
@node with-standard-io-syntax, *read-base*, set-syntax-from-char, Reader Dictionary
@subsection with-standard-io-syntax [Macro]
@code{with-standard-io-syntax} @i{@{@i{form}@}{*}} @result{} @i{@{@i{result}@}{*}}
@subsubheading Arguments and Values::
@i{forms}---an @i{implicit progn}.
@i{results}---the @i{values} returned by the @i{forms}.
@subsubheading Description::
Within the dynamic extent of the body of @i{forms}, all reader/printer control
variables, including any @i{implementation-defined} ones not specified by
this standard, are bound to values that produce standard read/print
behavior. The values for the variables specified by this standard are listed in
Figure 23--1.
[Reviewer Note by Barrett: *print-pprint-dispatch* should probably be mentioned here, too.]
@group
@noindent
@w{ Variable Value }
@w{ @b{*package*} The @t{CL-USER} @i{package} }
@w{ @b{*print-array*} @b{t} }
@w{ @b{*print-base*} @t{10} }
@w{ @b{*print-case*} @t{:upcase} }
@w{ @b{*print-circle*} @b{nil} }
@w{ @b{*print-escape*} @b{t} }
@w{ @b{*print-gensym*} @b{t} }
@w{ @b{*print-length*} @b{nil} }
@w{ @b{*print-level*} @b{nil} }
@w{ @b{*print-lines*} @b{nil} }
@w{ @b{*print-miser-width*} @b{nil} }
@w{ @b{*print-pprint-dispatch*} The @i{standard pprint dispatch table} }
@w{ @b{*print-pretty*} @b{nil} }
@w{ @b{*print-radix*} @b{nil} }
@w{ @b{*print-readably*} @b{t} }
@w{ @b{*print-right-margin*} @b{nil} }
@w{ @b{*read-base*} @t{10} }
@w{ @b{*read-default-float-format*} @b{single-float} }
@w{ @b{*read-eval*} @b{t} }
@w{ @b{*read-suppress*} @b{nil} }
@w{ @b{*readtable*} The @i{standard readtable} }
@noindent
@w{ Figure 23--1: Values of standard control variables }
@end group
@subsubheading Examples::
@example
(with-open-file (file pathname :direction :output)
(with-standard-io-syntax
(print data file)))
;;; ... Later, in another Lisp:
(with-open-file (file pathname :direction :input)
(with-standard-io-syntax
(setq data (read file))))
@end example
@node *read-base*, *read-default-float-format*, with-standard-io-syntax, Reader Dictionary
@subsection *read-base* [Variable]
@subsubheading Value Type::
a @i{radix}.
@subsubheading Initial Value::
@t{10}.
@subsubheading Description::
Controls the interpretation of tokens by @b{read} as being
@i{integers} or @i{ratios}.
The @i{value} of @b{*read-base*}, called the @i{current input base}
@IGindex{current input base}
,
is the radix in which @i{integers} and
@i{ratios} are to be read by the @i{Lisp reader}.
The parsing of other numeric @i{types} (@i{e.g.}, @i{floats}) is
not affected by this option.
The effect of @b{*read-base*} on the reading of any particular
@i{rational} number can be locally overridden by explicit use of the
@t{#O}, @t{#X}, @t{#B}, or @t{#@i{n}R} syntax
or by a trailing decimal point.
@subsubheading Examples::
@example
(dotimes (i 6)
(let ((*read-base* (+ 10. i)))
(let ((object (read-from-string "(\\DAD DAD |BEE| BEE 123. 123)")))
(print (list *read-base* object)))))
@t{ |> } (10 (DAD DAD BEE BEE 123 123))
@t{ |> } (11 (DAD DAD BEE BEE 123 146))
@t{ |> } (12 (DAD DAD BEE BEE 123 171))
@t{ |> } (13 (DAD DAD BEE BEE 123 198))
@t{ |> } (14 (DAD 2701 BEE BEE 123 227))
@t{ |> } (15 (DAD 3088 BEE 2699 123 258))
@result{} NIL
@end example
@subsubheading Notes::
Altering the input radix can be useful when reading data files in special formats.
@node *read-default-float-format*, *read-eval*, *read-base*, Reader Dictionary
@subsection *read-default-float-format* [Variable]
@subsubheading Value Type::
one of the @i{atomic type specifiers}
@b{short-float},
@b{single-float},
@b{double-float},
or @b{long-float},
or else some other @i{type specifier} defined
by the @i{implementation} to be acceptable.
@subsubheading Initial Value::
The @i{symbol} @b{single-float}.
@subsubheading Description::
Controls the floating-point format that is to be used when reading a
floating-point number that has no @i{exponent marker} or that has
@t{e} or @t{E} for an @i{exponent marker}. Other @i{exponent markers}
explicitly prescribe the floating-point format to be used.
The printer uses @b{*read-default-float-format*} to guide the
choice of @i{exponent markers} when printing floating-point numbers.
@subsubheading Examples::
@example
(let ((*read-default-float-format* 'double-float))
(read-from-string "(1.0 1.0e0 1.0s0 1.0f0 1.0d0 1.0L0)"))
@result{} (1.0 1.0 1.0 1.0 1.0 1.0) ;Implementation has float format F.
@result{} (1.0 1.0 1.0s0 1.0 1.0 1.0) ;Implementation has float formats S and F.
@result{} (1.0d0 1.0d0 1.0 1.0 1.0d0 1.0d0) ;Implementation has float formats F and D.
@result{} (1.0d0 1.0d0 1.0s0 1.0 1.0d0 1.0d0) ;Implementation has float formats S, F, D.
@result{} (1.0d0 1.0d0 1.0 1.0 1.0d0 1.0L0) ;Implementation has float formats F, D, L.
@result{} (1.0d0 1.0d0 1.0s0 1.0 1.0d0 1.0L0) ;Implementation has formats S, F, D, L.
@end example
@node *read-eval*, *read-suppress*, *read-default-float-format*, Reader Dictionary
@subsection *read-eval* [Variable]
@subsubheading Value Type::
a @i{generalized boolean}.
@subsubheading Initial Value::
@i{true}.
@subsubheading Description::
If it is @i{true}, the @t{#.} @i{reader macro} has its normal effect.
Otherwise, that @i{reader macro} signals an error of @i{type} @b{reader-error}.
@subsubheading See Also::
@b{*print-readably*}
@subsubheading Notes::
If @b{*read-eval*} is @i{false} and @b{*print-readably*} is @i{true},
any @i{method} for @b{print-object} that would output a reference
to the @t{#.} @i{reader macro} either outputs something different
or signals an error of @i{type} @b{print-not-readable}.
@node *read-suppress*, *readtable*, *read-eval*, Reader Dictionary
@subsection *read-suppress* [Variable]
@subsubheading Value Type::
a @i{generalized boolean}.
@subsubheading Initial Value::
@i{false}.
@subsubheading Description::
This variable is intended primarily to support the operation of the
read-time conditional notations @t{#+} and @t{#-}. It is important for the
@i{reader macros} which implement these notations
to be able to skip over the printed representation of an
@i{expression} despite the possibility that the syntax of the skipped
@i{expression} may not be entirely valid for the current implementation,
since @t{#+} and @t{#-} exist in order to allow the same program to be
shared among several @r{Lisp} implementations (including dialects other than @r{Common Lisp})
despite small incompatibilities of syntax.
If it is @i{false}, the @i{Lisp reader} operates normally.
If the @i{value} of @b{*read-suppress*} is @i{true},
@b{read},
@b{read-preserving-whitespace},
@b{read-delimited-list},
and @b{read-from-string}
all return a @i{primary value} of @b{nil} when they complete successfully;
however, they continue to parse the representation of an @i{object}
in the normal way, in order to skip over the @i{object},
and continue to indicate @i{end of file} in the normal way.
Except as noted below,
any @i{standardized} @i{reader macro}_2
that is defined to @i{read}_2
a following @i{object} or @i{token}
will do so,
but not signal an error if the @i{object}
read is not of an appropriate type or syntax.
The @i{standard syntax} and its associated @i{reader macros}
will not construct any new @i{objects}
(@i{e.g.}, when reading the representation of a @i{symbol},
no @i{symbol} will be constructed or interned).
@table @asis
@item Extended tokens
All extended tokens are completely uninterpreted.
Errors such as those that might otherwise be signaled due to
detection of invalid @i{potential numbers},
invalid patterns of @i{package markers},
and invalid uses of the @i{dot} character are suppressed.
@item Dispatching macro characters (including @i{sharpsign})
@i{Dispatching macro characters} continue to parse an infix numerical
argument, and invoke the dispatch function. The @i{standardized}
@i{sharpsign} @i{reader macros} do not enforce any constraints
on either the presence of or the value of the numerical argument.
@item #=
The @t{#=} notation is totally ignored. It does not read
a following @i{object}. It produces no @i{object},
but is treated as @i{whitespace}_2.
@item ##
The @t{##} notation always produces @b{nil}.
@end table
No matter what the @i{value} of @b{*read-suppress*},
parentheses still continue to delimit and construct @i{lists};
the @t{#(} notation continues to delimit @i{vectors};
and comments, @i{strings},
and the @i{single-quote} and @i{backquote} notations continue to be
interpreted properly. Such situations as
@t{')}, @t{#<},
@t{#)}, and @t{#<@i{Space}>} continue to signal errors.
@subsubheading Examples::
@example
(let ((*read-suppress* t))
(mapcar #'read-from-string
'("#(foo bar baz)" "#P(:type :lisp)" "#c1.2"
"#.(PRINT 'FOO)" "#3AHELLO" "#S(INTEGER)"
"#*ABC" "#\GARBAGE" "#RALPHA" "#3R444")))
@result{} (NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL)
@end example
@subsubheading See Also::
@ref{read; read-preserving-whitespace}
,
{@ref{Syntax}}
@subsubheading Notes::
@i{Programmers} and @i{implementations} that define additional
@i{macro characters} are strongly encouraged to make them respect
@b{*read-suppress*} just as @i{standardized} @i{macro characters} do.
That is, when the @i{value} of @b{*read-suppress*} is @i{true},
they should ignore type errors when reading a following @i{object}
and the @i{functions} that implement @i{dispatching macro characters}
should tolerate @b{nil} as their infix @i{parameter} value even if a numeric
value would ordinarily be required.
@node *readtable*, reader-error, *read-suppress*, Reader Dictionary
@subsection *readtable* [Variable]
@subsubheading Value Type::
a @i{readtable}.
@subsubheading Initial Value::
A @i{readtable} that conforms to the description of @r{Common Lisp} syntax in @ref{Syntax}.
@subsubheading Description::
The @i{value} of @b{*readtable*} is called the @i{current readtable}.
It controls the parsing behavior of the @i{Lisp reader},
and can also influence the @i{Lisp printer} (@i{e.g.}, see the @i{function} @b{readtable-case}).
@subsubheading Examples::
@example
(readtablep *readtable*) @result{} @i{true}
(setq zvar 123) @result{} 123
(set-syntax-from-char #\z #\' (setq table2 (copy-readtable))) @result{} T
zvar @result{} 123
(setq *readtable* table2) @result{} #<READTABLE>
zvar @result{} VAR
(setq *readtable* (copy-readtable nil)) @result{} #<READTABLE>
zvar @result{} 123
@end example
@subsubheading Affected By::
@b{compile-file},
@b{load}
@subsubheading See Also::
@ref{compile-file}
,
@ref{load}
,
@ref{readtable}
,
@ref{The Current Readtable}
@node reader-error, , *readtable*, Reader Dictionary
@subsection reader-error [Condition Type]
@subsubheading Class Precedence List::
@b{reader-error},
@b{parse-error},
@b{stream-error},
@b{error},
@b{serious-condition},
@b{condition},
@b{t}
@subsubheading Description::
The @i{type} @b{reader-error} consists of
error conditions that are related to tokenization and parsing
done by the @i{Lisp reader}.
@subsubheading See Also::
@ref{read; read-preserving-whitespace}
,
@ref{stream-error-stream}
,
@ref{Reader Concepts}
@c end of including dict-reader
@c %**end of chapter
|