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.