2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/modes
6 @node Modes, Documentation, Keymaps, Top
7 @chapter Major and Minor Modes
10 A @dfn{mode} is a set of definitions that customize Emacs and can be
11 turned on and off while you edit. There are two varieties of modes:
12 @dfn{major modes}, which are mutually exclusive and used for editing
13 particular kinds of text, and @dfn{minor modes}, which provide features
14 that users can enable individually.
16 This chapter describes how to write both major and minor modes, how to
17 indicate them in the mode line, and how they run hooks supplied by the
18 user. For related topics such as keymaps and syntax tables, see
19 @ref{Keymaps}, and @ref{Syntax Tables}.
22 * Major Modes:: Defining major modes.
23 * Minor Modes:: Defining minor modes.
24 * Mode Line Format:: Customizing the text that appears in the mode line.
25 * Imenu:: How a mode can provide a menu
26 of definitions in the buffer.
27 * Font Lock Mode:: How modes can highlight text according to syntax.
28 * Hooks:: How to use hooks; how to write code that provides hooks.
34 @cindex Fundamental mode
36 Major modes specialize Emacs for editing particular kinds of text.
37 Each buffer has only one major mode at a time.
39 The least specialized major mode is called @dfn{Fundamental mode}.
40 This mode has no mode-specific definitions or variable settings, so each
41 Emacs command behaves in its default manner, and each option is in its
42 default state. All other major modes redefine various keys and options.
43 For example, Lisp Interaction mode provides special key bindings for
44 @kbd{C-j} (@code{eval-print-last-sexp}), @key{TAB}
45 (@code{lisp-indent-line}), and other keys.
47 When you need to write several editing commands to help you perform a
48 specialized editing task, creating a new major mode is usually a good
49 idea. In practice, writing a major mode is easy (in contrast to
50 writing a minor mode, which is often difficult).
52 If the new mode is similar to an old one, it is often unwise to modify
53 the old one to serve two purposes, since it may become harder to use and
54 maintain. Instead, copy and rename an existing major mode definition
55 and alter the copy---or define a @dfn{derived mode} (@pxref{Derived
56 Modes}). For example, Rmail Edit mode, which is in
57 @file{emacs/lisp/mail/rmailedit.el}, is a major mode that is very similar to
58 Text mode except that it provides two additional commands. Its
59 definition is distinct from that of Text mode, but uses that of Text mode.
61 Rmail Edit mode offers an example of changing the major mode
62 temporarily for a buffer, so it can be edited in a different way (with
63 ordinary Emacs commands rather than Rmail commands). In such cases, the
64 temporary major mode usually provides a command to switch back to the
65 buffer's usual mode (Rmail mode, in this case). You might be tempted to
66 present the temporary redefinitions inside a recursive edit and restore
67 the usual ones when the user exits; but this is a bad idea because it
68 constrains the user's options when it is done in more than one buffer:
69 recursive edits must be exited most-recently-entered first. Using an
70 alternative major mode avoids this limitation. @xref{Recursive
73 The standard GNU Emacs Lisp library directory tree contains the code
74 for several major modes, in files such as @file{text-mode.el},
75 @file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
76 @file{rmail.el}. They are found in various subdirectories of the
77 @file{lisp} directory. You can study these libraries to see how modes
78 are written. Text mode is perhaps the simplest major mode aside from
79 Fundamental mode. Rmail mode is a complicated and specialized mode.
82 * Major Mode Conventions:: Coding conventions for keymaps, etc.
83 * Example Major Modes:: Text mode and Lisp modes.
84 * Auto Major Mode:: How Emacs chooses the major mode automatically.
85 * Mode Help:: Finding out how to use a mode.
86 * Derived Modes:: Defining a new major mode based on another major
90 @node Major Mode Conventions
91 @subsection Major Mode Conventions
93 The code for existing major modes follows various coding conventions,
94 including conventions for local keymap and syntax table initialization,
95 global names, and hooks. Please follow these conventions when you
96 define a new major mode:
100 Define a command whose name ends in @samp{-mode}, with no arguments,
101 that switches to the new mode in the current buffer. This command
102 should set up the keymap, syntax table, and buffer-local variables in an
103 existing buffer, without changing the buffer's contents.
106 Write a documentation string for this command that describes the
107 special commands available in this mode. @kbd{C-h m}
108 (@code{describe-mode}) in your mode will display this string.
110 The documentation string may include the special documentation
111 substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
112 @samp{\<@var{keymap}>}, which enable the documentation to adapt
113 automatically to the user's own key bindings. @xref{Keys in
117 The major mode command should start by calling
118 @code{kill-all-local-variables}. This is what gets rid of the
119 buffer-local variables of the major mode previously in effect.
122 The major mode command should set the variable @code{major-mode} to the
123 major mode command symbol. This is how @code{describe-mode} discovers
124 which documentation to print.
127 The major mode command should set the variable @code{mode-name} to the
128 ``pretty'' name of the mode, as a string. This string appears in the
132 @cindex functions in modes
133 Since all global names are in the same name space, all the global
134 variables, constants, and functions that are part of the mode should
135 have names that start with the major mode name (or with an abbreviation
136 of it if the name is long). @xref{Coding Conventions}.
139 @cindex keymaps in modes
140 The major mode should usually have its own keymap, which is used as the
141 local keymap in all buffers in that mode. The major mode command should
142 call @code{use-local-map} to install this local map. @xref{Active
143 Keymaps}, for more information.
145 This keymap should be stored permanently in a global variable named
146 @code{@var{modename}-mode-map}. Normally the library that defines the
147 mode sets this variable.
149 @xref{Tips for Defining}, for advice about how to write the code to set
150 up the mode's keymap variable.
153 The key sequences bound in a major mode keymap should usually start with
154 @kbd{C-c}, followed by a control character, a digit, or @kbd{@{},
155 @kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}. The other punctuation
156 characters are reserved for minor modes, and ordinary letters are
159 It is reasonable for a major mode to rebind a key sequence with a
160 standard meaning, if it implements a command that does ``the same job''
161 in a way that fits the major mode better. For example, a major mode for
162 editing a programming language might redefine @kbd{C-M-a} to ``move to
163 the beginning of a function'' in a way that works better for that
166 Major modes such as Dired or Rmail that do not allow self-insertion of
167 text can reasonably redefine letters and other printing characters as
168 editing commands. Dired and Rmail both do this.
171 @cindex syntax tables in modes
172 The mode may have its own syntax table or may share one with other
173 related modes. If it has its own syntax table, it should store this in
174 a variable named @code{@var{modename}-mode-syntax-table}. @xref{Syntax
178 If the mode handles a language that has a syntax for comments, it should
179 set the variables that define the comment syntax. @xref{Options for
180 Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}.
183 @cindex abbrev tables in modes
184 The mode may have its own abbrev table or may share one with other
185 related modes. If it has its own abbrev table, it should store this in
186 a variable named @code{@var{modename}-mode-abbrev-table}. @xref{Abbrev
190 The mode should specify how to do highlighting for Font Lock mode, by
191 setting up a buffer-local value for the variable
192 @code{font-lock-defaults} (@pxref{Font Lock Mode}).
195 The mode should specify how Imenu should find the definitions or
196 sections of a buffer, by setting up a buffer-local value for the
197 variable @code{imenu-generic-expression} or
198 @code{imenu-create-index-function} (@pxref{Imenu}).
201 Use @code{defvar} or @code{defcustom} to set mode-related variables, so
202 that they are not reinitialized if they already have a value. (Such
203 reinitialization could discard customizations made by the user.)
206 @cindex buffer-local variables in modes
207 To make a buffer-local binding for an Emacs customization variable, use
208 @code{make-local-variable} in the major mode command, not
209 @code{make-variable-buffer-local}. The latter function would make the
210 variable local to every buffer in which it is subsequently set, which
211 would affect buffers that do not use this mode. It is undesirable for a
212 mode to have such global effects. @xref{Buffer-Local Variables}.
214 With rare exceptions, the only reasonable way to use use
215 @code{make-variable-buffer-local} in a Lisp package is for a variable
216 which is used only within that package. Using it on a variable used by
217 other packages would interfere with them.
221 @cindex major mode hook
222 Each major mode should have a @dfn{mode hook} named
223 @code{@var{modename}-mode-hook}. The major mode command should run that
224 hook, with @code{run-hooks}, as the very last thing it
228 The major mode command may also run the hooks of some more basic modes.
229 For example, @code{indented-text-mode} runs @code{text-mode-hook} as
230 well as @code{indented-text-mode-hook}. It may run these other hooks
231 immediately before the mode's own hook (that is, after everything else),
232 or it may run them earlier.
235 If something special should be done if the user switches a buffer from
236 this mode to any other major mode, this mode can set up a buffer-local
237 value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}).
240 If this mode is appropriate only for specially-prepared text, then the
241 major mode command symbol should have a property named @code{mode-class}
242 with value @code{special}, put on as follows:
244 @cindex @code{mode-class} property
245 @cindex @code{special}
247 (put 'funny-mode 'mode-class 'special)
251 This tells Emacs that new buffers created while the current buffer is in
252 Funny mode should not inherit Funny mode. Modes such as Dired, Rmail,
253 and Buffer List use this feature.
256 If you want to make the new mode the default for files with certain
257 recognizable names, add an element to @code{auto-mode-alist} to select
258 the mode for those file names. If you define the mode command to
259 autoload, you should add this element in the same file that calls
260 @code{autoload}. Otherwise, it is sufficient to add the element in the
261 file that contains the mode definition. @xref{Auto Major Mode}.
264 In the documentation, you should provide a sample @code{autoload} form
265 and an example of how to add to @code{auto-mode-alist}, that users can
266 include in their init files (@pxref{Init File}).
270 The top-level forms in the file defining the mode should be written so
271 that they may be evaluated more than once without adverse consequences.
272 Even if you never load the file more than once, someone else will.
275 @node Example Major Modes
276 @subsection Major Mode Examples
278 Text mode is perhaps the simplest mode besides Fundamental mode.
279 Here are excerpts from @file{text-mode.el} that illustrate many of
280 the conventions listed above:
284 ;; @r{Create mode-specific tables.}
285 (defvar text-mode-syntax-table nil
286 "Syntax table used while in text mode.")
290 (if text-mode-syntax-table
291 () ; @r{Do not change the table if it is already set up.}
292 (setq text-mode-syntax-table (make-syntax-table))
293 (modify-syntax-entry ?\" ". " text-mode-syntax-table)
294 (modify-syntax-entry ?\\ ". " text-mode-syntax-table)
295 (modify-syntax-entry ?' "w " text-mode-syntax-table))
299 (defvar text-mode-abbrev-table nil
300 "Abbrev table used while in text mode.")
301 (define-abbrev-table 'text-mode-abbrev-table ())
305 (defvar text-mode-map nil ; @r{Create a mode-specific keymap.}
306 "Keymap for Text mode.
307 Many other modes, such as Mail mode, Outline mode and Indented Text mode,
308 inherit all the commands defined in this map.")
311 () ; @r{Do not change the keymap if it is already set up.}
312 (setq text-mode-map (make-sparse-keymap))
313 (define-key text-mode-map "\e\t" 'ispell-complete-word)
314 (define-key text-mode-map "\t" 'indent-relative)
315 (define-key text-mode-map "\es" 'center-line)
316 (define-key text-mode-map "\eS" 'center-paragraph))
320 Here is the complete major mode function definition for Text mode:
325 "Major mode for editing text intended for humans to read...
326 Special commands: \\@{text-mode-map@}
329 Turning on text-mode runs the hook `text-mode-hook'."
331 (kill-all-local-variables)
332 (use-local-map text-mode-map)
335 (setq local-abbrev-table text-mode-abbrev-table)
336 (set-syntax-table text-mode-syntax-table)
339 (make-local-variable 'paragraph-start)
340 (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter))
341 (make-local-variable 'paragraph-separate)
342 (setq paragraph-separate paragraph-start)
343 (make-local-variable 'indent-line-function)
344 (setq indent-line-function 'indent-relative-maybe)
347 (setq mode-name "Text")
348 (setq major-mode 'text-mode)
349 (run-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
350 ; @r{customize the mode with a hook.}
354 @cindex @file{lisp-mode.el}
355 The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
356 Interaction mode) have more features than Text mode and the code is
357 correspondingly more complicated. Here are excerpts from
358 @file{lisp-mode.el} that illustrate how these modes are written.
360 @cindex syntax table example
363 ;; @r{Create mode-specific table variables.}
364 (defvar lisp-mode-syntax-table nil "")
365 (defvar emacs-lisp-mode-syntax-table nil "")
366 (defvar lisp-mode-abbrev-table nil "")
370 (if (not emacs-lisp-mode-syntax-table) ; @r{Do not change the table}
371 ; @r{if it is already set.}
373 (setq emacs-lisp-mode-syntax-table (make-syntax-table))
377 ;; @r{Set syntax of chars up to 0 to class of chars that are}
378 ;; @r{part of symbol names but not words.}
379 ;; @r{(The number 0 is @code{48} in the @sc{ascii} character set.)}
381 (modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table)
386 ;; @r{Set the syntax for other characters.}
387 (modify-syntax-entry ? " " emacs-lisp-mode-syntax-table)
388 (modify-syntax-entry ?\t " " emacs-lisp-mode-syntax-table)
392 (modify-syntax-entry ?\( "() " emacs-lisp-mode-syntax-table)
393 (modify-syntax-entry ?\) ")( " emacs-lisp-mode-syntax-table)
395 ;; @r{Create an abbrev table for lisp-mode.}
396 (define-abbrev-table 'lisp-mode-abbrev-table ())
400 Much code is shared among the three Lisp modes. The following
401 function sets various variables; it is called by each of the major Lisp
406 (defun lisp-mode-variables (lisp-syntax)
408 (set-syntax-table lisp-mode-syntax-table)))
409 (setq local-abbrev-table lisp-mode-abbrev-table)
414 Functions such as @code{forward-paragraph} use the value of the
415 @code{paragraph-start} variable. Since Lisp code is different from
416 ordinary text, the @code{paragraph-start} variable needs to be set
417 specially to handle Lisp. Also, comments are indented in a special
418 fashion in Lisp and the Lisp modes need their own mode-specific
419 @code{comment-indent-function}. The code to set these variables is the
420 rest of @code{lisp-mode-variables}.
424 (make-local-variable 'paragraph-start)
425 (setq paragraph-start (concat page-delimiter "\\|$" ))
426 (make-local-variable 'paragraph-separate)
427 (setq paragraph-separate paragraph-start)
431 (make-local-variable 'comment-indent-function)
432 (setq comment-indent-function 'lisp-comment-indent))
437 Each of the different Lisp modes has a slightly different keymap. For
438 example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other
439 Lisp modes do not. However, all Lisp modes have some commands in
440 common. The following code sets up the common commands:
444 (defvar shared-lisp-mode-map ()
445 "Keymap for commands shared by all sorts of Lisp modes.")
447 (if shared-lisp-mode-map
449 (setq shared-lisp-mode-map (make-sparse-keymap))
450 (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp)
451 (define-key shared-lisp-mode-map "\177"
452 'backward-delete-char-untabify))
457 And here is the code to set up the keymap for Lisp mode:
461 (defvar lisp-mode-map ()
462 "Keymap for ordinary Lisp mode...")
466 (setq lisp-mode-map (make-sparse-keymap))
467 (set-keymap-parent lisp-mode-map shared-lisp-mode-map)
468 (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun)
469 (define-key lisp-mode-map "\C-c\C-z" 'run-lisp))
473 Finally, here is the complete major mode function definition for
479 "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
481 Delete converts tabs to spaces as it moves back.
482 Blank lines separate paragraphs. Semicolons start comments.
484 Note that `run-lisp' may be used either to start an inferior Lisp job
485 or to switch back to an existing one.
489 Entry to this mode calls the value of `lisp-mode-hook'
490 if that value is non-nil."
492 (kill-all-local-variables)
495 (use-local-map lisp-mode-map) ; @r{Select the mode's keymap.}
496 (setq major-mode 'lisp-mode) ; @r{This is how @code{describe-mode}}
497 ; @r{finds out what to describe.}
498 (setq mode-name "Lisp") ; @r{This goes into the mode line.}
499 (lisp-mode-variables t) ; @r{This defines various variables.}
502 (setq imenu-case-fold-search t)
503 (set-syntax-table lisp-mode-syntax-table)
504 (run-hooks 'lisp-mode-hook)) ; @r{This permits the user to use a}
505 ; @r{hook to customize the mode.}
509 @node Auto Major Mode
510 @subsection How Emacs Chooses a Major Mode
512 Based on information in the file name or in the file itself, Emacs
513 automatically selects a major mode for the new buffer when a file is
514 visited. It also processes local variables specified in the file text.
516 @deffn Command fundamental-mode
517 Fundamental mode is a major mode that is not specialized for anything
518 in particular. Other major modes are defined in effect by comparison
519 with this one---their definitions say what to change, starting from
520 Fundamental mode. The @code{fundamental-mode} function does @emph{not}
521 run any hooks; you're not supposed to customize it. (If you want Emacs
522 to behave differently in Fundamental mode, change the @emph{global}
526 @deffn Command normal-mode &optional find-file
527 This function establishes the proper major mode and buffer-local variable
528 bindings for the current buffer. First it calls @code{set-auto-mode},
529 then it runs @code{hack-local-variables} to parse, and bind or
530 evaluate as appropriate, the file's local variables.
532 If the @var{find-file} argument to @code{normal-mode} is non-@code{nil},
533 @code{normal-mode} assumes that the @code{find-file} function is calling
534 it. In this case, it may process a local variables list at the end of
535 the file and in the @samp{-*-} line. The variable
536 @code{enable-local-variables} controls whether to do so. @xref{File
537 variables, , Local Variables in Files, emacs, The GNU Emacs Manual}, for
538 the syntax of the local variables section of a file.
540 If you run @code{normal-mode} interactively, the argument
541 @var{find-file} is normally @code{nil}. In this case,
542 @code{normal-mode} unconditionally processes any local variables list.
544 @cindex file mode specification error
545 @code{normal-mode} uses @code{condition-case} around the call to the
546 major mode function, so errors are caught and reported as a @samp{File
547 mode specification error}, followed by the original error message.
550 @defopt enable-local-variables
551 This variable controls processing of local variables lists in files
552 being visited. A value of @code{t} means process the local variables
553 lists unconditionally; @code{nil} means ignore them; anything else means
554 ask the user what to do for each file. The default value is @code{t}.
557 @defvar ignored-local-variables
558 This variable holds a list of variables that should not be
559 set by a file's local variables list. Any value specified
560 for one of these variables is ignored.
563 In addition to this list, any variable whose name has a non-@code{nil}
564 @code{risky-local-variable} property is also ignored.
566 @defopt enable-local-eval
567 This variable controls processing of @samp{Eval:} in local variables
568 lists in files being visited. A value of @code{t} means process them
569 unconditionally; @code{nil} means ignore them; anything else means ask
570 the user what to do for each file. The default value is @code{maybe}.
574 @cindex visited file mode
575 This function selects the major mode that is appropriate for the
576 current buffer. It may base its decision on the value of the @w{@samp{-*-}}
577 line, on the visited file name (using @code{auto-mode-alist}), on the
578 @w{@samp{#!}} line (using @code{interpreter-mode-alist}), or on the
579 file's local variables list. However, this function does not look for
580 the @samp{mode:} local variable near the end of a file; the
581 @code{hack-local-variables} function does that. @xref{Choosing Modes, ,
582 How Major Modes are Chosen, emacs, The GNU Emacs Manual}.
585 @defopt default-major-mode
586 This variable holds the default major mode for new buffers. The
587 standard value is @code{fundamental-mode}.
589 If the value of @code{default-major-mode} is @code{nil}, Emacs uses
590 the (previously) current buffer's major mode for the major mode of a new
591 buffer. However, if that major mode symbol has a @code{mode-class}
592 property with value @code{special}, then it is not used for new buffers;
593 Fundamental mode is used instead. The modes that have this property are
594 those such as Dired and Rmail that are useful only with text that has
595 been specially prepared.
598 @defun set-buffer-major-mode buffer
599 This function sets the major mode of @var{buffer} to the value of
600 @code{default-major-mode}. If that variable is @code{nil}, it uses
601 the current buffer's major mode (if that is suitable).
603 The low-level primitives for creating buffers do not use this function,
604 but medium-level commands such as @code{switch-to-buffer} and
605 @code{find-file-noselect} use it whenever they create buffers.
608 @defvar initial-major-mode
609 @cindex @samp{*scratch*}
610 The value of this variable determines the major mode of the initial
611 @samp{*scratch*} buffer. The value should be a symbol that is a major
612 mode command. The default value is @code{lisp-interaction-mode}.
615 @defvar auto-mode-alist
616 This variable contains an association list of file name patterns
617 (regular expressions; @pxref{Regular Expressions}) and corresponding
618 major mode commands. Usually, the file name patterns test for suffixes,
619 such as @samp{.el} and @samp{.c}, but this need not be the case. An
620 ordinary element of the alist looks like @code{(@var{regexp} .
621 @var{mode-function})}.
627 (("\\`/tmp/fol/" . text-mode)
628 ("\\.texinfo\\'" . texinfo-mode)
629 ("\\.texi\\'" . texinfo-mode)
632 ("\\.el\\'" . emacs-lisp-mode)
639 When you visit a file whose expanded file name (@pxref{File Name
640 Expansion}) matches a @var{regexp}, @code{set-auto-mode} calls the
641 corresponding @var{mode-function}. This feature enables Emacs to select
642 the proper major mode for most files.
644 If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
645 @var{function} t)}, then after calling @var{function}, Emacs searches
646 @code{auto-mode-alist} again for a match against the portion of the file
647 name that did not match before. This feature is useful for
648 uncompression packages: an entry of the form @code{("\\.gz\\'"
649 @var{function} t)} can uncompress the file and then put the uncompressed
650 file in the proper mode according to the name sans @samp{.gz}.
652 Here is an example of how to prepend several pattern pairs to
653 @code{auto-mode-alist}. (You might use this sort of expression in your
658 (setq auto-mode-alist
660 ;; @r{File name (within directory) starts with a dot.}
661 '(("/\\.[^/]*\\'" . fundamental-mode)
662 ;; @r{File name has no dot.}
663 ("[^\\./]*\\'" . fundamental-mode)
664 ;; @r{File name ends in @samp{.C}.}
665 ("\\.C\\'" . c++-mode))
671 @defvar interpreter-mode-alist
672 This variable specifies major modes to use for scripts that specify a
673 command interpreter in a @samp{#!} line. Its value is a list of
674 elements of the form @code{(@var{interpreter} . @var{mode})}; for
675 example, @code{("perl" . perl-mode)} is one element present by default.
676 The element says to use mode @var{mode} if the file specifies
677 an interpreter which matches @var{interpreter}. The value of
678 @var{interpreter} is actually a regular expression.
680 This variable is applicable only when the @code{auto-mode-alist} does
681 not indicate which major mode to use.
684 @defun hack-local-variables &optional force
685 This function parses, and binds or evaluates as appropriate, any local
686 variables specified by the contents of the current buffer.
688 The handling of @code{enable-local-variables} documented for
689 @code{normal-mode} actually takes place here. The argument @var{force}
690 usually comes from the argument @var{find-file} given to
695 @subsection Getting Help about a Major Mode
697 @cindex help for major mode
698 @cindex documentation for major mode
700 The @code{describe-mode} function is used to provide information
701 about major modes. It is normally called with @kbd{C-h m}. The
702 @code{describe-mode} function uses the value of @code{major-mode},
703 which is why every major mode function needs to set the
704 @code{major-mode} variable.
706 @deffn Command describe-mode
707 This function displays the documentation of the current major mode.
709 The @code{describe-mode} function calls the @code{documentation}
710 function using the value of @code{major-mode} as an argument. Thus, it
711 displays the documentation string of the major mode function.
712 (@xref{Accessing Documentation}.)
716 This variable holds the symbol for the current buffer's major mode.
717 This symbol should have a function definition that is the command to
718 switch to that major mode. The @code{describe-mode} function uses the
719 documentation string of the function as the documentation of the major
724 @subsection Defining Derived Modes
726 It's often useful to define a new major mode in terms of an existing
727 one. An easy way to do this is to use @code{define-derived-mode}.
729 @defmac define-derived-mode variant parent name docstring body@dots{}
730 This construct defines @var{variant} as a major mode command, using
731 @var{name} as the string form of the mode name.
733 The new command @var{variant} is defined to call the function
734 @var{parent}, then override certain aspects of that parent mode:
738 The new mode has its own keymap, named @code{@var{variant}-map}.
739 @code{define-derived-mode} initializes this map to inherit from
740 @code{@var{parent}-map}, if it is not already set.
743 The new mode has its own syntax table, kept in the variable
744 @code{@var{variant}-syntax-table}.
745 @code{define-derived-mode} initializes this variable by copying
746 @code{@var{parent}-syntax-table}, if it is not already set.
749 The new mode has its own abbrev table, kept in the variable
750 @code{@var{variant}-abbrev-table}.
751 @code{define-derived-mode} initializes this variable by copying
752 @code{@var{parent}-abbrev-table}, if it is not already set.
755 The new mode has its own mode hook, @code{@var{variant}-hook},
756 which it runs in standard fashion as the very last thing that it does.
757 (The new mode also runs the mode hook of @var{parent} as part
758 of calling @var{parent}.)
761 In addition, you can specify how to override other aspects of
762 @var{parent} with @var{body}. The command @var{variant}
763 evaluates the forms in @var{body} after setting up all its usual
764 overrides, just before running @code{@var{variant}-hook}.
766 The argument @var{docstring} specifies the documentation string for the
767 new mode. If you omit @var{docstring}, @code{define-derived-mode}
768 generates a documentation string.
770 Here is a hypothetical example:
773 (define-derived-mode hypertext-mode
774 text-mode "Hypertext"
775 "Major mode for hypertext.
776 \\@{hypertext-mode-map@}"
777 (setq case-fold-search nil))
779 (define-key hypertext-mode-map
780 [down-mouse-3] 'do-hyper-link)
788 A @dfn{minor mode} provides features that users may enable or disable
789 independently of the choice of major mode. Minor modes can be enabled
790 individually or in combination. Minor modes would be better named
791 ``generally available, optional feature modes,'' except that such a name
794 A minor mode is not usually meant as a variation of a single major mode.
795 Usually they are general and can apply to many major modes. For
796 example, Auto Fill mode works with any major mode that permits text
797 insertion. To be general, a minor mode must be effectively independent
798 of the things major modes do.
800 A minor mode is often much more difficult to implement than a major
801 mode. One reason is that you should be able to activate and deactivate
802 minor modes in any order. A minor mode should be able to have its
803 desired effect regardless of the major mode and regardless of the other
804 minor modes in effect.
806 Often the biggest problem in implementing a minor mode is finding a
807 way to insert the necessary hook into the rest of Emacs. Minor mode
808 keymaps make this easier than it used to be.
811 * Minor Mode Conventions:: Tips for writing a minor mode.
812 * Keymaps and Minor Modes:: How a minor mode can have its own keymap.
813 * Easy-Mmode:: A convenient facility for defining minor modes.
816 @node Minor Mode Conventions
817 @subsection Conventions for Writing Minor Modes
818 @cindex minor mode conventions
819 @cindex conventions for writing minor modes
821 There are conventions for writing minor modes just as there are for
822 major modes. Several of the major mode conventions apply to minor
823 modes as well: those regarding the name of the mode initialization
824 function, the names of global symbols, and the use of keymaps and
827 In addition, there are several conventions that are specific to
832 @cindex mode variable
833 Make a variable whose name ends in @samp{-mode} to control the minor
834 mode. We call this the @dfn{mode variable}. The minor mode command
835 should set this variable (@code{nil} to disable; anything else to
838 If possible, implement the mode so that setting the variable
839 automatically enables or disables the mode. Then the minor mode command
840 does not need to do anything except set the variable.
842 This variable is used in conjunction with the @code{minor-mode-alist} to
843 display the minor mode name in the mode line. It can also enable
844 or disable a minor mode keymap. Individual commands or hooks can also
845 check the variable's value.
847 If you want the minor mode to be enabled separately in each buffer,
848 make the variable buffer-local.
851 Define a command whose name is the same as the mode variable.
852 Its job is to enable and disable the mode by setting the variable.
854 The command should accept one optional argument. If the argument is
855 @code{nil}, it should toggle the mode (turn it on if it is off, and off
856 if it is on). Otherwise, it should turn the mode on if the argument is
857 a positive integer, a symbol other than @code{nil} or @code{-}, or a
858 list whose @sc{car} is such an integer or symbol; it should turn the
861 Here is an example taken from the definition of @code{transient-mark-mode}.
862 It shows the use of @code{transient-mark-mode} as a variable that enables or
863 disables the mode's behavior, and also shows the proper way to toggle,
864 enable or disable the minor mode based on the raw prefix argument value.
868 (setq transient-mark-mode
869 (if (null arg) (not transient-mark-mode)
870 (> (prefix-numeric-value arg) 0)))
875 Add an element to @code{minor-mode-alist} for each minor mode
876 (@pxref{Mode Line Variables}), if you want to indicate the minor mode in
877 the mode line. This element should be a list of the following form:
880 (@var{mode-variable} @var{string})
883 Here @var{mode-variable} is the variable that controls enabling of the
884 minor mode, and @var{string} is a short string, starting with a space,
885 to represent the mode in the mode line. These strings must be short so
886 that there is room for several of them at once.
888 When you add an element to @code{minor-mode-alist}, use @code{assq} to
889 check for an existing element, to avoid duplication. For example:
893 (unless (assq 'leif-mode minor-mode-alist)
894 (setq minor-mode-alist
895 (cons '(leif-mode " Leif") minor-mode-alist)))
900 or like this, using @code{add-to-list} (@pxref{Setting Variables}):
904 (add-to-list 'minor-mode-alist '(leif-mode " Leif"))
909 Global minor modes distributed with Emacs should if possible support
910 enabling and disabling via Custom (@pxref{Customization}). To do this,
911 the first step is to define the mode variable with @code{defcustom}, and
912 specify @code{:type boolean}.
914 If just setting the variable is not sufficient to enable the mode, you
915 should also specify a @code{:set} method which enables the mode by
916 invoke the mode command. Note in the variable's documentation string that
917 setting the variable other than via Custom may not take effect.
919 Also mark the definition with an autoload cookie (@pxref{Autoload}),
920 and specify a @code{:require} so that customizing the variable will load
921 the library that defines the mode. This will copy suitable definitions
922 into @file{loaddefs.el} so that users can use @code{customize-option} to
923 enable the mode. For example:
929 (defcustom msb-mode nil
931 Setting this variable directly does not take effect;
932 use either \\[customize] or the function `msb-mode'."
933 :set (lambda (symbol value)
934 (msb-mode (or value 0)))
935 :initialize 'custom-initialize-default
943 @node Keymaps and Minor Modes
944 @subsection Keymaps and Minor Modes
946 Each minor mode can have its own keymap, which is active when the mode
947 is enabled. To set up a keymap for a minor mode, add an element to the
948 alist @code{minor-mode-map-alist}. @xref{Active Keymaps}.
950 @cindex @code{self-insert-command}, minor modes
951 One use of minor mode keymaps is to modify the behavior of certain
952 self-inserting characters so that they do something else as well as
953 self-insert. In general, this is the only way to do that, since the
954 facilities for customizing @code{self-insert-command} are limited to
955 special cases (designed for abbrevs and Auto Fill mode). (Do not try
956 substituting your own definition of @code{self-insert-command} for the
957 standard one. The editor command loop handles this function specially.)
959 The key sequences bound in a minor mode should consist of @kbd{C-c}
960 followed by a punctuation character @emph{other than} @kbd{@{},
961 @kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:}, and @kbd{;}. (Those few punctuation
962 characters are reserved for major modes.)
965 @subsection Easy-Mmode
967 The easy-mmode package provides a convenient way of implementing a
968 mode in one self-contained definition. It currently supports only
969 buffer-local minor modes, not global ones.
971 @defmac easy-mmode-define-minor-mode mode doc &optional init-value mode-indicator keymap
972 @tindex easy-mmode-define-minor-mode
973 This macro defines a new minor mode whose name is @var{mode} (a symbol).
975 This macro defines a command named @var{mode} which toggles the minor
976 mode, and has @var{doc} as its documentation string.
978 It also defines a variable named @var{mode}, which is set to @code{t} or
979 @code{nil} by enabling or disabling the mode. The variable is
980 initialized to @var{init-value}.
982 The string @var{mode-indicator} says what to display in the mode line
983 when the mode is enabled; if it is @code{nil}, the mode is not displayed
986 The optional argument @var{keymap} specifies the keymap for the minor mode.
987 It can be a variable name, whose value is the keymap, or it can be an alist
988 specifying bindings in this form:
991 (@var{key-sequence} . @var{definition})
995 Here is an example of using @code{easy-mmode-define-minor-mode}:
998 (easy-mmode-define-minor-mode hungry-mode
1000 With no argument, this command toggles the mode.
1001 Non-null prefix argument turns on the mode.
1002 Null prefix argument turns off the mode.
1004 When Hungry mode is enabled, the control delete key
1005 gobbles all preceding whitespace except the last.
1006 See the command \\[hungry-electric-delete]."
1007 ;; The initial value.
1009 ;; The indicator for the mode line.
1011 ;; The minor mode bindings.
1012 '(("\C-\^?" . hungry-electric-delete)
1016 (hungry-electric-delete t)))))
1020 This defines a minor mode named ``Hungry mode'', a command named
1021 @code{hungry-mode} to toggle it, a variable named @code{hungry-mode}
1022 which indicates whether the mode is enabled, and a variable named
1023 @code{hungry-mode-map} which holds the keymap that is active when the
1024 mode is enabled. It initializes the keymap with key bindings for
1025 @kbd{C-@key{DEL}} and @kbd{C-M-@key{DEL}}.
1027 @node Mode Line Format
1028 @section Mode Line Format
1031 Each Emacs window (aside from minibuffer windows) typically has a mode
1032 line at the bottom, which displays status information about the buffer
1033 displayed in the window. The mode line contains information about the
1034 buffer, such as its name, associated file, depth of recursive editing,
1035 and major and minor modes. A window can also have a @dfn{header
1036 line}, which is much like the mode line but appears at the top of the
1037 window (starting in Emacs 21).
1039 This section describes how to control the contents of the mode line
1040 and header line. We include it in this chapter because much of the
1041 information displayed in the mode line relates to the enabled major and
1044 @code{mode-line-format} is a buffer-local variable that holds a
1045 template used to display the mode line of the current buffer. All
1046 windows for the same buffer use the same @code{mode-line-format}, so
1047 their mode lines appear the same---except for scrolling percentages, and
1048 line and column numbers, since those depend on point and on how the
1049 window is scrolled. @code{header-line-format} is used likewise for
1052 The mode line and header line of a window are normally updated
1053 whenever a different buffer is shown in the window, or when the buffer's
1054 modified-status changes from @code{nil} to @code{t} or vice-versa. If
1055 you modify any of the variables referenced by @code{mode-line-format}
1056 (@pxref{Mode Line Variables}), or any other variables and data
1057 structures that affect how text is displayed (@pxref{Display}), you may
1058 want to force an update of the mode line so as to display the new
1059 information or display it in the new way.
1062 @defun force-mode-line-update
1063 Force redisplay of the current buffer's mode line and header line.
1066 The mode line is usually displayed in inverse video; see
1067 @code{mode-line-inverse-video} in @ref{Inverse Video}.
1070 * Mode Line Data:: The data structure that controls the mode line.
1071 * Mode Line Variables:: Variables used in that data structure.
1072 * %-Constructs:: Putting information into a mode line.
1073 * Properties in Mode:: Using text properties in the mode line.
1074 * Header Lines:: Like a mode line, but at the top.
1077 @node Mode Line Data
1078 @subsection The Data Structure of the Mode Line
1079 @cindex mode line construct
1081 The mode line contents are controlled by a data structure of lists,
1082 strings, symbols, and numbers kept in buffer-local variables. The data
1083 structure is called a @dfn{mode line construct}, and it is built in
1084 recursive fashion out of simpler mode line constructs. The same data
1085 structure is used for constructing frame titles (@pxref{Frame Titles})
1086 and header lines (@pxref{Header Lines}).
1088 @defvar mode-line-format
1089 The value of this variable is a mode line construct with overall
1090 responsibility for the mode line format. The value of this variable
1091 controls which other variables are used to form the mode line text, and
1094 If you set this variable to @code{nil} in a buffer, that buffer does not
1095 have a mode line. (This feature was added in Emacs 21.)
1098 A mode line construct may be as simple as a fixed string of text, but
1099 it usually specifies how to use other variables to construct the text.
1100 Many of these variables are themselves defined to have mode line
1101 constructs as their values.
1103 The default value of @code{mode-line-format} incorporates the values
1104 of variables such as @code{mode-name} and @code{minor-mode-alist}.
1105 Because of this, very few modes need to alter @code{mode-line-format}
1106 itself. For most purposes, it is sufficient to alter some of the
1107 variables that @code{mode-line-format} refers to.
1109 A mode line construct may be a list, a symbol, or a string. If the
1110 value is a list, each element may be a list, a symbol, or a string.
1112 The mode line can display various faces, if the strings that control
1113 it have the @code{face} property. @xref{Properties in Mode}. In
1114 addition, the face @code{mode-line} is used as a default for the whole
1115 mode line (@pxref{Standard Faces}).
1118 @cindex percent symbol in mode line
1120 A string as a mode line construct is displayed verbatim in the mode line
1121 except for @dfn{@code{%}-constructs}. Decimal digits after the @samp{%}
1122 specify the field width for space filling on the right (i.e., the data
1123 is left justified). @xref{%-Constructs}.
1126 A symbol as a mode line construct stands for its value. The value of
1127 @var{symbol} is used as a mode line construct, in place of @var{symbol}.
1128 However, the symbols @code{t} and @code{nil} are ignored, as is any
1129 symbol whose value is void.
1131 There is one exception: if the value of @var{symbol} is a string, it is
1132 displayed verbatim: the @code{%}-constructs are not recognized.
1134 @item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{})
1135 A list whose first element is a string or list means to process all the
1136 elements recursively and concatenate the results. This is the most
1137 common form of mode line construct.
1139 @item (:eval @var{form})
1140 A list whose first element is the symbol @code{:eval} says to evaluate
1141 @var{form}, and use the result as a string to display.
1142 (This feature is new as of Emacs 21.)
1144 @item (@var{symbol} @var{then} @var{else})
1145 A list whose first element is a symbol that is not a keyword specifies a
1146 conditional. Its meaning depends on the value of @var{symbol}. If the
1147 value is non-@code{nil}, the second element, @var{then}, is processed
1148 recursively as a mode line element. But if the value of @var{symbol} is
1149 @code{nil}, the third element, @var{else}, is processed recursively.
1150 You may omit @var{else}; then the mode line element displays nothing if
1151 the value of @var{symbol} is @code{nil}.
1153 @item (@var{width} @var{rest}@dots{})
1154 A list whose first element is an integer specifies truncation or
1155 padding of the results of @var{rest}. The remaining elements
1156 @var{rest} are processed recursively as mode line constructs and
1157 concatenated together. Then the result is space filled (if
1158 @var{width} is positive) or truncated (to @minus{}@var{width} columns,
1159 if @var{width} is negative) on the right.
1161 For example, the usual way to show what percentage of a buffer is above
1162 the top of the window is to use a list like this: @code{(-3 "%p")}.
1165 If you do alter @code{mode-line-format} itself, the new value should
1166 use the same variables that appear in the default value (@pxref{Mode
1167 Line Variables}), rather than duplicating their contents or displaying
1168 the information in another fashion. This way, customizations made by
1169 the user or by Lisp programs (such as @code{display-time} and major
1170 modes) via changes to those variables remain effective.
1172 @cindex Shell mode @code{mode-line-format}
1173 Here is an example of a @code{mode-line-format} that might be
1174 useful for @code{shell-mode}, since it contains the host name and default
1179 (setq mode-line-format
1181 'mode-line-mule-info
1183 'mode-line-frame-identification
1187 ;; @r{Note that this is evaluated while making the list.}
1188 ;; @r{It makes a mode line construct which is just a string.}
1196 '(:eval (mode-line-mode-name))
1202 '(which-func-mode ("" which-func-format "--"))
1203 '(line-number-mode "L%l--")
1204 '(column-number-mode "C%c--")
1211 (The variables @code{line-number-mode}, @code{column-number-mode}
1212 and @code{which-func-mode} enable particular minor modes; as usual,
1213 these variable names are also the minor mode command names.)
1215 @node Mode Line Variables
1216 @subsection Variables Used in the Mode Line
1218 This section describes variables incorporated by the
1219 standard value of @code{mode-line-format} into the text of the mode
1220 line. There is nothing inherently special about these variables; any
1221 other variables could have the same effects on the mode line if
1222 @code{mode-line-format} were changed to use them.
1224 @defvar mode-line-mule-info
1225 @tindex mode-line-mule-info
1226 This variable holds the value of the mode-line construct that displays
1227 information about the language environment, buffer coding system, and
1228 current input method. @xref{Non-ASCII Characters}.
1231 @defvar mode-line-modified
1232 This variable holds the value of the mode-line construct that displays
1233 whether the current buffer is modified.
1235 The default value of @code{mode-line-modified} is @code{("%1*%1+")}.
1236 This means that the mode line displays @samp{**} if the buffer is
1237 modified, @samp{--} if the buffer is not modified, @samp{%%} if the
1238 buffer is read only, and @samp{%*} if the buffer is read only and
1241 Changing this variable does not force an update of the mode line.
1244 @defvar mode-line-frame-identification
1245 @tindex mode-line-frame-identification
1246 This variable identifies the current frame. The default value is
1247 @code{" "} if you are using a window system which can show multiple
1248 frames, or @code{"-%F "} on an ordinary terminal which shows only one
1252 @defvar mode-line-buffer-identification
1253 This variable identifies the buffer being displayed in the window. Its
1254 default value is @code{("%12b")}, which displays the buffer name, padded
1255 with spaces to at least 12 columns.
1258 @defvar global-mode-string
1259 This variable holds a mode line spec that appears in the mode line by
1260 default, just after the buffer name. The command @code{display-time}
1261 sets @code{global-mode-string} to refer to the variable
1262 @code{display-time-string}, which holds a string containing the time and
1265 The @samp{%M} construct substitutes the value of
1266 @code{global-mode-string}, but that is obsolete, since the variable is
1267 included in the mode line from @code{mode-line-format}.
1271 This buffer-local variable holds the ``pretty'' name of the current
1272 buffer's major mode. Each major mode should set this variable so that the
1273 mode name will appear in the mode line.
1276 @defvar minor-mode-alist
1277 This variable holds an association list whose elements specify how the
1278 mode line should indicate that a minor mode is active. Each element of
1279 the @code{minor-mode-alist} should be a two-element list:
1282 (@var{minor-mode-variable} @var{mode-line-string})
1285 More generally, @var{mode-line-string} can be any mode line spec. It
1286 appears in the mode line when the value of @var{minor-mode-variable} is
1287 non-@code{nil}, and not otherwise. These strings should begin with
1288 spaces so that they don't run together. Conventionally, the
1289 @var{minor-mode-variable} for a specific mode is set to a non-@code{nil}
1290 value when that minor mode is activated.
1292 The default value of @code{minor-mode-alist} is:
1297 @result{} ((vc-mode vc-mode)
1298 (abbrev-mode " Abbrev")
1299 (overwrite-mode overwrite-mode)
1300 (auto-fill-function " Fill")
1301 (defining-kbd-macro " Def")
1302 (isearch-mode isearch-mode))
1306 @code{minor-mode-alist} itself is not buffer-local. Each variable
1307 mentioned in the alist should be buffer-local if its minor mode can be
1308 enabled separately in each buffer.
1311 @defvar mode-line-process
1312 This buffer-local variable contains the mode line information on process
1313 status in modes used for communicating with subprocesses. It is
1314 displayed immediately following the major mode name, with no intervening
1315 space. For example, its value in the @samp{*shell*} buffer is
1316 @code{(":%s")}, which allows the shell to display its status along
1317 with the major mode as: @samp{(Shell:run)}. Normally this variable
1321 Some variables are used by @code{minor-mode-alist} to display
1322 a string for various minor modes when enabled. This is a typical
1326 The variable @code{vc-mode}, buffer-local in each buffer, records
1327 whether the buffer's visited file is maintained with version control,
1328 and, if so, which kind. Its value is a string that appears in the mode
1329 line, or @code{nil} for no version control.
1332 The variable @code{default-mode-line-format} is where
1333 @code{mode-line-format} usually gets its value:
1335 @defvar default-mode-line-format
1336 This variable holds the default @code{mode-line-format} for buffers
1337 that do not override it. This is the same as @code{(default-value
1338 'mode-line-format)}.
1340 The default value of @code{default-mode-line-format} is this list:
1347 mode-line-frame-identification
1348 mode-line-buffer-identification
1354 ;; @r{@code{mode-line-mode-name} is a function}
1355 ;; @r{that copies the mode name and adds text
1356 ;; @r{properties to make it mouse-sensitive.}
1357 (:eval (mode-line-mode-name))
1364 (which-func-mode ("" which-func-format "--"))
1365 (line-number-mode "L%l--")
1366 (column-number-mode "C%c--")
1374 @subsection @code{%}-Constructs in the Mode Line
1376 The following table lists the recognized @code{%}-constructs and what
1377 they mean. In any construct except @samp{%%}, you can add a decimal
1378 integer after the @samp{%} to specify how many characters to display.
1382 The current buffer name, obtained with the @code{buffer-name} function.
1383 @xref{Buffer Names}.
1386 The current column number of point.
1389 The visited file name, obtained with the @code{buffer-file-name}
1390 function. @xref{Buffer File Name}.
1393 The title (only on a window system) or the name of the selected frame.
1394 @xref{Window Frame Parameters}.
1397 The current line number of point, counting within the accessible portion
1401 @samp{Narrow} when narrowing is in effect; nothing otherwise (see
1402 @code{narrow-to-region} in @ref{Narrowing}).
1405 The percentage of the buffer text above the @strong{top} of window, or
1406 @samp{Top}, @samp{Bottom} or @samp{All}. Note that the default
1407 mode-line specification truncates this to three characters.
1410 The percentage of the buffer text that is above the @strong{bottom} of
1411 the window (which includes the text visible in the window, as well as
1412 the text above the top), plus @samp{Top} if the top of the buffer is
1413 visible on screen; or @samp{Bottom} or @samp{All}.
1416 The status of the subprocess belonging to the current buffer, obtained with
1417 @code{process-status}. @xref{Process Information}.
1420 Whether the visited file is a text file or a binary file. This is a
1421 meaningful distinction only on certain operating systems (@pxref{MS-DOS
1425 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
1426 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
1427 @samp{-} otherwise. @xref{Buffer Modification}.
1430 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
1431 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
1432 @samp{-} otherwise. This differs from @samp{%*} only for a modified
1433 read-only buffer. @xref{Buffer Modification}.
1436 @samp{*} if the buffer is modified, and @samp{-} otherwise.
1439 An indication of the depth of recursive editing levels (not counting
1440 minibuffer levels): one @samp{[} for each editing level.
1441 @xref{Recursive Editing}.
1444 One @samp{]} for each recursive editing level (not counting minibuffer
1448 Dashes sufficient to fill the remainder of the mode line.
1451 The character @samp{%}---this is how to include a literal @samp{%} in a
1452 string in which @code{%}-constructs are allowed.
1455 The following two @code{%}-constructs are still supported, but they are
1456 obsolete, since you can get the same results with the variables
1457 @code{mode-name} and @code{global-mode-string}.
1461 The value of @code{mode-name}.
1464 The value of @code{global-mode-string}. Currently, only
1465 @code{display-time} modifies the value of @code{global-mode-string}.
1468 @node Properties in Mode
1469 @subsection Properties in the Mode Line
1471 Starting in Emacs 21, certain text properties are meaningful in the
1472 mode line. The @code{face} property affects the appearance of text; the
1473 @code{help-echo} property associate help strings with the text, and
1474 @code{local-map} can make the text mouse-sensitive.
1476 There are three ways to specify text properties for text in the mode
1481 Put a string with the @code{local-map} property directly into the
1482 mode-line data structure.
1485 Put a @code{local-map} property on a mode-line %-construct
1486 such as @samp{%12b}; then the expansion of the %-construct
1487 will have that same text property.
1490 Use a list containing @code{:eval @var{form}} in the mode-line data
1491 structure, and make @var{form} evaluate to a string that has a
1492 @code{local-map} property.
1495 You use the @code{local-map} property to specify a keymap. Like any
1496 keymap, it can bind character keys and function keys; but that has no
1497 effect, since it is impossible to move point into the mode line. This
1498 keymap can only take real effect for mouse clicks.
1501 @subsection Window Header Lines
1502 @cindex header line (of a window)
1503 @cindex window header line
1505 Starting in Emacs 21, a window can have a @dfn{header line} at the
1506 top, just as it can have a mode line at the bottom. The header line
1507 feature works just like the mode line feature, except that it's
1508 controlled by different variables.
1510 @tindex header-line-format
1511 @defvar header-line-format
1512 This variable, local in every buffer, specifies how to display the
1513 header line, for windows displaying the buffer. The format of the value
1514 is the same as for @code{mode-line-format} (@xref{Mode Line Data}).
1517 @tindex default-header-line-format
1518 @defvar default-header-line-format
1519 This variable holds the default @code{header-line-format} for buffers
1520 that do not override it. This is the same as @code{(default-value
1521 'header-line-format)}.
1523 It is normally @code{nil}, so that ordinary buffers have no header line.
1530 @dfn{Imenu} is a feature that lets users select a definition or
1531 section in the buffer, from a menu which lists all of them, to go
1532 directly to that location in the buffer. Imenu works by constructing a
1533 buffer index which lists the names and buffer positions of the
1534 definitions, or other named portions of the buffer; then the user can
1535 choose one of them and move point to it. This section explains how to
1536 customize how Imenu finds the definitions or buffer portions for a
1537 particular major mode.
1539 The usual and simplest way is to set the variable
1540 @code{imenu-generic-expression}:
1542 @defvar imenu-generic-expression
1543 This variable, if non-@code{nil}, specifies regular expressions for
1544 finding definitions for Imenu. In the simplest case, elements should
1548 (@var{menu-title} @var{regexp} @var{subexp})
1551 Here, if @var{menu-title} is non-@code{nil}, it says that the matches
1552 for this element should go in a submenu of the buffer index;
1553 @var{menu-title} itself specifies the name for the submenu. If
1554 @var{menu-title} is @code{nil}, the matches for this element go directly
1555 in the top level of the buffer index.
1557 The second item in the list, @var{regexp}, is a regular expression
1558 (@pxref{Regular Expressions}); anything in the buffer that it matches is
1559 considered a definition, something to mention in the buffer index. The
1560 third item, @var{subexp}, indicates which subexpression in @var{regexp}
1561 matches the definition's name.
1563 An element can also look like this:
1566 (@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{})
1569 Each match for this element creates a special index item which, if
1570 selected by the user, calls @var{function} with arguments consisting of
1571 the item name, the buffer position, and @var{arguments}.
1573 For Emacs Lisp mode, @var{pattern} could look like this:
1575 @c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]
1578 ((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
1579 \\s-+\\([-A-Za-z0-9+]+\\)" 2)
1582 ("*Vars*" "^\\s-*(def\\(var\\|const\\)\
1583 \\s-+\\([-A-Za-z0-9+]+\\)" 2)
1588 (def\\(type\\|struct\\|class\\|ine-condition\\)\
1589 \\s-+\\([-A-Za-z0-9+]+\\)" 2))
1593 Setting this variable makes it buffer-local in the current buffer.
1596 @defvar imenu-case-fold-search
1597 This variable controls whether matching against
1598 @var{imenu-generic-expression} is case-sensitive: @code{t}, the default,
1599 means matching should ignore case.
1601 Setting this variable makes it buffer-local in the current buffer.
1604 @defvar imenu-syntax-alist
1605 This variable is an alist of syntax table modifiers to use while
1606 processing @code{imenu-generic-expression}, to override the syntax table
1607 of the current buffer. Each element should have this form:
1610 (@var{characters} . @var{syntax-description})
1613 The @sc{car}, @var{characters}, can be either a character or a string.
1614 The element says to give that character or characters the syntax
1615 specified by @var{syntax-description}, which is passed to
1616 @code{modify-syntax-entry} (@pxref{Syntax Table Functions}).
1618 This feature is typically used to give word syntax to characters which
1619 normally have symbol syntax, and thus to simplify
1620 @code{imenu-generic-expression} and speed up matching.
1621 For example, Fortran mode uses it this way:
1624 (setq imenu-syntax-alist '(("_$" . "w")))
1627 The @code{imenu-generic-expression} patterns can then use @samp{\\sw+}
1628 instead of @samp{\\(\\sw\\|\\s_\\)+}. Note that this technique may be
1629 inconvenient when the mode needs to limit the initial character
1630 of a name to a smaller set of characters than are allowed in the rest
1633 Setting this variable makes it buffer-local in the current buffer.
1636 Another way to customize Imenu for a major mode is to set the
1637 variables @code{imenu-prev-index-position-function} and
1638 @code{imenu-extract-index-name-function}:
1640 @defvar imenu-prev-index-position-function
1641 If this variable is non-@code{nil}, its value should be a funtion that
1642 finds the next ``definition'' to put in the buffer index, scanning
1643 backward in the buffer from point. It should return @code{nil} if it
1644 doesn't find another ``definition'' before point. Otherwise it shuould
1645 leave point at the place it finds a ``definition,'' and return any
1646 non-@code{nil} value.
1648 Setting this variable makes it buffer-local in the current buffer.
1651 @defvar imenu-extract-index-name-function
1652 If this variable is non-@code{nil}, its value should be a function to
1653 return the name for a definition, assuming point is in that definition
1654 as the @code{imenu-prev-index-position-function} function would leave
1657 Setting this variable makes it buffer-local in the current buffer.
1660 The last way to customize Imenu for a major mode is to set the
1661 variable @code{imenu-create-index-function}:
1663 @defvar imenu-create-index-function
1664 This variable specifies the function to use for creating a buffer index.
1665 The function should take no arguments, and return an index for the
1666 current buffer. It is called within @code{save-excursion}, so where it
1667 leaves point makes no difference.
1669 The default value is a function that uses
1670 @code{imenu-generic-expression} to produce the index alist. If you
1671 specify a different function, then @code{imenu-generic-expression} is
1674 Setting this variable makes it buffer-local in the current buffer.
1677 @defvar imenu-index-alist
1678 This variable holds the index alist for the current buffer.
1679 Setting it makes it buffer-local in the current buffer.
1681 Simple elements in the alist look like @code{(@var{index-name}
1682 . @var{index-position})}. Selecting a simple element has the effect of
1683 moving to position @var{index-position} in the buffer.
1685 Special elements look like @code{(@var{index-name} @var{position}
1686 @var{function} @var{arguments}@dots{})}. Selecting a special element
1690 (funcall @var{function} @var{index-name} @var{position} @var{arguments}@dots{})
1693 A nested sub-alist element looks like @code{(@var{index-name}
1697 @node Font Lock Mode
1698 @section Font Lock Mode
1699 @cindex Font Lock Mode
1701 @dfn{Font Lock mode} is a feature that automatically attaches
1702 @code{face} properties to certain parts of the buffer based on their
1703 syntactic role. How it parses the buffer depends on the major mode;
1704 most major modes define syntactic criteria for which faces to use in
1705 which contexts. This section explains how to customize Font Lock for a
1706 particular major mode.
1708 Font Lock mode finds text to highlight in two ways: through syntactic
1709 parsing based on the syntax table, and through searching (usually for
1710 regular expressions). Syntactic fontification happens first; it finds
1711 comments and string constants, and highlights them using
1712 @code{font-lock-comment-face} and @code{font-lock-string-face}
1713 (@pxref{Faces for Font Lock}). Search-based fontification follows.
1716 * Font Lock Basics::
1717 * Search-based Fontification::
1718 * Other Font Lock Variables::
1719 * Levels of Font Lock::
1720 * Faces for Font Lock::
1721 * Syntactic Font Lock::
1724 @node Font Lock Basics
1725 @subsection Font Lock Basics
1727 There are several variables that control how Font Lock mode highlights
1728 text. But major modes should not set any of these variables directly.
1729 Instead, they should set @code{font-lock-defaults} as a buffer-local
1730 variable. The value assigned to this variable is used, if and when Font
1731 Lock mode is enabled, to set all the other variables.
1733 @defvar font-lock-defaults
1734 This variable is set by major modes, as a buffer-local variable, to
1735 specify how to fontify text in that mode. The value should look like
1739 (@var{keywords} @var{keywords-only} @var{case-fold}
1740 @var{syntax-alist} @var{syntax-begin} @var{other-vars}@dots{})
1743 The first element, @var{keywords}, indirectly specifies the value of
1744 @code{font-lock-keywords}. It can be a symbol, a variable whose value
1745 is the list to use for @code{font-lock-keywords}. It can also be a list of
1746 several such symbols, one for each possible level of fontification. The
1747 first symbol specifies how to do level 1 fontification, the second
1748 symbol how to do level 2, and so on.
1750 The second element, @var{keywords-only}, specifies the value of the
1751 variable @code{font-lock-keywords-only}. If this is non-@code{nil},
1752 syntactic fontification (of strings and comments) is not performed.
1754 The third element, @var{case-fold}, specifies the value of
1755 @code{font-lock-case-fold-search}. If it is non-@code{nil}, Font Lock
1756 mode ignores case when searching as directed by
1757 @code{font-lock-keywords}.
1759 If the fourth element, @var{syntax-alist}, is non-@code{nil}, it should be
1760 a list of cons cells of the form @code{(@var{char-or-string}
1761 . @var{string})}. These are used to set up a syntax table for
1762 fontification (@pxref{Syntax Table Functions}). The resulting syntax
1763 table is stored in @code{font-lock-syntax-table}.
1765 The fifth element, @var{syntax-begin}, specifies the value of
1766 @code{font-lock-beginning-of-syntax-function} (see below).
1768 All the remaining elements (if any) are collectively called
1769 @var{other-vars}. Each of these elements should have the form
1770 @code{(@var{variable} . @var{value})}---which means, make @var{variable}
1771 buffer-local and then set it to @var{value}. You can use these
1772 @var{other-vars} to set other variables that affect fontification,
1773 aside from those you can control with the first five elements.
1776 @node Search-based Fontification
1777 @subsection Search-based Fontification
1779 The most important variable for customizing Font Lock mode is
1780 @code{font-lock-keywords}. It specifies the search criteria for
1781 search-based fontification.
1783 @defvar font-lock-keywords
1784 This variable's value is a list of the keywords to highlight. Be
1785 careful when composing regular expressions for this list; a poorly
1786 written pattern can dramatically slow things down!
1789 Each element of @code{font-lock-keywords} specifies how to find
1790 certain cases of text, and how to highlight those cases. Font Lock mode
1791 processes the elements of @code{font-lock-keywords} one by one, and for
1792 each element, it finds and handles all matches. Ordinarily, once
1793 part of the text has been fontified already, this cannot be overridden
1794 by a subsequent match in the same text; but you can specify different
1795 behavior using the @var{override} element of a @var{highlighter}.
1797 Each element of @code{font-lock-keywords} should have one of these
1802 Highlight all matches for @var{regexp} using
1803 @code{font-lock-keyword-face}. For example,
1806 ;; @r{Highlight discrete occurrences of @samp{foo}}
1807 ;; @r{using @code{font-lock-keyword-face}.}
1811 The function @code{regexp-opt} (@pxref{Syntax of Regexps}) is useful for
1812 calculating optimal regular expressions to match a number of different
1815 @item @var{function}
1816 Find text by calling @var{function}, and highlight the matches
1817 it finds using @code{font-lock-keyword-face}.
1819 When @var{function} is called, it receives one argument, the limit of
1820 the search. It should return non-@code{nil} if it succeeds, and set the
1821 match data to describe the match that was found.
1823 @item (@var{matcher} . @var{match})
1824 In this kind of element, @var{matcher} is either a regular
1825 expression or a function, as described above. The @sc{cdr},
1826 @var{match}, specifies which subexpression of @var{matcher} should be
1827 highlighted (instead of the entire text that @var{matcher} matched).
1830 ;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},}
1831 ;; @r{using @code{font-lock-keyword-face}.}
1835 If you use @code{regexp-opt} to produce the regular expression
1836 @var{matcher}, then you can use @code{regexp-opt-depth} (@pxref{Syntax
1837 of Regexps}) to calculate the value for @var{match}.
1839 @item (@var{matcher} . @var{facename})
1840 In this kind of element, @var{facename} is an expression whose value
1841 specifies the face name to use for highlighting.
1844 ;; @r{Highlight occurrences of @samp{fubar},}
1845 ;; @r{using the face which is the value of @code{fubar-face}.}
1846 ("fubar" . fubar-face)
1849 @item (@var{matcher} . @var{highlighter})
1850 In this kind of element, @var{highlighter} is a list
1851 which specifies how to highlight matches found by @var{matcher}.
1855 (@var{subexp} @var{facename} @var{override} @var{laxmatch})
1858 The @sc{car}, @var{subexp}, is an integer specifying which subexpression
1859 of the match to fontify (0 means the entire matching text). The second
1860 subelement, @var{facename}, specifies the face, as described above.
1862 The last two values in @var{highlighter}, @var{override} and
1863 @var{laxmatch}, are flags. If @var{override} is @code{t}, this element
1864 can override existing fontification made by previous elements of
1865 @code{font-lock-keywords}. If it is @code{keep}, then each character is
1866 fontified if it has not been fontified already by some other element.
1867 If it is @code{prepend}, the face @var{facename} is added to the
1868 beginning of the @code{face} property. If it is @code{append}, the face
1869 @var{facename} is added to the end of the @code{face} property.
1871 If @var{laxmatch} is non-@code{nil}, it means there should be no error
1872 if there is no subexpression numbered @var{subexp} in @var{matcher}.
1873 Obviously, fontification of the subexpression numbered @var{subexp} will
1874 not occur. However, fontification of other subexpressions (and other
1875 regexps) will continue. If @var{laxmatch} is @code{nil}, and the
1876 specified subexpression is missing, then an error is signalled which
1877 terminates search-based fontification.
1879 Here are some examples of elements of this kind, and what they do:
1882 ;; @r{Highlight occurrences of either @samp{foo} or @samp{bar},}
1883 ;; @r{using @code{foo-bar-face}, even if they have already been highlighted.}
1884 ;; @r{@code{foo-bar-face} should be a variable whose value is a face.}
1885 ("foo\\|bar" 0 foo-bar-face t)
1887 ;; @r{Highlight the first subexpression within each occurrence}
1888 ;; @r{that the function @code{fubar-match} finds,}
1889 ;; @r{using the face which is the value of @code{fubar-face}.}
1890 (fubar-match 1 fubar-face)
1893 @item (@var{matcher} @var{highlighters}@dots{})
1894 This sort of element specifies several @var{highlighter} lists for a
1895 single @var{matcher}. In order for this to be useful, each
1896 @var{highlighter} should have a different value of @var{subexp}; that is,
1897 each one should apply to a different subexpression of @var{matcher}.
1900 @item (@var{matcher} . @var{anchored})
1901 In this kind of element, @var{anchored} acts much like a
1902 @var{highlighter}, but it is more complex and can specify multiple
1903 successive searches.
1905 For highlighting single items, typically only @var{highlighter} is
1906 required. However, if an item or (typically) items are to be
1907 highlighted following the instance of another item (the anchor) then
1908 @var{anchored} may be required.
1913 (@var{submatcher} @var{pre-match-form} @var{post-match-form} @var{highlighters}@dots{})
1916 @c I can't parse this text -- rms
1917 where @var{submatcher} is much like @var{matcher}, with one
1918 exception---see below. @var{pre-match-form} and @var{post-match-form}
1919 are evaluated before the first, and after the last, instance
1920 @var{anchored}'s @var{submatcher} is used. Therefore they can be used
1921 to initialize before, and cleanup after, @var{submatcher} is used.
1922 Typically, @var{pre-match-form} is used to move to some position
1923 relative to the original @var{submatcher}, before starting with
1924 @var{anchored}'s @var{submatcher}. @var{post-match-form} might be used
1925 to move, before resuming with @var{anchored}'s parent's @var{matcher}.
1927 For example, an element of the form highlights (if not already highlighted):
1930 ("\\<anchor\\>" (0 anchor-face) ("\\<item\\>" nil nil (0 item-face)))
1933 Discrete occurrences of @samp{anchor} in the value of
1934 @code{anchor-face}, and subsequent discrete occurrences of @samp{item}
1935 (on the same line) in the value of @code{item-face}. (Here
1936 @var{pre-match-form} and @var{post-match-form} are @code{nil}.
1937 Therefore @samp{item} is initially searched for starting from the end of
1938 the match of @samp{anchor}, and searching for subsequent instance of
1939 @samp{anchor} resumes from where searching for @samp{item} concluded.)
1941 The above-mentioned exception is as follows. The limit of the
1942 @var{submatcher} search defaults to the end of the line after
1943 @var{pre-match-form} is evaluated. However, if @var{pre-match-form}
1944 returns a position greater than the position after @var{pre-match-form}
1945 is evaluated, that position is used as the limit of the search. It is
1946 generally a bad idea to return a position greater than the end of the
1947 line; in other words, the @var{submatcher} search should not span lines.
1949 @item (@var{matcher} @var{highlighters-or-anchoreds} ...)
1952 @item (eval . @var{form})
1953 Here @var{form} is an expression to be evaluated the first time
1954 this value of @code{font-lock-keywords} is used in a buffer.
1955 Its value should have one of the forms described in this table.
1958 @strong{Warning:} Do not design an element of @code{font-lock-keywords}
1959 to match text which spans lines; this does not work reliably. While
1960 @code{font-lock-fontify-buffer} handles multi-line patterns correctly,
1961 updating when you edit the buffer does not, since it considers text one
1964 @node Other Font Lock Variables
1965 @subsection Other Font Lock Variables
1967 This section describes additional variables that a major mode
1968 can set by means of @code{font-lock-defaults}.
1970 @defvar font-lock-keywords-only
1971 Non-@code{nil} means Font Lock should not fontify comments or strings
1972 syntactically; it should only fontify based on
1973 @code{font-lock-keywords}.
1977 Other variables include those for buffer-specialized fontification functions,
1978 `font-lock-fontify-buffer-function', `font-lock-unfontify-buffer-function',
1979 `font-lock-fontify-region-function', `font-lock-unfontify-region-function',
1980 `font-lock-inhibit-thing-lock' and `font-lock-maximum-size'.
1983 @defvar font-lock-keywords-case-fold-search
1984 Non-@code{nil} means that regular expression matching for the sake of
1985 @code{font-lock-keywords} should be case-insensitive.
1988 @defvar font-lock-syntax-table
1989 This variable specifies the syntax table to use for fontification of
1990 comments and strings.
1993 @defvar font-lock-beginning-of-syntax-function
1994 If this variable is non-@code{nil}, it should be a function to move
1995 point back to a position that is syntactically at ``top level'' and
1996 outside of strings or comments. Font Lock uses this when necessary
1997 to get the right results for syntactic fontification.
1999 This function is called with no arguments. It should leave point at the
2000 beginning of any enclosing syntactic block. Typical values are
2001 @code{beginning-of-line} (i.e., the start of the line is known to be
2002 outside a syntactic block), or @code{beginning-of-defun} for programming
2003 modes or @code{backward-paragraph} for textual modes (i.e., the
2004 mode-dependent function is known to move outside a syntactic block).
2006 If the value is @code{nil}, the beginning of the buffer is used as a
2007 position outside of a syntactic block. This cannot be wrong, but it can
2011 @defvar font-lock-mark-block-function
2012 If this variable is non-@code{nil}, it should be a function that is
2013 called with no arguments, to choose an enclosing range of text for
2014 refontification for the command @kbd{M-g M-g}
2015 (@code{font-lock-fontify-block}).
2017 The function should report its choice by placing the region around it.
2018 A good choice is a range of text large enough to give proper results,
2019 but not too large so that refontification becomes slow. Typical values
2020 are @code{mark-defun} for programming modes or @code{mark-paragraph} for
2024 @node Levels of Font Lock
2025 @subsection Levels of Font Lock
2027 Many major modes offer three different levels of fontification. You
2028 can define multiple levels by using a list of symbols for @var{keywords}
2029 in @code{font-lock-defaults}. Each symbol specifies one level of
2030 fontification; it is up to the user to choose one of these levels. The
2031 chosen level's symbol value is used to initialize
2032 @code{font-lock-keywords}.
2034 Here are the conventions for how to define the levels of
2039 Level 1: highlight function declarations, file directives (such as include or
2040 import directives), strings and comments. The idea is speed, so only
2041 the most important and top-level components are fontified.
2044 Level 2: in addition to level 1, highlight all language keywords,
2045 including type names that act like keywords, as well as named constant
2046 values. The idea is that all keywords (either syntactic or semantic)
2047 should be fontified appropriately.
2050 Level 3: in addition to level 2, highlight the symbols being defined in
2051 function and variable declarations, and all builtin function names,
2052 wherever they appear.
2055 @node Faces for Font Lock
2056 @subsection Faces for Font Lock
2058 You can make Font Lock mode use any face, but several faces are
2059 defined specifically for Font Lock mode. Each of these symbols is both
2060 a face name, and a variable whose default value is the symbol itself.
2061 Thus, the default value of @code{font-lock-comment-face} is
2062 @code{font-lock-comment-face}. This means you can write
2063 @code{font-lock-comment-face} in a context such as
2064 @code{font-lock-keywords} where a face-name-valued expression is used.
2067 @item font-lock-comment-face
2068 @vindex font-lock-comment-face
2069 Used (typically) for comments.
2071 @item font-lock-string-face
2072 @vindex font-lock-string-face
2073 Used (typically) for string constants.
2075 @item font-lock-keyword-face
2076 @vindex font-lock-keyword-face
2077 Used (typically) for keywords---names that have special syntactic
2078 significance, like @code{for} and @code{if} in C.
2080 @item font-lock-builtin-face
2081 @vindex font-lock-builtin-face
2082 Used (typically) for built-in function names.
2084 @item font-lock-function-name-face
2085 @vindex font-lock-function-name-face
2086 Used (typically) for the name of a function being defined or declared,
2087 in a function definition or declaration.
2089 @item font-lock-variable-name-face
2090 @vindex font-lock-variable-name-face
2091 Used (typically) for the name of a variable being defined or declared,
2092 in a variable definition or declaration.
2094 @item font-lock-type-face
2095 @vindex font-lock-type-face
2096 Used (typically) for names of user-defined data types,
2097 where they are defined and where they are used.
2099 @item font-lock-constant-face
2100 @vindex font-lock-constant-face
2101 Used (typically) for constant names.
2103 @item font-lock-warning-face
2104 @vindex font-lock-warning-face
2105 Used (typically) for constructs that are peculiar, or that greatly
2106 change the meaning of other text. For example, this is used for
2107 @samp{;;;###autoload} cookies in Emacs Lisp, and for @code{#error}
2111 @node Syntactic Font Lock
2112 @subsection Syntactic Font Lock
2114 Font Lock mode can be used to update @code{syntax-table} properties
2115 automatically. This is useful in languages for which a single syntax
2116 table by itself is not sufficient.
2118 @defvar font-lock-syntactic-keywords
2119 This variable enables and controls syntactic Font Lock. Its value
2120 should be a list of elements of this form:
2123 (@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch})
2126 The parts of this element have the same meanings as in the corresponding
2127 sort of element of @code{font-lock-keywords},
2130 (@var{matcher} @var{subexp} @var{facename} @var{override} @var{laxmatch})
2133 However, instead of specifying the value @var{facename} to use for the
2134 @code{face} property, it specifies the value @var{syntax} to use for the
2135 @code{syntax-table} property. Here, @var{syntax} can be a variable
2136 whose value is a syntax table, a syntax entry of the form
2137 @code{(@var{syntax-code} . @var{matching-char})}, or an expression whose
2138 value is one of those two types.
2145 A @dfn{hook} is a variable where you can store a function or functions
2146 to be called on a particular occasion by an existing program. Emacs
2147 provides hooks for the sake of customization. Most often, hooks are set
2148 up in the init file (@pxref{Init File}), but Lisp programs can set them also.
2149 @xref{Standard Hooks}, for a list of standard hook variables.
2152 Most of the hooks in Emacs are @dfn{normal hooks}. These variables
2153 contain lists of functions to be called with no arguments. When the
2154 hook name ends in @samp{-hook}, that tells you it is normal. We try to
2155 make all hooks normal, as much as possible, so that you can use them in
2158 Every major mode function is supposed to run a normal hook called the
2159 @dfn{mode hook} as the last step of initialization. This makes it easy
2160 for a user to customize the behavior of the mode, by overriding the
2161 buffer-local variable assignments already made by the mode. But hooks
2162 are used in other contexts too. For example, the hook
2163 @code{suspend-hook} runs just before Emacs suspends itself
2164 (@pxref{Suspending Emacs}).
2166 The recommended way to add a hook function to a normal hook is by
2167 calling @code{add-hook} (see below). The hook functions may be any of
2168 the valid kinds of functions that @code{funcall} accepts (@pxref{What Is
2169 a Function}). Most normal hook variables are initially void;
2170 @code{add-hook} knows how to deal with this.
2172 @cindex abnormal hook
2173 If the hook variable's name does not end with @samp{-hook}, that
2174 indicates it is probably an @dfn{abnormal hook}. Then you should look at its
2175 documentation to see how to use the hook properly.
2177 If the variable's name ends in @samp{-functions} or @samp{-hooks},
2178 then the value is a list of functions, but it is abnormal in that either
2179 these functions are called with arguments or their values are used in
2180 some way. You can use @code{add-hook} to add a function to the list,
2181 but you must take care in writing the function. (A few of these
2182 variables are actually normal hooks which were named before we
2183 established the convention of using @samp{-hook} for them.)
2185 If the variable's name ends in @samp{-function}, then its value
2186 is just a single function, not a list of functions.
2188 Here's an example that uses a mode hook to turn on Auto Fill mode when
2189 in Lisp Interaction mode:
2192 (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
2195 At the appropriate time, Emacs uses the @code{run-hooks} function to
2196 run particular hooks. This function calls the hook functions that have
2197 been added with @code{add-hook}.
2199 @defun run-hooks &rest hookvars
2200 This function takes one or more hook variable names as arguments, and
2201 runs each hook in turn. Each argument should be a symbol that is a hook
2202 variable. These arguments are processed in the order specified.
2204 If a hook variable has a non-@code{nil} value, that value may be a
2205 function or a list of functions. If the value is a function (either a
2206 lambda expression or a symbol with a function definition), it is called.
2207 If it is a list, the elements are called, in order. The hook functions
2208 are called with no arguments. Nowadays, storing a single function in
2209 the hook variable is semi-obsolete; you should always use a list of
2212 For example, here's how @code{emacs-lisp-mode} runs its mode hook:
2215 (run-hooks 'emacs-lisp-mode-hook)
2219 @defun run-hook-with-args hook &rest args
2220 This function is the way to run an abnormal hook which passes arguments
2221 to the hook functions. It calls each of the hook functions, passing
2222 each of them the arguments @var{args}.
2225 @defun run-hook-with-args-until-failure hook &rest args
2226 This function is the way to run an abnormal hook which passes arguments
2227 to the hook functions, and stops as soon as any hook function fails. It
2228 calls each of the hook functions, passing each of them the arguments
2229 @var{args}, until some hook function returns @code{nil}. Then it stops,
2230 and returns @code{nil} if some hook function returned @code{nil}.
2231 Otherwise it returns a non-@code{nil} value.
2234 @defun run-hook-with-args-until-success hook &rest args
2235 This function is the way to run an abnormal hook which passes arguments
2236 to the hook functions, and stops as soon as any hook function succeeds.
2237 It calls each of the hook functions, passing each of them the arguments
2238 @var{args}, until some hook function returns non-@code{nil}. Then it
2239 stops, and returns whatever was returned by the last hook function
2243 @defun add-hook hook function &optional append local
2244 This function is the handy way to add function @var{function} to hook
2245 variable @var{hook}. The argument @var{function} may be any valid Lisp
2246 function with the proper number of arguments. For example,
2249 (add-hook 'text-mode-hook 'my-text-hook-function)
2253 adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
2255 You can use @code{add-hook} for abnormal hooks as well as for normal
2258 It is best to design your hook functions so that the order in which they
2259 are executed does not matter. Any dependence on the order is ``asking
2260 for trouble.'' However, the order is predictable: normally,
2261 @var{function} goes at the front of the hook list, so it will be
2262 executed first (barring another @code{add-hook} call). If the optional
2263 argument @var{append} is non-@code{nil}, the new hook function goes at
2264 the end of the hook list and will be executed last.
2266 If @var{local} is non-@code{nil}, that says to make the new hook
2267 function buffer-local in the current buffer. Before you can do this, you must
2268 make the hook itself buffer-local by calling @code{make-local-hook}
2269 (@strong{not} @code{make-local-variable}). If the hook itself is not
2270 buffer-local, then the value of @var{local} makes no difference---the
2271 hook function is always global.
2274 @defun remove-hook hook function &optional local
2275 This function removes @var{function} from the hook variable @var{hook}.
2277 If @var{local} is non-@code{nil}, that says to remove @var{function}
2278 from the buffer-local hook list instead of from the global hook list.
2279 If the hook variable itself is not buffer-local, then the value of
2280 @var{local} makes no difference.
2283 @defun make-local-hook hook
2284 This function makes the hook variable @code{hook} buffer-local in the
2285 current buffer. When a hook variable is buffer-local, it can have
2286 buffer-local and global hook functions, and @code{run-hooks} runs all of
2289 This function works by adding @code{t} as an element of the buffer-local
2290 value. That serves as a flag to use the hook functions listed in the default
2291 value of the hook variable, as well as those listed in the buffer-local value.
2292 Since @code{run-hooks} understands this flag, @code{make-local-hook}
2293 works with all normal hooks. It works for only some non-normal
2294 hooks---those whose callers have been updated to understand this meaning
2297 Do not use @code{make-local-variable} directly for hook variables; it is