elisp: Variable Definitions
14.3 Defining Customization Variables
=====================================
“Customizable variables”, also called “user options”, are global Lisp
variables whose values can be set through the Customize interface.
Unlike other global variables, which are defined with ‘defvar’ (
Defining Variables), customizable variables are defined using the
‘defcustom’ macro. In addition to calling ‘defvar’ as a subroutine,
‘defcustom’ states how the variable should be displayed in the Customize
interface, the values it is allowed to take, etc.
-- Macro: defcustom option standard doc [keyword value]...
This macro declares OPTION as a user option (i.e., a customizable
variable). You should not quote OPTION.
The argument STANDARD is an expression that specifies the standard
value for OPTION. Evaluating the ‘defcustom’ form evaluates
STANDARD, but does not necessarily bind the option to that value.
If OPTION already has a default value, it is left unchanged. If
the user has already saved a customization for OPTION, the user’s
customized value is installed as the default value. Otherwise, the
result of evaluating STANDARD is installed as the default value.
Like ‘defvar’, this macro marks ‘option’ as a special variable,
meaning that it should always be dynamically bound. If OPTION is
already lexically bound, that lexical binding remains in effect
until the binding construct exits. Variable Scoping.
The expression STANDARD can be evaluated at various other times,
too—whenever the customization facility needs to know OPTION’s
standard value. So be sure to use an expression which is harmless
to evaluate at any time.
The argument DOC specifies the documentation string for the
variable.
If a ‘defcustom’ does not specify any ‘:group’, the last group
defined with ‘defgroup’ in the same file will be used. This way,
most ‘defcustom’ do not need an explicit ‘:group’.
When you evaluate a ‘defcustom’ form with ‘C-M-x’ in Emacs Lisp
mode (‘eval-defun’), a special feature of ‘eval-defun’ arranges to
set the variable unconditionally, without testing whether its value
is void. (The same feature applies to ‘defvar’, Defining
Variables.) Using ‘eval-defun’ on a defcustom that is already
defined calls the ‘:set’ function (see below), if there is one.
If you put a ‘defcustom’ in a pre-loaded Emacs Lisp file (
Building Emacs), 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
‘custom-reevaluate-setting’, described below, to re-evaluate the
standard value after Emacs starts up.
In addition to the keywords listed in Common Keywords, this
macro accepts the following keywords:
‘:type TYPE’
Use TYPE as the data type for this option. It specifies which
values are legitimate, and how to display the value (
Customization Types). Every ‘defcustom’ should specify a value
for this keyword.
‘:options VALUE-LIST’
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.
This is meaningful only for certain types, currently including
‘hook’, ‘plist’ and ‘alist’. See the definition of the individual
types for a description of how to use ‘:options’.
‘:set SETFUNCTION’
Specify SETFUNCTION as the way to change the value of this option
when using the Customize interface. The function SETFUNCTION
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
SETFUNCTION is ‘set-default’.
If you specify this keyword, the variable’s documentation string
should describe how to do the same job in hand-written Lisp code.
‘:get GETFUNCTION’
Specify GETFUNCTION as the way to extract the value of this option.
The function GETFUNCTION 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 ‘default-value’.
You have to really understand the workings of Custom to use ‘:get’
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 GETFUNCTION for a value that
really is stored in a Lisp variable.
‘:initialize FUNCTION’
FUNCTION should be a function used to initialize the variable when
the ‘defcustom’ 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:
‘custom-initialize-set’
Use the variable’s ‘:set’ function to initialize the variable,
but do not reinitialize it if it is already non-void.
‘custom-initialize-default’
Like ‘custom-initialize-set’, but use the function
‘set-default’ to set the variable, instead of the variable’s
‘:set’ function. This is the usual choice for a variable
whose ‘:set’ 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.
‘custom-initialize-reset’
Always use the ‘:set’ function to initialize the variable. If
the variable is already non-void, reset it by calling the
‘:set’ function using the current value (returned by the
‘:get’ method). This is the default ‘:initialize’ function.
‘custom-initialize-changed’
Use the ‘:set’ function to initialize the variable, if it is
already set or has been customized; otherwise, just use
‘set-default’.
‘custom-initialize-safe-set’
‘custom-initialize-safe-default’
These functions behave like ‘custom-initialize-set’
(‘custom-initialize-default’, respectively), but catch errors.
If an error occurs during initialization, they set the
variable to ‘nil’ using ‘set-default’, and signal no error.
These functions are meant for options defined in pre-loaded
files, where the STANDARD expression may signal an error
because some required variable or function is not yet defined.
The value normally gets updated in ‘startup.el’, ignoring the
value computed by ‘defcustom’. After startup, if one unsets
the value and reevaluates the ‘defcustom’, the STANDARD
expression can be evaluated without error.
‘:risky VALUE’
Set the variable’s ‘risky-local-variable’ property to VALUE (
File Local Variables).
‘:safe FUNCTION’
Set the variable’s ‘safe-local-variable’ property to FUNCTION
(File Local Variables).
‘:set-after VARIABLES’
When setting variables according to saved customizations, make sure
to set the variables VARIABLES before this one; i.e., delay setting
this variable until after those others have been handled. Use
‘:set-after’ if setting this variable won’t work properly unless
those other variables already have their intended values.
It is useful to specify the ‘:require’ 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. Common
Keywords. Here is an example, from the library ‘saveplace.el’:
(defcustom save-place nil
"Non-nil means automatically save place in each file..."
:type 'boolean
:require 'saveplace
:group 'save-place)
If a customization item has a type such as ‘hook’ or ‘alist’, which
supports ‘:options’, you can add additional values to the list from
outside the ‘defcustom’ declaration by calling
‘custom-add-frequent-value’. For example, if you define a function
‘my-lisp-mode-initialization’ intended to be called from
‘emacs-lisp-mode-hook’, you might want to add that to the list of
reasonable values for ‘emacs-lisp-mode-hook’, but not by editing its
definition. You can do it thus:
(custom-add-frequent-value 'emacs-lisp-mode-hook
'my-lisp-mode-initialization)
-- Function: custom-add-frequent-value symbol value
For the customization option SYMBOL, add VALUE to the list of
reasonable values.
The precise effect of adding a value depends on the customization
type of SYMBOL.
Internally, ‘defcustom’ uses the symbol property ‘standard-value’ to
record the expression for the standard value, ‘saved-value’ to record
the value saved by the user with the customization buffer, and
‘customized-value’ to record the value set by the user with the
customization buffer, but not saved. Symbol Properties. These
properties are lists, the car of which is an expression that evaluates
to the value.
-- Function: custom-reevaluate-setting symbol
This function re-evaluates the standard value of SYMBOL, which
should be a user option declared via ‘defcustom’. 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
‘:set’ property if that is defined).
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.
-- Function: custom-variable-p arg
This function returns non-‘nil’ if ARG is a customizable variable.
A customizable variable is either a variable that has a
‘standard-value’ or ‘custom-autoload’ property (usually meaning it
was declared with ‘defcustom’), or an alias for another
customizable variable.
Info Catalog
elisp: Group Definitions
elisp: Customization
elisp: Customization Types