modes.texi 162 KB
Newer Older
Glenn Morris's avatar
Glenn Morris committed
1 2
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
Glenn Morris's avatar
Glenn Morris committed
3
@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
Glenn Morris's avatar
Glenn Morris committed
4
@c See the file elisp.texi for copying conditions.
5
@node Modes
Glenn Morris's avatar
Glenn Morris committed
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
@chapter Major and Minor Modes
@cindex mode

  A @dfn{mode} is a set of definitions that customize Emacs and can be
turned on and off while you edit.  There are two varieties of modes:
@dfn{major modes}, which are mutually exclusive and used for editing
particular kinds of text, and @dfn{minor modes}, which provide features
that users can enable individually.

  This chapter describes how to write both major and minor modes, how to
indicate them in the mode line, and how they run hooks supplied by the
user.  For related topics such as keymaps and syntax tables, see
@ref{Keymaps}, and @ref{Syntax Tables}.

@menu
21 22 23 24 25 26 27 28 29
* Hooks::             How to use hooks; how to write code that provides hooks.
* Major Modes::       Defining major modes.
* Minor Modes::       Defining minor modes.
* Mode Line Format::  Customizing the text that appears in the mode line.
* Imenu::             Providing a menu of definitions made in a buffer.
* Font Lock Mode::    How modes can highlight text according to syntax.
* Auto-Indentation::  How to teach Emacs to indent for a major mode.
* Desktop Save Mode:: How modes can have buffer state saved between
                        Emacs sessions.
Glenn Morris's avatar
Glenn Morris committed
30 31 32 33 34 35 36 37 38 39
@end menu

@node Hooks
@section Hooks
@cindex hooks

  A @dfn{hook} is a variable where you can store a function or functions
to be called on a particular occasion by an existing program.  Emacs
provides hooks for the sake of customization.  Most often, hooks are set
up in the init file (@pxref{Init File}), but Lisp programs can set them also.
Glenn Morris's avatar
Glenn Morris committed
40
@xref{Standard Hooks}, for a list of some standard hook variables.
Glenn Morris's avatar
Glenn Morris committed
41 42 43 44 45 46 47 48

@cindex normal hook
  Most of the hooks in Emacs are @dfn{normal hooks}.  These variables
contain lists of functions to be called with no arguments.  By
convention, whenever the hook name ends in @samp{-hook}, that tells
you it is normal.  We try to make all hooks normal, as much as
possible, so that you can use them in a uniform way.

49
  Every major mode command is supposed to run a normal hook called the
50 51 52 53 54 55 56 57 58 59
@dfn{mode hook} as one of the last steps of initialization.  This makes
it easy for a user to customize the behavior of the mode, by overriding
the buffer-local variable assignments already made by the mode.  Most
minor mode functions also run a mode hook at the end.  But hooks are
used in other contexts too.  For example, the hook @code{suspend-hook}
runs just before Emacs suspends itself (@pxref{Suspending Emacs}).

  The recommended way to add a hook function to a hook is by calling
@code{add-hook} (@pxref{Setting Hooks}).  The hook functions may be any
of the valid kinds of functions that @code{funcall} accepts (@pxref{What
Glenn Morris's avatar
Glenn Morris committed
60 61 62 63 64 65 66 67 68 69 70 71 72
Is a Function}).  Most normal hook variables are initially void;
@code{add-hook} knows how to deal with this.  You can add hooks either
globally or buffer-locally with @code{add-hook}.

@cindex abnormal hook
  If the hook variable's name does not end with @samp{-hook}, that
indicates it is probably an @dfn{abnormal hook}.  That means the hook
functions are called with arguments, or their return values are used
in some way.  The hook's documentation says how the functions are
called.  You can use @code{add-hook} to add a function to an abnormal
hook, but you must write the function to follow the hook's calling
convention.

Stefan Monnier's avatar
Stefan Monnier committed
73 74 75
  By convention, abnormal hook names end in @samp{-functions}.  If the
variable's name ends in @samp{-function}, then its value is just a single
function, not a list of functions.
Glenn Morris's avatar
Glenn Morris committed
76

77
@menu
78 79
* Running Hooks::    How to run a hook.
* Setting Hooks::    How to put functions on a hook, or remove them.
80
@end menu
Glenn Morris's avatar
Glenn Morris committed
81

82 83
@node Running Hooks
@subsection Running Hooks
Glenn Morris's avatar
Glenn Morris committed
84

85 86 87
  In this section, we document the @code{run-hooks} function, which is
used to run a normal hook.  We also document the functions for running
various kinds of abnormal hooks.
Glenn Morris's avatar
Glenn Morris committed
88 89 90 91 92 93 94 95 96 97 98 99 100 101

@defun run-hooks &rest hookvars
This function takes one or more normal hook variable names as
arguments, and runs each hook in turn.  Each argument should be a
symbol that is a normal hook variable.  These arguments are processed
in the order specified.

If a hook variable has a non-@code{nil} value, that value should be a
list of functions.  @code{run-hooks} calls all the functions, one by
one, with no arguments.

The hook variable's value can also be a single function---either a
lambda expression or a symbol with a function definition---which
@code{run-hooks} calls.  But this usage is obsolete.
102 103 104 105 106

If the hook variable is buffer-local, the buffer-local variable will
be used instead of the global variable.  However, if the buffer-local
variable contains the element @code{t}, the global hook variable will
be run as well.
Glenn Morris's avatar
Glenn Morris committed
107 108 109
@end defun

@defun run-hook-with-args hook &rest args
110 111
This function runs an abnormal hook by calling all the hook functions in
@var{hook}, passing each one the arguments @var{args}.
Glenn Morris's avatar
Glenn Morris committed
112 113 114
@end defun

@defun run-hook-with-args-until-failure hook &rest args
115 116 117 118 119
This function runs an abnormal hook by calling each hook function in
turn, stopping if one of them ``fails'' by returning @code{nil}.  Each
hook function is passed the arguments @var{args}.  If this function
stops because one of the hook functions fails, it returns @code{nil};
otherwise it returns a non-@code{nil} value.
Glenn Morris's avatar
Glenn Morris committed
120 121 122
@end defun

@defun run-hook-with-args-until-success hook &rest args
123 124 125 126 127 128
This function runs an abnormal hook by calling each hook function,
stopping if one of them ``succeeds'' by returning a non-@code{nil}
value.  Each hook function is passed the arguments @var{args}.  If this
function stops because one of the hook functions returns a
non-@code{nil} value, it returns that value; otherwise it returns
@code{nil}.
Glenn Morris's avatar
Glenn Morris committed
129 130
@end defun

131 132 133 134 135
@defmac with-wrapper-hook hook args &rest body
This macro runs the abnormal hook @code{hook} as a series of nested
``wrapper functions'' around the @var{body} forms.  The effect is
similar to nested @code{around} advices (@pxref{Around-Advice}).

136
Each hook function should accept an argument list consisting of a function
137
@var{fun}, followed by the additional arguments listed in @var{args}.
138 139 140
The first hook function is passed a function @var{fun} that, if it is
called with arguments @var{args}, performs @var{body} (i.e., the default
operation).  The @var{fun} passed to each successive hook function is
141 142 143 144 145
constructed from all the preceding hook functions (and @var{body}); if
this @var{fun} is called with arguments @var{args}, it does what the
@code{with-wrapper-hook} call would if the preceding hook functions were
the only ones in @var{hook}.

146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161
Each hook function may call its @var{fun} argument as many times as it
wishes, including never.  In that case, such a hook function acts to
replace the default definition altogether, and any preceding hook
functions.  Of course, a subsequent hook function may do the same thing.

Each hook function definition is used to construct the @var{fun} passed
to the next hook function in @var{hook}, if any.  The last or
``outermost'' @var{fun} is called once to produce the overall effect.

When might you want to use a wrapper hook?  The function
@code{filter-buffer-substring} illustrates a common case.  There is a
basic functionality, performed by @var{body}---in this case, to extract
a buffer-substring.  Then any number of hook functions can act in
sequence to modify that string, before returning the final result.
A wrapper-hook also allows for a hook function to completely replace the
default definition (by not calling @var{fun}).
162 163
@end defmac

164 165 166 167 168 169 170 171
@defun run-hook-wrapped hook wrap-function &rest args
This function is similar to @code{run-hook-with-args-until-success}.
Like that function, it runs the functions on the abnormal hook
@code{hook}, stopping at the first one that returns non-@code{nil}.
Instead of calling the hook functions directly, though, it actually
calls @code{wrap-function} with arguments @code{fun} and @code{args}.
@end defun

172 173 174 175 176 177 178
@node Setting Hooks
@subsection Setting Hooks

  Here's an example that uses a mode hook to turn on Auto Fill mode when
in Lisp Interaction mode:

