A variable is a Lisp symbol which has a value. The symbol's name is also called the name of the variable. A variable name can contain any characters that can appear in a file, but conventionally variable names consist of words separated by hyphens. A variable can have a documentation string which describes what kind of value it should have and how the value will be used.
Lisp allows any variable to have any kind of value, but most variables that Emacs uses require a value of a certain type. Often the value should always be a string, or should always be a number. Sometimes we say that a certain feature is turned on if a variable is "non-nil," meaning that if the variable's value is nil, the feature is off, but the feature is on for any other value. The conventional value to use to turn on the feature--since you have to pick one particular value when you set the variable--is t.
Emacs uses many Lisp variables for internal record keeping, as any Lisp program must, but the most interesting variables for you are the ones that exist for the sake of customization. Emacs does not (usually) change the values of these variables; instead, you set the values, and thereby alter and control the behavior of certain Emacs commands. These variables are called user options. Most user options are documented in this manual, and appear in the Variable Index (Variable Index).
One example of a variable which is a user option is fill-column, which specifies the position of the right margin (as a number of characters from the left margin) to be used by the fill commands (Section 23.5).
Display the value and documentation of variable var (describe-variable).
Change the value of variable var to value.
To examine the value of a single variable, use C-h v (describe-variable), which reads a variable name using the minibuffer, with completion. It displays both the value and the documentation of the variable. For example,
C-h v fill-column RET |
displays something like this:
fill-column's value is 75 Documentation: *Column beyond which automatic line-wrapping should happen. Automatically becomes buffer-local when set in any fashion. |
The star at the beginning of the documentation indicates that this variable is a user option. C-h v is not restricted to user options; it allows any variable name.
The most convenient way to set a specific user option is with M-x set-variable. This reads the variable name with the minibuffer (with completion), and then reads a Lisp expression for the new value using the minibuffer a second time. For example,
M-x set-variable RET fill-column RET 75 RET |
sets fill-column to 75.
M-x set-variable is limited to user option variables, but you can set any variable with a Lisp expression, using the function setq. Here is a setq expression to set fill-column:
(setq fill-column 75) |
To execute an expression like this one, go to the *scratch* buffer, type in the expression, and then type C-j. Section 25.9.
Setting variables, like all means of customizing Emacs except where otherwise stated, affects only the current Emacs session.
A convenient way to find the user option variables that you want to change, and then change them, is with M-x customize. This command creates a customization buffer with which you can browse through the Emacs user options in a logically organized structure, then edit and set their values. You can also use the customization buffer to save settings permanently. (Not all Emacs user options are included in this structure as of yet, but we are adding the rest.)
The appearance of the example buffers in the following is typically different under a window system where faces can be used to indicate the active fields and other features.
For customization purposes, user options are organized into groups to help you find them. Groups are collected into bigger groups, all the way up to a master group called Emacs.
M-x customize creates a customization buffer that shows the top-level Emacs group and the second-level groups immediately under it. It looks like this, in part:
/- Emacs group: ---------------------------------------------------\
[State]: visible group members are all at standard settings.
Customization of the One True Editor.
See also [Manual].
Editing group: [Go to Group]
Basic text editing facilities.
External group: [Go to Group]
Interfacing to external utilities.
more second-level groups
\- Emacs group end ------------------------------------------------/
|
This says that the buffer displays the contents of the Emacs group. The other groups are listed because they are its contents. But they are listed differently, without indentation and dashes, because their contents are not included. Each group has a single-line documentation string; the Emacs group also has a [State] line.
Most of the text in the customization buffer is read-only, but it typically includes some editable fields that you can edit. There are also active fields; this means a field that does something when you invoke it. To invoke an active field, either click on it with Mouse-1, or move point to it and type RET.
For example, the phrase [Go to Group] that appears in a second-level group is an active field. Invoking the [Go to Group] field for a group creates a new customization buffer, which shows that group and its contents. This field is a kind of hypertext link to another group.
The Emacs group does not include any user options itself, but other groups do. By examining various groups, you will eventually find the options and faces that belong to the feature you are interested in customizing. Then you can use the customization buffer to set them.
You can view the structure of customization groups on a larger scale with M-x customize-browse. This command creates a special kind of customization buffer which shows only the names of the groups (and options and faces), and their structure.
In this buffer, you can show the contents of a group by invoking [+]. When the group contents are visible, this button changes to [-]; invoking that hides the group contents.
Each group, option or face name in this buffer has an active field which says [Group], [Option] or [Face]. Invoking that active field creates an ordinary customization buffer showing just that group and its contents, just that option, or just that face. This is the way to set values in it.
Here is an example of what a user option looks like in the customization buffer:
Kill Ring Max: [Hide] 30 [State]: this option is unchanged from its standard setting. Maximum length of kill ring before oldest elements are thrown away. |
The text following [Hide], 30 in this case, indicates the current value of the option. If you see [Show] instead of [Hide], it means that the value is hidden; the customization buffer initially hides values that take up several lines. Invoke [Show] to show the value.
The line after the option name indicates the customization state of the option: in the example above, it says you have not changed the option yet. The word [State] at the beginning of this line is active; you can get a menu of various operations by invoking it with Mouse-1 or RET. These operations are essential for customizing the variable.
The line after the [State] line displays the beginning of the option's documentation string. If there are more lines of documentation, this line ends with [More]; invoke this 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.
When you begin to alter the text, you will see the [State] line change to say that you have edited the value:
[State]: you have edited the value as text, but not set the option. |
Editing the value does not actually set the option variable. To do that, you must set the option. To do this, invoke the word [State] and choose Set for Current Session.
The state of the option changes visibly when you set it:
[State]: you have set this option, but not saved it for future sessions. |
You don't have to worry about specifying a value that is not valid; setting the option checks for validity and will not really install an unacceptable value.
While editing a value or 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.
Some options have a small fixed set of possible legitimate values. These options don't let you edit the value textually. Instead, an active field [Value Menu] appears before the value; invoke this field to edit the value. For a boolean "on or off" value, the active field says [Toggle], and it changes to the other value. [Value Menu] and [Toggle] edit the buffer; the changes take effect when you use the Set for Current Session operation.
Some options 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]
[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: no-conversion
Encoding: no-conversion
[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]: this option is unchanged from its standard setting.
Alist to decide a coding system to use for a file I/O operation. [Hide]
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 or "active" fields. You can edit the regexps and coding systems using ordinary editing commands. You can also invoke [Value Menu] to switch to a 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 active or editable field; S-TAB (widget-backward) moves backward to the previous active 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 option changes its value in the current Emacs session; saving the value changes it for future sessions as well. This works by writing code into your ~/.emacs file so as to set the option variable again each time you start Emacs. To save the option, invoke [State] and select the Save for Future Sessions operation.
You can also restore the option to its standard value by invoking [State] and selecting the Erase Customization operation. There are actually three reset operations:
If you have made some modifications and not yet set the option, this restores the text in the customization buffer to match the actual value.
This restores the value of the option to the last saved value, and updates the text accordingly.
This sets the option to its standard value, and updates the text accordingly. This also eliminates any saved value for the option, so that you will get the standard value in future Emacs sessions.
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 option 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. You can select Set for Current Session, Save for Future Sessions and the various kinds of Reset operation for the group; these operations on the group apply to all options in the group and its subgroups.
Near the top of the customization buffer there are two lines containing several active fields:
[Set for Current Session] [Save for Future Sessions] [Reset] [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-function; the default is to bury the buffer. Each of the other fields performs an operation--set, save or reset--on each of the items in the buffer that could meaningfully be set, saved or reset.
In addition to user options, some customization groups also include faces. When you show the contents of a group, both the user options and the faces in the group appear in the customization buffer. Here is an example of how a face looks:
Custom Changed Face: (sample) [Hide]
[State]: this face is unchanged from its standard setting.
Parent groups: [Custom Magic Faces]
Attributes: [ ] Font family: [Value Menu] *
[ ] Width: [Value Menu] *
[ ] Height: [Value Menu] *
[ ] Weight: [Value Menu] *
[ ] Slant: [Value Menu] *
[ ] Underline: [Value Menu] *
[ ] Overline: [Value Menu] *
[ ] Strike-through: [Value Menu] *
[ ] Box around text: [Value Menu] Off
[ ] Inverse-video: [Value Menu] *
[X] Foreground: [Value Menu] Color: white (sample)
[X] Background: [Value Menu] Color: blue (sample)
[ ] Stipple: [Value Menu] * |
Each face attribute has its own line. The [x] field before the attribute name indicates whether the attribute is enabled; X means that it is. You can enable or disable the attribute by invoking that field. When the attribute is enabled, you can change the attribute value in the usual ways.
On a black-and-white display, the colors you can use for the background are black, white, gray, gray1, and gray3. Emacs supports these shades of gray by using background stipple patterns instead of a color.
Setting, saving and resetting a face work like the same operations for options (Section 32.2.2.2).
A face can specify different appearances for different types of display. For example, a face can make text red on a color display, but use a bold font on a monochrome display. To specify multiple appearances for a face, select Show Display Types in the menu you get from invoking [State].
Another more basic way to set the attributes of a specific face is with M-x modify-face. This command reads the name of a face, then reads the attributes one by one. For the color and stipple attributes, the attribute's current value is the default--type just RET if you don't want to change that attribute. Type none if you want to clear out the attribute.
Instead of finding the options you want to change by moving down through the structure of groups, you can specify the particular option, face or group that you want to customize.
Set up a customization buffer with just one option, option.
Set up a customization buffer with just one face, face.
Set up a customization buffer with just one group, group.
Set up a customization buffer with all the options, faces and groups that match regexp.
Set up a customization buffer with all the options, faces and groups whose meaning has changed since Emacs version version.
Set up a customization buffer containing all options and faces that you have saved with customization buffers.
Set up a customization buffer containing all options and faces that you have customized but not saved.
If you want to alter a particular user option variable with the customization buffer, and you know its name, you can use the command M-x customize-option and specify the option name. This sets up the customization buffer with just one option--the one that you asked for. Editing, setting and saving the value work as described above, but only for the specified option.
Likewise, you can modify a specific face, chosen by name, using M-x customize-face.
You can also set up the customization buffer with a specific group, using M-x customize-group. The immediate contents of the chosen group, including option variables, faces, and other groups, all appear as well. However, these subgroups' own contents start out hidden. You can show their contents in the usual way, by invoking [Show].
To control more precisely what to customize, you can use M-x customize-apropos. You specify a regular expression as argument; then all options, faces and groups whose names match this regular expression are set up in the customization buffer. If you specify an empty regular expression, this includes all groups, options and faces in the customization buffer (but that takes a long time).
When you upgrade to a new Emacs version, you might want to customize new options and options whose meanings or default values have changed. To do this, use M-x customize-changed-options and specify a previous Emacs version number using the minibuffer. It creates a customization buffer which shows all the options (and groups) whose definitions have been changed since the specified version.
If you change option values and then decide the change was a mistake, you can use two special commands to revisit your previous changes. Use customize-saved to look at the options and faces that you have saved. Use M-x customize-customized to look at the options and faces that you have set but not saved.
Hooks are an important mechanism for customization of Emacs. A hook is a Lisp variable which holds a list of functions, to be called on some well-defined occasion. (This is called running the hook.) The individual functions in the list are called the hook functions of the hook. With rare exceptions, hooks in Emacs are empty when Emacs starts up, so the only hook functions in any given hook are the ones you explicitly put there as customization.
Most major modes run one or more mode hooks as the last step of initialization. This makes it easy for you to customize the behavior of the mode, by setting up a hook function to override the local variable assignments already made by the mode. But hooks are also used in other contexts. For example, the hook suspend-hook runs just before Emacs suspends itself (Section 6.1).
Most Emacs hooks are normal hooks. This means that running the hook operates by calling all the hook functions, unconditionally, with no arguments. We have made an effort to keep most hooks normal so that you can use them in a uniform way. Every variable in Emacs whose name ends in -hook is a normal hook.
There are also a few abnormal hooks. These variables' names end in -hooks or -functions, instead of -hook. What makes these hooks abnormal is that there is something peculiar about the way its functions are called--perhaps they are given arguments, or perhaps the values they return are used in some way. For example, find-file-not-found-hooks (Section 16.2) is abnormal because as soon as one hook function returns a non-nil value, the rest are not called at all. The documentation of each abnormal hook variable explains in detail what is peculiar about it.
The recommended way to add a hook function to a hook (either normal or abnormal) is by calling add-hook. You can use any valid Lisp function as the hook function, provided it can handle the proper number of arguments (zero arguments, in the case of a normal hook). Of course, not every Lisp function is useful in any particular hook.
For example, here's how to set up a hook to turn on Auto Fill mode when entering Text mode and other modes based on Text mode:
(add-hook 'text-mode-hook 'turn-on-auto-fill) |
The next example shows how to use a hook to customize the indentation of C code. (People often have strong personal preferences for one format compared to another.) Here the hook function is an anonymous lambda expression.
(setq my-c-style
'((c-comment-only-line-offset . 4)
(c-cleanup-list . (scope-operator
empty-defun-braces
defun-close-semi))
(c-offsets-alist . ((arglist-close . c-lineup-arglist)
(substatement-open . 0)))))
(add-hook 'c-mode-common-hook
'(lambda ()
(c-add-style "my-style" my-c-style t))) |
It is best to design your hook functions so that the order in which they are executed does not matter. Any dependence on the order is "asking for trouble." However, the order is predictable: the most recently added hook functions are executed first.
Make variable var have a local value in the current buffer.
Make variable var use its global value in the current buffer.
Mark variable var so that setting it will make it local to the buffer that is current at that time.
Almost any variable can be made local to a specific Emacs buffer. This means that its value in that buffer is independent of its value in other buffers. A few variables are always local in every buffer. Every other Emacs variable has a global value which is in effect in all buffers that have not made the variable local.
M-x make-local-variable reads the name of a variable and makes it local to the current buffer. Further changes in this buffer will not affect others, and further changes in the global value will not affect this buffer.
M-x make-variable-buffer-local reads the name of a variable and changes the future behavior of the variable so that it will become local automatically when it is set. More precisely, once a variable has been marked in this way, the usual ways of setting the variable automatically do make-local-variable first. We call such variables per-buffer variables.
Major modes (Chapter 21) always make variables local to the buffer before setting the variables. This is why changing major modes in one buffer has no effect on other buffers. Minor modes also work by setting variables--normally, each minor mode has one controlling variable which is non-nil when the mode is enabled (Section 32.1). For most minor modes, the controlling variable is per buffer.
Emacs contains a number of variables that are always per-buffer. These include abbrev-mode, auto-fill-function, case-fold-search, comment-column, ctl-arrow, fill-column, fill-prefix, indent-tabs-mode, left-margin, mode-line-format, overwrite-mode, selective-display-ellipses, selective-display, tab-width, and truncate-lines. Some other variables are always local in every buffer, but they are used for internal purposes.
A few variables cannot be local to a buffer because they are always local to each display instead (Section 19.10). If you try to make one of these variables buffer-local, you'll get an error message.
M-x kill-local-variable reads the name of a variable and makes it cease to be local to the current buffer. The global value of the variable henceforth is in effect in this buffer. Setting the major mode kills all the local variables of the buffer except for a few variables specially marked as permanent locals.
To set the global value of a variable, regardless of whether the variable has a local value in the current buffer, you can use the Lisp construct setq-default. This construct is used just like setq, but it sets variables' global values instead of their local values (if any). When the current buffer does have a local value, the new global value may not be visible until you switch to another buffer. Here is an example:
(setq-default fill-column 75) |
setq-default is the only way to set the global value of a variable that has been marked with make-variable-buffer-local.
Lisp programs can use default-value to look at a variable's default value. This function takes a symbol as argument and returns its default value. The argument is evaluated; usually you must quote it explicitly. For example, here's how to obtain the default value of fill-column:
(default-value 'fill-column) |
A file can specify local variable values for use when you edit the file with Emacs. Visiting the file checks for local variable specifications; it automatically makes these variables local to the buffer, and sets them to the values specified in the file.
There are two ways to specify local variable values: in the first line, or with a local variables list. Here's how to specify them in the first line:
-*- mode: modename; var: value; … -*- |
You can specify any number of variables/value pairs in this way, each pair with a colon and semicolon as shown above. mode: modename; specifies the major mode; this should come first in the line. The values are not evaluated; they are used literally. Here is an example that specifies Lisp mode and sets two variables with numeric values:
;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*- |
You can also specify the coding system for a file in this way: just specify a value for the "variable" named coding. The "value" must be a coding system name that Emacs recognizes. Section 20.6.
The eval pseudo-variable, described below, can be specified in the first line as well.
In shell scripts, the first line is used to identify the script interpreter, so you cannot put any local variables there. To accomodate for this, when Emacs visits a shell script, it looks for local variable specifications in the second line.
A local variables list goes near the end of the file, in the last page. (It is often best to put it on a page by itself.) The local variables list starts with a line containing the string Local Variables:, and ends with a line containing the string End:. In between come the variable names and values, one set per line, as variable: value. The values are not evaluated; they are used literally. If a file has both a local variables list and a -*- line, Emacs processes everything in the -*- line first, and everything in the local variables list afterward.
Here is an example of a local variables list:
;;; Local Variables: *** ;;; mode:lisp *** ;;; comment-column:0 *** ;;; comment-start: ";;; " *** ;;; comment-end:"***" *** ;;; End: *** |
As you see, each line starts with the prefix ;;; and each line ends with the suffix ***. Emacs recognizes these as the prefix and suffix based on the first line of the list, by finding them surrounding the magic string Local Variables:; then it automatically discards them from the other lines of the list.
The usual reason for using a prefix and/or suffix is to embed the local variables list in a comment, so it won't confuse other programs that the file is intended as input for. The example above is for a language where comment lines start with ;;; and end with ***; the local values for comment-start and comment-end customize the rest of Emacs for this unusual syntax. Don't use a prefix (or a suffix) if you don't need one.
Two "variable names" have special meanings in a local variables list: a value for the variable mode really sets the major mode, and a value for the variable eval is simply evaluated as an expression and the value is ignored. mode and eval are not real variables; setting variables named mode and eval in any other context has no special meaning. If mode is used to set a major mode, it should be the first "variable" in the list.
You can use the mode "variable" to set minor modes as well as major modes; in fact, you can use it more than once, first to set the major mode and then to set minor modes which are specific to particular buffers. But most minor modes should not be specified in the file in any fashion, because they represent user preferences.
For example, you may be tempted to try to turn on Auto Fill mode with a local variable list. That is a mistake. The choice of Auto Fill mode or not is a matter of individual taste, not a matter of the contents of particular files. If you want to use Auto Fill, set up major mode hooks with your .emacs file to turn it on (when appropriate) for you alone (Section 32.7). Don't use a local variable list to impose your taste on everyone.
The start of the local variables list must be no more than 3000 characters from the end of the file, and must be in the last page if the file is divided into pages. Otherwise, Emacs will not notice it is there. The purpose of this rule is so that a stray Local Variables: not in the last page does not confuse Emacs, and so that visiting a long file that is all one page and has no local variables list need not take the time to search the whole file.
Use the command normal-mode to reset the local variables and major mode of a buffer according to the file name and contents, including the local variables list if any. Section 21.1.
The variable enable-local-variables controls whether to process local variables in files, and thus gives you a chance to override them. Its default value is t, which means do process local variables in files. If you set the value to nil, Emacs simply ignores local variables in files. Any other value says to query you about each file that has local variables, showing you the local variable specifications so you can judge.
The eval "variable," and certain actual variables, create a special risk; when you visit someone else's file, local variable specifications for these could affect your Emacs in arbitrary ways. Therefore, the option enable-local-eval controls whether Emacs processes eval variables, as well variables with names that end in -hook, -hooks, -function or -functions, and certain other variables. The three possibilities for the option's value are t, nil, and anything else, just as for enable-local-variables. The default is maybe, which is neither t nor nil, so normally Emacs does ask for confirmation about file settings for these variables.