User Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

cl:macros:define-symbol-macro [2019/08/16 12:00]
cl:macros:define-symbol-macro [2019/08/23 05:00] (current)
Line 1: Line 1:
 +====== Macro DEFINE-SYMBOL-MACRO ======
 +
 +====Syntax====
 +  * **define-symbol-macro** //symbol expansion// → //symbol//
 +
 +====Arguments and Values====
 +  * //symbol// - a //​[[CL:​Glossary:​symbol]]//​.
 +  * //​expansion//​ - a //​[[CL:​Glossary:​form]]//​.
 +
 +====Description====
 +Provides a mechanism for globally affecting the //​[[CL:​Glossary:​macro expansion]]//​ of the indicated //symbol//.
 +
 +Globally establishes an expansion function for the //​[[CL:​Glossary:​symbol macro]]// named by //symbol//.
 +
 +The only guaranteed property of an expansion //​[[CL:​Glossary:​function]]//​ for a //​[[CL:​Glossary:​symbol macro]]// is that when it is applied to the //​[[CL:​Glossary:​form]]//​ and the //​[[CL:​Glossary:​environment]]//​ it returns the correct expansion. (In particular, it is //​[[CL:​Glossary:​implementation-dependent]]//​ whether the expansion is conceptually stored in the expansion function, the //​[[CL:​Glossary:​environment]]//,​ or both.)
 +
 +Each global reference to //symbol// (i.e. not //​[[CL:​Glossary:​shadow|shadowed]]//​ by a //​[[CL:​Glossary:​binding]]//​ for a //​[[CL:​Glossary:​variable]]//​ or //​[[CL:​Glossary:​symbol macro]]// named by the same //​[[CL:​Glossary:​symbol]]//​) is expanded by the normal macro expansion process; see section {\secref\SymbolsAsForms}. The expansion of a //​[[CL:​Glossary:​symbol macro]]// is subject to further //​[[CL:​Glossary:​macro expansion]]//​ in the same //​[[CL:​Glossary:​lexical environment]]//​ as the //​[[CL:​Glossary:​symbol macro]]// reference, exactly analogous to normal //​[[CL:​Glossary:​macro|macros]]//​.
 +
 +The consequences are unspecified if a **[[CL:​Declarations:​special]]** declaration is made for //symbol// while in the scope of this definition (i.e. when it is not //​[[CL:​Glossary:​shadow|shadowed]]//​ by a //​[[CL:​Glossary:​binding]]//​ for a //​[[CL:​Glossary:​variable]]//​ or //​[[CL:​Glossary:​symbol macro]]// named by the same //​[[CL:​Glossary:​symbol]]//​).
 +
 +Any use of **[[CL:​Special Operators:​setq]]** to set the value of the //symbol// while in the scope of this definition is treated as if it were a **[[CL:​Macros:​setf]]**. **[[CL:​Macros:​psetq]]** of //symbol// is treated as if it were a **[[CL:​Macros:​psetf]]**,​ and **[[CL:​Macros:​multiple-value-setq]]** is treated as if it were a **[[CL:​Special Operators:​setf]]** of **[[CL:​Functions:​value|values]]**.
 +
 +A //​[[CL:​Glossary:​binding]]//​ for a //​[[CL:​Glossary:​symbol macro]]// can be //​[[CL:​Glossary:​shadow|shadowed]]//​ by **[[CL:​Special Operators:​let]]** or **[[CL:​Special Operators:​symbol-macrolet]]**.
 +
 +====Examples====
 +<​blockquote>​
 +([[CL:​Macros:​defvar]] *things* ([[CL:​Functions:​list]] 'alpha 'beta '​gamma)) <​r>​*THINGS*</​r>​
 +
 +(define-symbol-macro *thing1* (first *things*)) <​r>​*THING1*</​r>​
 +(define-symbol-macro *thing2* (second *things*)) <​r>​*THING2*</​r>​
 +(define-symbol-macro *thing3* (third *things*)) <​r>​*THING3*</​r>​
 +
 +*thing1* <​r>​ALPHA</​r>​
 +([[CL:​Macros:​setf]] *thing1* 'ONE) <​r>​ONE</​r>​
 +*things* <​r>​(ONE BETA GAMMA)</​r>​
 +
 +([[CL:​Macros:​setf]] ([[CL:​Functions:​values]] *thing2* *thing3*) ([[CL:​Functions:​values]] 'two '​three)) ​
 +<​r>​TWO
 +THREE</​r>​
 +*thing3* <​r>​THREE </r>
 +*things* <​r>​(ONE TWO THREE)</​r>​
 +
 +([[CL:​Functions:​list]] *thing2* ([[CL:​Special Operators:​let]] ((*thing2* 2)) *thing2*)) <​r>​(TWO 2)</​r>​
 +</​blockquote>​
 +
 +====Affected By====
 +None.
 +
 +====Exceptional Situations====
 +If //symbol// is already defined as a //​[[CL:​Glossary:​global variable]]//,​ an error of type **[[CL:​Types:​program-error]]** is signaled.
 +
 +====See Also====
 +**[[CL:​Special Operators:​symbol-macrolet|Special Operator SYMBOL-MACROLET]]**,​ **[[CL:​Functions:​macroexpand|Function MACROEXPAND]]**
 +
 +====Notes====
 +None.