@example
179
(add-hook 'lisp-interaction-mode-hook 'auto-fill-mode)
180 181
@end example

Glenn Morris's avatar
Glenn Morris committed
182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197
@defun add-hook hook function &optional append local
This function is the handy way to add function @var{function} to hook
variable @var{hook}.  You can use it for abnormal hooks as well as for
normal hooks.  @var{function} can be any Lisp function that can accept
the proper number of arguments for @var{hook}.  For example,

@example
(add-hook 'text-mode-hook 'my-text-hook-function)
@end example

@noindent
adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.

If @var{function} is already present in @var{hook} (comparing using
@code{equal}), then @code{add-hook} does not add it a second time.

198 199 200 201 202
If @var{function} has a non-@code{nil} property
@code{permanent-local-hook}, then @code{kill-all-local-variables} (or
changing major modes) won't delete it from the hook variable's local
value.

203 204 205 206 207 208 209
For a normal hook, hook functions should be designed so that the order
in which they are executed does not matter.  Any dependence on the order
is asking for trouble.  However, the order is predictable: normally,
@var{function} goes at the front of the hook list, so it is executed
first (barring another @code{add-hook} call).  If the optional argument
@var{append} is non-@code{nil}, the new hook function goes at the end of
the hook list and is executed last.
Glenn Morris's avatar
Glenn Morris committed
210 211 212 213 214

@code{add-hook} can handle the cases where @var{hook} is void or its
value is a single function; it sets or changes the value to a list of
functions.

215 216 217 218 219
If @var{local} is non-@code{nil}, that says to add @var{function} to the
buffer-local hook list instead of to the global hook list.  This makes
the hook buffer-local and adds @code{t} to the buffer-local value.  The
latter acts as a flag to run the hook functions in the default value as
well as in the local value.
Glenn Morris's avatar
Glenn Morris committed
220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235
@end defun

@defun remove-hook hook function &optional local
This function removes @var{function} from the hook variable
@var{hook}.  It compares @var{function} with elements of @var{hook}
using @code{equal}, so it works for both symbols and lambda
expressions.

If @var{local} is non-@code{nil}, that says to remove @var{function}
from the buffer-local hook list instead of from the global hook list.
@end defun

@node Major Modes
@section Major Modes
@cindex major mode

236
@cindex major mode command
Glenn Morris's avatar
Glenn Morris committed
237
  Major modes specialize Emacs for editing particular kinds of text.
238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266
Each buffer has one major mode at a time.  Every major mode is
associated with a @dfn{major mode command}, whose name should end in
@samp{-mode}.  This command takes care of switching to that mode in the
current buffer, by setting various buffer-local variables such as a
local keymap.  @xref{Major Mode Conventions}.

  The least specialized major mode is called @dfn{Fundamental mode},
which has no mode-specific definitions or variable settings.

@deffn Command fundamental-mode
This is the major mode command for Fundamental mode.  Unlike other mode
commands, it does @emph{not} run any mode hooks (@pxref{Major Mode
Conventions}), since you are not supposed to customize this mode.
@end deffn

  The easiest way to write a major mode is to use the macro
@code{define-derived-mode}, which sets up the new mode as a variant of
an existing major mode.  @xref{Derived Modes}.  We recommend using
@code{define-derived-mode} even if the new mode is not an obvious
derivative of another mode, as it automatically enforces many coding
conventions for you.  @xref{Basic Major Modes}, for common modes to
derive from.

  The standard GNU Emacs Lisp directory tree contains the code for
several major modes, in files such as @file{text-mode.el},
@file{texinfo.el}, @file{lisp-mode.el}, and @file{rmail.el}.  You can
study these libraries to see how modes are written.

@defopt major-mode
267 268 269
The buffer-local value of this variable holds the symbol for the current
major mode.  Its default value holds the default major mode for new
buffers.  The standard default value is @code{fundamental-mode}.
270 271 272 273 274 275 276 277

If the default value is @code{nil}, then whenever Emacs creates a new
buffer via a command such as @kbd{C-x b} (@code{switch-to-buffer}), the
new buffer is put in the major mode of the previously current buffer.
As an exception, if the major mode of the previous buffer has a
@code{mode-class} symbol property with value @code{special}, the new
buffer is put in Fundamental mode (@pxref{Major Mode Conventions}).
@end defopt
Glenn Morris's avatar
Glenn Morris committed
278 279

@menu
280 281 282 283
* Major Mode Conventions::  Coding conventions for keymaps, etc.
* Auto Major Mode::         How Emacs chooses the major mode automatically.
* Mode Help::               Finding out how to use a mode.
* Derived Modes::           Defining a new major mode based on another major
Glenn Morris's avatar
Glenn Morris committed
284
                              mode.
285
* Basic Major Modes::       Modes that other modes are often derived from.
Glenn Morris's avatar
Glenn Morris committed
286
* Mode Hooks::              Hooks run at the end of major mode functions.
287
* Tabulated List Mode::     Parent mode for buffers containing tabulated data.
288
* Generic Modes::           Defining a simple major mode that supports
Glenn Morris's avatar
Glenn Morris committed
289
                              comment syntax and Font Lock mode.
290
* Example Major Modes::     Text mode and Lisp modes.
Glenn Morris's avatar
Glenn Morris committed
291 292 293 294 295 296 297
@end menu

@node Major Mode Conventions
@subsection Major Mode Conventions
@cindex major mode conventions
@cindex conventions for writing major modes

298 299 300 301 302 303
  The code for every major mode should follow various coding
conventions, including conventions for local keymap and syntax table
initialization, function and variable names, and hooks.

  If you use the @code{define-derived-mode} macro, it will take care of
many of these conventions automatically.  @xref{Derived Modes}.  Note
304 305
also that Fundamental mode is an exception to many of these conventions,
because it represents the default state of Emacs.
Glenn Morris's avatar
Glenn Morris committed
306

307 308 309
  The following list of conventions is only partial.  Each major mode
should aim for consistency in general with other Emacs major modes, as
this makes Emacs as a whole more coherent.  It is impossible to list
Glenn Morris's avatar
Glenn Morris committed
310 311 312 313 314 315
here all the possible points where this issue might come up; if the
Emacs developers point out an area where your major mode deviates from
the usual conventions, please make it compatible.

@itemize @bullet
@item
316 317 318 319 320
Define a major mode command whose name ends in @samp{-mode}.  When
called with no arguments, this command should switch to the new mode in
the current buffer by setting up the keymap, syntax table, and
buffer-local variables in an existing buffer.  It should not change the
buffer's contents.
Glenn Morris's avatar
Glenn Morris committed
321 322

@item
323 324
Write a documentation string for this command that describes the special
commands available in this mode.  @xref{Mode Help}.
Glenn Morris's avatar
Glenn Morris committed
325 326 327

The documentation string may include the special documentation
substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
328
@samp{\<@var{keymap}>}, which allow the help display to adapt
Glenn Morris's avatar
Glenn Morris committed
329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345
automatically to the user's own key bindings.  @xref{Keys in
Documentation}.

@item
The major mode command should start by calling
@code{kill-all-local-variables}.  This runs the normal hook
@code{change-major-mode-hook}, then gets rid of the buffer-local
variables of the major mode previously in effect.  @xref{Creating
Buffer-Local}.

@item
The major mode command should set the variable @code{major-mode} to the
major mode command symbol.  This is how @code{describe-mode} discovers
which documentation to print.

@item
The major mode command should set the variable @code{mode-name} to the
346 347 348
``pretty'' name of the mode, usually a string (but see @ref{Mode Line
Data}, for other possible forms).  The name of the mode appears
in the mode line.
Glenn Morris's avatar
Glenn Morris committed
349 350 351 352 353 354 355 356 357 358 359 360 361

@item
@cindex functions in modes
Since all global names are in the same name space, all the global
variables, constants, and functions that are part of the mode should
have names that start with the major mode name (or with an abbreviation
of it if the name is long).  @xref{Coding Conventions}.

@item
In a major mode for editing some kind of structured text, such as a
programming language, indentation of text according to structure is
probably useful.  So the mode should set @code{indent-line-function}
to a suitable function, and probably customize other variables
362
for indentation.  @xref{Auto-Indentation}.
Glenn Morris's avatar
Glenn Morris committed
363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386

@item
@cindex keymaps in modes
The major mode should usually have its own keymap, which is used as the
local keymap in all buffers in that mode.  The major mode command should
call @code{use-local-map} to install this local map.  @xref{Active
Keymaps}, for more information.

This keymap should be stored permanently in a global variable named
@code{@var{modename}-mode-map}.  Normally the library that defines the
mode sets this variable.

@xref{Tips for Defining}, for advice about how to write the code to set
up the mode's keymap variable.

