GNU Emacs Lisp Reference Manual

20.1.3: How Emacs Chooses a Major Mode

Based on information in the file name or in the file itself, Emacs automatically selects a major mode for the new buffer when a file is visited.

Command: fundamental-mode

Fundamental mode is a major mode that is not specialized for anything in particular. Other major modes are defined in effect by comparison with this one---their definitions say what to change, starting from Fundamental mode. The fundamental-mode function does not run any hooks; you're not supposed to customize it. (If you want Emacs to behave differently in Fundamental mode, change the global state of Emacs.)

Command: normal-mode &optional find-file

This function establishes the proper major mode and local variable bindings for the current buffer. First it calls set-auto-mode, then it runs hack-local-variables to parse, and bind or evaluate as appropriate, any local variables.

If the find-file argument to normal-mode is non-nil, normal-mode assumes that the find-file function is calling it. In this case, it may process a local variables list at the end of the file and in the -*- line. The variable enable-local-variables controls whether to do so.

If you run normal-mode interactively, the argument find-file is normally nil. In this case, normal-mode unconditionally processes any local variables list. See File variables, for the syntax of the local variables section of a file.

normal-mode uses condition-case around the call to the major mode function, so errors are caught and reported as a File mode specification error, followed by the original error message.

User Option: enable-local-variables

This variable controls processing of local variables lists in files being visited. A value of t means process the local variables lists unconditionally; nil means ignore them; anything else means ask the user what to do for each file. The default value is t.

Variable: ignored-local-variables

This variable holds a list of variables that should not be set by a local variables list. Any value specified for one of these variables is ignored.

In addition to this list, any variable whose name has a non-nil risky-local-variable property is also ignored.

User Option: enable-local-eval

This variable controls processing of Eval: in local variables lists in files being visited. A value of t means process them unconditionally; nil means ignore them; anything else means ask the user what to do for each file. The default value is maybe.

Function: set-auto-mode

This function selects the major mode that is appropriate for the current buffer. It may base its decision on the value of the -*- line, on the visited file name (using auto-mode-alist), or on the value of a local variable. However, this function does not look for the mode: local variable near the end of a file; the hack-local-variables function does that. See Choosing Modes.

User Option: default-major-mode

This variable holds the default major mode for new buffers. The standard value is fundamental-mode.

If the value of default-major-mode is nil, Emacs uses the (previously) current buffer's major mode for the major mode of a new buffer. However, if the major mode symbol has a mode-class property with value special, then it is not used for new buffers; Fundamental mode is used instead. The modes that have this property are those such as Dired and Rmail that are useful only with text that has been specially prepared.

Function: set-buffer-major-mode buffer

This function sets the major mode of buffer to the value of default-major-mode. If that variable is nil, it uses the current buffer's major mode (if that is suitable).

The low-level primitives for creating buffers do not use this function, but medium-level commands such as switch-to-buffer and find-file-noselect use it whenever they create buffers.

Variable: initial-major-mode

The value of this variable determines the major mode of the initial *scratch* buffer. The value should be a symbol that is a major mode command name. The default value is lisp-interaction-mode.

Variable: auto-mode-alist

This variable contains an association list of file name patterns (regular expressions; see Regular Expressions) and corresponding major mode functions. Usually, the file name patterns test for suffixes, such as .el and .c, but this need not be the case. An ordinary element of the alist looks like (regexp . mode-function).

For example,

(("^/tmp/fol/" . text-mode)
 ("\\.texinfo\\'" . texinfo-mode)
 ("\\.texi\\'" . texinfo-mode)
 ("\\.el\\'" . emacs-lisp-mode)
 ("\\.c\\'" . c-mode) 
 ("\\.h\\'" . c-mode)
 ...)

When you visit a file whose expanded file name (see File Name Expansion) matches a regexp, set-auto-mode calls the corresponding mode-function. This feature enables Emacs to select the proper major mode for most files.

If an element of auto-mode-alist has the form (regexp function t), then after calling function, Emacs searches auto-mode-alist again for a match against the portion of the file name that did not match before.

This match-again feature is useful for uncompression packages: an entry of the form ("\\.gz\\'" . function) can uncompress the file and then put the uncompressed file in the proper mode according to the name sans .gz.

Here is an example of how to prepend several pattern pairs to auto-mode-alist. (You might use this sort of expression in your .emacs file.)

(setq auto-mode-alist
  (append 
   ;; File name starts with a dot.
   '(("/\\.[^/]*\\'" . fundamental-mode)  
     ;; File name has no dot.
     ("[^\\./]*\\'" . fundamental-mode)   
     ;; File name ends in .C.
     ("\\.C\\'" . c++-mode))
   auto-mode-alist))

Variable: interpreter-mode-alist

This variable specifes major modes to use for scripts that specify a command interpreter in an !# line. Its value is a list of elements of the form (interpreter . mode); for example, ("perl" . perl-mode) is one element present by default. The element says to use mode mode if the file specifies interpreter.

This variable is applicable only when the auto-mode-alist does not indicate which major mode to use.

Function: hack-local-variables &optional force

This function parses, and binds or evaluates as appropriate, any local variables for the current buffer.

The handling of enable-local-variables documented for normal-mode actually takes place here. The argument force usually comes from the argument find-file given to normal-mode.