;;; -*- Mode:gate; Fonts:(HL12 HL12I HL12B CPTFONTB HL12BI HL12B HL12I ) -*- =Node: 4The Readtable* =Text: 3THE READTABLE* The syntax used by the reader is controlled by a data structure called the 1readtable*. (Some aspects of printing are also controlled by the readtable.) There can be many readtables, but the one that is used is the one which is the value of 2*readtable**. A particular syntax can be selected for use by setting or binding 2*readtable** to a readtable which specifies that syntax before reading or printing. In particular, this is how Common Lisp or traditional syntax is selected. The readtable also controls the symbol substitutions which implement the distinction between the traditional and Common Lisp versions of functions such as 2subst*, 2member*and 2defstruct*. The functions in this section allow you to modify the syntax of individual characters in a readtable in limited ways. You can also copy a readtable; then you can modify one copy and leave the other unchanged. A readtables may have one or more names. Named readtables are recorded in a central data base so that you can find a readtable by name. When you copy a readtable, the new one is anonymous and is not recorded in the data base. 3readtable* 1Variable* 3*readtable** 1Variable* The value of 2readtable* or 2*readtable** is the current readtable. This starts out as the initial standard readtable. You can bind this variable to change temporarily the readtable being used. The two names are synonymous. 3si:standard-readtable* 1Constant* This is copied into 2*readtable** every time the machine is booted. Therefore, it is normally the same as 2*readtable** unless you make 2*readtable** be some other readtable. If you alter the contents of 2*readtable** without setting or binding it to some other readtable, this readtable is changed. 3si:initial-readtable* 1Constant* The value of 2si:initial-readtable* is a read-only copy of the default current readtable. Its purpose is to preserve a copy of the standard read syntax in case you modify the contents of 2*readtable** and regret it later. You could use 2si:initial-readtable* as the 1from-readtable* argument to 2copy-readtable* or 2set-syntax-from-char* to restore all or part of the standard syntax. 3si:common-lisp-readtable* 1Constant* A readtable which initially is set up to define Common Lisp read syntax. Reading of Common Lisp programs is done using this readtable. 3si:initial-common-lisp-readtable* 1Constant* A read-only copy of 2si:common-lisp-readtable*, whose purpose is to preserve a copy of the standard Common Lisp syntax in case you modify 2si:common-lisp-readtable* (such as, by reading a Common Lisp program which modifies the current readtable). 3si:rdtbl-names* 1readtable* Returns the list of names of 2readtable*. You may 2setf* this to add or remove names. 3si:find-readtable-named* 1name* Returns the readtable named 2name*, or 2nil* if none is recorded. 3readtablep* 1object* 2t* if 1object* is a readtable. The user can program the reader by changing the readtable in any of three ways. The syntax of a character can be set to one of several predefined possibilities. A character can be made into a 1macro character*, whose interpretation is controlled by a user-supplied function which is called when the character is read. The user can create a completely new readtable, using the readtable compiler (2SYS: IO; RTC LISP*) to define new kinds of syntax and to assign syntax classes to characters. Use of the readtable compiler is not documented here. 3copy-readtable* &optional 1from-readtable* 1to-readtable* 1from-readtable*, which defaults to the current readtable, is copied. If 1from-readtable* is 2nil*, the standard Common Lisp syntax is copied. If 1to-readtable* is unsupplied or 2nil*, a fresh copy is made. Otherwise 1to-readtable* is clobbered with the copied syntax. Use 2copy-readtable* to get a private readtable before using the following functions to change the syntax of characters in it. The value of 2*readtable** at the start of a Lisp Machine session is the initial standard readtable, which usually should not be modified. 3set-syntax-from-char* 1to-char* 1from-char* &optional 1to-readtable* 1from-readtable* Copies the syntax of 1from-char* in 1from-readtable* to character 1to-char* in 1to-readtable*. 1to-readtable* defaults to the current readtable and 1from-readtable* defaults to 2si:initial-standard-readtable* (standard traditional syntax). 3cli:set-syntax-from-char* 1to-char* 1from-char* &optional 1to-readtable* 1from-readtable* Is a Common Lisp function which copies the syntax of 1from-char* in 1from-readtable* to character 1to-char* in 1to-readtable*. 1to-readtable* defaults to the current readtable and 1from-readtable* defaults to 2si:initial-common-lisp-readtable* (standard Common Lisp syntax). Common Lisp has a peculiar idea of what it means to copy the syntax of a character. The only aspect of syntax that the readtable supposedly specifies is the choice among 3** token constituent: digits, letters, random things like 2@*, 2!*, 2$*, and also colon! 3** whitespace: spaces, 2Tab*, 2Return*. 3** single escape character: 2/* traditionally, 2\* in Common Lisp. 3** multiple escape character: vertical-bar. 3** macro character: standardly 2()",.'`;* 3** nonterminating macro character: 2#* is the only such character standardly defined. The differences among macro characters are determined entirely by the functions that they invoke. The differences among token constituents (including the difference between 2A* and colon) are fixed! You can make 2A* be a macro character, or whitespace, or a quote character, but if you make it a token constituent then it always behaves the way it normally does. You can make colon be a macro character, or whitespace, etc., but if it is a token constituent it always delimits package names. If you make open-parenthesis into a token constituent, there is only one kind of token constituent it can be (it forces the token to be a symbol, like 2$* or 2@* or 2%*). This is not how Lisp Machine readtables really work, but since 2cli:set-syntax-from-char* is provided just for Common Lisp, the behavior specified by Common Lisp is laboriously provided. So, if 1from-char* is some kind of token constituent, this function makes 1to-char* into a token constituent of the kind that 1to-char* is supposed to be--not the kind of token constituent that 1from-char* is. By contrast, the non-Common-Lisp 2set-syntax-from-char* would make 1to-char* have exactly the same syntactic properties that 1from-char* has. 3set-character-translation* 1from-char* 1to-char* &optional 1readtable* Changes 1readtable* so that 1from-char* will be translated to 1to-char* upon read-in, when 1readtable* is the current readtable. This is normally used only for translating lower case letters to upper case. Character translation is inhibited by escape characters and within strings. 1readtable* defaults to the current readtable. The following syntax-setting functions are more or less obsolete. 3set-syntax-from-description* 1char* 1description* &optional 1readtable* Sets the syntax of 1char* in 1readtable* to be that described by the symbol 1description*. 1readtable* defaults to the current readtable. Each readtable has its own set of descriptions which it defines. The following descriptions are defined in the standard readtable: 2si:alphabetic* An ordinary character such as `2A*'. 2si:break* A token separator such as `2(*'. (Obviously left parenthesis has other properties besides being a break. 2si:whitespace* A token separator that can be ignored, such as `2 *'. 2si:single* A self-delimiting single-character symbol. The initial readtable does not contain any of these. 2si:escape* The character quoter. In the initial readtable this is `2/*'. 2si:multiple-escape* The symbol print-name quoter. In the initial readtable this is `2|*'. 2si:macro* A macro character. Don't use this; use 2set-macro-character* (4(READPRINT-4)Read-Macro Characters*). 2si:non-terminating-macro* A macro character recognized only at the start of a token. In the initial readtable, `3#*' is such a character. (It is also a dispatching macro, but that is another matter.) The correct way to make a character be a macro is with 2set-macro-character*. 2si:character-code-escape* The octal escape for special characters. In the initial readtable this is `2*'. 2si:digitscale* a character for shifting an integer by digits. In the initial readtable this is `3^*'. 2si:bitscale* A character for shifting an integer by bits. In the initial readtable this is `3_*' (underscore). 2si:slash* 2si:circlecross*Obsolete synonyms for 2si:escape* and 2si:character-code-escape*. Unfortunately it is no longer possible to provide 2si:doublequote* as double-quote is now an ordinary macro character. These symbols may be moved to the keyword package at some point. 3setsyntax* 1character* 1arg2* 1arg3* This exists only for Maclisp compatibility. The above functions are preferred in new programs. The syntax of 1character* is altered in the current readtable, according to 1arg2* and 1arg3*. 1character* can be a fixnum, a symbol, or a string, i.e. anything acceptable to the 2character* function. 1arg2* is usually a keyword; it can be in any package since this is a Maclisp compatibility function. The following values are allowed for 1arg2*: 2:macro* The character becomes a macro character. 1arg3* is the name of a function to be invoked when this character is read. The function takes no arguments, may 2tyi* or 2read* from 2*standard-input** (i.e. may call 2tyi* or 2read* without specifying a stream), and returns an object which is taken as the result of the read. 2:splicing* Like 2:macro* but the object returned by the macro function is a list that is 2nconc*ed into the list being read. If the character is read anywhere except inside a list (at top level or after a dotted-pair dot), then it may return 2()*, which means it is ignored, or 2(1obj*)*, which means that 1obj* is read. 2:single* The character becomes a self-delimiting single-character symbol. If 1arg3* is a fixnum, the character is translated to that character. 2nil* The syntax of the character is not changed, but if 1arg3* is a fixnum, the character is translated to that character. 2a symbol* The syntax of the character is changed to be the same as that of the character 1arg2* in the standard initial readtable. 1arg2* is converted to a character by taking the first character of its print name. Also if 1arg3* is a fixnum, the character is translated to that character. =Node: 4Read-Macro Characters* =Text: 3READ-MACRO CHARACTERS* A 1read-macro character* (or just 1macro character*) is a character whose syntax is defined by a function which the reader calls whenever that character is seen (unless it is escaped). This function can optionally read additional characters and is then responsible for returning the object which they represent. The standard meanings of the characters open-parenthesis, semicolon, single-quote, double-quote, 2#*, backquote (2`*) and comma are implemented by making them macro characters. For example, open-parenthesis is implemented as a macro character whose defining function reads expressions until a close-parenthesis is found, throws away the close-parenthesis, and returns a list of the expressions read. (It actually must be more complicated than this in order to deal properly with dotted lists and with indentation checking.) Semicolon is implemented as a macro character whose defining function swallows characters until a 2Return* and then returns no values. Close-parenthesis and close-horseshoe () are also macro characters so that they will terminate symbols. Their defining functions signal errors if actually called; but when these delimiters are encountered in their legitimate contexts they are recognized and handled specially before the defining function is called. The user can also define macro characters. When a macro's defining function is called, it receives two arguments: the input stream, and the macro character being handled. The function may read characters from the stream, and should return zero or more values, which are the objects that the macro construct ``reads as''. Zero values causes the macro construct to be ignored (the semicolon macro character does this), and one value causes the macro construct to read as a single object (most macro characters do this). More than one value is allowed only within a list. Macro characters may be 1terminating* or 1non-terminating*. A non-terminating macro character is only recognized as a macro character when it appears at the beginning of a token. If it appears when a token is already in progress, it is treated as a symbol constituent. Of the standard macro characters, all but 2#* are terminating. One kind of macro character is the 1dispatch* macro character. This kind of character is handled by reading one more character, converting it to upper case, and looking it up in a table. Thus, the dispatch macro character is the start of a two-character sequence, with which is associated a defining function. 2#* is the only standardly defined dispatch macro character. When a dispatch macro character is used, it may be followed by a decimal integer which serves as a parameter. The character for the dispatch is actually the first non-digit seen. The defining function for a dispatch macro two-character sequence is almost like that of an ordinary macro character. However, it receives one more argument. This is the parameter, the decimal integer that followed the dispatch macro character, or 2nil* if no parameter was written. Also, the second argument is the subdispatch character, the second character of the sequence. The dispatch macro character itself is not available. 3set-macro-character* 1char* 1function* &optional 1non-terminating-p* 1in-readtable* Sets the syntax of character 1char* in readtable 1in-readtable* to be that of a macro character which is handled by 1function*. When that character is read by 2read*, 1function* is called. 1char* is made a non-terminating macro character if 1non-terminating-p* is non-2nil*, a terminating one otherwise. 3get-macro-character* 1char* 1in-readtable* Returns two values that describe the macro character status of 1char* in 1in-readtable*. If 1char* is not a macro character, both values are 2nil*. Otherwise, the first value is the 1function* and the second value is the 1non-terminating-p* for this character. Those two values, passed to 2set-macro-character*, are usually sufficient to recreate exactly the syntax 1char* has now; however, since one of the arguments that the function receives is the macro character that invoked it, it may not behave the same if installed on a different character or in a different readtable. In particular, the definition of a dispatch macro character is a standard function that looks the macro character up in the readtable. Thus, the definition only records that the macro character 1is* a dispatch macro character; it does not say what subcharacters are allowed or what they mean. 3make-dispatch-macro-character* 1char* &optional 1non-terminating-p* 1in-readtable* Makes 1char* be a dispatch macro character in 1in-readtable*. This means that when 1char* is seen 2read* will read one more character to decide what to do. 2#* is an example of a dispatch macro character. 1non-terminating-p* means the same thing as in 2set-macro-character*. 3set-dispatch-macro-character* 1char* 1subchar* 1function* &optional 1in-readtable* Sets the syntax of the two-character sequence 1char* 1subchar*, assuming that 1char* is already a dispatch macro character. 1function* becomes the defining function for this sequence. If 1subchar* is lower case, it is converted to upper case. Case is never significant for the character that follows a dispatch macro character. The decimal digits may not be defined as subchars since they are always used for infix numeric arguments as in 3#5r*. 3get-dispatch-macro-character* 1char* 1subchar* &optional 1in-readtable* Returns the 1function* for 1subchar* following dispatch macro character 1char* in readtable 1in-readtable*. The value is 2nil* if 1subchar* is not defined for following 1char*. These subroutines are for use by the defining functions of macro characters. Ordinary 2read* should not be used for reading subexpressions, and the ordinary 2:tyi* operation or functions 2read-char* or 2tyi* should not be used for single-character input. The functions below should be used instead. 3si:read-recursive* &optional 1stream* Equivalent to 2(cli:read 1stream* t nil t)*. See 4(READPRINT-3)Expression Input Functions*. This is the recommended way for a macro character's defining function to read a subexpression. 3si:xr-xrtyi* 1stream* 1ignore-whitespace* 1no-chars-special* 1no-multiple-escapes* Reads the next input character from 1stream*, for a macro character's defining function. If 1ignore-whitespace* is non-2nil*, any whitespace characters seen are discarded and the first non-whitespace character is returned. The first value is the character as translated; the third value is the original character, before translation. The second value is a syntax code which is of no interest to users except to be passed to 2si:xr-xruntyi* if this character must be unread. Normally, this function processes all the escape characters, and performs translations (such as from lower case letters to upper case letters) on characters not escaped. Font specifiers (epsilons followed by digits or 3**) are ignored if the file is formatted using them. If 1no-multiple-escapes* is non-2nil*, multiple escapes (vertical bar characters) are not processed; they are returned to the caller. This mode is used for reading the contents of strings. If 1no-chars-special* is non-2nil*, no escape characters are processed. All characters are simply returned to the caller (except that font specifiers are still discarded if appropriate). 3si:xr-xruntyi* 1stream* 1char* 1num* Unreads 1char*, for a macro character's defining function. 1char* should be the third value returned by the last call to 2si:xr-xrtyi*, and 1num* should be the second value. 3*read-suppress** 1Variable* If this variable is non-2nil*, all the standard read functions and macro characters do their best to avoid any errors, and any side effects except for removing characters from the input stream. For example, symbols are not interned to avoid either errors (for nonexistent packages) or side effects (adding new symbols to packages). In fact, 2nil* is used in place of any symbol that is written. User macro characters should also notice this variable when appropriate. The purpose of the variable is to allow expressions to be skipped and discarded. The read-time conditional constructs 3#+* and 3#-* bind it to 2t* to skip the following expression if it is not wanted. The following functions for defining macro characters are more or less obsolete. 3set-syntax-macro-char* 1char* 1function* &optional 1readtable* Changes 1readtable* so that 1char* is a macro character. When 1char* is read, 1function* is called. 1readtable* defaults to the current readtable. 1function* is called with two arguments, 1list-so-far* and the input stream. When a list is being read, 1list-so-far* is that list (2nil* if this is the first element). At the top level of 2read*, 1list-so-far* is the symbol 2:toplevel*. After a dotted-pair dot, 1list-so-far* is the symbol 2:after-dot*. 1function* may read any number of characters from the input stream and process them however it likes. 1function* should return three values, called 1thing*, 1type*, and 1splice-p*. 1thing* is the object read. If 1splice-p* is 2nil*, 1thing* is the result. If 1splice-p* is non-2nil*, then when reading a list 1thing* replaces the list being read--often it will be 1list-so-far* with something else 2nconc*'ed onto the end. At top-level and after a dot, if 1splice-p* is non-2nil* the 1thing* is ignored and the macro-character does not contribute anything to the result of 2read*. 1type* is a historical artifact and is not really used; 2nil* is a safe value. Most macro character functions return just one value and let the other two default to 2nil*. Note that the convention for values returned by 1function* is different from that used for functions specified in 2set-macro-character*, above. 2set-syntax-macro-char* works by encapsulating 1function* in a closure to convert the values to the sort that 2set-macro-character* wants and then passing the closure to 2set-macro-character*. 1function* should not have any side-effects other than on the stream and 1list-so-far*. Because of the way the rubout-handler works, 1function* can be called several times during the reading of a single expression in which the macro character only appears once. 1char* is given the same syntax that single-quote, backquote, and comma have in the initial readtable (it is called 2:macro* syntax). 3set-syntax-* 1#-macro-char* 1char* 1function* &optional 1readtable* Causes 1function* to be called when 3#1char** is read. 1readtable* defaults to the current readtable. The function's arguments and return values are the same as for normal macro characters, documented above. When 1function* is called, the special variable 2si:xr-sharp-argument* contains 2nil* or a number that is the number or special bits between the 2#* and 1char*. 3setsyntax-sharp-macro* 1character* 1type* 1function* &optional 1readtable* This exists only for Maclisp compatibility. 2set-dispatch-macro-character* should be used instead. If 1function* is 2nil*, 3#1character** is turned off, otherwise it becomes a macro that calls 1function*. 1type* can be 2:macro*, 2:peek-macro*, 2:splicing*, or 2:peek-splicing*. The splicing part controls whether 1function* returns a single object or a list of objects. Specifying peek causes 1character* to remain in the input stream when 1function* is called; this is useful if 1character* is something like a left parenthesis. 1function* gets one argument, which is 2nil* or the number between the 2#* and the 1character*. =Node: 4The :read and :print Stream Operations* =Text: 3THE :READ AND :PRINT STREAM OPERATIONS* A stream can specially handle the reading and printing of objects by handling the 2:read* and 2:print* stream operations. Note that these operations are optional and most streams do not support them. If the 2read* function is given a stream that has 2:read* in its which-operations, then instead of reading in the normal way it sends the 2:read* message to the stream with one argument, 2read*'s 1eof-option* if it had one or a magic internal marker if it didn't. Whatever the stream returns is what 2read* returns. If the stream wants to implement the 2:read* operation by internally calling 2read*, it must use a different stream that does not have 2:read* in its which-operations. If a stream has 2:print* in its which-operations, it may intercept all object printing operations, including those due to the 2print*, 2prin1*, and 2princ* functions, those due to 2format*, and those used internally, for instance in printing the elements of a list. The stream receives the 2:print* message with three arguments: the object being printed, the 1depth* (for comparison against the 2*print-level** variable), and 1escape-p* (which is the value of 2*print-escape**). If the stream returns 2nil*, then normal printing takes place as usual. If the stream returns non-2nil*, then 2print* does nothing; the stream is assumed to have output an appropriate printed representation for the object. The two following functions are useful in this connection; however, they are in the 2system-internals* package and may be changed without much notice. 3si:print-object* 1object* 1depth* 1stream* &optional 1which-operations* Outputs the printed-representation of 1object* to 1stream*, as modified by 1depth* and the values of the 2*print-...* variables. This is the internal guts of the Lisp printer. When a stream's 2:print* handler calls this function, it should supply the list 2(:string-out)* for 1which-operations*, to prevent itself from being called recursively. Or it can supply 2nil* if it does not want to receive 2:string-out* messages. If you want to customize the behavior of all printing of Lisp objects, advising (see 4(DEBUGGING-5)Advising a Function*) this function is the way to do it. See 4(READPRINT-1)What the Printer Produces*. 3si:print-list* 1list* 1depth* 1stream* 1which-operations* This is the part of the Lisp printer that prints lists. A stream's 2:print* handler can call this function, passing along its own arguments and its own which-operations, to arrange for a list to be printed the normal way and the stream's 2:print* hook to get a chance at each of the list's elements.