;;; -*- Mode:gate; Fonts:(HL12 HL12I HL12B CPTFONTB HL12BI HL12B HL12I ) -*- =Node: Aids for Debugging Macros =Text: 3AIDS FOR DEBUGGING MACROS mexp* &optional 1form* 2mexp* goes into a loop in which it reads forms and sequentially expands them, printing out the result of each expansion (using the grinder (see 4(READPRINT-3)Pretty-Printing Output Functions*) to improve readability). When the form itself has been expanded until it is no longer a macro call, 2macroexpand-all* is used to expand all its subforms, and the result is printed if it is different from what preceded. This allows you to see what your macros are expanding into, without actually evaluating the result of the expansion. If the form you type is an atom, 2mexp* returns. Usually one simply uses 2Abort* to exit it. If the form you type is a list that not a macro call, nothing is printed. You are prompted immediately for another form. If the argument 1form* is given, it is expanded and printed as usual, and then 2mexp* returns immediately. If you type 3(mexp)* followed by 3(rest (first x))* then 3mexp* will print 3(cdr (first x))* and then 3(cdr (car x))* You would then type 2Abort* to exit 2mexp*. ;;; -*- Mode:gate; Fonts:(HL12 HL12I HL12B CPTFONTB HL12BI HL12B HL12I ) -*- =Node: Displacing Macro Calls =Text: 3DISPLACING MACRO CALLS* Every time the the evaluator sees a macro form, it must call the macro to expand the form. This is time consuming. To speed things up, the expansion of the macro is recorded automatically by modifying the form using 2rplaca* and 2rplacd* so that it no longer appears to need expansion. If the same form is evaluated again, it can be processed straight away. This is done using the function 2displace*. A consequence of the evaluator's policy of displacing macro calls is that if you change the definition of a macro, the new definition does not take effect in any form that has already been displaced. An existing form which calls the macro will use the new definition only if the form has never been evaluated. 3displace* 1form* 1expansion* 1form* must be a list. 2displace* replaces the car and cdr of 1form* so that it looks like: 3(si:displaced 1form* 1expansion*)* When a form whose car is 2si:displaced* is evaluated, the evaluator simply extracts the expansion and evaluates it. 1old-form-copy* is a newly consed pair whose car and cdr are the same as the original car and cdr of the form; thus, it records the macro call which was expanded. 2grindef* uses this information to print the code as it was, rather than as it has been expanded. 2displace* returns 1expansion*. The precise format of a displaced macro call may be changed in the future to facilitate the implementation of automatic reexpansion if the called macro changes. =Node: Functions to Expand Macros =Text: 3FUNCTIONS TO EXPAND MACROS* The following two functions are provided to allow the user to control expansion of macros; they are often useful for the writer of advanced macro systems, and in tools that want to examine and understand code that may contain macros. 3macroexpand-1* 1form* &optional 1local-macros-environment* If 1form* is a macro form, this expands it (once) and returns the expanded form. Otherwise it just returns 1form*. The second value is 2t* if 1form* has been expanded. 1local-macros-environment* is a data structure which specifies the local macro definitions (made by 2macrolet*) to be used for this expansion in addition to the global macro definitions (made by 2defmacro* and recorded in function cells of symbols). When 2macroexpand-1* is called by the evaluator, this argument comes from the evaluator's own data structures set up by any 2macrolet* forms which 1form* was found within. When 2macroexpand-1* is called by the compiler, this argument comes from data structures kept by the compiler in its handling of 2macrolet*. Sometimes macro definitions call 2macroexpand-1*; in that case, if 1form* was a subform of the macro call, a 2&environment* argument in the macro definition can be used to obtain a value to pass as 1local-macros-environment*. See 4(MACROS-1)Defmacro*. 2setf* is one example of a macro that needs to use 2&environment* since it expands some of its subforms in deciding what code to expand into. See 2setf*. If 1local-macros-environment* is omitted or 2nil*, only global macro definitions are used. 2macroexpand-1* expands 2defsubst* function forms as well as macro forms. 3macroexpand* 1form* &optional 1local-macros-environment* If 1form* is a macro form, this expands it repeatedly until it is not a macro form and returns the final expansion. Otherwise, it just returns 1form*. The second value is 2t* if one or more expansions have take place. Everything said about 1local-macros-environment* under 2macroexpand-1* applies here too. 2macroexpand* expands 2defsubst* function forms as well as macro forms. 3macroexpand-all* 1form* &optional 1local-macros-environment* Expands all macro calls in 1form*, including those which are its subforms, and returns the result. By contrast, 2macroexpand* would not expand the subforms. This function knows the syntax of all Lisp special forms, so the result is completely accurate. Note, however, that quoted list structure within 1form* is not altered; there is no way to know whether you intend such list structure to be code or to be used in constructing code. 3*macroexpand-hook** 1Variable* The value is a function which is used by 2macroexpand-1* to invoke the expander function of a macro. It receives arguments just like 2funcall*: the expander function, and the arguments for it. In fact, the default value of this variable 1is* 2funcall*. The variable exists so that the user can set it to some other function, which performs the 2funcall* and possibly other associated record-keeping. 2*macroexpand-hook** is not used when a macro is expanded by the interpreter. ;;; -*- Mode:gate; Fonts:(HL12 HL12I HL12B CPTFONTB HL12BI HL12B HL12I ) -*- =Node: Definitions of Macros =Text: 3DEFINITIONS OF MACROS* The definition of a macro is a list whose car is the symbol 2macro*. The cdr of the list is the macro's 1expander function*. This expander function contains the code written in the 2defmacro* or other construct which was used to define the macro. It may be a 2lambda* expression, or it may be a compiled function object (FEF). Expanding the macro is done by invoking the expander function. When an expander function is called, it receives two arguments: the macro call to be expanded, and the local macros environment. If the expansion is being done by 2macroexpand-1* then the local macros environment passed is the one that was given to 2macroexpand-1*. In a macro defined with 2defmacro*, the local macros environment can be accessed by writing an 2&environment* parameter (see 4(MACROS-1)Defmacro*). Expander functions used to be given only one argument. For compatibility, it is useful to define expander functions so that the second argument is optional; 2defmacro* does so. In addition, old macro definitions still work, because 2macroexpand-1* actually checks the number of arguments which the expander function is ready to receive, and passes only one argument if the expander function expects only one. This is done using 2call* (see 4(EVAL-4)Some Functions and Special Forms*). 3macro-function* 1function-spec* If 1function-spec* is defined as a macro, then this returns its expander-function: the function which should be called, with a macro call as its sole argument, to produce the macro expansion. For certain special forms, 2macro-function* returns the ``alternate macro definition'' (see below). Otherwise, 2macro-function* returns 2nil*. Since a definition as a macro is really a list of the form 2(macro . 1expander-function*)*, you can get the expander function using 2(cdr (fdefinition 1function-spec*))*. But it is cleaner to use 2macro-function*. 3(setf (macro-function 1function-spec*) 1expander*)* is permitted, and is equivalent to 3(fdefine 2function-spec* (cons 'macro 2expander*))* Certain constructs which Common Lisp specifies as macros are actually implemented as special forms (2cond*, for example). These special forms have ``alternate macro definitions'' which are the definitions they might have if they were implemented as macros. This is so that the caller of 2macro-function*, if it is a portable Common Lisp program, need not know about any special forms except the standard Common Lisp ones in order to make deductions about all valid Common Lisp programs. It can instead regard as a macro any symbol on which 2macro-function* returns a non-2nil* value, and treat that value as the macro expander function. The alternate macro definition of a symbol such as 2cond* is not actually its function definition. It exists only for 2macro-function* to return. The existence of alternate macro definitions means that 2macro-function* is not useful for testing whether a symbol really is defined as a macro. =Node: Extending setf and locf =Text: 3EXTENDING SETF AND LOCF* There are three ways to tell the system how to 2setf* a function: simple 2defsetf* when it is trivial, general 2defsetf* which handles most other cases, and 2define-setf-method* which provides the utmost generality. 3defsetf* 1Macro* The simple way to use 2defsetf* is useful when there is a setting function which does all the work of storing a value into the appropriate place and has the proper calling conventions. 3(defsetf 1function* 1setting-function*)* says that the way to store into 2(1function* 1args*...)* is to do 2(1setting-function* 1args*...* 1new-value2)**. For example, 3(defsetf car sys:setcar)* is the way 2setf* of 2car* is defined. Its meaning is that 2(setf (car 1x*) 1y*)* should expand into 2(sys:setcar 1x* 1y*)*. (2setcar* is like 2rplaca* except that 2setcar* returns its second argument). The more general form of 2defsetf* is used when there is no setting function with exactly the right calling sequence. Thus, 3(defsetf 1function* (1function-args*...) (1value-arg*) 1body*...)* tells 2setf* how to store into 2(1function* 1args*...)* by providing something like a macro defininition to expand into code to do the storing. 1body* computes the code; the last form in 1body* returns a suitable expression. 1function-args* should be a lambda list, which can have optional and rest args. 1body* can substitute the values of the variables in this lambda list, to refer to the arguments in the form being 2setf*'ed. Likewise, it can substitute in 1value-arg* to refer to the value to be stored. In fact, the 1function-args* and 1value-arg* are not actually the subforms of the form being 2setf*d and the value to be stored; they are gensyms. After the 1body* returns, the corresponding expressions may be substituted for the gensyms, or the gensyms may remain as local variables with a suitable 2let* provided to bind them. This is how 2setf* ensures a correct order of evaluation. Example: 3(defsetf car (list) (value) `(sys:setcar ,list ,value))* is how one could define the 2setf*'ing of 2car* using the general form of 2defsetf*. The simple form of 2defsetf* can be regarded as an abbreviation for something like this. Since 2setf* automatically expands macros, if you define a macro whose expansion is usable in 2setf* then the macro is usable there also. Sometimes this is not desirable. For example, the accessor subst for a slot in a 2defstruct* structure probably expands into 2aref*, but if the slot is declared 2:read-only* this should not be allowed. It is prevented by means of a 2defsetf* like this: 3(defsetf 1accessor-function*)* This means that 2setf* is explicitly prohibited on that function. 3define-setf-method* 1function* 1(function-args...)* 1(value-arg)* 1body...* 1Macro* Defines how to do 2setf* on 1place*'s starting with 1function*, with more power and generality than 2defsetf* provides, but more complexity of use. The 2define-setf-method* form receives its arguments almost like an analogous 2defsetf*. However, the values it receives are the actual subforms, and the actual form for the value, rather than gensyms which stand for them. The 1function-args* are the actual subforms of the place to be 2setf*'ed, and the full power of 2defmacro* arglists can be used to match against it. 1value-arg* is the actual form used as the second argument to 2setf*. 1body* is once again evaluated, but it does not return an expression to do the storing. Instead, it returns five values which contain sufficient information to enable anyone to examine and modify the contents of the place. This information tells the caller which subforms of the place need to be evaluated, and how to use them to examine or set the value of the place. (Generally the function-args arglist is arranged to make each arg get one subform.) A temporary variable must be found or made (usually with 2gensym*) for each of them. Another temporary variable should be made to correspond to the value to be stored. Then the five values to be returned are: 20* A list of the temporary variables for the subforms of the place. 21* A list of the subforms that they correspond to. 22* A list of the temporary variables for the values to be stored. Currently there can only be one value to be stored, so there is only one variable in this list, always. 23* A form to do the storing. This form refers to some or all of the temporary variables listed in value 1. 24* A form to get the value of the place. 2setf* does not need to do this, but 2push* and 2incf* do. This too should refer only to the temporary variables. No expression of contained it it should be a subexpression of the place being stored in. This information is everything that the macro (2setf* or something more complicated) needs to know to decide what to do. Example: 3(define-setf-method car (function-spec)* 3 (let ((tempvars (list (gensym)))* 3(tempargs (list (list-form)))* 3(storevar (gensym)))* 3 (values tempvars tempargs (list storevar)* 3 `(sys:setcar ,(first tempvars) ,storevar)* 3 `(car ,(first tempvars)))))* is how one could define the 2setf*'ing of 2car* using 2define-setf-method*. This definition is equivalent to the other two definitions using the simpler techniques. 3get-setf-method* 1form* Invokes the 2setf* method for form (which must be a list) and returns the five values produced by the body of the 2define-setf-method* for the symbol which is the car of form. The meanings of these five values are given immediately above. If the way to 2setf* that symbol was defined with 2defsetf* you still get five values, which you can interpret in the same ways; thus, 2defsetf* is effectively an abbreviation for a suitable 2define-setf-method*. There are two ways to use 2get-setf-method*. One is in a macro which, like 2setf* or 2incf* or 2push*, wants to store into a place. The other is in a 2define-setf-method* for something like 2ldb*, which is 2setf* by setting one of its arguments. You would append your new tempvars and tempargs to the ones you got from 2get-setf-method* to get the combined lists which you return. The forms returned by the 2get-setf-method* you would stick into the forms you return. An example of a macro which uses 2get-setf-method* is 2pushnew*. (The real 2pushnew* is a little hairier than this, to handle the 1test*, 1test-not* and 1key* arguments). 3(defmacro pushnew (value place)* 3 (multiple-value-bind* 3 (tempvars tempargs storevars storeform refform)* 3 (get-setf-method place)* 3 (si:sublis-eval-once* 3 (cons `(-val- . ,value) (pairlis tempvars tempargs))* 3 `(if (memq -val- ,refform)* 3 ,refform* 3 ,(sublis (list (cons (car storevars)* 3 `(cons -val- ,refform)))* 3 storeform))* 3 t t)))* An example of a 3define-setf-method* that uses 3get-setf-method* is that for 3ldb*: 3(define-setf-method ldb (bytespec int)* 3 (multiple-value-bind * 3 (temps vals stores store-form access-form)* 3 (get-setf-method int)* 3 (let ((btemp (gensym))* 3 (store (gensym))* 3 (itemp (first stores)))* 3 (values (cons btemp temps)* 3 (cons bytespec vals)* 3 (list store)* 3 `(progn * 3 ,(sublis* 3 (list (cons itemp* 3`(dpb ,store ,btemp* 3 ,access-form)))* 3 store-form)* 3,store)* 3 `(ldb ,btemp ,access-form)))))* What this says is that the way to 2setf* 2(ldb 1byte* (foo))* is computed based on the way to 2setf* 2(foo)*. 3si:sublis-eval-once* 1alist* 1form* &optional 1reuse-tempvars* 1sequential-flag* Replaces temporary variables in 1form* with corresponding values according to 1alist*, but generates local variables when necessary to make sure that the corresponding values are evaluated exactly once and in same order that they appear in 1alist*. (This complication is skipped when the values are constant). 1alist* should be a list of elements 2(1tempvar* . 1value*)*. The result is a form equivalent to 3`(let ,(mapcar #'(lambda (elt) (list (car elt) (cdr elt)))* 3 alist)* 3 ,form)* but it usually contains fewer temporary variables and executes faster. If 1reuse-tempvars* is non-2nil*, the temporary variables which appear as the cars of the elements of 1alist* are allowed to appear in the resulting form. Otherwise, none of them appears in the resulting form, and if any local variables turn out to be needed, they are made afresh with 2gensym*. 1reuse-tempvars* should be used only when it is guaranteed that none of the temporary variables in 1alist* is referred to by any of the values to be substituted; as, when the temporary variables have been freshly made with 2gensym*. If 1sequential-flag* is non-2nil*, then the value substituted for a temporary variable is allowed to refer to the temporary variables preceding it in alist. 2setf* and similar macros should all use this option. 3define-modify-macro* 1macro-name* 1(lambda-list...)* 1combiner-function* 1[doc-string]* Is a quick way to define 2setf*'ing macros which resemble 2incf*. For example, here is how 2incf* is defined: 3(define-modify-macro incf (&optional (delta 1)) +* 3 "Increment PLACE's value by DELTA.")* 1lambda-list* describes any arguments the macro accepts, but not first argument, which is always the place to be examined and modified. The old value of this place, and any additional arguments such as 2delta* in the case of 2incf*, are combined using the 1combiner-function* (in this case, 2+*) to get the new value which is stored back in the place. 3deflocf* 1Macro* Defines how to perform 2locf* on a generalized variable. There are two forms of usage, analogous to those of 2defsetf*. 3(deflocf 1function* 1locating-function*)* says that the way to get the location of 2(1function* 1args*...)* is to do 2(1locating-function* 1args*...)*. For example, 3(deflocf car sys:car-location)* could be used to define 2locf* on 2car* forms. is the way 2setf* of 2car* is defined. Its meaning is that 2(locf (car 1x*))* should expand into 2(sys:car-location 1x*)*. The more general form of 2deflocf* is used when there is no locating function with exactly the right calling sequence. Thus, 3(deflocf 1function* (1function-args*...) 1body*...)* tells 2locf* how to locate 2(1function* 1args*...)* by providing something like a macro defininition to expand into code to do the locating. 1body* computes the code; the last form in 1body* returns a suitable expression. 1function-args* should be a lambda list, which can have optional and rest args. 1body* can substitute the values of the variables in this lambda list, to refer to the arguments in the form being 2locf*'ed. Example: 3(deflocf car (list) `(sys:car-location ,list))* is how one could define the 2locf*'ing of 2car* using the general form of 2deflocf*. The simple form of 2deflocf* can be regarded as an abbreviation for something like this. 3(deflocf 1function*)* says that 2locf* should not be allowed on forms starting with 1function*. This is useful only when 1function* is defined as a macro or subst, for then 2locf*'s normal action is to expand the macro call and try again. In other cases there is no way to 2locf* a function unless you define one, so you can simply refrain from defining any way.