@item
The key sequences bound in a major mode keymap should usually start with
@kbd{C-c}, followed by a control character, a digit, or @kbd{@{},
@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}.  The other punctuation
characters are reserved for minor modes, and ordinary letters are
reserved for users.

A major mode can also rebind the keys @kbd{M-n}, @kbd{M-p} and
@kbd{M-s}.  The bindings for @kbd{M-n} and @kbd{M-p} should normally
387
be some kind of ``moving forward and backward'', but this does not
Glenn Morris's avatar
Glenn Morris committed
388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404
necessarily mean cursor motion.

It is legitimate for a major mode to rebind a standard key sequence if
it provides a command that does ``the same job'' in a way better
suited to the text this mode is used for.  For example, a major mode
for editing a programming language might redefine @kbd{C-M-a} to
``move to the beginning of a function'' in a way that works better for
that language.

It is also legitimate for a major mode to rebind a standard key
sequence whose standard meaning is rarely useful in that mode.  For
instance, minibuffer modes rebind @kbd{M-r}, whose standard meaning is
rarely of any use in the minibuffer.  Major modes such as Dired or
Rmail that do not allow self-insertion of text can reasonably redefine
letters and other printing characters as special commands.

@item
Juanma Barranquero's avatar
Juanma Barranquero committed
405
Major modes for editing text should not define @key{RET} to do
Glenn Morris's avatar
Glenn Morris committed
406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443
anything other than insert a newline.  However, it is ok for
specialized modes for text that users don't directly edit, such as
Dired and Info modes, to redefine @key{RET} to do something entirely
different.

@item
Major modes should not alter options that are primarily a matter of user
preference, such as whether Auto-Fill mode is enabled.  Leave this to
each user to decide.  However, a major mode should customize other
variables so that Auto-Fill mode will work usefully @emph{if} the user
decides to use it.

@item
@cindex syntax tables in modes
The mode may have its own syntax table or may share one with other
related modes.  If it has its own syntax table, it should store this in
a variable named @code{@var{modename}-mode-syntax-table}.  @xref{Syntax
Tables}.

@item
If the mode handles a language that has a syntax for comments, it should
set the variables that define the comment syntax.  @xref{Options for
Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}.

@item
@cindex abbrev tables in modes
The mode may have its own abbrev table or may share one with other
related modes.  If it has its own abbrev table, it should store this
in a variable named @code{@var{modename}-mode-abbrev-table}.  If the
major mode command defines any abbrevs itself, it should pass @code{t}
for the @var{system-flag} argument to @code{define-abbrev}.
@xref{Defining Abbrevs}.

@item
The mode should specify how to do highlighting for Font Lock mode, by
setting up a buffer-local value for the variable
@code{font-lock-defaults} (@pxref{Font Lock Mode}).

444 445
@item
Each face that the mode defines should, if possible, inherit from an
446
existing Emacs face.  @xref{Basic Faces}, and @ref{Faces for Font Lock}.
447

Glenn Morris's avatar
Glenn Morris committed
448 449 450 451 452 453 454 455 456 457 458 459 460
@item
The mode should specify how Imenu should find the definitions or
sections of a buffer, by setting up a buffer-local value for the
variable @code{imenu-generic-expression}, for the two variables
@code{imenu-prev-index-position-function} and
@code{imenu-extract-index-name-function}, or for the variable
@code{imenu-create-index-function} (@pxref{Imenu}).

@item
The mode can specify a local value for
@code{eldoc-documentation-function} to tell ElDoc mode how to handle
this mode.

461
@item
462 463 464
The mode can specify how to complete various keywords by adding one or
more buffer-local entries to the special hook
@code{completion-at-point-functions}.  @xref{Completion in Buffers}.
465

Glenn Morris's avatar
Glenn Morris committed
466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484
@item
@cindex buffer-local variables in modes
To make a buffer-local binding for an Emacs customization variable, use
@code{make-local-variable} in the major mode command, not
@code{make-variable-buffer-local}.  The latter function would make the
variable local to every buffer in which it is subsequently set, which
would affect buffers that do not use this mode.  It is undesirable for a
mode to have such global effects.  @xref{Buffer-Local Variables}.

With rare exceptions, the only reasonable way to use
@code{make-variable-buffer-local} in a Lisp package is for a variable
which is used only within that package.  Using it on a variable used by
other packages would interfere with them.

@item
@cindex mode hook
@cindex major mode hook
Each major mode should have a normal @dfn{mode hook} named
@code{@var{modename}-mode-hook}.  The very last thing the major mode command
485 486 487
should do is to call @code{run-mode-hooks}.  This runs the normal
hook @code{change-major-mode-after-body-hook}, the mode hook,
and then the normal hook @code{after-change-major-mode-hook}.
Glenn Morris's avatar
Glenn Morris committed
488 489 490 491 492 493
@xref{Mode Hooks}.

@item
The major mode command may start by calling some other major mode
command (called the @dfn{parent mode}) and then alter some of its
settings.  A mode that does this is called a @dfn{derived mode}.  The
494 495 496
recommended way to define one is to use the @code{define-derived-mode}
macro, but this is not required.  Such a mode should call the parent
mode command inside a @code{delay-mode-hooks} form.  (Using
Glenn Morris's avatar
Glenn Morris committed
497 498 499 500 501 502 503 504 505
@code{define-derived-mode} does this automatically.)  @xref{Derived
Modes}, and @ref{Mode Hooks}.

@item
If something special should be done if the user switches a buffer from
this mode to any other major mode, this mode can set up a buffer-local
value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}).

@item
506 507 508 509 510
If this mode is appropriate only for specially-prepared text produced by
the mode itself (rather than by the user typing at the keyboard or by an
external file), then the major mode command symbol should have a
property named @code{mode-class} with value @code{special}, put on as
follows:
Glenn Morris's avatar
Glenn Morris committed
511 512

