| 1 | @c This is part of the Emacs manual. |
| 2 | @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software |
| 3 | @c Foundation, Inc. |
| 4 | @c See file emacs.texi for copying conditions. |
| 5 | @node Modes |
| 6 | @chapter Major and Minor Modes |
| 7 | |
| 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}. |
| 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 |
| 41 | normally shows the name of the current major mode, in parentheses |
| 42 | (@pxref{Mode Line}). |
| 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 |
| 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 |
| 68 | command to select that mode (e.g., @kbd{M-x lisp-mode} enters Lisp mode). |
| 69 | |
| 70 | @vindex major-mode |
| 71 | The value of the buffer-local variable @code{major-mode} is a symbol |
| 72 | with the same name as the major mode command (e.g., @code{lisp-mode}). |
| 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 | |
| 83 | @example |
| 84 | (setq-default major-mode 'text-mode) |
| 85 | @end example |
| 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; |
| 98 | for instance, programming language modes typically set a buffer-local |
| 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 |
| 113 | hooks. Each mode hook is named after its major mode, e.g., Fortran |
| 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. |
| 117 | Hook functions can look at the value of the variable @code{major-mode} |
| 118 | to see which mode is actually being entered. |
| 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 |
| 130 | |
| 131 | @node Minor Modes |
| 132 | @section Minor Modes |
| 133 | @cindex minor modes |
| 134 | @cindex mode, minor |
| 135 | |
| 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 |
| 138 | minor modes can be in effect at any time. Some minor modes are |
| 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 |
| 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 |
| 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. |
| 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. |
| 204 | @xref{Enriched Text}. |
| 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 |
| 218 | Linum mode displays each line's line number in the window's left margin. |
| 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 | |
| 252 | @noindent |
| 253 | And here are some useful global minor modes: |
| 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 |
| 266 | you are in the minibuffer and completion is active. @xref{Icomplete}. |
| 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 |
| 320 | Lisp treat this line as a comment. You could equivalently write |
| 321 | |
| 322 | @example |
| 323 | ; -*- mode: Lisp;-*- |
| 324 | @end example |
| 325 | |
| 326 | @noindent |
| 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: |
| 330 | |
| 331 | @example |
| 332 | ; -*- mode: Lisp; eval: (auto-fill-mode 1); -*- |
| 333 | @end example |
| 334 | |
| 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}). |
| 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 |
| 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}. |
| 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 |
| 387 | set the major mode with @var{mode-function}. |
| 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 |
| 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}. |
| 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 |
| 432 | files, HTML/XML/SGML files, and PostScript files. |
| 433 | |
| 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}. |