129 lines
14 KiB
HTML
129 lines
14 KiB
HTML
<!-- Common Lisp HyperSpec (TM), version 7.0 generated by Kent M. Pitman on Mon, 11-Apr-2005 2:31am EDT -->
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>CLHS: Macro DEFPARAMETER, DEFVAR</TITLE>
|
|
<LINK HREF="../Data/clhs.css" REL="stylesheet" TYPE="text/css" />
|
|
<META HTTP-EQUIV="Author" CONTENT="Kent M. Pitman">
|
|
<META HTTP-EQUIV="Organization" CONTENT="LispWorks Ltd.">
|
|
<LINK REL=TOP HREF="../Front/index.htm">
|
|
<LINK REL=COPYRIGHT HREF="../Front/Help.htm#Legal">
|
|
<LINK REL=DISCLAIMER HREF="../Front/Help.htm#Disclaimer">
|
|
<LINK REL=PREV HREF="m_defcon.htm">
|
|
<LINK REL=UP HREF="c_data_a.htm">
|
|
<LINK REL=NEXT HREF="m_destru.htm">
|
|
</HEAD>
|
|
<BODY>
|
|
<H1><A REV=MADE HREF="http://www.lispworks.com/"><IMG WIDTH=80 HEIGHT=65 ALT="[LISPWORKS]" SRC="../Graphics/LWSmall.gif" ALIGN=Bottom></A><A REL=TOP HREF="../Front/index.htm"><IMG WIDTH=237 HEIGHT=65 ALT="[Common Lisp HyperSpec (TM)]" SRC="../Graphics/CLHS_Sm.gif" ALIGN=Bottom></A> <A REL=PREV HREF="m_defcon.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Previous]" SRC="../Graphics/Prev.gif" ALIGN=Bottom></A><A REL=UP HREF="c_data_a.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Up]" SRC="../Graphics/Up.gif" ALIGN=Bottom></A><A REL=NEXT HREF="m_destru.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Next]" SRC="../Graphics/Next.gif" ALIGN=Bottom></A></H1>
|
|
|
|
<HR>
|
|
|
|
<A NAME="defparameter"><A NAME="defvar"><I>Macro</I> <B>DEFPARAMETER, DEFVAR</B></A></A> <P>
|
|
<P><B>Syntax:</B><P>
|
|
<P>
|
|
|
|
<B>defparameter</B> <I>name initial-value [documentation] </I> => <I>name</I><P>
|
|
|
|
<B>defvar</B> <I>name [initial-value [documentation]]</I> => <I>name</I><P>
|
|
<P>
|
|
<P><B>Arguments and Values:</B><P>
|
|
<P>
|
|
<I>name</I>---a <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbol</I></A>; not evaluated. <P>
|
|
<P>
|
|
<I>initial-value</I>---a <A REL=DEFINITION HREF="26_glo_f.htm#form"><I>form</I></A>; for <A REL=DEFINITION HREF="#defparameter"><B>defparameter</B></A>, it is always <I>evaluated</I>, but for <A REL=DEFINITION HREF="#defvar"><B>defvar</B></A> it is <I>evaluated</I> only if <I>name</I> is not already <A REL=DEFINITION HREF="26_glo_b.htm#bound"><I>bound</I></A>. <P>
|
|
<I>documentation</I>---a <I>string</I>; not evaluated. <P>
|
|
<P><B>Description:</B><P>
|
|
<P>
|
|
<A REL=DEFINITION HREF="#defparameter"><B>defparameter</B></A> and <A REL=DEFINITION HREF="#defvar"><B>defvar</B></A> <A REL=DEFINITION HREF="26_glo_e.htm#establish"><I>establish</I></A> <I>name</I> as a <A REL=DEFINITION HREF="26_glo_d.htm#dynamic_variable"><I>dynamic variable</I></A>. <P>
|
|
<A REL=DEFINITION HREF="#defparameter"><B>defparameter</B></A> unconditionally <A REL=DEFINITION HREF="26_glo_a.htm#assign"><I>assigns</I></A> the <I>initial-value</I> to the <A REL=DEFINITION HREF="26_glo_d.htm#dynamic_variable"><I>dynamic variable</I></A> named <I>name</I>. <A REL=DEFINITION HREF="#defvar"><B>defvar</B></A>, by contrast, <A REL=DEFINITION HREF="26_glo_a.htm#assign"><I>assigns</I></A> <I>initial-value</I> (if supplied) to the <A REL=DEFINITION HREF="26_glo_d.htm#dynamic_variable"><I>dynamic variable</I></A> named <I>name</I> only if <I>name</I> is not already <A REL=DEFINITION HREF="26_glo_b.htm#bound"><I>bound</I></A>. <P>
|
|
If no <I>initial-value</I> is supplied, <A REL=DEFINITION HREF="#defvar"><B>defvar</B></A> leaves the <A REL=DEFINITION HREF="26_glo_v.htm#value_cell"><I>value cell</I></A> of the <A REL=DEFINITION HREF="26_glo_d.htm#dynamic_variable"><I>dynamic variable</I></A> named <I>name</I> undisturbed; if <I>name</I> was previously <A REL=DEFINITION HREF="26_glo_b.htm#bound"><I>bound</I></A>, its old <A REL=DEFINITION HREF="26_glo_v.htm#value"><I>value</I></A> persists, and if it was previously <A REL=DEFINITION HREF="26_glo_u.htm#unbound"><I>unbound</I></A>, it remains <A REL=DEFINITION HREF="26_glo_u.htm#unbound"><I>unbound</I></A>. <P>
|
|
If <I>documentation</I> is supplied, it is attached to <I>name</I> as a <A REL=DEFINITION HREF="26_glo_d.htm#documentation_string"><I>documentation string</I></A> of kind <A REL=DEFINITION HREF="f_docume.htm#variable"><B>variable</B></A>. <P>
|
|
<A REL=DEFINITION HREF="#defparameter"><B>defparameter</B></A> and <A REL=DEFINITION HREF="#defvar"><B>defvar</B></A> normally appear as a <A REL=DEFINITION HREF="26_glo_t.htm#top_level_form"><I>top level form</I></A>, but it is meaningful for them to appear as <A REL=DEFINITION HREF="26_glo_n.htm#non-top-level_form"><I>non-top-level forms</I></A>. However, the compile-time side effects described below only take place when they appear as <A REL=DEFINITION HREF="26_glo_t.htm#top_level_form"><I>top level forms</I></A>. <P>
|
|
<P><B>Examples:</B><P>
|
|
<P>
|
|
<PRE>
|
|
(defparameter *p* 1) => *P*
|
|
*p* => 1
|
|
(constantp '*p*) => <A REL=DEFINITION HREF="26_glo_f.htm#false">false</A>
|
|
(setq *p* 2) => 2
|
|
(defparameter *p* 3) => *P*
|
|
*p* => 3
|
|
|
|
(defvar *v* 1) => *V*
|
|
*v* => 1
|
|
(constantp '*v*) => <A REL=DEFINITION HREF="26_glo_f.htm#false">false</A>
|
|
(setq *v* 2) => 2
|
|
(defvar *v* 3) => *V*
|
|
*v* => 2
|
|
|
|
(defun foo ()
|
|
(let ((*p* 'p) (*v* 'v))
|
|
(bar))) => FOO
|
|
(defun bar () (list *p* *v*)) => BAR
|
|
(foo) => (P V)
|
|
</PRE>
|
|
</TT> <P>
|
|
The principal operational distinction between <A REL=DEFINITION HREF="#defparameter"><B>defparameter</B></A> and <A REL=DEFINITION HREF="#defvar"><B>defvar</B></A> is that <A REL=DEFINITION HREF="#defparameter"><B>defparameter</B></A> makes an unconditional assignment to <I>name</I>, while <A REL=DEFINITION HREF="#defvar"><B>defvar</B></A> makes a conditional one. In practice, this means that <A REL=DEFINITION HREF="#defparameter"><B>defparameter</B></A> is useful in situations where loading or reloading the definition would want to pick up a new value of the variable, while <A REL=DEFINITION HREF="#defvar"><B>defvar</B></A> is used in situations where the old value would want to be retained if the file were loaded or reloaded. For example, one might create a file which contained: <P>
|
|
<PRE>
|
|
(defvar *the-interesting-numbers* '())
|
|
(defmacro define-interesting-number (name n)
|
|
`(progn (defvar ,name ,n)
|
|
(pushnew ,name *the-interesting-numbers*)
|
|
',name))
|
|
(define-interesting-number *my-height* 168) ;cm
|
|
(define-interesting-number *my-weight* 13) ;stones
|
|
</PRE>
|
|
</TT> <P>
|
|
Here the initial value, <TT>()</TT>, for the variable <TT>*the-interesting-numbers*</TT> is just a seed that we are never likely to want to reset to something else once something has been grown from it. As such, we have used <A REL=DEFINITION HREF="#defvar"><B>defvar</B></A> to avoid having the <TT>*interesting-numbers*</TT> information reset if the file is loaded a second time. It is true that the two calls to <B>define-interesting-number</B> here would be reprocessed, but if there were additional calls in another file, they would not be and that information would be lost. On the other hand, consider the following code: <P>
|
|
<PRE>
|
|
(defparameter *default-beep-count* 3)
|
|
(defun beep (&optional (n *default-beep-count*))
|
|
(dotimes (i n) (si:%beep 1000. 100000.) (sleep 0.1)))
|
|
</PRE>
|
|
</TT> <P>
|
|
Here we could easily imagine editing the code to change the initial value of <TT>*default-beep-count*</TT>, and then reloading the file to pick up the new value. In order to make value updating easy, we have used <A REL=DEFINITION HREF="#defparameter"><B>defparameter</B></A>. <P>
|
|
On the other hand, there is potential value to using <A REL=DEFINITION HREF="#defvar"><B>defvar</B></A> in this situation. For example, suppose that someone had predefined an alternate value for <TT>*default-beep-count*</TT>, or had loaded the file and then manually changed the value. In both cases, if we had used <A REL=DEFINITION HREF="#defvar"><B>defvar</B></A> instead of <A REL=DEFINITION HREF="#defparameter"><B>defparameter</B></A>, those user preferences would not be overridden by (re)loading the file. <P>
|
|
The choice of whether to use <A REL=DEFINITION HREF="#defparameter"><B>defparameter</B></A> or <A REL=DEFINITION HREF="#defvar"><B>defvar</B></A> has visible consequences to programs, but is nevertheless often made for subjective reasons. <P>
|
|
<P><B>Side Effects:</B><P>
|
|
<P>
|
|
If a <A REL=DEFINITION HREF="#defvar"><B>defvar</B></A> or <A REL=DEFINITION HREF="#defparameter"><B>defparameter</B></A> <A REL=DEFINITION HREF="26_glo_f.htm#form"><I>form</I></A> appears as a <A REL=DEFINITION HREF="26_glo_t.htm#top_level_form"><I>top level form</I></A>, the <A REL=DEFINITION HREF="26_glo_c.htm#compiler"><I>compiler</I></A> must recognize that the <I>name</I> has been proclaimed <A REL=DEFINITION HREF="d_specia.htm#special"><B>special</B></A>. However, it must neither <A REL=DEFINITION HREF="26_glo_e.htm#evaluate"><I>evaluate</I></A> the <I>initial-value</I> <A REL=DEFINITION HREF="26_glo_f.htm#form"><I>form</I></A> nor <A REL=DEFINITION HREF="26_glo_a.htm#assign"><I>assign</I></A> the <A REL=DEFINITION HREF="26_glo_d.htm#dynamic_variable"><I>dynamic variable</I></A> named <I>name</I> at compile time. <P>
|
|
There may be additional (<A REL=DEFINITION HREF="26_glo_i.htm#implementation-defined"><I>implementation-defined</I></A>) compile-time or run-time side effects, as long as such effects do not interfere with the correct operation of <A REL=DEFINITION HREF="26_glo_c.htm#conforming_program"><I>conforming programs</I></A>. <P>
|
|
<P><B>Affected By:</B><P>
|
|
<P>
|
|
<A REL=DEFINITION HREF="#defvar"><B>defvar</B></A> is affected by whether <I>name</I> is already <A REL=DEFINITION HREF="26_glo_b.htm#bound"><I>bound</I></A>. <P>
|
|
<P><B>Exceptional Situations:</B> None.
|
|
<P>
|
|
<P><B>See Also:</B><P>
|
|
<P>
|
|
<A REL=DEFINITION HREF="m_declai.htm#declaim"><B>declaim</B></A>, <A REL=DEFINITION HREF="m_defcon.htm#defconstant"><B>defconstant</B></A>, <A REL=DEFINITION HREF="f_docume.htm#documentation"><B>documentation</B></A>, <A REL=CHILD HREF="03_b.htm">Section 3.2 (Compilation)</A> <P>
|
|
<P><B>Notes:</B><P>
|
|
<P>
|
|
It is customary to name <A REL=DEFINITION HREF="26_glo_d.htm#dynamic_variable"><I>dynamic variables</I></A> with an <A REL=DEFINITION HREF="26_glo_a.htm#asterisk"><I>asterisk</I></A> at the beginning and end of the name. e.g., <TT>*foo*</TT> is a good name for a <A REL=DEFINITION HREF="26_glo_d.htm#dynamic_variable"><I>dynamic variable</I></A>, but not for a <A REL=DEFINITION HREF="26_glo_l.htm#lexical_variable"><I>lexical variable</I></A>; <TT>foo</TT> is a good name for a <A REL=DEFINITION HREF="26_glo_l.htm#lexical_variable"><I>lexical variable</I></A>, but not for a <A REL=DEFINITION HREF="26_glo_d.htm#dynamic_variable"><I>dynamic variable</I></A>. This naming convention is observed for all <A REL=DEFINITION HREF="26_glo_d.htm#defined_name"><I>defined names</I></A> in Common Lisp; however, neither <A REL=DEFINITION HREF="26_glo_c.htm#conforming_program"><I>conforming programs</I></A> nor <A REL=DEFINITION HREF="26_glo_c.htm#conforming_implementation"><I>conforming implementations</I></A> are obliged to adhere to this convention. <P>
|
|
The intent of the permission for additional side effects is to allow <A REL=DEFINITION HREF="26_glo_i.htm#implementation"><I>implementations</I></A> to do normal ``bookkeeping'' that accompanies definitions. For example, the <A REL=DEFINITION HREF="26_glo_m.htm#macro_expansion"><I>macro expansion</I></A> of a <A REL=DEFINITION HREF="#defvar"><B>defvar</B></A> or <A REL=DEFINITION HREF="#defparameter"><B>defparameter</B></A> <A REL=DEFINITION HREF="26_glo_f.htm#form"><I>form</I></A> might include code that arranges to record the name of the source file in which the definition occurs. <P>
|
|
<A REL=DEFINITION HREF="#defparameter"><B>defparameter</B></A> and <A REL=DEFINITION HREF="#defvar"><B>defvar</B></A> might be defined as follows: <P>
|
|
<PRE>
|
|
(defmacro defparameter (name initial-value
|
|
&optional (documentation nil documentation-p))
|
|
`(progn (declaim (special ,name))
|
|
(setf (symbol-value ',name) ,initial-value)
|
|
,(when documentation-p
|
|
`(setf (documentation ',name 'variable) ',documentation))
|
|
',name))
|
|
(defmacro defvar (name &optional
|
|
(initial-value nil initial-value-p)
|
|
(documentation nil documentation-p))
|
|
`(progn (declaim (special ,name))
|
|
,(when initial-value-p
|
|
`(unless (boundp ',name)
|
|
(setf (symbol-value ',name) ,initial-value)))
|
|
,(when documentation-p
|
|
`(setf (documentation ',name 'variable) ',documentation))
|
|
',name))
|
|
</PRE>
|
|
</TT> <P>
|
|
<P><HR>The following <A REL=META HREF="../Front/X3J13Iss.htm">X3J13 cleanup issues</A>, <I>not part of the specification</I>, apply to this section:<P><UL><LI> <A REL=CHILD HREF="../Issues/iss059.htm">COMPILE-FILE-HANDLING-OF-TOP-LEVEL-FORMS:CLARIFY</A><LI> <A REL=CHILD HREF="../Issues/iss104.htm">DEFINING-MACROS-NON-TOP-LEVEL:ALLOW</A><LI> <A REL=CHILD HREF="../Issues/iss125.htm">DEFVAR-INITIALIZATION:CONSERVATIVE</A><LI> <A REL=CHILD HREF="../Issues/iss123.htm">DEFVAR-DOCUMENTATION:UNEVALUATED</A><LI> <A REL=CHILD HREF="../Issues/iss124.htm">DEFVAR-INIT-TIME:NOT-DELAYED</A><P></UL><HR>
|
|
|
|
<A REL=NAVIGATOR HREF="../Front/StartPts.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Starting Points]" SRC="../Graphics/StartPts.gif" ALIGN=Bottom></A><A REL=TOC HREF="../Front/Contents.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Contents]" SRC="../Graphics/Contents.gif" ALIGN=Bottom></A><A REL=INDEX HREF="../Front/X_Master.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Index]" SRC="../Graphics/Index.gif" ALIGN=Bottom></A><A REL=INDEX HREF="../Front/X_Symbol.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Symbols]" SRC="../Graphics/Symbols.gif" ALIGN=Bottom></A><A REL=GLOSSARY HREF="../Body/26_a.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Glossary]" SRC="../Graphics/Glossary.gif" ALIGN=Bottom></A><A HREF="../Front/X3J13Iss.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Issues]" SRC="../Graphics/Issues.gif" ALIGN=Bottom></A><BR>
|
|
|
|
<A REL=COPYRIGHT HREF="../Front/Help.htm#Legal"><I>Copyright 1996-2005, LispWorks Ltd. All rights reserved.</I></A><P>
|
|
</BODY>
|
|
</HTML>
|