@kindex mode-class @r{(property)}
513
@cindex @code{special} modes
Glenn Morris's avatar
Glenn Morris committed
514 515 516 517 518
@example
(put 'funny-mode 'mode-class 'special)
@end example

@noindent
519 520 521 522 523 524 525
This tells Emacs that new buffers created while the current buffer is in
Funny mode should not be put in Funny mode, even though the default
value of @code{major-mode} is @code{nil}.  By default, the value of
@code{nil} for @code{major-mode} means to use the current buffer's major
mode when creating new buffers (@pxref{Auto Major Mode}), but with such
@code{special} modes, Fundamental mode is used instead.  Modes such as
Dired, Rmail, and Buffer List use this feature.
Glenn Morris's avatar
Glenn Morris committed
526

527 528 529 530
The function @code{view-buffer} does not enable View mode in buffers
whose mode-class is special, because such modes usually provide their
own View-like bindings.

531
The @code{define-derived-mode} macro automatically marks the derived
532 533 534
mode as special if the parent mode is special.  Special mode is a
convenient parent for such modes to inherit from; @xref{Basic Major
Modes}.
535

Glenn Morris's avatar
Glenn Morris committed
536 537 538 539 540 541 542 543 544 545 546 547 548 549 550
@item
If you want to make the new mode the default for files with certain
recognizable names, add an element to @code{auto-mode-alist} to select
the mode for those file names (@pxref{Auto Major Mode}).  If you
define the mode command to autoload, you should add this element in
the same file that calls @code{autoload}.  If you use an autoload
cookie for the mode command, you can also use an autoload cookie for
the form that adds the element (@pxref{autoload cookie}).  If you do
not autoload the mode command, it is sufficient to add the element in
the file that contains the mode definition.

@item
@cindex mode loading
The top-level forms in the file defining the mode should be written so
that they may be evaluated more than once without adverse consequences.
551 552 553 554
For instance, use @code{defvar} or @code{defcustom} to set mode-related
variables, so that they are not reinitialized if they already have a
value (@pxref{Defining Variables}).

Glenn Morris's avatar
Glenn Morris committed
555 556 557 558 559 560
@end itemize

@node Auto Major Mode
@subsection How Emacs Chooses a Major Mode
@cindex major mode, automatic selection

561 562 563
  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.
Glenn Morris's avatar
Glenn Morris committed
564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583

@deffn Command normal-mode &optional find-file
This function establishes the proper major mode and buffer-local variable
bindings for the current buffer.  First it calls @code{set-auto-mode}
(see below), then it runs @code{hack-local-variables} to parse, and
bind or evaluate as appropriate, the file's local variables
(@pxref{File Local Variables}).

If the @var{find-file} argument to @code{normal-mode} is non-@code{nil},
@code{normal-mode} assumes that the @code{find-file} function is calling
it.  In this case, it may process local variables in the @samp{-*-}
line or at the end of the file.  The variable
@code{enable-local-variables} controls whether to do so.  @xref{File
Variables, , Local Variables in Files, emacs, The GNU Emacs Manual},
for the syntax of the local variables section of a file.

If you run @code{normal-mode} interactively, the argument
@var{find-file} is normally @code{nil}.  In this case,
@code{normal-mode} unconditionally processes any file local variables.

584
The function calls @code{set-auto-mode} to choose a major mode.  If this
585 586
does not specify a mode, the buffer stays in the major mode determined
by the default value of @code{major-mode} (see below).
Glenn Morris's avatar
Glenn Morris committed
587 588 589

@cindex file mode specification error
@code{normal-mode} uses @code{condition-case} around the call to the
590 591
major mode command, so errors are caught and reported as a @samp{File
mode specification error}, followed by the original error message.
Glenn Morris's avatar
Glenn Morris committed
592 593 594 595 596
@end deffn

@defun set-auto-mode &optional keep-mode-if-same
@cindex visited file mode
  This function selects the major mode that is appropriate for the
597 598 599 600 601 602 603 604 605
current buffer.  It bases its decision (in order of precedence) on the
@w{@samp{-*-}} line, on any @samp{mode:} local variable near the end of
a file, on the @w{@samp{#!}} line (using @code{interpreter-mode-alist}),
on the text at the beginning of the buffer (using
@code{magic-mode-alist}), and finally on the visited file name (using
@code{auto-mode-alist}).  @xref{Choosing Modes, , How Major Modes are
Chosen, emacs, The GNU Emacs Manual}.  If @code{enable-local-variables}
is @code{nil}, @code{set-auto-mode} does not check the @w{@samp{-*-}}
line, or near the end of the file, for any mode tag.
Glenn Morris's avatar
Glenn Morris committed
606

607 608 609 610 611 612 613 614 615 616 617 618
@vindex inhibit-local-variables-regexps
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 @w{@samp{-*-}} pattern.  For these reasons, both these file
extensions are members of the list @var{inhibit-local-variables-regexps}.
Add patterns to this list to prevent Emacs searching them for local
variables of any kind (not just mode specifiers).

Glenn Morris's avatar
Glenn Morris committed
619 620 621 622 623 624 625 626
If @var{keep-mode-if-same} is non-@code{nil}, 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} sets this to
@code{t} to avoid killing buffer local variables that the user may
have set.
@end defun

@defun set-buffer-major-mode buffer
627 628
This function sets the major mode of @var{buffer} to the default value of
@code{major-mode}; if that is @code{nil}, it uses the
Glenn Morris's avatar
Glenn Morris committed
629
current buffer's major mode (if that is suitable).  As an exception,
630
if @var{buffer}'s name is @file{*scratch*}, it sets the mode to
Glenn Morris's avatar
Glenn Morris committed
631 632 633 634 635 636 637 638
@code{initial-major-mode}.

The low-level primitives for creating buffers do not use this function,
but medium-level commands such as @code{switch-to-buffer} and
@code{find-file-noselect} use it whenever they create buffers.
@end defun

@defopt initial-major-mode
639
@cindex @file{*scratch*}
Glenn Morris's avatar
Glenn Morris committed
640
The value of this variable determines the major mode of the initial
641
@file{*scratch*} buffer.  The value should be a symbol that is a major
Glenn Morris's avatar
Glenn Morris committed
642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717
mode command.  The default value is @code{lisp-interaction-mode}.
@end defopt

@defvar interpreter-mode-alist
This variable specifies major modes to use for scripts that specify a
command interpreter in a @samp{#!} line.  Its value is an alist with
elements of the form @code{(@var{interpreter} . @var{mode})}; for
example, @code{("perl" . perl-mode)} is one element present by
default.  The element says to use mode @var{mode} if the file
specifies an interpreter which matches @var{interpreter}.
@end defvar

@defvar magic-mode-alist
This variable's value is an alist with elements of the form
@code{(@var{regexp} .  @var{function})}, where @var{regexp} is a
regular expression and @var{function} is a function or @code{nil}.
After visiting a file, @code{set-auto-mode} calls @var{function} if
the text at the beginning of the buffer matches @var{regexp} and
@var{function} is non-@code{nil}; if @var{function} is @code{nil},
@code{auto-mode-alist} gets to decide the mode.
@end defvar

@defvar magic-fallback-mode-alist
This works like @code{magic-mode-alist}, except that it is handled
only if @code{auto-mode-alist} does not specify a mode for this file.
@end defvar

@defvar auto-mode-alist
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} and
@samp{.c}, but this need not be the case.  An ordinary element of the
alist looks like @code{(@var{regexp} .  @var{mode-function})}.

For example,

@smallexample
@group
(("\\`/tmp/fol/" . text-mode)
 ("\\.texinfo\\'" . texinfo-mode)
 ("\\.texi\\'" . texinfo-mode)
@end group
@group
 ("\\.el\\'" . emacs-lisp-mode)
 ("\\.c\\'" . c-mode)
 ("\\.h\\'" . c-mode)
 @dots{})
@end group
@end smallexample

When you visit a file whose expanded file name (@pxref{File Name
Expansion}), with version numbers and backup suffixes removed using
@code{file-name-sans-versions} (@pxref{File Name Components}), matches
a @var{regexp}, @code{set-auto-mode} calls the corresponding
@var{mode-function}.  This feature enables Emacs to select the proper
major mode for most files.

If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
@var{function} t)}, then after calling @var{function}, Emacs searches
@code{auto-mode-alist} 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} t)} can uncompress the file and then put the uncompressed
file in the proper mode according to the name sans @samp{.gz}.

Here is an example of how to prepend several pattern pairs to
@code{auto-mode-alist}.  (You might use this sort of expression in your
init file.)

@smallexample
@group
(setq auto-mode-alist
  (append
   ;; @r{File name (within directory) starts with a dot.}
   '(("/\\.[^/]*\\'" . fundamental-mode)
     ;; @r{File name has no dot.}
Chong Yidong's avatar
Chong Yidong committed
718
     ("/[^\\./]*\\'" . fundamental-mode)
Glenn Morris's avatar
Glenn Morris committed
719 720 721 722 723 724 725 726 727 728 729 730 731
     ;; @r{File name ends in @samp{.C}.}
     ("\\.C\\'" . c++-mode))
   auto-mode-alist))
@end group
@end smallexample
@end defvar

@node Mode Help
@subsection Getting Help about a Major Mode
@cindex mode help
@cindex help for major mode
@cindex documentation for major mode

Juri Linkov's avatar
Juri Linkov committed
732
  The @code{describe-mode} function provides information about major
733
modes.  It is normally bound to @kbd{C-h m}.  It uses the value of the
734 735
variable @code{major-mode} (@pxref{Major Modes}), which is why every
major mode command needs to set that variable.
Glenn Morris's avatar
Glenn Morris committed
736

Chong Yidong's avatar
Chong Yidong committed
737 738 739 740 741 742 743 744 745
@deffn Command describe-mode &optional buffer
This command displays the documentation of the current buffer's major
mode and minor modes.  It uses the @code{documentation} function to
retrieve the documentation strings of the major and minor mode
commands (@pxref{Accessing Documentation}).

If called from Lisp with a non-nil @var{buffer} argument, this
function displays the documentation for that buffer's major and minor
modes, rather than those of the current buffer.
Glenn Morris's avatar
Glenn Morris committed
746 747 748 749 750 751
@end deffn

@node Derived Modes
@subsection Defining Derived Modes
@cindex derived mode

752 753 754 755 756 757
  The recommended way to define a new major mode is to derive it from an
existing one using @code{define-derived-mode}.  If there is no closely
related mode, you should inherit from either @code{text-mode},
@code{special-mode}, or @code{prog-mode}.  @xref{Basic Major Modes}.  If
none of these are suitable, you can inherit from @code{fundamental-mode}
(@pxref{Major Modes}).
Glenn Morris's avatar
Glenn Morris committed
758 759

@defmac define-derived-mode variant parent name docstring keyword-args@dots{} body@dots{}
760
This macro defines @var{variant} as a major mode command, using
Glenn Morris's avatar
Glenn Morris committed
761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797
@var{name} as the string form of the mode name.  @var{variant} and
@var{parent} should be unquoted symbols.

The new command @var{variant} is defined to call the function
@var{parent}, then override certain aspects of that parent mode:

@itemize @bullet
@item
The new mode has its own sparse keymap, named
@code{@var{variant}-map}.  @code{define-derived-mode}
makes the parent mode's keymap the parent of the new map, unless
@code{@var{variant}-map} is already set and already has a parent.

@item
The new mode has its own syntax table, kept in the variable
@code{@var{variant}-syntax-table}, unless you override this using the
@code{:syntax-table} keyword (see below).  @code{define-derived-mode}
makes the parent mode's syntax-table the parent of
@code{@var{variant}-syntax-table}, unless the latter is already set
and already has a parent different from the standard syntax table.

