Info Catalog emacs: Minor Modes emacs: Modes

emacs: Choosing Modes

 
 23.3 Choosing File Modes
 ========================
 
 When you visit a file, Emacs chooses a major mode automatically.
 Normally, it makes the choice based on the file name—for example, files
 whose names end in ‘.c’ are normally edited in C mode—but sometimes it
 chooses the major mode based on special text in the file.  This special
 text can also be used to enable buffer-local minor modes.
 
    Here is the exact procedure:
 
    First, Emacs checks whether the file contains file-local mode
 variables.  File Variables.  If there is a file-local variable
 that specifies a major mode, then Emacs uses that major mode, ignoring
 all other criteria.  There are several methods to specify a major mode
 using a file-local variable; the simplest is to put the mode name in the
 first nonblank line, preceded and followed by ‘-*-’.  Other text may
 appear on the line as well.  For example,
 
      ; -*-Lisp-*-
 
 tells Emacs to use Lisp mode.  Note how the semicolon is used to make
 Lisp treat this line as a comment.  You could equivalently write
 
      ; -*- mode: Lisp;-*-
 
 You can also use file-local variables to specify buffer-local minor
 modes, by using ‘eval’ specifications.  For example, this first nonblank
 line puts the buffer in Lisp mode and enables Auto-Fill mode:
 
      ; -*- mode: Lisp; eval: (auto-fill-mode 1); -*-
 
 Note, however, that it is usually inappropriate to enable minor modes
 this way, since most minor modes represent individual user preferences.
 If you personally want to use a minor mode for a particular file type,
 it is better to enable the minor mode via a major mode hook (Major
 Modes).
 
    Second, if there is no file variable specifying a major mode, Emacs
 checks whether the file’s contents begin with ‘#!’.  If so, that
 indicates that the file can serve as an executable shell command, which
 works by running an interpreter named on the file’s first line (the rest
 of the file is used as input to the interpreter).  Therefore, Emacs
 tries to use the interpreter name to choose a mode.  For instance, a
 file that begins with ‘#!/usr/bin/perl’ is opened in Perl mode.  The
 variable ‘interpreter-mode-alist’ specifies the correspondence between
 interpreter program names and major modes.
 
    When the first line starts with ‘#!’, you usually cannot use the
 ‘-*-’ feature on the first line, because the system would get confused
 when running the interpreter.  So Emacs looks for ‘-*-’ on the second
 line in such files as well as on the first line.  The same is true for
 man pages which start with the magic string ‘'\"’ to specify a list of
 troff preprocessors.
 
    Third, Emacs tries to determine the major mode by looking at the text
 at the start of the buffer, based on the variable ‘magic-mode-alist’.
 By default, this variable is ‘nil’ (an empty list), so Emacs skips this
 step; however, you can customize it in your init file (Init
 File).  The value should be a list of elements of the form
 
      (REGEXP . MODE-FUNCTION)
 
 where REGEXP is a regular expression (Regexps), and
 MODE-FUNCTION is a major mode command.  If the text at the beginning of
 the file matches REGEXP, Emacs chooses the major mode specified by
 MODE-FUNCTION.
 
    Alternatively, an element of ‘magic-mode-alist’ may have the form
 
      (MATCH-FUNCTION . MODE-FUNCTION)
 
 where MATCH-FUNCTION is a Lisp function that is called at the beginning
 of the buffer; if the function returns non-‘nil’, Emacs set the major
 mode with MODE-FUNCTION.
 
    Fourth—if Emacs still hasn’t found a suitable major mode—it looks at
 the file’s name.  The correspondence between file names and major modes
 is controlled by the variable ‘auto-mode-alist’.  Its value is a list in
 which each element has this form,
 
      (REGEXP . MODE-FUNCTION)
 
 or this form,
 
      (REGEXP MODE-FUNCTION FLAG)
 
 For example, one element normally found in the list has the form
 ‘("\\.c\\'" . c-mode)’, and it is responsible for selecting C mode for
 files whose names end in ‘.c’.  (Note that ‘\\’ is needed in Lisp syntax
 to include a ‘\’ in the string, which must be used to suppress the
 special meaning of ‘.’ in regexps.)  If the element has the form
 ‘(REGEXP MODE-FUNCTION FLAG)’ and FLAG is non-‘nil’, then after calling
 MODE-FUNCTION, Emacs discards the suffix that matched REGEXP and
 searches the list again for another match.
 
    On GNU/Linux and other systems with case-sensitive file names, Emacs
 performs a case-sensitive search through ‘auto-mode-alist’; if this
 search fails, it performs a second case-insensitive search through the
 alist.  To suppress the second search, change the variable
 ‘auto-mode-case-fold’ to ‘nil’.  On systems with case-insensitive file
 names, such as Microsoft Windows, Emacs performs a single
 case-insensitive search through ‘auto-mode-alist’.
 
    Finally, if Emacs _still_ hasn’t found a major mode to use, it
 compares the text at the start of the buffer to the variable
 ‘magic-fallback-mode-alist’.  This variable works like
 ‘magic-mode-alist’, described above, except that is consulted only after
 ‘auto-mode-alist’.  By default, ‘magic-fallback-mode-alist’ contains
 forms that check for image files, HTML/XML/SGML files, PostScript files,
 and Unix style Conf files.
 
    If you have changed the major mode of a buffer, you can return to the
 major mode Emacs would have chosen automatically, by typing ‘M-x
 normal-mode’.  This is the same function that ‘find-file’ calls to
 choose the major mode.  It also processes the file’s ‘-*-’ line or local
 variables list (if any).  File Variables.
 
    The commands ‘C-x C-w’ and ‘set-visited-file-name’ change to a new
 major mode if the new file name implies a mode (Saving).  (‘C-x
 C-s’ does this too, if the buffer wasn’t visiting a file.)  However,
 this does not happen if the buffer contents specify a major mode, and
 certain special major modes do not allow the mode to change.  You can
 turn off this mode-changing feature by setting
 ‘change-major-mode-with-file-name’ to ‘nil’.
 

Info Catalog emacs: Minor Modes emacs: Modes