DEFINE-SYMBOL-MACRO(3cl)

Common Lisp Reference

DEFINE-SYMBOL-MACRO(3cl)

 

NAME

define-symbol-macro – establish an expansion function for a symbol macro (macro)

SYNOPSIS

 

define-symbol-macro symbol expansion
symbol
 

ARGUMENTS and VALUES

symbol—a symbol.  

expansion—a form.    

DESCRIPTION

Provides a mechanism for globally affecting the macro expansion of the indicated symbol.  

Globally establishes an expansion function for the symbol macro named by symbol. The only guaranteed property of an expansion function for a symbol macro is that when it is applied to the form and the environment it returns the correct expansion. (In particular, it is implementation-dependent whether the expansion is conceptually stored in the expansion function, the environment, or both.)   

Each global reference to symbol (i.e., not shadowed by a binding for a variable or symbol macro named by the same symbol) is expanded by the normal macro expansion process. The expansion of a symbol macro is subject to further macro expansion in the same lexical environment as the symbol macro reference, exactly analogous  to normal macros.  

The consequences are unspecified if a special declaration is made for symbol while in the scope of this definition (i.e., when it is not shadowed by a binding for a variable or symbol macro named by the same symbol).  

Any use of setq to set the value of the symbol while in the scope of this definition is treated as if it were a setf. psetq of symbol is treated as if it were a psetf, and multiple-value-setq is treated as if it were a setf of values.  

A binding for a symbol macro can be shadowed by let or symbol-macrolet.    

AFFECTED BY

(none)    

EXCEPTIONAL SITUATIONS

If symbol is already defined as a global variable, an error of type program-error is signaled.   

NOTES

(none)   

EXAMPLES

( defvar *things* ( list alpha beta gamma )) *THINGS*  

( define-symbol-macro thing1 ( first *things* )) THING1  
( define-symbol-macro thing2 ( second *things* )) THING2  
( define-symbol-macro thing3 ( third *things* )) THING3  

thing1 ALPHA  
( setq thing1 ONE ) ONE  
*things* ( ONE BETA GAMMA )  
( multiple-value-setq ( thing2 thing3 ) ( values two three ))
TWO  
thing3 THREE  
*things* ( ONE TWO THREE )  

(list thing2 (let ((thing2 2)) thing2)) (TWO 2)      

SEE ALSO

symbol-macrolet(3cl), macroexpand(3cl)    

AUTHOR and COPYRIGHT

Substantial portions of this page are taken from draft proposed American National Standard for Information Systems—Programming Language—Common Lisp, X3J13/94-101R, Version 15.17R, Fri 12-Aug-1994 6:35pm EDT; no copyright indicated.

Additional clarification and comments by Michael Marking <marking@tatanka.com>, http://www.tatanka.com/software/cl-manpages/; alternatively, https://github.com/wakinyantanka/cl-manpages/. Copyright 2017 Michael Marking as both an original and a derivative work.

Licensed under Creative Commons Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0).

This page last revised Sunday 26 February 2017.