path: root/devdocs/elisp/auto-major-mode.html

 <h4 class="subsection">How Emacs Chooses a Major Mode</h4>  <p>When Emacs visits a file, it automatically selects a major mode for the buffer based on information in the file name or in the file itself. It also processes local variables specified in the file text. </p> <dl> <dt id="normal-mode">Command: <strong>normal-mode</strong> <em>&amp;optional find-file</em>
</dt> <dd>
<p>This function establishes the proper major mode and buffer-local variable bindings for the current buffer. It calls <code>set-auto-mode</code> (see below). As of Emacs 26.1, it no longer runs <code>hack-local-variables</code>, this now being done in <code>run-mode-hooks</code> at the initialization of major modes (see <a href="mode-hooks">Mode Hooks</a>). </p> <p>If the <var>find-file</var> argument to <code>normal-mode</code> is non-<code>nil</code>, <code>normal-mode</code> assumes that the <code>find-file</code> function is calling it. In this case, it may process local variables in the ‘<samp>-*-</samp>’ line or at the end of the file. The variable <code>enable-local-variables</code> controls whether to do so. See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/File-Variables.html#File-Variables">Local Variables in Files</a> in <cite>The GNU Emacs Manual</cite>, for the syntax of the local variables section of a file. </p> <p>If you run <code>normal-mode</code> interactively, the argument <var>find-file</var> is normally <code>nil</code>. In this case, <code>normal-mode</code> unconditionally processes any file local variables. </p> <p>The function calls <code>set-auto-mode</code> to choose and set a major mode. If this does not specify a mode, the buffer stays in the major mode determined by the default value of <code>major-mode</code> (see below). </p>  <p><code>normal-mode</code> uses <code>condition-case</code> around the call to the major mode command, so errors are caught and reported as a ‘<samp>File mode specification error</samp>’, followed by the original error message. </p>
</dd>
</dl> <dl> <dt id="set-auto-mode">Function: <strong>set-auto-mode</strong> <em>&amp;optional keep-mode-if-same</em>
</dt> <dd>
 <p>This function selects and sets the major mode that is appropriate for the current buffer. It bases its decision (in order of precedence) on the ‘<samp><span class="nolinebreak">-*-</span></samp>’ line, on any ‘<samp>mode:</samp>’ local variable near the end of a file, on the ‘<samp>#!</samp>’ line (using <code>interpreter-mode-alist</code>), on the text at the beginning of the buffer (using <code>magic-mode-alist</code>), and finally on the visited file name (using <code>auto-mode-alist</code>). See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Choosing-Modes.html#Choosing-Modes">How Major Modes are Chosen</a> in <cite>The GNU Emacs Manual</cite>. If <code>enable-local-variables</code> is <code>nil</code>, <code>set-auto-mode</code> does not check the ‘<samp><span class="nolinebreak">-*-</span></samp>’ line, or near the end of the file, for any mode tag. </p>  <p>There are some file types where it is not appropriate to scan the file contents for a mode specifier. For example, a tar archive may happen to contain, near the end of the file, a member file that has a local variables section specifying a mode for that particular file. This should not be applied to the containing tar file. Similarly, a tiff image file might just happen to contain a first line that seems to match the ‘<samp><span class="nolinebreak">-*-</span></samp>’ pattern. For these reasons, both these file extensions are members of the list <code>inhibit-local-variables-regexps</code>. Add patterns to this list to prevent Emacs searching them for local variables of any kind (not just mode specifiers). </p> <p>If <var>keep-mode-if-same</var> is non-<code>nil</code>, this function does not call the mode command if the buffer is already in the proper major mode. For instance, <code>set-visited-file-name</code> sets this to <code>t</code> to avoid killing buffer local variables that the user may have set. </p>
</dd>
</dl> <dl> <dt id="set-buffer-major-mode">Function: <strong>set-buffer-major-mode</strong> <em>buffer</em>
</dt> <dd>
<p>This function sets the major mode of <var>buffer</var> to the default value of <code>major-mode</code>; if that is <code>nil</code>, it uses the current buffer’s major mode (if that is suitable). As an exception, if <var>buffer</var>’s name is <samp>*scratch*</samp>, it sets the mode to <code>initial-major-mode</code>. </p> <p>The low-level primitives for creating buffers do not use this function, but medium-level commands such as <code>switch-to-buffer</code> and <code>find-file-noselect</code> use it whenever they create buffers. </p>
</dd>
</dl> <dl> <dt id="initial-major-mode">User Option: <strong>initial-major-mode</strong>
</dt> <dd>
 <p>The value of this variable determines the major mode of the initial <samp>*scratch*</samp> buffer. The value should be a symbol that is a major mode command. The default value is <code>lisp-interaction-mode</code>. </p>