@item
The new mode has its own abbrev table, kept in the variable
@code{@var{variant}-abbrev-table}, unless you override this using the
@code{:abbrev-table} keyword (see below).

@item
The new mode has its own mode hook, @code{@var{variant}-hook}.  It
runs this hook, after running the hooks of its ancestor modes, with
@code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}.
@end itemize

In addition, you can specify how to override other aspects of
@var{parent} with @var{body}.  The command @var{variant}
evaluates the forms in @var{body} after setting up all its usual
overrides, just before running the mode hooks.

798 799 800 801 802 803
If @var{parent} has a non-@code{nil} @code{mode-class} symbol
property, then @code{define-derived-mode} sets the @code{mode-class}
property of @var{variant} to the same value.  This ensures, for
example, that if @var{parent} is a special mode, then @var{variant} is
also a special mode (@pxref{Major Mode Conventions}).

Glenn Morris's avatar
Glenn Morris committed
804 805 806 807
You can also specify @code{nil} for @var{parent}.  This gives the new
mode no parent.  Then @code{define-derived-mode} behaves as described
above, but, of course, omits all actions connected with @var{parent}.

808 809 810 811
The argument @var{docstring} specifies the documentation string for the
new mode.  @code{define-derived-mode} adds some general information
about the mode's hook, followed by the mode's keymap, at the end of this
documentation string.  If you omit @var{docstring},
Glenn Morris's avatar
Glenn Morris committed
812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857
@code{define-derived-mode} generates a documentation string.

The @var{keyword-args} are pairs of keywords and values.  The values
are evaluated.  The following keywords are currently supported:

@table @code
@item :syntax-table
You can use this to explicitly specify a syntax table for the new
mode.  If you specify a @code{nil} value, the new mode uses the same
syntax table as @var{parent}, or the standard syntax table if
@var{parent} is @code{nil}.  (Note that this does @emph{not} follow
the convention used for non-keyword arguments that a @code{nil} value
is equivalent with not specifying the argument.)

@item :abbrev-table
You can use this to explicitly specify an abbrev table for the new
mode.  If you specify a @code{nil} value, the new mode uses the same
abbrev table as @var{parent}, or @code{fundamental-mode-abbrev-table}
if @var{parent} is @code{nil}.  (Again, a @code{nil} value is
@emph{not} equivalent to not specifying this keyword.)

@item :group
If this is specified, the value should be the customization group for
this mode.  (Not all major modes have one.)  Only the (still
experimental and unadvertised) command @code{customize-mode} currently
uses this.  @code{define-derived-mode} does @emph{not} automatically
define the specified customization group.
@end table

Here is a hypothetical example:

@example
(define-derived-mode hypertext-mode
  text-mode "Hypertext"
  "Major mode for hypertext.
\\@{hypertext-mode-map@}"
  (setq case-fold-search nil))

