16.2 Specifying Variables using defcustom

You can specify variables using defcustom so that you and others can then use Emacs’s customize feature to set their values. (You cannot use customize to write function definitions; but you can write defuns in your .emacs file. Indeed, you can write any Lisp expression in your .emacs file.)

The customize feature depends on the defcustom macro. Although you can use defvar or setq for variables that users set, the defcustom macro is designed for the job.

You can use your knowledge of defvar for writing the first three arguments for defcustom. The first argument to defcustom is the name of the variable. The second argument is the variable’s initial value, if any; and this value is set only if the value has not already been set. The third argument is the documentation.

The fourth and subsequent arguments to defcustom specify types and options; these are not featured in defvar. (These arguments are optional.)

Each of these arguments consists of a keyword followed by a value. Each keyword starts with the colon character ‘:’.

For example, the customizable user option variable text-mode-hook looks like this:

(defcustom text-mode-hook nil
  "Normal hook run when entering Text mode and many related modes."
  :type 'hook
  :options '(turn-on-auto-fill flyspell-mode)
  :group 'wp)

The name of the variable is text-mode-hook; it has no default value; and its documentation string tells you what it does.

The :type keyword tells Emacs the kind of data to which text-mode-hook should be set and how to display the value in a Customization buffer.

The :options keyword specifies a suggested list of values for the variable. Usually, :options applies to a hook. The list is only a suggestion; it is not exclusive; a person who sets the variable may set it to other values; the list shown following the :options keyword is intended to offer convenient choices to a user.

Finally, the :group keyword tells the Emacs Customization command in which group the variable is located. This tells where to find it.

The defcustom macro recognizes more than a dozen keywords. For more information, see Writing Customization Definitions in The GNU Emacs Lisp Reference Manual.

Consider text-mode-hook as an example.

There are two ways to customize this variable. You can use the customization command or write the appropriate expressions yourself.

Using the customization command, you can type:

M-x customize

and find that the group for editing files of text is called “Text”. Enter that group. Text Mode Hook is the first member. You can click on its various options, such as turn-on-auto-fill, to set the values. After you click on the button to

Save for Future Sessions

Emacs will write an expression into your .emacs file. It will look like this:

(custom-set-variables
  ;; custom-set-variables was added by Custom.
  ;; If you edit it by hand, you could mess it up, so be careful.
  ;; Your init file should contain only one such instance.
  ;; If there is more than one, they won't work right.
 '(text-mode-hook '(turn-on-auto-fill text-mode-hook-identify)))

(The text-mode-hook-identify function tells toggle-text-mode-auto-fill which buffers are in Text mode. It comes on automatically.)

The custom-set-variables function works somewhat differently than a setq. While I have never learned the differences, I modify the custom-set-variables expressions in my .emacs file by hand: I make the changes in what appears to me to be a reasonable manner and have not had any problems. Others prefer to use the Customization command and let Emacs do the work for them.

Another custom-set-… function is custom-set-faces. This function sets the various font faces. Over time, I have set a considerable number of faces. Some of the time, I re-set them using customize; other times, I simply edit the custom-set-faces expression in my .emacs file itself.

The second way to customize your text-mode-hook is to set it yourself in your .emacs file using code that has nothing to do with the custom-set-… functions.

When you do this, and later use customize, you will see a message that says

CHANGED outside Customize; operating on it here may be unreliable.

This message is only a warning. If you click on the button to

Save for Future Sessions

Emacs will write a custom-set-… expression near the end of your .emacs file that will be evaluated after your hand-written expression. It will, therefore, overrule your hand-written expression. No harm will be done. When you do this, however, be careful to remember which expression is active; if you forget, you may confuse yourself.

So long as you remember where the values are set, you will have no trouble. In any event, the values are always set in your initialization file, which is usually called .emacs.

I myself use customize for hardly anything. Mostly, I write expressions myself.

Incidentally, to be more complete concerning defines: defsubst defines an inline function. The syntax is just like that of defun. defconst defines a symbol as a constant. The intent is that neither programs nor users should ever change a value set by defconst. (You can change it; the value set is a variable; but please do not.)