Function: defcustom
defcustom is a macro defined in custom.el.gz.
Signature
(defcustom SYMBOL STANDARD DOC &rest ARGS)
Documentation
Declare SYMBOL as a customizable variable.
SYMBOL is the variable name; it should not be quoted.
STANDARD is an expression specifying the variable's standard
value. It should not be quoted. It is evaluated once by
defcustom, and the value is assigned to SYMBOL if the variable
is unbound. The expression itself is also stored, so that
Customize can re-evaluate it later to get the standard value.
DOC is the variable documentation.
This macro uses defvar as a subroutine, which also marks the
variable as "special", so that it is always dynamically bound
even when lexical-binding is t.
The remaining arguments to defcustom should have the form
[KEYWORD VALUE]...
The following keywords are meaningful:
:type VALUE should be a widget type for editing the symbol's value.
Every defcustom should specify a value for this keyword.
See Info node (elisp) Customization Types for a list of
base types and useful composite types.
:options VALUE should be a list of valid members of the widget type.
:initialize
VALUE should be a function used to initialize the
variable. It takes two arguments, the symbol and value
given in the defcustom call. The default is
custom-initialize-reset.
:set VALUE should be a function to set the value of the symbol
when using the Customize user interface. It takes two arguments,
the symbol to set and the value to give it. The function should
not modify its value argument destructively. The default choice
of function is set-default-toplevel-value. If this keyword is
defined, modifying the value of SYMBOL via setopt will call the
function specified by VALUE to install the new value.
:get VALUE should be a function to extract the value of symbol.
The function takes one argument, a symbol, and should return
the current value for that symbol. The default choice of function
is default-toplevel-value.
:require
VALUE should be a feature symbol. If you save a value
for this option, then when your init file loads the value,
it does (require VALUE) first.
:set-after VARIABLES
Specifies that SYMBOL should be set after the list of variables
VARIABLES when both have been customized.
:risky Set SYMBOL's risky-local-variable property to VALUE.
:safe Set SYMBOL's safe-local-variable property to VALUE.
See Info node (elisp) File Local Variables.
:local If VALUE is t, mark SYMBOL as automatically buffer-local.
If VALUE is permanent, also set SYMBOL's permanent-local
property to t.
The following common keywords are also meaningful.
:group VALUE should be a customization group.
Add SYMBOL (or FACE with defface) to that group.
:link LINK-DATA
Include an external link after the documentation string for this
item. This is a sentence containing an active field which
references some other documentation.
There are several alternatives you can use for LINK-DATA:
(custom-manual INFO-NODE)
Link to an Info node; INFO-NODE is a string which specifies
the node name, as in "(emacs)Top".
(info-link INFO-NODE)
Like custom-manual except that the link appears in the
customization buffer with the Info node name.
(url-link URL)
Link to a web page; URL is a string which specifies the URL.
(emacs-commentary-link LIBRARY)
Link to the commentary section of LIBRARY.
(emacs-library-link LIBRARY)
Link to an Emacs Lisp LIBRARY file.
(file-link FILE)
Link to FILE.
(function-link FUNCTION)
Link to the documentation of FUNCTION.
(variable-link VARIABLE)
Link to the documentation of VARIABLE.
(custom-group-link GROUP)
Link to another customization GROUP.
You can specify the text to use in the customization buffer by
adding :tag NAME after the first element of the LINK-DATA; for
example, (info-link :tag "foo" "(emacs)Top") makes a link to the
Emacs manual which appears in the buffer as foo.
An item can have more than one external link; however, most items
have none at all.
:version
VALUE should be a string specifying that the variable was
first introduced, or its default value was changed, in Emacs
version VERSION.
:package-version
VALUE should be a list with the form (PACKAGE . VERSION)
specifying that the variable was first introduced, or its
default value was changed, in PACKAGE version VERSION. This
keyword takes priority over :version. For packages which
are bundled with Emacs releases, the PACKAGE and VERSION
must appear in the alist customize-package-emacs-version-alist.
Since PACKAGE must be unique and the user might see it in an
error message, a good choice is the official name of the
package, such as MH-E or Gnus.
:tag LABEL
Use LABEL, a string, instead of the item's name, to label the item
in customization menus and buffers.
:load FILE
Load file FILE (a string) before displaying this customization
item. Loading is done with load, and only if the file is
not already loaded.
If SYMBOL has a local binding, then this form affects the local
binding. This is normally not what you want. Thus, if you need
to load a file defining variables with this form, or with
defvar or defconst, you should always load that file
_outside_ any bindings for these variables. (defvar and
defconst behave similarly in this respect.)
This macro calls custom-declare-variable. If you want to
programmatically alter a customizable variable (for instance, to
write a package that extends the syntax of a variable), you can
call that function directly.
See Info node (elisp) Customization in the Emacs Lisp manual for more information.
Probably introduced at or before Emacs version 20.1.
Source Code
;; Defined in /usr/src/emacs/lisp/custom.el.gz
(defmacro defcustom (symbol standard doc &rest args)
"Declare SYMBOL as a customizable variable.
SYMBOL is the variable name; it should not be quoted.
STANDARD is an expression specifying the variable's standard
value. It should not be quoted. It is evaluated once by
`defcustom', and the value is assigned to SYMBOL if the variable
is unbound. The expression itself is also stored, so that
Customize can re-evaluate it later to get the standard value.
DOC is the variable documentation.
This macro uses `defvar' as a subroutine, which also marks the
variable as \"special\", so that it is always dynamically bound
even when `lexical-binding' is t.
The remaining arguments to `defcustom' should have the form
[KEYWORD VALUE]...
The following keywords are meaningful:
:type VALUE should be a widget type for editing the symbol's value.
Every `defcustom' should specify a value for this keyword.
See Info node `(elisp) Customization Types' for a list of
base types and useful composite types.
:options VALUE should be a list of valid members of the widget type.
:initialize
VALUE should be a function used to initialize the
variable. It takes two arguments, the symbol and value
given in the `defcustom' call. The default is
`custom-initialize-reset'.
:set VALUE should be a function to set the value of the symbol
when using the Customize user interface. It takes two arguments,
the symbol to set and the value to give it. The function should
not modify its value argument destructively. The default choice
of function is `set-default-toplevel-value'. If this keyword is
defined, modifying the value of SYMBOL via `setopt' will call the
function specified by VALUE to install the new value.
:get VALUE should be a function to extract the value of symbol.
The function takes one argument, a symbol, and should return
the current value for that symbol. The default choice of function
is `default-toplevel-value'.
:require
VALUE should be a feature symbol. If you save a value
for this option, then when your init file loads the value,
it does (require VALUE) first.
:set-after VARIABLES
Specifies that SYMBOL should be set after the list of variables
VARIABLES when both have been customized.
:risky Set SYMBOL's `risky-local-variable' property to VALUE.
:safe Set SYMBOL's `safe-local-variable' property to VALUE.
See Info node `(elisp) File Local Variables'.
:local If VALUE is t, mark SYMBOL as automatically buffer-local.
If VALUE is `permanent', also set SYMBOL's `permanent-local'
property to t.
The following common keywords are also meaningful.
:group VALUE should be a customization group.
Add SYMBOL (or FACE with `defface') to that group.
:link LINK-DATA
Include an external link after the documentation string for this
item. This is a sentence containing an active field which
references some other documentation.
There are several alternatives you can use for LINK-DATA:
(custom-manual INFO-NODE)
Link to an Info node; INFO-NODE is a string which specifies
the node name, as in \"(emacs)Top\".
(info-link INFO-NODE)
Like `custom-manual' except that the link appears in the
customization buffer with the Info node name.
(url-link URL)
Link to a web page; URL is a string which specifies the URL.
(emacs-commentary-link LIBRARY)
Link to the commentary section of LIBRARY.
(emacs-library-link LIBRARY)
Link to an Emacs Lisp LIBRARY file.
(file-link FILE)
Link to FILE.
(function-link FUNCTION)
Link to the documentation of FUNCTION.
(variable-link VARIABLE)
Link to the documentation of VARIABLE.
(custom-group-link GROUP)
Link to another customization GROUP.
You can specify the text to use in the customization buffer by
adding `:tag NAME' after the first element of the LINK-DATA; for
example, (info-link :tag \"foo\" \"(emacs)Top\") makes a link to the
Emacs manual which appears in the buffer as `foo'.
An item can have more than one external link; however, most items
have none at all.
:version
VALUE should be a string specifying that the variable was
first introduced, or its default value was changed, in Emacs
version VERSION.
:package-version
VALUE should be a list with the form (PACKAGE . VERSION)
specifying that the variable was first introduced, or its
default value was changed, in PACKAGE version VERSION. This
keyword takes priority over :version. For packages which
are bundled with Emacs releases, the PACKAGE and VERSION
must appear in the alist `customize-package-emacs-version-alist'.
Since PACKAGE must be unique and the user might see it in an
error message, a good choice is the official name of the
package, such as MH-E or Gnus.
:tag LABEL
Use LABEL, a string, instead of the item's name, to label the item
in customization menus and buffers.
:load FILE
Load file FILE (a string) before displaying this customization
item. Loading is done with `load', and only if the file is
not already loaded.
If SYMBOL has a local binding, then this form affects the local
binding. This is normally not what you want. Thus, if you need
to load a file defining variables with this form, or with
`defvar' or `defconst', you should always load that file
_outside_ any bindings for these variables. (`defvar' and
`defconst' behave similarly in this respect.)
This macro calls `custom-declare-variable'. If you want to
programmatically alter a customizable variable (for instance, to
write a package that extends the syntax of a variable), you can
call that function directly.
See Info node `(elisp) Customization' in the Emacs Lisp manual
for more information."
(declare (doc-string 3) (debug (name body))
(indent defun))
;; It is better not to use backquote in this file,
;; because that makes a bootstrapping problem
;; if you need to recompile all the Lisp files using interpreted code.
`(custom-declare-variable
',symbol
,(if lexical-binding
;; The STANDARD arg should be an expression that evaluates to
;; the standard value. The use of `eval' for it is spread
;; over many different places and hence difficult to
;; eliminate, yet we want to make sure that the `standard'
;; expression is checked by the byte-compiler, and that
;; lexical-binding is obeyed, so quote the expression with
;; `lambda' rather than with `quote'.
``(funcall #',(lambda () "" ,standard))
`',standard)
,doc
,@args))