57.2.3 Changing a Variable

Here is an example of what a variable (a user option) looks like in the customization buffer:

     Kill Ring Max: [Hide Value] 60
        [State]: STANDARD.
     Maximum length of kill ring before oldest elements are thrown away.

The text following ‘[Hide Value]’, ‘60’ in this case, indicates the current value of the variable. If you see ‘[Show Value]’ instead of ‘[Hide Value]’, it means that the value is hidden; the customization buffer initially hides values that take up several lines. Invoke ‘[Show Value]’ to show the value.

The line after the variable name indicates the customization state of the variable: in the example above, it says you have not changed the option yet. The ‘[State]’ button at the beginning of this line gives you a menu of various operations for customizing the variable.

The line after the ‘[State]’ line displays the beginning of the variable's documentation string. If there are more lines of documentation, this line ends with a ‘[More]’ button; invoke that to show the full documentation string.

To enter a new value for ‘Kill Ring Max’, move point to the value and edit it textually. For example, you can type M-d, then insert another number. As you begin to alter the text, you will see the ‘[State]’ line change to say that you have edited the value:

     [State]: EDITED, shown value does not take effect until you set or ...
                                                                save it.

Editing the value does not actually set the variable. To do that, you must set the variable. To do this, invoke the ‘[State]’ button and choose ‘Set for Current Session’.

The state of the variable changes visibly when you set it:

     [State]: SET for current session only.

You don't have to worry about specifying a value that is not valid; the ‘Set for Current Session’ operation checks for validity and will not install an unacceptable value.

While editing a field that is a file name, directory name, command name, or anything else for which completion is defined, you can type M-<TAB> (widget-complete) to do completion. (<ESC> <TAB> and C-M-i do the same thing.)

Some variables have a small fixed set of possible legitimate values. These variables don't let you edit the value textually. Instead, a ‘[Value Menu]’ button appears before the value; invoke this button to change the value. For a boolean “on or off” value, the button says ‘[Toggle]’, and it changes to the other value. ‘[Value Menu]’ and ‘[Toggle]’ simply edit the buffer; the changes take real effect when you use the ‘Set for Current Session’ operation.

Some variables have values with complex structure. For example, the value of file-coding-system-alist is an association list. Here is how it appears in the customization buffer:

     File Coding System Alist: [Hide Value]
     [INS] [DEL] File regexp: \.elc\'
                 Choice: [Value Menu] Encoding/decoding pair:
                 Decoding: emacs-mule
                 Encoding: emacs-mule
     [INS] [DEL] File regexp: \(\`\|/\)loaddefs.el\'
                 Choice: [Value Menu] Encoding/decoding pair:
                 Decoding: raw-text
                 Encoding: raw-text-unix
     [INS] [DEL] File regexp: \.tar\'
                 Choice: [Value Menu] Encoding/decoding pair:
                 Decoding: no-conversion
                 Encoding: no-conversion
     [INS] [DEL] File regexp:
                 Choice: [Value Menu] Encoding/decoding pair:
                 Decoding: undecided
                 Encoding: nil
     [INS]
        [State]: STANDARD.
     Alist to decide a coding system to use for a file I/O ...
                                     operation. [Hide Rest]
     The format is ((PATTERN . VAL) ...),
     where PATTERN is a regular expression matching a file name,
     [...more lines of documentation...]

Each association in the list appears on four lines, with several editable fields and/or buttons. You can edit the regexps and coding systems using ordinary editing commands. You can also invoke ‘[Value Menu]’ to switch to a different kind of value—for instance, to specify a function instead of a pair of coding systems.

To delete an association from the list, invoke the ‘[DEL]’ button for that item. To add an association, invoke ‘[INS]’ at the position where you want to add it. There is an ‘[INS]’ button between each pair of association, another at the beginning and another at the end, so you can add the new association at any position in the list.

Two special commands, <TAB> and S-<TAB>, are useful for moving through the customization buffer. <TAB> (widget-forward) moves forward to the next button or editable field; S-<TAB> (widget-backward) moves backward to the previous button or editable field.

Typing <RET> on an editable field also moves forward, just like <TAB>. We set it up this way because people often type <RET> when they are finished editing a field. To insert a newline within an editable field, use C-o or C-q C-j.

Setting the variable changes its value in the current Emacs session; saving the value changes it for future sessions as well. To save the variable, invoke ‘[State]’ and select the ‘Save for Future Sessions’ operation. This works by writing code so as to set the variable again, each time you start Emacs (see Saving Customizations).

You can also restore the variable to its standard value by invoking ‘[State]’ and selecting the ‘Erase Customization’ operation. There are actually four reset operations:

‘Reset to Current’

If you have made some modifications and not yet set the variable, this restores the text in the customization buffer to match the actual value.

‘Reset to Saved’

This restores the value of the variable to the last saved value, and updates the text accordingly.

‘Erase Customization’

This sets the variable to its standard value, and updates the text accordingly. This also eliminates any saved value for the variable, so that you will get the standard value in future Emacs sessions.

‘Use Backup Value’

This sets the variable to a previous value that was set in the customization buffer in this session. If you customize a variable and then reset it, which discards the customized value, you can get the customized value back again with this operation.

Sometimes it is useful to record a comment about a specific customization. Use the ‘Add Comment’ item from the ‘[State]’ menu to create a field for entering the comment. The comment you enter will be saved, and displayed again if you again view the same variable in a customization buffer, even in another session.

The state of a group indicates whether anything in that group has been edited, set or saved.

Near the top of the customization buffer there are two lines of buttons:

      [Set for Current Session] [Save for Future Sessions]
      [Reset to Current] [Reset to Saved] [Erase Customization]   [Finish]

Invoking ‘[Finish]’ either buries or kills this customization buffer according to the setting of the option custom-buffer-done-kill; the default is to bury the buffer. Each of the other buttons performs an operation—set, save or reset—on each of the settings in the buffer that could meaningfully be set, saved or reset. They do not operate on settings whose values are hidden, nor on subgroups not visible in the buffer.