(define-key hypertext-mode-map
  [down-mouse-3] 'do-hyper-link)
@end example

Do not write an @code{interactive} spec in the definition;
@code{define-derived-mode} does that automatically.
@end defmac

858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901
@defun derived-mode-p &rest modes
This function returns non-@code{nil} if the current major mode is
derived from any of the major modes given by the symbols @var{modes}.
@end defun

@node Basic Major Modes
@subsection Basic Major Modes

  Apart from Fundamental mode, there are three major modes that other
major modes commonly derive from: Text mode, Prog mode, and Special
mode.  While Text mode is useful in its own right (e.g. for editing
files ending in @file{.txt}), Prog mode and Special mode exist mainly to
let other modes derive from them.

@vindex prog-mode-hook
  As far as possible, new major modes should be derived, either directly
or indirectly, from one of these three modes.  One reason is that this
allows users to customize a single mode hook
(e.g. @code{prog-mode-hook}) for an entire family of relevant modes
(e.g. all programming language modes).

@deffn Command text-mode
Text mode is a major mode for editing human languages.  It defines the
@samp{"} and @samp{\} characters as having punctuation syntax
(@pxref{Syntax Class Table}), and binds @kbd{M-@key{TAB}} to
@code{ispell-complete-word} (@pxref{Spelling,,, emacs, The GNU Emacs
Manual}).

An example of a major mode derived from Text mode is HTML mode.
@xref{HTML Mode,,SGML and HTML Modes, emacs, The GNU Emacs Manual}.
@end deffn

@deffn Command prog-mode
Prog mode is a basic major mode for buffers containing programming
language source code.  Most of the programming language major modes
built into Emacs are derived from it.

Prog mode binds @code{parse-sexp-ignore-comments} to @code{t}
(@pxref{Motion via Parsing}) and @code{bidi-paragraph-direction} to
@code{left-to-right} (@pxref{Bidirectional Display}).
@end deffn

@deffn Command special-mode
Special mode is a basic major mode for buffers containing text that is
902 903 904
produced specially by Emacs, rather than directly from a file.  Major
modes derived from Special mode are given a @code{mode-class} property
of @code{special} (@pxref{Major Mode Conventions}).
905 906 907 908 909 910 911

Special mode sets the buffer to read-only.  Its keymap defines several
common bindings, including @kbd{q} for @code{quit-window}, @kbd{z} for
@code{kill-this-buffer}, and @kbd{g} for @code{revert-buffer}
(@pxref{Reverting}).

An example of a major mode derived from Special mode is Buffer Menu
912
mode, which is used by the @file{*Buffer List*} buffer.  @xref{List
913 914 915
Buffers,,Listing Existing Buffers, emacs, The GNU Emacs Manual}.
@end deffn

916 917 918
  In addition, modes for buffers of tabulated data can inherit from
Tabulated List mode, which is in turn derived from Special mode.
@xref{Tabulated List Mode}.
Glenn Morris's avatar
Glenn Morris committed
919 920 921 922

@node Mode Hooks
@subsection Mode Hooks

923 924 925
  Every major mode command should finish by running the mode-independent
normal hook @code{change-major-mode-after-body-hook}, its mode hook,
and the normal hook @code{after-change-major-mode-hook}.
Glenn Morris's avatar
Glenn Morris committed
926 927 928 929 930 931 932 933
It does this by calling @code{run-mode-hooks}.  If the major mode is a
derived mode, that is if it calls another major mode (the parent mode)
in its body, it should do this inside @code{delay-mode-hooks} so that
the parent won't run these hooks itself.  Instead, the derived mode's
call to @code{run-mode-hooks} runs the parent's mode hook too.
@xref{Major Mode Conventions}.

  Emacs versions before Emacs 22 did not have @code{delay-mode-hooks}.
934 935 936 937 938 939
Versions before 24 did not have @code{change-major-mode-after-body-hook}.
When user-implemented major modes do not use @code{run-mode-hooks} and
have not been updated to use these newer features, they won't entirely
follow these conventions: they may run the parent's mode hook too early,
or fail to run @code{after-change-major-mode-hook}.  If you encounter
such a major mode, please correct it to follow these conventions.
Glenn Morris's avatar
Glenn Morris committed
940 941 942

  When you defined a major mode using @code{define-derived-mode}, it
automatically makes sure these conventions are followed.  If you
943
define a major mode ``by hand'', not using @code{define-derived-mode},
Glenn Morris's avatar
Glenn Morris committed
944 945 946 947 948
use the following functions to handle these conventions automatically.

@defun run-mode-hooks &rest hookvars
Major modes should run their mode hook using this function.  It is
similar to @code{run-hooks} (@pxref{Hooks}), but it also runs
949
@code{change-major-mode-after-body-hook} and
Glenn Morris's avatar
Glenn Morris committed
950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968
@code{after-change-major-mode-hook}.

When this function is called during the execution of a
@code{delay-mode-hooks} form, it does not run the hooks immediately.
Instead, it arranges for the next call to @code{run-mode-hooks} to run
them.
@end defun

@defmac delay-mode-hooks body@dots{}
When one major mode command calls another, it should do so inside of
@code{delay-mode-hooks}.

This macro executes @var{body}, but tells all @code{run-mode-hooks}
calls during the execution of @var{body} to delay running their hooks.
The hooks will actually run during the next call to
@code{run-mode-hooks} after the end of the @code{delay-mode-hooks}
construct.
@end defmac

969 970 971 972 973
@defvar change-major-mode-after-body-hook
This is a normal hook run by @code{run-mode-hooks}.  It is run before
the mode hooks.
@end defvar

Glenn Morris's avatar
Glenn Morris committed
974 975
@defvar after-change-major-mode-hook
This is a normal hook run by @code{run-mode-hooks}.  It is run at the
976
very end of every properly-written major mode command.
Glenn Morris's avatar
Glenn Morris committed
977
@end defvar
978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126

@node Tabulated List Mode
@subsection Tabulated List mode
@cindex Tabulated List mode

  Tabulated List mode is a major mode for displaying tabulated data,
i.e.@: data consisting of @dfn{entries}, each entry occupying one row of
text with its contents divided into columns.  Tabulated List mode
provides facilities for pretty-printing rows and columns, and sorting
the rows according to the values in each column.  It is derived from
Special mode (@pxref{Basic Major Modes}).

  Tabulated List mode is intended to be used as a parent mode by a more
specialized major mode.  Examples include Process Menu mode
(@pxref{Process Information}) and Package Menu mode (@pxref{Package
Menu,,, emacs, The GNU Emacs Manual}).

@findex tabulated-list-mode
  Such a derived mode should use @code{define-derived-mode} in the usual
way, specifying @code{tabulated-list-mode} as the second argument
(@pxref{Derived Modes}).  The body of the @code{define-derived-mode}
form should specify the format of the tabulated data, by assigning
values to the variables documented below; then, it should call the
function @code{tabulated-list-init-header} to initialize the header
line.

  The derived mode should also define a @dfn{listing command}.  This,
not the mode command, is what the user calls (e.g.@: @kbd{M-x
list-processes}).  The listing command should create or switch to a
buffer, turn on the derived mode, specify the tabulated data, and
finally call @code{tabulated-list-print} to populate the buffer.

@defvar tabulated-list-format
This buffer-local variable specifies the format of the Tabulated List
data.  Its value should be a vector.  Each element of the vector
represents a data column, and should be a list @code{(@var{name}
@var{width} @var{sort})}, where

@itemize
@item
@var{name} is the column's name (a string).

@item
@var{width} is the width to reserve for the column (an integer).  This
is meaningless for the last column, which runs to the end of each line.

@item
@var{sort} specifies how to sort entries by the column.  If @code{nil},
the column cannot be used for sorting.  If @code{t}, the column is
sorted by comparing string values.  Otherwise, this should be a
predicate function for @code{sort} (@pxref{Rearrangement}), which
accepts two arguments with the same form as the elements of
@code{tabulated-list-entries} (see below).
@end itemize
@end defvar

@defvar tabulated-list-entries
This buffer-local variable specifies the entries displayed in the
Tabulated List buffer.  Its value should be either a list, or a
function.

If the value is a list, each list element corresponds to one entry, and
should have the form @w{@code{(@var{id} @var{contents})}}, where

@itemize
@item
@var{id} is either @code{nil}, or a Lisp object that identifies the
entry.  If the latter, the cursor stays on the ``same'' entry when
re-sorting entries.  Comparison is done with @code{equal}.

@item
@var{contents} is a vector with the same number of elements as
@code{tabulated-list-format}.  Each vector element is either a string,
which is inserted into the buffer as-is, or a list @code{(@var{label}
. @var{properties})}, which means to insert a text button by calling
@code{insert-text-button} with @var{label} and @var{properties} as
arguments (@pxref{Making Buttons}).

There should be no newlines in any of these strings.
@end itemize

Otherwise, the value should be a function which returns a list of the
above form when called with no arguments.
@end defvar

@defvar tabulated-list-revert-hook
This normal hook is run prior to reverting a Tabulated List buffer.  A
derived mode can add a function to this hook to recompute
@code{tabulated-list-entries}.
@end defvar

@defvar tabulated-list-printer
The value of this variable is the function called to insert an entry at
point, including its terminating newline.  The function should accept
two arguments, @var{id} and @var{contents}, having the same meanings as
in @code{tabulated-list-entries}.  The default value is a function which
inserts an entry in a straightforward way; a mode which uses Tabulated
List mode in a more complex way can specify another function.
@end defvar

@defvar tabulated-list-sort-key
The value of this variable specifies the current sort key for the
Tabulated List buffer.  If it is @code{nil}, no sorting is done.
Otherwise, it should have the form @code{(@var{name} . @var{flip})},
where @var{name} is a string matching one of the column names in
@code{tabulated-list-format}, and @var{flip}, if non-@code{nil}, means
to invert the sort order.
@end defvar

@defun tabulated-list-init-header
This function computes and sets @code{header-line-format} for the
Tabulated List buffer (@pxref{Header Lines}), and assigns a keymap to
the header line to allow sort entries by clicking on column headers.

Modes derived from Tabulated List mode should call this after setting
the above variables (in particular, only after setting
@code{tabulated-list-format}).
@end defun

@defun tabulated-list-print &optional remember-pos
This function populates the current buffer with entries.  It should be
called by the listing command.  It erases the buffer, sorts the entries
specified by @code{tabulated-list-entries} according to
@code{tabulated-list-sort-key}, then calls the function specified by
@code{tabulated-list-printer} to insert each entry.

If the optional argument @var{remember-pos} is non-@code{nil}, this
function looks for the @var{id} element on the current line, if any, and
tries to move to that entry after all the entries are (re)inserted.
@end defun

@node Generic Modes
@subsection Generic Modes
@cindex generic mode

  @dfn{Generic modes} are simple major modes with basic support for
comment syntax and Font Lock mode.  To define a generic mode, use the
macro @code{define-generic-mode}.  See the file @file{generic-x.el}
for some examples of the use of @code{define-generic-mode}.

@defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring
This macro defines a generic mode command named @var{mode} (a symbol,
not quoted).  The optional argument @var{docstring} is the
documentation for the mode command.  If you do not supply it,
@code{define-generic-mode} generates one by default.

The argument @var{comment-list} is a list in which each element is
either a character, a string of one or two characters, or a cons cell.
A character or a string is set up in the mode's syntax table as a
1127 1128
``comment starter''.  If the entry is a cons cell, the @sc{car} is set
up as a ``comment starter'' and the @sc{cdr} as a ``comment ender''.
1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148
(Use @code{nil} for the latter if you want comments to end at the end
of the line.)  Note that the syntax table mechanism has limitations
about what comment starters and enders are actually possible.
@xref{Syntax Tables}.

The argument @var{keyword-list} is a list of keywords to highlight
with @code{font-lock-keyword-face}.  Each keyword should be a string.
Meanwhile, @var{font-lock-list} is a list of additional expressions to
highlight.  Each element of this list should have the same form as an
element of @code{font-lock-keywords}.  @xref{Search-based
Fontification}.

The argument @var{auto-mode-list} is a list of regular expressions to
add to the variable @code{auto-mode-alist}.  They are added by the execution
of the @code{define-generic-mode} form, not by expanding the macro call.

Finally, @var{function-list} is a list of functions for the mode
command to call for additional setup.  It calls these functions just
before it runs the mode hook variable @code{@var{mode}-hook}.
@end defmac
Glenn Morris's avatar
Glenn Morris committed
1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176

@node Example Major Modes
@subsection Major Mode Examples

  Text mode is perhaps the simplest mode besides Fundamental mode.
Here are excerpts from  @file{text-mode.el} that illustrate many of
the conventions listed above:

@smallexample
@group
;; @r{Create the syntax table for this mode.}
(defvar text-mode-syntax-table
  (let ((st (make-syntax-table)))
    (modify-syntax-entry ?\" ".   " st)
    (modify-syntax-entry ?\\ ".   " st)
    ;; Add `p' so M-c on `hello' leads to `Hello', not `hello'.
    (modify-syntax-entry ?' "w p" st)
    st)
  "Syntax table used while in `text-mode'.")
@end group

;; @r{Create the keymap for this mode.}
@group
(defvar text-mode-map
  (let ((map (make-sparse-keymap)))
    (define-key map "\e\t" 'ispell-complete-word)
    map)
  "Keymap for `text-mode'.
1177 1178
Many other modes, such as `mail-mode', `outline-mode' and
`indented-text-mode', inherit all the commands defined in this map.")
Glenn Morris's avatar
Glenn Morris committed
1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194
@end group
@end smallexample

  Here is how the actual mode command is defined now:

@smallexample
@group
(define-derived-mode text-mode nil "Text"
  "Major mode for editing text written for humans to read.
In this mode, paragraphs are delimited only by blank or white lines.
You can thus get the full benefit of adaptive filling
 (see the variable `adaptive-fill-mode').
\\@{text-mode-map@}
Turning on Text mode runs the normal hook `text-mode-hook'."
@end group
@group
1195
  (set (make-local-variable 'text-mode-variant) t)
Glenn Morris's avatar
Glenn Morris committed
1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206
  (set (make-local-variable 'require-final-newline)
       mode-require-final-newline)
  (set (make-local-variable 'indent-line-function) 'indent-relative))
@end group
@end smallexample

@noindent
(The last line is redundant nowadays, since @code{indent-relative} is
the default value, and we'll delete it in a future version.)

@cindex @file{lisp-mode.el}
1207 1208 1209 1210 1211 1212
  The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp Interaction
mode) have more features than Text mode and the code is correspondingly
more complicated.  Here are excerpts from @file{lisp-mode.el} that
illustrate how these modes are written.

  Here is how the Lisp mode syntax and abbrev tables are defined:
Glenn Morris's avatar
Glenn Morris committed
1213 1214 1215 1216 1217

@cindex syntax table example
@smallexample
@group
;; @r{Create mode-specific table variables.}
1218
(defvar lisp-mode-abbrev-table nil)
Glenn Morris's avatar
Glenn Morris committed
1219
(define-abbrev-table 'lisp-mode-abbrev-table ())
1220 1221 1222 1223 1224 1225 1226 1227 1228

(defvar lisp-mode-syntax-table
  (let ((table (copy-syntax-table emacs-lisp-mode-syntax-table)))
    (modify-syntax-entry ?\[ "_   " table)
    (modify-syntax-entry ?\] "_   " table)
    (modify-syntax-entry ?# "' 14" table)
    (modify-syntax-entry ?| "\" 23bn" table)
    table)
  "Syntax table used in `lisp-mode'.")
Glenn Morris's avatar
Glenn Morris committed
1229 1230 1231 1232 1233 1234 1235 1236
@end group
@end smallexample

  The three modes for Lisp share much of their code.  For instance,
each calls the following function to set various variables:

@smallexample
@group
1237 1238
(defun lisp-mode-variables (&optional syntax keywords-case-insensitive)
  (when syntax
Glenn Morris's avatar
Glenn Morris committed
1239 1240 1241 1242 1243 1244
    (set-syntax-table lisp-mode-syntax-table))
  (setq local-abbrev-table lisp-mode-abbrev-table)
  @dots{}
@end group
@end smallexample

1245 1246 1247
@noindent
Amongst other things, this function sets up the @code{comment-start}
variable to handle Lisp comments:
Glenn Morris's avatar
Glenn Morris committed
1248 1249 1250

@smallexample
@group
1251 1252
  (make-local-variable 'comment-start)
  (setq comment-start ";")
Glenn Morris's avatar
Glenn Morris committed
1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263
  @dots{}
@end group
@end smallexample

  Each of the different Lisp modes has a slightly different keymap.  For
example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other
Lisp modes do not.  However, all Lisp modes have some commands in
common.  The following code sets up the common commands:

@smallexample
@group
1264
(defvar lisp-mode-shared-map
1265
  (let ((map (make-sparse-keymap)))
1266 1267
    (define-key map "\e\C-q" 'indent-sexp)
    (define-key map "\177" 'backward-delete-char-untabify)
1268
    map)
Glenn Morris's avatar
Glenn Morris committed
1269 1270 1271 1272 1273 1274 1275 1276 1277
  "Keymap for commands shared by all sorts of Lisp modes.")
@end group
@end smallexample

@noindent
And here is the code to set up the keymap for Lisp mode:

@smallexample
@group
1278
(defvar lisp-mode-map
1279 1280 1281
  (let ((map (make-sparse-keymap))
	(menu-map (make-sparse-keymap "Lisp")))
    (set-keymap-parent map lisp-mode-shared-map)
1282 1283
    (define-key map "\e\C-x" 'lisp-eval-defun)
    (define-key map "\C-c\C-z" 'run-lisp)
1284
    @dots{}
1285
    map)
1286 1287
  "Keymap for ordinary Lisp mode.
All commands in `lisp-mode-shared-map' are inherited by this map.")
Glenn Morris's avatar
Glenn Morris committed
1288 1289 1290
@end group
@end smallexample

1291 1292
@noindent
Finally, here is the major mode command for Lisp mode:
Glenn Morris's avatar
Glenn Morris committed
1293 1294 1295

@smallexample
@group
1296
(define-derived-mode lisp-mode prog-mode "Lisp"
Glenn Morris's avatar
Glenn Morris committed
1297 1298 1299 1300
  "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
Commands:
Delete converts tabs to spaces as it moves back.
Blank lines separate paragraphs.  Semicolons start comments.
1301

Glenn Morris's avatar
Glenn Morris committed
1302 1303 1304 1305 1306 1307 1308 1309
\\@{lisp-mode-map@}
Note that `run-lisp' may be used either to start an inferior Lisp job
or to switch back to an existing one.
@end group

@group
Entry to this mode calls the value of `lisp-mode-hook'
if that value is non-nil."
1310
  (lisp-mode-variables nil t)
1311 1312 1313
  (set (make-local-variable 'find-tag-default-function)
       'lisp-find-tag-default)
  (set (make-local-variable 'comment-start-skip)
1314
       "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *")
1315
  (setq imenu-case-fold-search t))
Glenn Morris's avatar
Glenn Morris committed
1316 1317 1318 1319 1320 1321 1322
@end group
@end smallexample

@node Minor Modes
@section Minor Modes
@cindex minor mode

1323 1324 1325
  A @dfn{minor mode} provides optional features that users may enable or
disable independently of the choice of major mode.  Minor modes can be
enabled individually or in combination.
Glenn Morris's avatar
Glenn Morris committed
1326

1327 1328 1329 1330 1331 1332
  Most minor modes implement features that are independent of the major
mode, and can thus be used with most major modes.  For example, Auto
Fill mode works with any major mode that permits text insertion.  A few
minor modes, however, are specific to a particular major mode.  For
example, Diff Auto Refine mode is a minor mode that is intended to be
used only with Diff mode.
Glenn Morris's avatar
Glenn Morris committed
1333

1334 1335 1336
  Ideally, a minor mode should have its desired effect regardless of the
other minor modes in effect.  It should be possible to activate and
deactivate minor modes in any order.
Glenn Morris's avatar
Glenn Morris committed
1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353

@defvar minor-mode-list
The value of this variable is a list of all minor mode commands.
@end defvar

@menu
* Minor Mode Conventions::      Tips for writing a minor mode.
* Keymaps and Minor Modes::     How a minor mode can have its own keymap.
* Defining Minor Modes::        A convenient facility for defining minor modes.
@end menu

@node Minor Mode Conventions
@subsection Conventions for Writing Minor Modes
@cindex minor mode conventions
@cindex conventions for writing minor modes

  There are conventions for writing minor modes just as there are for
1354 1355 1356
major modes.  These conventions are described below.  The easiest way to
follow them is to use the macro @code{define-minor-mode}.
@xref{Defining Minor Modes}.
Glenn Morris's avatar
Glenn Morris committed
1357 1358 1359 1360

@itemize @bullet
@item
@cindex mode variable
1361 1362 1363 1364 1365
Define a variable whose name ends in @samp{-mode}.  We call this the
@dfn{mode variable}.  The minor mode command should set this variable.
The value will be @code{nil} is the mode is disabled, and non-@code{nil}
if the mode is enabled.  The variable should be buffer-local if the
minor mode is buffer-local.
Glenn Morris's avatar
Glenn Morris committed
1366 1367

This variable is used in conjunction with the @code{minor-mode-alist} to
1368 1369 1370 1371
display the minor mode name in the mode line.  It also determines
whether the minor mode keymap is active, via @code{minor-mode-map-alist}
(@pxref{Controlling Active Maps}).  Individual commands or hooks can
also check its value.
Glenn Morris's avatar
Glenn Morris committed
1372 1373

@item
1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392
Define a command, called the @dfn{mode command}, whose name is the same
as the mode variable.  Its job is to set the value of the mode variable,
plus anything else that needs to be done to actually enable or disable
the mode's features.

The mode command should accept one optional argument.  If called
interactively with no prefix argument, it should toggle the mode
(i.e.@: enable if it is disabled, and disable if it is enabled).  If
called interactively with a prefix argument, it should enable the mode
if the argument is positive and disable it otherwise.

If the mode command is called from Lisp (i.e.@: non-interactively), it
should enable the mode if the argument is omitted or @code{nil}; it
should toggle the mode if the argument is the symbol @code{toggle};
otherwise it should treat the argument in the same way as for an
interactive call with a numeric prefix argument, as described above.

The following example shows how to implement this behavior (it is
similar to the code generated by the @code{define-minor-mode} macro):
Glenn Morris's avatar
Glenn Morris committed
1393

1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423
@example
(interactive (list (or current-prefix-arg 'toggle)))
(let ((enable (if (eq arg 'toggle)
                  (not foo-mode) ; @r{this mode's mode variable}
                (> (prefix-numeric-value arg) 0))))
  (if enable
      @var{do-enable}
    @var{do-disable}))
@end example

The reason for this somewhat complex behavior is that it lets users
easily toggle the minor mode interactively, and also lets the minor mode
be easily enabled in a mode hook, like this:

@example
(add-hook 'text-mode-hook 'foo-mode)
@end example

@noindent
This behaves correctly whether or not @code{foo-mode} was already
enabled, since the @code{foo-mode} mode command unconditionally enables
the minor mode when it is called from Lisp with no argument.  Disabling
a minor mode in a mode hook is a little uglier:

@example
(add-hook 'text-mode-hook (lambda () (foo-mode -1)))
@end example

@noindent
However, this is not very commonly done.
Glenn Morris's avatar
Glenn Morris committed
1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445

@item
Add an element to @code{minor-mode-alist} for each minor mode
(@pxref{Definition of minor-mode-alist}), if you want to indicate the
minor mode in the mode line.  This element should be a list of the
following form:

@smallexample
(@var{mode-variable} @var{string})
@end smallexample

Here @var{mode-variable} is the variable that controls enabling of the
minor mode, and @var{string} is a short string, starting with a space,
to represent the mode in the mode line.  These strings must be short so
that there is room for several of them at once.

When you add an element to @code{minor-mode-alist}, use @code{assq} to
check for an existing element, to avoid duplication.  For example:

@smallexample
@group
(unless (assq 'leif-mode minor-mode-alist)
1446
  (push '(leif-mode " Leif") minor-mode-alist))
Glenn Morris's avatar
Glenn Morris committed
1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459
@end group
@end smallexample

@noindent
or like this, using @code{add-to-list} (@pxref{List Variables}):

@smallexample
@group
(add-to-list 'minor-mode-alist '(leif-mode " Leif"))
@end group
@end smallexample
@end itemize

1460 1461 1462 1463
  In addition, several major mode conventions apply to minor modes as
well: those regarding the names of global symbols, the use of a hook at
the end of the initialization function, and the use of keymaps and other
tables.
Glenn Morris's avatar
Glenn Morris committed
1464

1465 1466 1467 1468
  The minor mode should, if possible, support enabling and disabling via
Custom (@pxref{Customization}).  To do this, the mode variable should be
defined with @code{defcustom}, usually with @code{:type 'boolean}.  If
just setting the variable is not sufficient to enable the mode, you
Glenn Morris's avatar
Glenn Morris committed
1469
should also specify a @code{:set} method which enables the mode by
1470 1471 1472 1473 1474
invoking the mode command.  Note in the variable's documentation string
that setting the variable other than via Custom may not take effect.
Also, mark the definition with an autoload cookie (@pxref{autoload
cookie}), and specify a @code{:require} so that customizing the variable
will load the library that defines the mode.  For example:
Glenn Morris's avatar
Glenn Morris committed
1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501

@smallexample
@group
;;;###autoload
(defcustom msb-mode nil
  "Toggle msb-mode.
Setting this variable directly does not take effect;
use either \\[customize] or the function `msb-mode'."
  :set 'custom-set-minor-mode
  :initialize 'custom-initialize-default
  :version "20.4"
  :type    'boolean
  :group   'msb
  :require 'msb)
@end group
@end smallexample

@node Keymaps and Minor Modes
@subsection Keymaps and Minor Modes

  Each minor mode can have its own keymap, which is active when the mode
is enabled.  To set up a keymap for a minor mode, add an element to the
alist @code{minor-mode-map-alist}.  @xref{Definition of minor-mode-map-alist}.

@cindex @code{self-insert-command}, minor modes
  One use of minor mode keymaps is to modify the behavior of certain
self-inserting characters so that they do something else as well as
Glenn Morris's avatar
Glenn Morris committed
1502 1503 1504 1505 1506 1507
self-insert.  (Another way to customize @code{self-insert-command} is
through @code{post-self-insert-hook}.  Apart from this, the facilities
for customizing @code{self-insert-command} are limited to special cases,
designed for abbrevs and Auto Fill mode.  Do not try substituting your
own definition of @code{self-insert-command} for the standard one.  The
editor command loop handles this function specially.)
Glenn Morris's avatar
Glenn Morris committed
1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521

The key sequences bound in a minor mode should consist of @kbd{C-c}
followed by one of @kbd{.,/?`'"[]\|~!#$%^&*()-_+=}.  (The other
punctuation characters are reserved for major modes.)

@node Defining Minor Modes
@subsection Defining Minor Modes

  The macro @code{define-minor-mode} offers a convenient way of
implementing a mode in one self-contained definition.

@defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args@dots{} body@dots{}
This macro defines a new minor mode whose name is @var{mode} (a
symbol).  It defines a command named @var{mode} to toggle the minor
1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536
mode, with @var{doc} as its documentation string.

The toggle command takes one optional (prefix) argument.
If called interactively with no argument it toggles the mode on or off.
A positive prefix argument enables the mode, any other prefix argument
disables it.  From Lisp, an argument of @code{toggle} toggles the mode,
whereas an omitted or @code{nil} argument enables the mode.
This makes it easy to enable the minor mode in a major mode hook, for example.
If @var{doc} is nil, the macro supplies a default documentation string
explaining the above.

By default, it also defines a variable named @var{mode}, which is set to
@code{t} or @code{nil} by enabling or disabling the mode.  The variable
is initialized to @var{init-value}.  Except in unusual circumstances
(see below), this value must be @code{nil}.
Glenn Morris's avatar
Glenn Morris committed
1537 1538 1539 1540 1541

The string @var{lighter} says what to display in the mode line
when the mode is enabled; if it is @code{nil}, the mode is not displayed
in the mode line.

1542 1543 1544
The optional argument @var{keymap} specifies the keymap for the minor
mode.  If non-@code{nil}, it should be a variable name (whose value is
a keymap), a keymap, or an alist of the form
Glenn Morris's avatar
Glenn Morris committed
1545 1546 1547 1548 1549

@example
(@var{key-sequence} . @var{definition})
@end example

1550 1551 1552 1553 1554 1555
@noindent
where each @var{key-sequence} and @var{definition} are arguments
suitable for passing to @code{define-key} (@pxref{Changing Key
Bindings}).  If @var{keymap} is a keymap or an alist, this also
defines the variable @code{@var{mode}-map}.

Glenn Morris's avatar
Glenn Morris committed
1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574
The above three arguments @var{init-value}, @var{lighter}, and
@var{keymap} can be (partially) omitted when @var{keyword-args} are
used.  The @var{keyword-args} consist of keywords followed by
corresponding values.  A few keywords have special meanings:

@table @code
@item :group @var{group}
Custom group name to use in all generated @code{defcustom} forms.
Defaults to @var{mode} without the possible trailing @samp{-mode}.
@strong{Warning:} don't use this default group name unless you have
written a @code{defgroup} to define that group properly.  @xref{Group
Definitions}.

@item :global @var{global}
If non-@code{nil}, this specifies that the minor mode should be global
rather than buffer-local.  It defaults to @code{nil}.

One of the effects of making a minor mode global is that the
@var{mode} variable becomes a customization variable.  Toggling it
1575 1576
through the Customize interface turns the mode on and off, and its
value can be saved for future Emacs sessions (@pxref{Saving
Glenn Morris's avatar
Glenn Morris committed
1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590
Customizations,,, emacs, The GNU Emacs Manual}.  For the saved
variable to work, you should ensure that the @code{define-minor-mode}
form is evaluated each time Emacs starts; for packages that are not
part of Emacs, the easiest way to do this is to specify a
@code{:require} keyword.

@item :init-value @var{init-value}
This is equivalent to specifying @var{init-value} positionally.

@item :lighter @var{lighter}
This is equivalent to specifying @var{lighter} positionally.

@item :keymap @var{keymap}
This is equivalent to specifying @var{keymap} positionally.
1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601

@item :variable @var{place}
This replaces the default variable @var{mode}, used to store the state
of the mode.  If you specify this, the @var{mode} variable is not
defined, and any @var{init-value} argument is unused.  @var{place}
can be a different named variable (which you must define yourself), or
anything that can be used with the @code{setf} function
(@pxref{Generalized Variables,,, cl, Common Lisp Extensions}).
@var{place} can also be a cons @code{(@var{get} . @var{set})},
where @var{get} is an expression that returns the current state,
and @var{set} is a function of one argument (a state) that sets it.
1602 1603

@item :after-hook @var{after-hook}
1604
This defines a single Lisp form which is evaluated after the mode hooks
1605
have run.  It should not be quoted.
Glenn Morris's avatar
Glenn Morris committed
1606 1607 1608 1609 1610
@end table

Any other keyword arguments are passed directly to the
@code{defcustom} generated for the variable @var{mode}.

1611 1612 1613 1614 1615
The command named @var{mode} first performs the standard actions such as
setting the variable named @var{mode} and then executes the @var{body}
forms, if any.  It then runs the mode hook variable
@code{@var{mode}-hook} and finishes by evaluating any form in
@code{:after-hook}.
Glenn Morris's avatar
Glenn Morris committed
1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634
@end defmac

  The initial value must be @code{nil} except in cases where (1) the
mode is preloaded in Emacs, or (2) it is painless for loading to
enable the mode even though the user did not request it.  For
instance, if the mode has no effect unless something else is enabled,
and will always be loaded by that time, enabling it by default is