</dd>
</dl> <dl> <dt id="interpreter-mode-alist">Variable: <strong>interpreter-mode-alist</strong>
</dt> <dd><p>This variable specifies major modes to use for scripts that specify a command interpreter in a ‘<samp>#!</samp>’ line. Its value is an alist with elements of the form <code>(<var>regexp</var> . <var>mode</var>)</code>; this says to use mode <var>mode</var> if the file specifies an interpreter which matches <code>\\`<var>regexp</var>\\'</code>. For example, one of the default elements is <code>("python[0-9.]*" . python-mode)</code>. </p></dd>
</dl> <dl> <dt id="magic-mode-alist">Variable: <strong>magic-mode-alist</strong>
</dt> <dd><p>This variable’s value is an alist with elements of the form <code>(<var>regexp</var> .  <var>function</var>)</code>, where <var>regexp</var> is a regular expression and <var>function</var> is a function or <code>nil</code>. After visiting a file, <code>set-auto-mode</code> calls <var>function</var> if the text at the beginning of the buffer matches <var>regexp</var> and <var>function</var> is non-<code>nil</code>; if <var>function</var> is <code>nil</code>, <code>auto-mode-alist</code> gets to decide the mode. </p></dd>
</dl> <dl> <dt id="magic-fallback-mode-alist">Variable: <strong>magic-fallback-mode-alist</strong>
</dt> <dd><p>This works like <code>magic-mode-alist</code>, except that it is handled only if <code>auto-mode-alist</code> does not specify a mode for this file. </p></dd>
</dl> <dl> <dt id="auto-mode-alist">Variable: <strong>auto-mode-alist</strong>
</dt> <dd>
<p>This variable contains an association list of file name patterns (regular expressions) and corresponding major mode commands. Usually, the file name patterns test for suffixes, such as ‘<samp>.el</samp>’ and ‘<samp>.c</samp>’, but this need not be the case. An ordinary element of the alist looks like <code>(<var>regexp</var> .  <var>mode-function</var>)</code>. </p> <p>For example, </p> <div class="example"> <pre class="example">(("\\`/tmp/fol/" . text-mode)
 ("\\.texinfo\\'" . texinfo-mode)
 ("\\.texi\\'" . texinfo-mode)
</pre>
<pre class="example"> ("\\.el\\'" . emacs-lisp-mode)
 ("\\.c\\'" . c-mode)
 ("\\.h\\'" . c-mode)
 …)
</pre>
</div> <p>When you visit a file whose expanded file name (see <a href="file-name-expansion">File Name Expansion</a>), with version numbers and backup suffixes removed using <code>file-name-sans-versions</code> (see <a href="file-name-components">File Name Components</a>), matches a <var>regexp</var>, <code>set-auto-mode</code> calls the corresponding <var>mode-function</var>. This feature enables Emacs to select the proper major mode for most files. </p> <p>If an element of <code>auto-mode-alist</code> has the form <code>(<var>regexp</var>
<var>function</var> t)</code>, then after calling <var>function</var>, Emacs searches <code>auto-mode-alist</code> again for a match against the portion of the file name that did not match before. This feature is useful for uncompression packages: an entry of the form <code>("\\.gz\\'"
<var>function</var> t)</code> can uncompress the file and then put the uncompressed file in the proper mode according to the name sans ‘<samp>.gz</samp>’. </p> <p>If <code>auto-mode-alist</code> has more than one element whose <var>regexp</var> matches the file name, Emacs will use the first match. </p> <p>Here is an example of how to prepend several pattern pairs to <code>auto-mode-alist</code>. (You might use this sort of expression in your init file.) </p> <div class="example"> <pre class="example">(setq auto-mode-alist
  (append
   ;; <span class="roman">File name (within directory) starts with a dot.</span>
   '(("/\\.[^/]*\\'" . fundamental-mode)
     ;; <span class="roman">File name has no dot.</span>
     ("/[^\\./]*\\'" . fundamental-mode)
     ;; <span class="roman">File name ends in ‘<samp>.C</samp>’.</span>
     ("\\.C\\'" . c++-mode))
   auto-mode-alist))
</pre>
</div> </dd>
</dl><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Auto-Major-Mode.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Auto-Major-Mode.html</a>
  </p>
</div>