path: root/devdocs/elisp/variable-definitions.html

 <h3 class="section">Defining Customization Variables</h3>    <p><em>Customizable variables</em>, also called <em>user options</em>, are global Lisp variables whose values can be set through the Customize interface. Unlike other global variables, which are defined with <code>defvar</code> (see <a href="defining-variables">Defining Variables</a>), customizable variables are defined using the <code>defcustom</code> macro. In addition to calling <code>defvar</code> as a subroutine, <code>defcustom</code> states how the variable should be displayed in the Customize interface, the values it is allowed to take, etc. </p> <dl> <dt id="defcustom">Macro: <strong>defcustom</strong> <em>option standard doc [keyword value]…</em>
</dt> <dd>
<p>This macro declares <var>option</var> as a user option (i.e., a customizable variable). You should not quote <var>option</var>. </p> <p>The argument <var>standard</var> is an expression that specifies the standard value for <var>option</var>. Evaluating the <code>defcustom</code> form evaluates <var>standard</var>, but does not necessarily bind the option to that value. If <var>option</var> already has a default value, it is left unchanged. If the user has already saved a customization for <var>option</var>, the user’s customized value is installed as the default value. Otherwise, the result of evaluating <var>standard</var> is installed as the default value. </p> <p>Like <code>defvar</code>, this macro marks <code>option</code> as a special variable, meaning that it should always be dynamically bound. If <var>option</var> is already lexically bound, that lexical binding remains in effect until the binding construct exits. See <a href="variable-scoping">Variable Scoping</a>. </p> <p>The expression <var>standard</var> can be evaluated at various other times, too—whenever the customization facility needs to know <var>option</var>’s standard value. So be sure to use an expression which is harmless to evaluate at any time. </p> <p>The argument <var>doc</var> specifies the documentation string for the variable. </p> <p>If a <code>defcustom</code> does not specify any <code>:group</code>, the last group defined with <code>defgroup</code> in the same file will be used. This way, most <code>defcustom</code> do not need an explicit <code>:group</code>. </p>  <p>When you evaluate a <code>defcustom</code> form with <kbd>C-M-x</kbd> in Emacs Lisp mode (<code>eval-defun</code>), a special feature of <code>eval-defun</code> arranges to set the variable unconditionally, without testing whether its value is void. (The same feature applies to <code>defvar</code>, see <a href="defining-variables">Defining Variables</a>.) Using <code>eval-defun</code> on a defcustom that is already defined calls the <code>:set</code> function (see below), if there is one. </p> <p>If you put a <code>defcustom</code> in a pre-loaded Emacs Lisp file (see <a href="building-emacs">Building Emacs</a>), the standard value installed at dump time might be incorrect, e.g., because another variable that it depends on has not been assigned the right value yet. In that case, use <code>custom-reevaluate-setting</code>, described below, to re-evaluate the standard value after Emacs starts up. </p>
</dd>
</dl> <p>In addition to the keywords listed in <a href="common-keywords">Common Keywords</a>, this macro accepts the following keywords: </p> <dl compact> <dt><code>:type <var>type</var></code></dt> <dd>
<p>Use <var>type</var> as the data type for this option. It specifies which values are legitimate, and how to display the value (see <a href="customization-types">Customization Types</a>). Every <code>defcustom</code> should specify a value for this keyword. </p> </dd> <dt><code>:options <var>value-list</var></code></dt> <dd>
 <p>Specify the list of reasonable values for use in this option. The user is not restricted to using only these values, but they are offered as convenient alternatives. </p> <p>This is meaningful only for certain types, currently including <code>hook</code>, <code>plist</code> and <code>alist</code>. See the definition of the individual types for a description of how to use <code>:options</code>. </p> <p>Re-evaluating a <code>defcustom</code> form with a different <code>:options</code> value does not clear the values added by previous evaluations, or added by calls to <code>custom-add-frequent-value</code> (see below). </p> </dd> <dt><code>:set <var>setfunction</var></code></dt> <dd>
 <p>Specify <var>setfunction</var> as the way to change the value of this option when using the Customize interface. The function <var>setfunction</var> should take two arguments, a symbol (the option name) and the new value, and should do whatever is necessary to update the value properly for this option (which may not mean simply setting the option as a Lisp variable); preferably, though, it should not modify its value argument destructively. The default for <var>setfunction</var> is <code>set-default</code>. </p> <p>If you specify this keyword, the variable’s documentation string should describe how to do the same job in hand-written Lisp code. </p> </dd> <dt><code>:get <var>getfunction</var></code></dt> <dd>
 <p>Specify <var>getfunction</var> as the way to extract the value of this option. The function <var>getfunction</var> should take one argument, a symbol, and should return whatever customize should use as the current value for that symbol (which need not be the symbol’s Lisp value). The default is <code>default-value</code>. </p> <p>You have to really understand the workings of Custom to use <code>:get</code> correctly. It is meant for values that are treated in Custom as variables but are not actually stored in Lisp variables. It is almost surely a mistake to specify <var>getfunction</var> for a value that really is stored in a Lisp variable. </p> </dd> <dt><code>:initialize <var>function</var></code></dt> <dd>
 <p><var>function</var> should be a function used to initialize the variable when the <code>defcustom</code> is evaluated. It should take two arguments, the option name (a symbol) and the value. Here are some predefined functions meant for use in this way: </p> <dl compact> <dt><code>custom-initialize-set</code></dt> <dd>
