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