Commit | Line | Data |
---|---|---|
8875da1e | 1 | @c This is part of the Emacs manual. |
ba318903 | 2 | @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software |
ab422c4d | 3 | @c Foundation, Inc. |
8875da1e | 4 | @c See file emacs.texi for copying conditions. |
abb9615e | 5 | @node Modes |
dc95a8b0 | 6 | @chapter Major and Minor Modes |
8875da1e | 7 | |
dc95a8b0 CY |
8 | Emacs contains many @dfn{editing modes} that alter its basic |
9 | behavior in useful ways. These are divided into @dfn{major modes} and | |
10 | @dfn{minor modes}. | |
8875da1e CY |
11 | |
12 | Major modes provide specialized facilities for working on a | |
13 | particular file type, such as a C source file (@pxref{Programs}), or a | |
14 | particular type of non-file buffer, such as a shell buffer | |
15 | (@pxref{Shell}). Major modes are mutually exclusive; each buffer has | |
16 | one and only one major mode at any time. | |
17 | ||
18 | Minor modes are optional features which you can turn on or off, not | |
19 | necessarily specific to a type of file or buffer. For example, Auto | |
20 | Fill mode is a minor mode in which @key{SPC} breaks lines between | |
21 | words as you type (@pxref{Auto Fill}). Minor modes are independent of | |
22 | one another, and of the selected major mode. | |
23 | ||
24 | @menu | |
25 | * Major Modes:: Text mode vs. Lisp mode vs. C mode... | |
26 | * Minor Modes:: Each minor mode is a feature you can turn on | |
27 | independently of any others. | |
28 | * Choosing Modes:: How modes are chosen when visiting files. | |
29 | @end menu | |
30 | ||
31 | @node Major Modes | |
32 | @section Major Modes | |
33 | @cindex major modes | |
34 | @cindex mode, major | |
35 | @kindex TAB @r{(and major modes)} | |
36 | @kindex DEL @r{(and major modes)} | |
37 | @kindex C-j @r{(and major modes)} | |
38 | ||
39 | Every buffer possesses a major mode, which determines the editing | |
40 | behavior of Emacs while that buffer is current. The mode line | |
dc95a8b0 CY |
41 | normally shows the name of the current major mode, in parentheses |
42 | (@pxref{Mode Line}). | |
8875da1e CY |
43 | |
44 | The least specialized major mode is called @dfn{Fundamental mode}. | |
45 | This mode has no mode-specific redefinitions or variable settings, so | |
46 | that each Emacs command behaves in its most general manner, and each | |
47 | user option variable is in its default state. | |
48 | ||
49 | For editing text of a specific type that Emacs knows about, such as | |
50 | Lisp code or English text, you typically use a more specialized major | |
dc95a8b0 CY |
51 | mode, such as Lisp mode or Text mode. Most major modes fall into |
52 | three major groups. The first group contains modes for normal text, | |
53 | either plain or with mark-up. It includes Text mode, HTML mode, SGML | |
54 | mode, @TeX{} mode and Outline mode. The second group contains modes | |
55 | for specific programming languages. These include Lisp mode (which | |
56 | has several variants), C mode, Fortran mode, and others. The third | |
57 | group consists of major modes that are not associated directly with | |
58 | files; they are used in buffers created for specific purposes by | |
59 | Emacs, such as Dired mode for buffers made by Dired (@pxref{Dired}), | |
60 | Message mode for buffers made by @kbd{C-x m} (@pxref{Sending Mail}), | |
61 | and Shell mode for buffers used to communicate with an inferior shell | |
62 | process (@pxref{Interactive Shell}). | |
63 | ||
64 | Usually, the major mode is automatically set by Emacs, when you | |
65 | first visit a file or create a buffer (@pxref{Choosing Modes}). You | |
66 | can explicitly select a new major mode by using an @kbd{M-x} command. | |
67 | Take the name of the mode and add @code{-mode} to get the name of the | |
eceeb5fc | 68 | command to select that mode (e.g., @kbd{M-x lisp-mode} enters Lisp mode). |
dc95a8b0 CY |
69 | |
70 | @vindex major-mode | |
71 | The value of the buffer-local variable @code{major-mode} is a symbol | |
1df7defd | 72 | with the same name as the major mode command (e.g., @code{lisp-mode}). |
dc95a8b0 CY |
73 | This variable is set automatically; you should not change it yourself. |
74 | ||
75 | The default value of @code{major-mode} determines the major mode to | |
76 | use for files that do not specify a major mode, and for new buffers | |
77 | created with @kbd{C-x b}. Normally, this default value is the symbol | |
78 | @code{fundamental-mode}, which specifies Fundamental mode. You can | |
79 | change this default value via the Customization interface (@pxref{Easy | |
80 | Customization}), or by adding a line like this to your init file | |
81 | (@pxref{Init File}): | |
82 | ||
eceeb5fc | 83 | @example |
dc95a8b0 | 84 | (setq-default major-mode 'text-mode) |
eceeb5fc | 85 | @end example |
dc95a8b0 CY |
86 | |
87 | @noindent | |
88 | If the default value of @code{major-mode} is @code{nil}, the major | |
89 | mode is taken from the previously current buffer. | |
90 | ||
91 | Specialized major modes often change the meanings of certain keys to | |
92 | do something more suitable for the mode. For instance, programming | |
93 | language modes bind @key{TAB} to indent the current line according to | |
94 | the rules of the language (@pxref{Indentation}). The keys that are | |
95 | commonly changed are @key{TAB}, @key{DEL}, and @kbd{C-j}. Many modes | |
96 | also define special commands of their own, usually bound in the prefix | |
97 | key @kbd{C-c}. Major modes can also alter user options and variables; | |
22bcf204 | 98 | for instance, programming language modes typically set a buffer-local |
dc95a8b0 CY |
99 | value for the variable @code{comment-start}, which determines how |
100 | source code comments are delimited (@pxref{Comments}). | |
101 | ||
102 | @findex describe-mode | |
103 | @kindex C-h m | |
104 | To view the documentation for the current major mode, including a | |
105 | list of its key bindings, type @code{C-h m} (@code{describe-mode}). | |
106 | ||
107 | @cindex mode hook | |
108 | @vindex text-mode-hook | |
109 | @vindex prog-mode-hook | |
110 | Every major mode, apart from Fundamental mode, defines a @dfn{mode | |
111 | hook}, a customizable list of Lisp functions to run each time the mode | |
112 | is enabled in a buffer. @xref{Hooks}, for more information about | |
1df7defd | 113 | hooks. Each mode hook is named after its major mode, e.g., Fortran |
dc95a8b0 CY |
114 | mode has @code{fortran-mode-hook}. Furthermore, all text-based major |
115 | modes run @code{text-mode-hook}, and all programming language modes | |
116 | run @code{prog-mode-hook}, prior to running their own mode hooks. | |
95ca9bc7 CY |
117 | Hook functions can look at the value of the variable @code{major-mode} |
118 | to see which mode is actually being entered. | |
dc95a8b0 CY |
119 | |
120 | Mode hooks are commonly used to enable minor modes (@pxref{Minor | |
121 | Modes}). For example, you can put the following lines in your init | |
122 | file to enable Flyspell minor mode in all text-based major modes | |
123 | (@pxref{Spelling}), and Eldoc minor mode in Emacs Lisp mode | |
124 | (@pxref{Lisp Doc}): | |
125 | ||
126 | @example | |
127 | (add-hook 'text-mode-hook 'flyspell-mode) | |
128 | (add-hook 'emacs-lisp-mode-hook 'eldoc-mode) | |
129 | @end example | |
8875da1e CY |
130 | |
131 | @node Minor Modes | |
132 | @section Minor Modes | |
133 | @cindex minor modes | |
134 | @cindex mode, minor | |
135 | ||
dc95a8b0 CY |
136 | A minor mode is an optional editing mode that alters the behavior of |
137 | Emacs in some well-defined way. Unlike major modes, any number of | |
8875da1e | 138 | minor modes can be in effect at any time. Some minor modes are |
dc95a8b0 CY |
139 | @dfn{buffer-local}, and can be turned on (enabled) in certain buffers |
140 | and off (disabled) in others. Other minor modes are @dfn{global}: | |
141 | while enabled, they affect everything you do in the Emacs session, in | |
142 | all buffers. Most minor modes are disabled by default, but a few are | |
143 | enabled by default. | |
144 | ||
145 | Most buffer-local minor modes say in the mode line when they are | |
146 | enabled, just after the major mode indicator. For example, | |
147 | @samp{Fill} in the mode line means that Auto Fill mode is enabled. | |
148 | @xref{Mode Line}. | |
149 | ||
150 | @cindex mode commands for minor modes | |
151 | Like major modes, each minor mode is associated with a @dfn{mode | |
152 | command}, whose name consists of the mode name followed by | |
153 | @samp{-mode}. For instance, the mode command for Auto Fill mode is | |
154 | @code{auto-fill-mode}. But unlike a major mode command, which simply | |
155 | enables the mode, the mode command for a minor mode can either enable | |
156 | or disable it: | |
157 | ||
158 | @itemize | |
159 | @item | |
160 | If you invoke the mode command directly with no prefix argument | |
161 | (either via @kbd{M-x}, or by binding it to a key and typing that key; | |
162 | @pxref{Key Bindings}), that @dfn{toggles} the minor mode. The minor | |
163 | mode is turned on if it was off, and turned off if it was on. | |
164 | ||
165 | @item | |
166 | If you invoke the mode command with a prefix argument, the minor mode | |
167 | is unconditionally turned off if that argument is zero or negative; | |
168 | otherwise, it is unconditionally turned on. | |
169 | ||
170 | @item | |
171 | If the mode command is called via Lisp, the minor mode is | |
172 | unconditionally turned on if the argument is omitted or @code{nil}. | |
173 | This makes it easy to turn on a minor mode from a major mode's mode | |
174 | hook (@pxref{Major Modes}). A non-@code{nil} argument is handled like | |
175 | an interactive prefix argument, as described above. | |
176 | @end itemize | |
8875da1e CY |
177 | |
178 | Most minor modes also have a @dfn{mode variable}, with the same name | |
179 | as the mode command. Its value is non-@code{nil} if the mode is | |
dc95a8b0 CY |
180 | enabled, and @code{nil} if it is disabled. In general, you should not |
181 | try to enable or disable the mode by changing the value of the mode | |
182 | variable directly in Lisp; you should run the mode command instead. | |
183 | However, setting the mode variable through the Customize interface | |
184 | (@pxref{Easy Customization}) will always properly enable or disable | |
185 | the mode, since Customize automatically runs the mode command for you. | |
8875da1e CY |
186 | |
187 | The following is a list of some buffer-local minor modes: | |
188 | ||
189 | @itemize @bullet | |
190 | @item | |
191 | Abbrev mode automatically expands text based on pre-defined | |
192 | abbreviation definitions. @xref{Abbrevs}. | |
193 | ||
194 | @item | |
195 | Auto Fill mode inserts newlines as you type to prevent lines from | |
196 | becoming too long. @xref{Filling}. | |
197 | ||
198 | @item | |
199 | Auto Save mode saves the buffer contents periodically to reduce the | |
200 | amount of work you can lose in case of a crash. @xref{Auto Save}. | |
201 | ||
202 | @item | |
203 | Enriched mode enables editing and saving of formatted text. | |
8863a584 | 204 | @xref{Enriched Text}. |
8875da1e CY |
205 | |
206 | @item | |
207 | Flyspell mode automatically highlights misspelled words. | |
208 | @xref{Spelling}. | |
209 | ||
210 | @item | |
211 | Font-Lock mode automatically highlights certain textual units found in | |
212 | programs. It is enabled globally by default, but you can disable it | |
213 | in individual buffers. @xref{Faces}. | |
214 | ||
215 | @findex linum-mode | |
216 | @cindex Linum mode | |
217 | @item | |
eceeb5fc | 218 | Linum mode displays each line's line number in the window's left margin. |
8875da1e CY |
219 | |
220 | @item | |
221 | Outline minor mode provides similar facilities to the major mode | |
222 | called Outline mode. @xref{Outline Mode}. | |
223 | ||
224 | @cindex Overwrite mode | |
225 | @cindex mode, Overwrite | |
226 | @findex overwrite-mode | |
227 | @kindex INSERT | |
228 | @item | |
229 | Overwrite mode causes ordinary printing characters to replace existing | |
230 | text instead of shoving it to the right. For example, if point is in | |
231 | front of the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing | |
232 | a @kbd{G} changes it to @samp{FOOGAR}, instead of producing | |
233 | @samp{FOOGBAR} as usual. In Overwrite mode, the command @kbd{C-q} | |
234 | inserts the next character whatever it may be, even if it is a | |
235 | digit---this gives you a way to insert a character instead of | |
236 | replacing an existing character. The mode command, | |
237 | @code{overwrite-mode}, is bound to the @key{Insert} key. | |
238 | ||
239 | @findex binary-overwrite-mode | |
240 | @item | |
241 | Binary Overwrite mode is a variant of Overwrite mode for editing | |
242 | binary files; it treats newlines and tabs like other characters, so | |
243 | that they overwrite other characters and can be overwritten by them. | |
244 | In Binary Overwrite mode, digits after @kbd{C-q} specify an octal | |
245 | character code, as usual. | |
246 | ||
247 | @item | |
248 | Visual Line mode performs ``word wrapping'', causing long lines to be | |
249 | wrapped at word boundaries. @xref{Visual Line Mode}. | |
250 | @end itemize | |
251 | ||
dc95a8b0 CY |
252 | @noindent |
253 | And here are some useful global minor modes: | |
8875da1e CY |
254 | |
255 | @itemize @bullet | |
256 | @item | |
257 | Column Number mode enables display of the current column number in the | |
258 | mode line. @xref{Mode Line}. | |
259 | ||
260 | @item | |
261 | Delete Selection mode causes text insertion to first delete the text | |
262 | in the region, if the region is active. @xref{Using Region}. | |
263 | ||
264 | @item | |
265 | Icomplete mode displays an indication of available completions when | |
a8cb4247 | 266 | you are in the minibuffer and completion is active. @xref{Icomplete}. |
8875da1e CY |
267 | |
268 | @item | |
269 | Line Number mode enables display of the current line number in the | |
270 | mode line. It is enabled by default. @xref{Mode Line}. | |
271 | ||
272 | @item | |
273 | Menu Bar mode gives each frame a menu bar. It is enabled by default. | |
274 | @xref{Menu Bars}. | |
275 | ||
276 | @item | |
277 | Scroll Bar mode gives each window a scroll bar. It is enabled by | |
278 | default, but the scroll bar is only displayed on graphical terminals. | |
279 | @xref{Scroll Bars}. | |
280 | ||
281 | @item | |
282 | Tool Bar mode gives each frame a tool bar. It is enabled by default, | |
283 | but the tool bar is only displayed on graphical terminals. @xref{Tool | |
284 | Bars}. | |
285 | ||
286 | @item | |
287 | Transient Mark mode highlights the region, and makes many Emacs | |
288 | commands operate on the region when the mark is active. It is enabled | |
289 | by default. @xref{Mark}. | |
290 | @end itemize | |
291 | ||
292 | @node Choosing Modes | |
293 | @section Choosing File Modes | |
294 | ||
295 | @cindex choosing a major mode | |
296 | @cindex choosing a minor mode | |
297 | @vindex auto-mode-alist | |
298 | When you visit a file, Emacs chooses a major mode automatically. | |
299 | Normally, it makes the choice based on the file name---for example, | |
300 | files whose names end in @samp{.c} are normally edited in C mode---but | |
301 | sometimes it chooses the major mode based on special text in the file. | |
302 | This special text can also be used to enable buffer-local minor modes. | |
303 | ||
304 | Here is the exact procedure: | |
305 | ||
306 | First, Emacs checks whether the file contains file-local mode | |
307 | variables. @xref{File Variables}. If there is a file-local variable | |
308 | that specifies a major mode, then Emacs uses that major mode, ignoring | |
309 | all other criteria. There are several methods to specify a major mode | |
310 | using a file-local variable; the simplest is to put the mode name in | |
311 | the first nonblank line, preceded and followed by @samp{-*-}. Other | |
312 | text may appear on the line as well. For example, | |
313 | ||
314 | @example | |
315 | ; -*-Lisp-*- | |
316 | @end example | |
317 | ||
318 | @noindent | |
319 | tells Emacs to use Lisp mode. Note how the semicolon is used to make | |
dc95a8b0 | 320 | Lisp treat this line as a comment. You could equivalently write |
8875da1e CY |
321 | |
322 | @example | |
323 | ; -*- mode: Lisp;-*- | |
324 | @end example | |
325 | ||
326 | @noindent | |
dc95a8b0 CY |
327 | You can also use file-local variables to specify buffer-local minor |
328 | modes, by using @code{eval} specifications. For example, this first | |
329 | nonblank line puts the buffer in Lisp mode and enables Auto-Fill mode: | |
8875da1e CY |
330 | |
331 | @example | |
dc95a8b0 | 332 | ; -*- mode: Lisp; eval: (auto-fill-mode 1); -*- |
8875da1e CY |
333 | @end example |
334 | ||
dc95a8b0 CY |
335 | @noindent |
336 | Note, however, that it is usually inappropriate to enable minor modes | |
337 | this way, since most minor modes represent individual user | |
338 | preferences. If you personally want to use a minor mode for a | |
339 | particular file type, it is better to enable the minor mode via a | |
340 | major mode hook (@pxref{Major Modes}). | |
8875da1e CY |
341 | |
342 | @vindex interpreter-mode-alist | |
343 | Second, if there is no file variable specifying a major mode, Emacs | |
344 | checks whether the file's contents begin with @samp{#!}. If so, that | |
345 | indicates that the file can serve as an executable shell command, | |
346 | which works by running an interpreter named on the file's first line | |
347 | (the rest of the file is used as input to the interpreter). | |
348 | Therefore, Emacs tries to use the interpreter name to choose a mode. | |
349 | For instance, a file that begins with @samp{#!/usr/bin/perl} is opened | |
350 | in Perl mode. The variable @code{interpreter-mode-alist} specifies | |
351 | the correspondence between interpreter program names and major modes. | |
352 | ||
353 | When the first line starts with @samp{#!}, you usually cannot use | |
354 | the @samp{-*-} feature on the first line, because the system would get | |
355 | confused when running the interpreter. So Emacs looks for @samp{-*-} | |
356 | on the second line in such files as well as on the first line. The | |
357 | same is true for man pages which start with the magic string | |
358 | @samp{'\"} to specify a list of troff preprocessors. | |
359 | ||
360 | @vindex magic-mode-alist | |
361 | Third, Emacs tries to determine the major mode by looking at the | |
362 | text at the start of the buffer, based on the variable | |
363 | @code{magic-mode-alist}. By default, this variable is @code{nil} (an | |
364 | empty list), so Emacs skips this step; however, you can customize it | |
365 | in your init file (@pxref{Init File}). The value should be a list of | |
366 | elements of the form | |
367 | ||
368 | @example | |
369 | (@var{regexp} . @var{mode-function}) | |
370 | @end example | |
371 | ||
372 | @noindent | |
373 | where @var{regexp} is a regular expression (@pxref{Regexps}), and | |
dc95a8b0 CY |
374 | @var{mode-function} is a major mode command. If the text at the |
375 | beginning of the file matches @var{regexp}, Emacs chooses the major | |
376 | mode specified by @var{mode-function}. | |
8875da1e CY |
377 | |
378 | Alternatively, an element of @code{magic-mode-alist} may have the form | |
379 | ||
380 | @example | |
381 | (@var{match-function} . @var{mode-function}) | |
382 | @end example | |
383 | ||
384 | @noindent | |
385 | where @var{match-function} is a Lisp function that is called at the | |
386 | beginning of the buffer; if the function returns non-@code{nil}, Emacs | |
dc95a8b0 | 387 | set the major mode with @var{mode-function}. |
8875da1e CY |
388 | |
389 | Fourth---if Emacs still hasn't found a suitable major mode---it | |
390 | looks at the file's name. The correspondence between file names and | |
391 | major modes is controlled by the variable @code{auto-mode-alist}. Its | |
392 | value is a list in which each element has this form, | |
393 | ||
394 | @example | |
395 | (@var{regexp} . @var{mode-function}) | |
396 | @end example | |
397 | ||
398 | @noindent | |
399 | or this form, | |
400 | ||
401 | @example | |
402 | (@var{regexp} @var{mode-function} @var{flag}) | |
403 | @end example | |
404 | ||
405 | @noindent | |
406 | For example, one element normally found in the list has the form | |
407 | @code{(@t{"\\.c\\'"} . c-mode)}, and it is responsible for selecting C | |
408 | mode for files whose names end in @file{.c}. (Note that @samp{\\} is | |
409 | needed in Lisp syntax to include a @samp{\} in the string, which must | |
410 | be used to suppress the special meaning of @samp{.} in regexps.) If | |
411 | the element has the form @code{(@var{regexp} @var{mode-function} | |
412 | @var{flag})} and @var{flag} is non-@code{nil}, then after calling | |
413 | @var{mode-function}, Emacs discards the suffix that matched | |
414 | @var{regexp} and searches the list again for another match. | |
415 | ||
416 | @vindex auto-mode-case-fold | |
3fd50d5c CY |
417 | On GNU/Linux and other systems with case-sensitive file names, Emacs |
418 | performs a case-sensitive search through @code{auto-mode-alist}; if | |
419 | this search fails, it performs a second case-insensitive search | |
420 | through the alist. To suppress the second search, change the variable | |
421 | @code{auto-mode-case-fold} to @code{nil}. On systems with | |
422 | case-insensitive file names, such as Microsoft Windows, Emacs performs | |
423 | a single case-insensitive search through @code{auto-mode-alist}. | |
8875da1e CY |
424 | |
425 | @vindex magic-fallback-mode-alist | |
426 | Finally, if Emacs @emph{still} hasn't found a major mode to use, it | |
427 | compares the text at the start of the buffer to the variable | |
428 | @code{magic-fallback-mode-alist}. This variable works like | |
429 | @code{magic-mode-alist}, described above, except that is consulted | |
430 | only after @code{auto-mode-alist}. By default, | |
431 | @code{magic-fallback-mode-alist} contains forms that check for image | |
7877f373 | 432 | files, HTML/XML/SGML files, and PostScript files. |
8875da1e | 433 | |
8875da1e CY |
434 | @findex normal-mode |
435 | If you have changed the major mode of a buffer, you can return to | |
436 | the major mode Emacs would have chosen automatically, by typing | |
437 | @kbd{M-x normal-mode}. This is the same function that | |
438 | @code{find-file} calls to choose the major mode. It also processes | |
439 | the file's @samp{-*-} line or local variables list (if any). | |
440 | @xref{File Variables}. | |
441 | ||
442 | @vindex change-major-mode-with-file-name | |
443 | The commands @kbd{C-x C-w} and @code{set-visited-file-name} change to | |
444 | a new major mode if the new file name implies a mode (@pxref{Saving}). | |
445 | (@kbd{C-x C-s} does this too, if the buffer wasn't visiting a file.) | |
446 | However, this does not happen if the buffer contents specify a major | |
447 | mode, and certain ``special'' major modes do not allow the mode to | |
448 | change. You can turn off this mode-changing feature by setting | |
449 | @code{change-major-mode-with-file-name} to @code{nil}. |