User Tools


Differences

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

Link to this comparison view

cl:macros:defconstant [2019/07/14 17:00]
cl:macros:defconstant [2019/07/18 14:00] (current)
Line 1: Line 1:
 +====== Macro DEFCONSTANT ======
 +
 +====Syntax====
 +  * **defconstant** //name initial-value [documentation]//​ → //name//
 +
 +====Arguments and Values====
 +  * //name// - a //​[[CL:​Glossary:​symbol]]//;​ not evaluated.
 +  * //​initial-value//​ - a //​[[CL:​Glossary:​form]]//;​ evaluated.
 +  * //​documentation//​ - a //​[[CL:​Glossary:​string]]//;​ not evaluated.
 +
 +====Description====
 +**defconstant** causes the global variable named by //name// to be given a value that is the result of evaluating //​initial-value//​.
 +
 +A constant defined by **defconstant** can be redefined with **defconstant**. However, the consequences are undefined if an attempt is made to assign a //​[[CL:​Glossary:​value]]//​ to the //​[[CL:​Glossary:​symbol]]//​ using another operator, or to assign it to a //​[[CL:​Glossary:​different]]//​ //​[[CL:​Glossary:​value]]//​ using a subsequent **defconstant**.
 +
 +If //​documentation//​ is supplied, it is attached to //name// as a //​[[CL:​Glossary:​documentation string]]// of kind **[[CL:​Types:​variable]]**.
 +
 +**defconstant** normally appears as a //​[[CL:​Glossary:​top level form]]//, but it is meaningful for it to appear as a //​[[CL:​Glossary:​non-top-level form]]//. However, the compile-time side effects described below only take place when **defconstant** appears as a //​[[CL:​Glossary:​top level form]]//.
 +
 +The consequences are undefined if there are any //​[[CL:​Glossary:​binding|bindings]]//​ of the variable named by //name// at the time **defconstant** is executed or if the value is not **[[CL:​Functions:​eql]]** to the value of //​initial-value//​.
 +
 +The consequences are undefined when constant //​[[CL:​Glossary:​symbol|symbols]]//​ are rebound as either lexical or dynamic variables. In other words, a reference to a //​[[CL:​Glossary:​symbol]]//​ declared with **defconstant** always refers to its global value.
 +
 +The side effects of the execution of **defconstant** must be equivalent to at least the side effects of the execution of the following code:
 +
 +<​blockquote>​
 +([[CL:​Macros:​setf]] (symbol-value '//​name//​) //​initial-value//​)
 +([[CL:​Macros:​setf]] (documentation '//​name//​ '​variable) '//​documentation//​)
 +</​blockquote>​
 +
 +If a **defconstant** //​[[CL:​Glossary:​form]]//​ appears as a //​[[CL:​Glossary:​top level form]]//, the //​[[CL:​Glossary:​compiler]]//​ must recognize that //name// names a //​[[CL:​Glossary:​constant variable]]//​. An implementation may choose to evaluate the value-form at compile time, load time, or both. Therefore, users must ensure that the //​initial-value//​ can be //​[[CL:​Glossary:​evaluate|evaluated]]//​ at compile time (regardless of whether or not references to //name// appear in the file) and that it always //​[[CL:​Glossary:​evaluate|evaluates]]//​ to the same value.
 +
 +====Examples====
 +<​blockquote>​
 +(defconstant this-is-a-constant '​never-changing "for a test") <​r>​THIS-IS-A-CONSTANT </r>
 +this-is-a-constant <​r>​NEVER-CHANGING</​r>​
 +(documentation '​this-is-a-constant '​variable) <​r>"​for a test"</​r>​
 +(constantp '​this-is-a-constant) <​r>//​[[CL:​Glossary:​true]]//</​r>​
 +</​blockquote>​
 +
 +====Affected By====
 +None.
 +
 +====Exceptional Situations====
 +None.
 +
 +====See Also====
 +  * **[[CL:​Macros:​declaim|Function DECLAIM]]**
 +  * **[[CL:​Macros:​defparameter|Macro DEFPARAMETER]]**
 +  * **[[CL:​Macros:​defvar|Macro DEFVAR]]**
 +  * **[[CL:​Functions:​documentation|Generic Function DOCUMENTATION]]**
 +  * **[[CL:​Functions:​proclaim|Function PROCLAIM]]**
 +  * {\secref\ConstantVars}
 +  * {\secref\Compilation}
 +
 +====Notes====
 +None.
 +
 +\issue{DEFVAR-DOCUMENTATION:​UNEVALUATED} \issue{DEFINING-MACROS-NON-TOP-LEVEL:​ALLOW} \issue{DEFCONSTANT-SPECIAL:​NO} \issue{COMPILE-FILE-HANDLING-OF-TOP-LEVEL-FORMS:​CLARIFY}