path: root/devdocs/elisp/defining-variables.html

 <h3 class="section">Defining Global Variables</h3>  <p>A <em>variable definition</em> is a construct that announces your intention to use a symbol as a global variable. It uses the special forms <code>defvar</code> or <code>defconst</code>, which are documented below. </p> <p>A variable definition serves three purposes. First, it informs people who read the code that the symbol is <em>intended</em> to be used a certain way (as a variable). Second, it informs the Lisp system of this, optionally supplying an initial value and a documentation string. Third, it provides information to programming tools such as <code>etags</code>, allowing them to find where the variable was defined. </p> <p>The difference between <code>defconst</code> and <code>defvar</code> is mainly a matter of intent, serving to inform human readers of whether the value should ever change. Emacs Lisp does not actually prevent you from changing the value of a variable defined with <code>defconst</code>. One notable difference between the two forms is that <code>defconst</code> unconditionally initializes the variable, whereas <code>defvar</code> initializes it only if it is originally void. </p> <p>To define a customizable variable, you should use <code>defcustom</code> (which calls <code>defvar</code> as a subroutine). See <a href="variable-definitions">Variable Definitions</a>. </p> <dl> <dt id="defvar">Special Form: <strong>defvar</strong> <em>symbol [value [doc-string]]</em>
</dt> <dd>
<p>This special form defines <var>symbol</var> as a variable. Note that <var>symbol</var> is not evaluated; the symbol to be defined should appear explicitly in the <code>defvar</code> form. The variable is marked as <em>special</em>, meaning that it should always be dynamically bound (see <a href="variable-scoping">Variable Scoping</a>). </p> <p>If <var>value</var> is specified, and <var>symbol</var> is void (i.e., it has no dynamically bound value; see <a href="void-variables">Void Variables</a>), then <var>value</var> is evaluated and <var>symbol</var> is set to the result. But if <var>symbol</var> is not void, <var>value</var> is not evaluated, and <var>symbol</var>’s value is left unchanged. If <var>value</var> is omitted, the value of <var>symbol</var> is not changed in any case. </p> <p>Note that specifying a value, even <code>nil</code>, marks the variable as special permanently. Whereas if <var>value</var> is omitted then the variable is only marked special locally (i.e. within the current lexical scope, or file if at the top-level). This can be useful for suppressing byte compilation warnings, see <a href="compiler-errors">Compiler Errors</a>. </p> <p>If <var>symbol</var> has a buffer-local binding in the current buffer, <code>defvar</code> acts on the default value, which is buffer-independent, rather than the buffer-local binding. It sets the default value if the default value is void. See <a href="buffer_002dlocal-variables">Buffer-Local Variables</a>. </p> <p>If <var>symbol</var> is already lexically bound (e.g., if the <code>defvar</code> form occurs in a <code>let</code> form with lexical binding enabled), then <code>defvar</code> sets the dynamic value. The lexical binding remains in effect until its binding construct exits. See <a href="variable-scoping">Variable Scoping</a>. </p>   <p>When you evaluate a top-level <code>defvar</code> form with <kbd>C-M-x</kbd> (<code>eval-defun</code>) or with <kbd>C-x C-e</kbd> (<code>eval-last-sexp</code>) in Emacs Lisp mode, a special feature of these two commands arranges to set the variable unconditionally, without testing whether its value is void. </p> <p>If the <var>doc-string</var> argument is supplied, it specifies the documentation string for the variable (stored in the symbol’s <code>variable-documentation</code> property). See <a href="documentation">Documentation</a>. </p> <p>Here are some examples. This form defines <code>foo</code> but does not initialize it: </p> <div class="example"> <pre class="example">(defvar foo)
     ⇒ foo
</pre>
</div> <p>This example initializes the value of <code>bar</code> to <code>23</code>, and gives it a documentation string: </p> <div class="example"> <pre class="example">(defvar bar 23
  "The normal weight of a bar.")
     ⇒ bar
</pre>
</div> <p>The <code>defvar</code> form returns <var>symbol</var>, but it is normally used at top level in a file where its value does not matter. </p> <p>For a more elaborate example of using <code>defvar</code> without a value, see <a href="using-lexical-binding#Local-defvar-example">Local defvar example</a>. </p>
</dd>
</dl>  <dl> <dt id="defconst">Special Form: <strong>defconst</strong> <em>symbol value [doc-string]</em>
</dt> <dd>
<p>This special form defines <var>symbol</var> as a value and initializes it. It informs a person reading your code that <var>symbol</var> has a standard global value, established here, that should not be changed by the user or by other programs. Note that <var>symbol</var> is not evaluated; the symbol to be defined must appear explicitly in the <code>defconst</code>. </p> <p>The <code>defconst</code> form, like <code>defvar</code>, marks the variable as <em>special</em>, meaning that it should always be dynamically bound (see <a href="variable-scoping">Variable Scoping</a>). In addition, it marks the variable as risky (see <a href="file-local-variables">File Local Variables</a>). </p> <p><code>defconst</code> always evaluates <var>value</var>, and sets the value of <var>symbol</var> to the result. If <var>symbol</var> does have a buffer-local binding in the current buffer, <code>defconst</code> sets the default value, not the buffer-local value. (But you should not be making buffer-local bindings for a symbol that is defined with <code>defconst</code>.) </p> <p>An example of the use of <code>defconst</code> is Emacs’s definition of <code>float-pi</code>—the mathematical constant <em>pi</em>, which ought not to be changed by anyone (attempts by the Indiana State Legislature notwithstanding). As the second form illustrates, however, <code>defconst</code> is only advisory. </p> <div class="example"> <pre class="example">(defconst float-pi 3.141592653589793 "The value of Pi.")
     ⇒ float-pi
</pre>
<pre class="example">(setq float-pi 3)
     ⇒ float-pi
</pre>
<pre class="example">float-pi
     ⇒ 3
</pre>
</div> </dd>
</dl> <p><strong>Warning:</strong> If you use a <code>defconst</code> or <code>defvar</code> special form while the variable has a local binding (made with <code>let</code>, or a function argument), it sets the local binding rather than the global binding. This is not what you usually want. To prevent this, use these special forms at top level in a file, where normally no local binding is in effect, and make sure to load the file before making a local binding for the variable. </p><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Defining-Variables.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Defining-Variables.html</a>
  </p>
</div>