Commit | Line | Data |
---|---|---|
8cf51b2c GM |
1 | @c This is part of the Emacs manual. |
2 | @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, | |
114f9c96 | 3 | @c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc. |
8cf51b2c GM |
4 | @c See file emacs.texi for copying conditions. |
5 | @node Major Modes, Indentation, International, Top | |
6 | @chapter Major Modes | |
7 | @cindex major modes | |
8 | @cindex mode, major | |
9 | @kindex TAB @r{(and major modes)} | |
10 | @kindex DEL @r{(and major modes)} | |
11 | @kindex C-j @r{(and major modes)} | |
12 | ||
13 | Emacs provides many alternative @dfn{major modes}, each of which | |
14 | customizes Emacs for editing text of a particular sort. The major modes | |
15 | are mutually exclusive, and each buffer has one major mode at any time. | |
16 | The mode line normally shows the name of the current major mode, in | |
17 | parentheses (@pxref{Mode Line}). | |
18 | ||
19 | The least specialized major mode is called @dfn{Fundamental mode}. | |
20 | This mode has no mode-specific redefinitions or variable settings, so | |
21 | that each Emacs command behaves in its most general manner, and each | |
22 | user option variable is in its default state. For editing text of a | |
23 | specific type that Emacs knows about, such as Lisp code or English | |
24 | text, you should switch to the appropriate major mode, such as Lisp | |
25 | mode or Text mode. | |
26 | ||
27 | Selecting a major mode changes the meanings of a few keys to become | |
28 | more specifically adapted to the language being edited. The ones that | |
29 | are changed frequently are @key{TAB}, @key{DEL}, and @kbd{C-j}. The | |
30 | prefix key @kbd{C-c} normally contains mode-specific commands. In | |
31 | addition, the commands which handle comments use the mode to determine | |
32 | how comments are to be delimited. Many major modes redefine the | |
33 | syntactical properties of characters appearing in the buffer. | |
34 | @xref{Syntax}. | |
35 | ||
36 | The major modes fall into three major groups. The first group | |
37 | contains modes for normal text, either plain or with mark-up. It | |
38 | includes Text mode, HTML mode, SGML mode, @TeX{} mode and Outline | |
39 | mode. The second group contains modes for specific programming | |
40 | languages. These include Lisp mode (which has several variants), C | |
41 | mode, Fortran mode, and others. The remaining major modes are not | |
42 | intended for use on users' files; they are used in buffers created for | |
43 | specific purposes by Emacs, such as Dired mode for buffers made by | |
44 | Dired (@pxref{Dired}), Mail mode for buffers made by @kbd{C-x m} | |
45 | (@pxref{Sending Mail}), and Shell mode for buffers used for | |
46 | communicating with an inferior shell process (@pxref{Interactive | |
47 | Shell}). | |
48 | ||
49 | Most programming-language major modes specify that only blank lines | |
50 | separate paragraphs. This is to make the paragraph commands useful. | |
51 | (@xref{Paragraphs}.) They also cause Auto Fill mode to use the | |
52 | definition of @key{TAB} to indent the new lines it creates. This is | |
53 | because most lines in a program are usually indented | |
54 | (@pxref{Indentation}). | |
55 | ||
56 | @menu | |
57 | * Choosing Modes:: How major modes are specified or chosen. | |
58 | @end menu | |
59 | ||
60 | @node Choosing Modes,,Major Modes,Major Modes | |
61 | @section How Major Modes are Chosen | |
62 | ||
63 | @cindex choosing a major mode | |
64 | You can select a major mode explicitly for the current buffer, but | |
65 | most of the time Emacs determines which mode to use based on the file | |
66 | name or on special text in the file. | |
67 | ||
68 | To explicitly select a new major, you use an @kbd{M-x} command. | |
69 | Take the name of a major mode and add @code{-mode} to get the name of | |
70 | the command to select that mode. Thus, you can enter Lisp mode by | |
71 | executing @kbd{M-x lisp-mode}. | |
72 | ||
73 | @vindex auto-mode-alist | |
8be68090 | 74 | When you visit a file, Emacs usually chooses the right major mode |
da77fe94 | 75 | automatically. Normally, it makes the choice based on the file |
8be68090 | 76 | name---for example, files whose names end in @samp{.c} are normally |
da77fe94 CY |
77 | edited in C mode---but sometimes it chooses the major mode based on |
78 | the contents of the file. Here is the exact procedure: | |
8be68090 CY |
79 | |
80 | First, Emacs checks whether the file contains a file-local variable | |
81 | that specifies the major mode. If so, it uses that major mode, | |
82 | ignoring all other criteria. @xref{File Variables}. There are | |
83 | several methods to specify a major mode using a file-local variable; | |
84 | the simplest is to put the mode name in the first nonblank line, | |
85 | preceded and followed by @samp{-*-}. Other text may appear on the | |
86 | line as well. For example, | |
8cf51b2c GM |
87 | |
88 | @example | |
8be68090 | 89 | ; -*-Lisp-*- |
8cf51b2c GM |
90 | @end example |
91 | ||
92 | @noindent | |
8be68090 CY |
93 | tells Emacs to use Lisp mode. Note how the semicolon is used to make |
94 | Lisp treat this line as a comment. Alternatively, you could write | |
8cf51b2c GM |
95 | |
96 | @example | |
8be68090 | 97 | ; -*- mode: Lisp;-*- |
8cf51b2c GM |
98 | @end example |
99 | ||
100 | @noindent | |
8be68090 CY |
101 | The latter format allows you to specify local variables as well, like |
102 | this: | |
103 | ||
104 | @example | |
105 | ; -*- mode: Lisp; tab-width: 4; -*- | |
106 | @end example | |
107 | ||
108 | @vindex interpreter-mode-alist | |
da77fe94 | 109 | Second, Emacs checks whether the file's contents begin with |
8be68090 CY |
110 | @samp{#!}. If so, that indicates that the file can serve as an |
111 | executable shell command, which works by running an interpreter named | |
112 | on the file's first line (the rest of the file is used as input to the | |
113 | interpreter). Therefore, Emacs tries to use the interpreter name to | |
114 | choose a mode. For instance, a file that begins with | |
115 | @samp{#!/usr/bin/perl} is opened in Perl mode. The variable | |
116 | @code{interpreter-mode-alist} specifies the correspondence between | |
117 | interpreter program names and major modes. | |
118 | ||
119 | When the first line starts with @samp{#!}, you usually cannot use | |
120 | the @samp{-*-} feature on the first line, because the system would get | |
121 | confused when running the interpreter. So Emacs looks for @samp{-*-} | |
122 | on the second line in such files as well as on the first line. The | |
123 | same is true for man pages which start with the magic string | |
124 | @samp{'\"} to specify a list of troff preprocessors. | |
8cf51b2c GM |
125 | |
126 | @vindex magic-mode-alist | |
da77fe94 | 127 | Third, Emacs tries to determine the major mode by looking at the |
8be68090 CY |
128 | text at the start of the buffer, based on the variable |
129 | @code{magic-mode-alist}. By default, this variable is @code{nil} (an | |
130 | empty list), so Emacs skips this step; however, you can customize it | |
131 | in your init file (@pxref{Init File}). The value should be a list of | |
132 | elements of the form | |
8cf51b2c GM |
133 | |
134 | @example | |
135 | (@var{regexp} . @var{mode-function}) | |
8cf51b2c GM |
136 | @end example |
137 | ||
138 | @noindent | |
8be68090 CY |
139 | where @var{regexp} is a regular expression (@pxref{Regexps}), and |
140 | @var{mode-function} is a Lisp function that toggles a major mode. If | |
141 | the text at the beginning of the file matches @var{regexp}, Emacs | |
142 | chooses the major mode specified by @var{mode-function}. | |
143 | ||
144 | Alternatively, an element of @code{magic-mode-alist} may have the form | |
8cf51b2c GM |
145 | |
146 | @example | |
8be68090 | 147 | (@var{match-function} . @var{mode-function}) |
8cf51b2c GM |
148 | @end example |
149 | ||
150 | @noindent | |
8be68090 CY |
151 | where @var{match-function} is a Lisp function that is called at the |
152 | beginning of the buffer; if the function returns non-@code{nil}, Emacs | |
153 | set the major mode wit @var{mode-function}. | |
8cf51b2c | 154 | |
da77fe94 | 155 | Fourth---if Emacs still hasn't found a suitable major mode---it |
8be68090 CY |
156 | looks at the file's name. The correspondence between file names and |
157 | major modes is controlled by the variable @code{auto-mode-alist}. Its | |
158 | value is a list in which each element has this form, | |
8cf51b2c GM |
159 | |
160 | @example | |
8be68090 | 161 | (@var{regexp} . @var{mode-function}) |
8cf51b2c GM |
162 | @end example |
163 | ||
164 | @noindent | |
8be68090 | 165 | or this form, |
8cf51b2c GM |
166 | |
167 | @example | |
8be68090 | 168 | (@var{regexp} @var{mode-function} @var{flag}) |
8cf51b2c GM |
169 | @end example |
170 | ||
171 | @noindent | |
8be68090 CY |
172 | For example, one element normally found in the list has the form |
173 | @code{(@t{"\\.c\\'"} . c-mode)}, and it is responsible for selecting C | |
174 | mode for files whose names end in @file{.c}. (Note that @samp{\\} is | |
175 | needed in Lisp syntax to include a @samp{\} in the string, which must | |
176 | be used to suppress the special meaning of @samp{.} in regexps.) If | |
177 | the element has the form @code{(@var{regexp} @var{mode-function} | |
178 | @var{flag})} and @var{flag} is non-@code{nil}, then after calling | |
179 | @var{mode-function}, Emacs discards the suffix that matched | |
180 | @var{regexp} and searches the list again for another match. | |
8cf51b2c GM |
181 | |
182 | @vindex auto-mode-case-fold | |
8be68090 CY |
183 | On systems with case-insensitive file names, such as Microsoft |
184 | Windows, Emacs performs a single case-insensitive search through | |
185 | @code{auto-mode-alist}. On other systems, Emacs normally performs a | |
186 | single case-sensitive search through the alist. However, if you | |
187 | change the variable @code{auto-mode-case-fold} to @code{t}, Emacs | |
188 | performs a second case-insensitive search if the first search fails. | |
189 | ||
190 | @vindex magic-fallback-mode-alist | |
191 | Finally, if Emacs @emph{still} hasn't found a major mode to use, it | |
192 | compares the text at the start of the buffer to the variable | |
193 | @code{magic-fallback-mode-alist}. This variable works like | |
194 | @code{magic-mode-alist}, described above, except that is consulted | |
195 | only after @code{auto-mode-alist}. By default, | |
196 | @code{magic-fallback-mode-alist} contains forms that check for image | |
197 | files, HTML/XML/SGML files, and Postscript files. | |
8cf51b2c | 198 | |
8cf51b2c | 199 | When you visit a file that does not specify a major mode to use, or |
4e3b4528 SM |
200 | when you create a new buffer with @kbd{C-x b}, the default value of |
201 | the variable @code{major-mode} specifies which major mode to use. Normally | |
8cf51b2c | 202 | its value is the symbol @code{fundamental-mode}, which specifies |
4e3b4528 SM |
203 | Fundamental mode. If the default value of @code{major-mode} is @code{nil}, |
204 | the major mode is taken from the previously current buffer. | |
8cf51b2c GM |
205 | |
206 | @findex normal-mode | |
207 | If you change the major mode of a buffer, you can go back to the major | |
208 | mode Emacs would choose automatically: use the command @kbd{M-x | |
209 | normal-mode} to do this. This is the same function that | |
210 | @code{find-file} calls to choose the major mode. It also processes | |
211 | the file's @samp{-*-} line or local variables list (if any). | |
212 | @xref{File Variables}. | |
213 | ||
214 | @vindex change-major-mode-with-file-name | |
215 | The commands @kbd{C-x C-w} and @code{set-visited-file-name} change to | |
216 | a new major mode if the new file name implies a mode (@pxref{Saving}). | |
217 | (@kbd{C-x C-s} does this too, if the buffer wasn't visiting a file.) | |
218 | However, this does not happen if the buffer contents specify a major | |
219 | mode, and certain ``special'' major modes do not allow the mode to | |
220 | change. You can turn off this mode-changing feature by setting | |
221 | @code{change-major-mode-with-file-name} to @code{nil}. | |
222 | ||
223 | @ignore | |
224 | arch-tag: f2558800-cf32-4839-8acb-7d3b4df2a155 | |
225 | @end ignore |