<p>Use the variable’s <code>:set</code> function to initialize the variable, but do not reinitialize it if it is already non-void. </p> </dd> <dt><code>custom-initialize-default</code></dt> <dd>
<p>Like <code>custom-initialize-set</code>, but use the function <code>set-default</code> to set the variable, instead of the variable’s <code>:set</code> function. This is the usual choice for a variable whose <code>:set</code> function enables or disables a minor mode; with this choice, defining the variable will not call the minor mode function, but customizing the variable will do so. </p> </dd> <dt><code>custom-initialize-reset</code></dt> <dd>
<p>Always use the <code>:set</code> function to initialize the variable. If the variable is already non-void, reset it by calling the <code>:set</code> function using the current value (returned by the <code>:get</code> method). This is the default <code>:initialize</code> function. </p> </dd> <dt><code>custom-initialize-changed</code></dt> <dd>
<p>Use the <code>:set</code> function to initialize the variable, if it is already set or has been customized; otherwise, just use <code>set-default</code>. </p> </dd> <dt><code>custom-initialize-delay</code></dt> <dd><p>This function behaves like <code>custom-initialize-set</code>, but it delays the actual initialization to the next Emacs start. This should be used in files that are preloaded (or for autoloaded variables), so that the initialization is done in the run-time context rather than the build-time context. This also has the side-effect that the (delayed) initialization is performed with the <code>:set</code> function. See <a href="building-emacs">Building Emacs</a>. </p></dd> </dl> </dd> <dt><code>:local <var>value</var></code></dt> <dd>
 <p>If the <var>value</var> is <code>t</code>, mark <var>option</var> as automatically buffer-local; if the value is <code>permanent</code>, also set <var>option</var>s <code>permanent-local</code> property to <code>t</code>. See <a href="creating-buffer_002dlocal">Creating Buffer-Local</a>. </p> </dd> <dt><code>:risky <var>value</var></code></dt> <dd>
 <p>Set the variable’s <code>risky-local-variable</code> property to <var>value</var> (see <a href="file-local-variables">File Local Variables</a>). </p> </dd> <dt><code>:safe <var>function</var></code></dt> <dd>
 <p>Set the variable’s <code>safe-local-variable</code> property to <var>function</var> (see <a href="file-local-variables">File Local Variables</a>). </p> </dd> <dt><code>:set-after <var>variables</var></code></dt> <dd>
 <p>When setting variables according to saved customizations, make sure to set the variables <var>variables</var> before this one; i.e., delay setting this variable until after those others have been handled. Use <code>:set-after</code> if setting this variable won’t work properly unless those other variables already have their intended values. </p>
</dd> </dl> <p>It is useful to specify the <code>:require</code> keyword for an option that turns on a certain feature. This causes Emacs to load the feature, if it is not already loaded, whenever the option is set. See <a href="common-keywords">Common Keywords</a>. Here is an example: </p> <div class="example"> <pre class="example">(defcustom frobnicate-automatically nil
  "Non-nil means automatically frobnicate all buffers."
  :type 'boolean
  :require 'frobnicate-mode
  :group 'frobnicate)
</pre>
</div> <p>If a customization item has a type such as <code>hook</code> or <code>alist</code>, which supports <code>:options</code>, you can add additional values to the list from outside the <code>defcustom</code> declaration by calling <code>custom-add-frequent-value</code>. For example, if you define a function <code>my-lisp-mode-initialization</code> intended to be called from <code>emacs-lisp-mode-hook</code>, you might want to add that to the list of reasonable values for <code>emacs-lisp-mode-hook</code>, but not by editing its definition. You can do it thus: </p> <div class="example"> <pre class="example">(custom-add-frequent-value 'emacs-lisp-mode-hook
   'my-lisp-mode-initialization)
</pre>
</div> <dl> <dt id="custom-add-frequent-value">Function: <strong>custom-add-frequent-value</strong> <em>symbol value</em>
</dt> <dd>
<p>For the customization option <var>symbol</var>, add <var>value</var> to the list of reasonable values. </p> <p>The precise effect of adding a value depends on the customization type of <var>symbol</var>. </p> <p>Since evaluating a <code>defcustom</code> form does not clear values added previously, Lisp programs can use this function to add values for user options not yet defined. </p>
</dd>
</dl> <p>Internally, <code>defcustom</code> uses the symbol property <code>standard-value</code> to record the expression for the standard value, <code>saved-value</code> to record the value saved by the user with the customization buffer, and <code>customized-value</code> to record the value set by the user with the customization buffer, but not saved. See <a href="symbol-properties">Symbol Properties</a>. In addition, there’s <code>themed-value</code>, which is used to record the value set by a theme (see <a href="custom-themes">Custom Themes</a>). These properties are lists, the car of which is an expression that evaluates to the value. </p> <dl> <dt id="custom-reevaluate-setting">Function: <strong>custom-reevaluate-setting</strong> <em>symbol</em>
</dt> <dd>
<p>This function re-evaluates the standard value of <var>symbol</var>, which should be a user option declared via <code>defcustom</code>. If the variable was customized, this function re-evaluates the saved value instead. Then it sets the user option to that value (using the option’s <code>:set</code> property if that is defined). </p> <p>This is useful for customizable options that are defined before their value could be computed correctly. For example, during startup Emacs calls this function for some user options that were defined in pre-loaded Emacs Lisp files, but whose initial values depend on information available only at run-time. </p>
</dd>
</dl> <dl> <dt id="custom-variable-p">Function: <strong>custom-variable-p</strong> <em>arg</em>
</dt> <dd><p>This function returns non-<code>nil</code> if <var>arg</var> is a customizable variable. A customizable variable is either a variable that has a <code>standard-value</code> or <code>custom-autoload</code> property (usually meaning it was declared with <code>defcustom</code>), or an alias for another customizable variable. </p></dd>
</dl><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/Variable-Definitions.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Variable-Definitions.html</a>
  </p>
</div>