2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002,
4 @c 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/modes
7 @node Modes, Documentation, Keymaps, Top
8 @chapter Major and Minor Modes
11 A @dfn{mode} is a set of definitions that customize Emacs and can be
12 turned on and off while you edit. There are two varieties of modes:
13 @dfn{major modes}, which are mutually exclusive and used for editing
14 particular kinds of text, and @dfn{minor modes}, which provide features
15 that users can enable individually.
17 This chapter describes how to write both major and minor modes, how to
18 indicate them in the mode line, and how they run hooks supplied by the
19 user. For related topics such as keymaps and syntax tables, see
20 @ref{Keymaps}, and @ref{Syntax Tables}.
23 * Hooks:: How to use hooks; how to write code that provides hooks.
24 * Major Modes:: Defining major modes.
25 * Minor Modes:: Defining minor modes.
26 * Mode Line Format:: Customizing the text that appears in the mode line.
27 * Imenu:: How a mode can provide a menu
28 of definitions in the buffer.
29 * Font Lock Mode:: How modes can highlight text according to syntax.
30 * Desktop Save Mode:: How modes can have buffer state saved between
38 A @dfn{hook} is a variable where you can store a function or functions
39 to be called on a particular occasion by an existing program. Emacs
40 provides hooks for the sake of customization. Most often, hooks are set
41 up in the init file (@pxref{Init File}), but Lisp programs can set them also.
42 @xref{Standard Hooks}, for a list of standard hook variables.
45 Most of the hooks in Emacs are @dfn{normal hooks}. These variables
46 contain lists of functions to be called with no arguments. By
47 convention, whenever the hook name ends in @samp{-hook}, that tells
48 you it is normal. We try to make all hooks normal, as much as
49 possible, so that you can use them in a uniform way.
51 Every major mode function is supposed to run a normal hook called
52 the @dfn{mode hook} as the one of the last steps of initialization.
53 This makes it easy for a user to customize the behavior of the mode,
54 by overriding the buffer-local variable assignments already made by
55 the mode. Most minor modes also run a mode hook at their end. But
56 hooks are used in other contexts too. For example, the hook
57 @code{suspend-hook} runs just before Emacs suspends itself
58 (@pxref{Suspending Emacs}).
60 The recommended way to add a hook function to a normal hook is by
61 calling @code{add-hook} (see below). The hook functions may be any of
62 the valid kinds of functions that @code{funcall} accepts (@pxref{What
63 Is a Function}). Most normal hook variables are initially void;
64 @code{add-hook} knows how to deal with this. You can add hooks either
65 globally or buffer-locally with @code{add-hook}.
68 If the hook variable's name does not end with @samp{-hook}, that
69 indicates it is probably an @dfn{abnormal hook}. Then you should look at its
70 documentation to see how to use the hook properly.
72 @dfn{Abnormal hooks} are hooks in which the functions are called
73 with arguments, or the return values are used in some way. By
74 convention, abnormal hook names end in @samp{-functions} or
75 @samp{-hooks}. You can use @code{add-hook} to add a function to the
76 list, but you must take care in writing the function.
78 If the variable's name ends in @samp{-function}, then its value
79 is just a single function, not a list of functions.
81 Here's an example that uses a mode hook to turn on Auto Fill mode when
82 in Lisp Interaction mode:
85 (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
88 At the appropriate time, Emacs uses the @code{run-hooks} function to
91 @defun run-hooks &rest hookvars
92 This function takes one or more normal hook variable names as
93 arguments, and runs each hook in turn. Each argument should be a
94 symbol that is a normal hook variable. These arguments are processed
95 in the order specified.
97 If a hook variable has a non-@code{nil} value, that value should be a
98 list of functions. Each function in this list is called,
99 consecutively, with no arguments.
101 A hook variable can also be a single function (either a lambda
102 expression or a symbol with a function definition) to be called. This
103 use is considered obsolete.
106 @defun run-hook-with-args hook &rest args
107 This function is the way to run an abnormal hook and always call all
108 of the hook functions. It calls each of the hook functions one by
109 one, passing each of them the arguments @var{args}.
112 @defun run-hook-with-args-until-failure hook &rest args
113 This function is the way to run an abnormal hook until one of the hook
114 functions fails. It calls each of the hook functions, passing each of
115 them the arguments @var{args}, until some hook function returns
116 @code{nil}. It then stops and returns @code{nil}. If none of the
117 hook functions return @code{nil}, it returns a non-@code{nil} value.
120 @defun run-hook-with-args-until-success hook &rest args
121 This function is the way to run an abnormal hook until a hook function
122 succeeds. It calls each of the hook functions, passing each of them
123 the arguments @var{args}, until some hook function returns
124 non-@code{nil}. Then it stops, and returns whatever was returned by
125 the last hook function that was called. If all hook functions return
126 @code{nil}, it returns @code{nil} as well.
129 @defun add-hook hook function &optional append local
130 This function is the handy way to add function @var{function} to hook
131 variable @var{hook}. You can use it for abnormal hooks as well as for
132 normal hooks. @var{function} can be any Lisp function that can accept
133 the proper number of arguments for @var{hook}. For example,
136 (add-hook 'text-mode-hook 'my-text-hook-function)
140 adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
142 If @var{function} is already present in @var{hook} (comparing using
143 @code{equal}), then @code{add-hook} does not add it a second time.
145 It is best to design your hook functions so that the order in which they
146 are executed does not matter. Any dependence on the order is ``asking
147 for trouble.'' However, the order is predictable: normally,
148 @var{function} goes at the front of the hook list, so it will be
149 executed first (barring another @code{add-hook} call). If the optional
150 argument @var{append} is non-@code{nil}, the new hook function goes at
151 the end of the hook list and will be executed last.
153 @code{add-hook} can handle the cases where @var{hook} is void or its
154 value is a single function; it sets or changes the value to a list of
157 If @var{local} is non-@code{nil}, that says to add @var{function} to
158 the buffer-local hook list instead of to the global hook list. If
159 needed, this makes the hook buffer-local and adds @code{t} to the
160 buffer-local value. The latter acts as a flag to run the hook
161 functions in the default value as well as in the local value.
164 @defun remove-hook hook function &optional local
165 This function removes @var{function} from the hook variable
166 @var{hook}. It compares @var{function} with elements of @var{hook}
167 using @code{equal}, so it works for both symbols and lambda
170 If @var{local} is non-@code{nil}, that says to remove @var{function}
171 from the buffer-local hook list instead of from the global hook list.
178 Major modes specialize Emacs for editing particular kinds of text.
179 Each buffer has only one major mode at a time. For each major mode
180 there is a function to switch to that mode in the current buffer; its
181 name should end in @samp{-mode}. These functions work by setting
182 buffer-local variable bindings and other data associated with the
183 buffer, such as a local keymap. The effect lasts until you switch
184 to another major mode in the same buffer.
187 * Major Mode Basics::
188 * Major Mode Conventions:: Coding conventions for keymaps, etc.
189 * Auto Major Mode:: How Emacs chooses the major mode automatically.
190 * Mode Help:: Finding out how to use a mode.
191 * Derived Modes:: Defining a new major mode based on another major
193 * Generic Modes:: Defining a simple major mode that supports
194 comment syntax and Font Lock mode.
195 * Mode Hooks:: Hooks run at the end of major mode functions.
196 * Example Major Modes:: Text mode and Lisp modes.
199 @node Major Mode Basics
200 @subsection Major Mode Basics
201 @cindex Fundamental mode
203 The least specialized major mode is called @dfn{Fundamental mode}.
204 This mode has no mode-specific definitions or variable settings, so each
205 Emacs command behaves in its default manner, and each option is in its
206 default state. All other major modes redefine various keys and options.
207 For example, Lisp Interaction mode provides special key bindings for
208 @kbd{C-j} (@code{eval-print-last-sexp}), @key{TAB}
209 (@code{lisp-indent-line}), and other keys.
211 When you need to write several editing commands to help you perform a
212 specialized editing task, creating a new major mode is usually a good
213 idea. In practice, writing a major mode is easy (in contrast to
214 writing a minor mode, which is often difficult).
216 If the new mode is similar to an old one, it is often unwise to
217 modify the old one to serve two purposes, since it may become harder
218 to use and maintain. Instead, copy and rename an existing major mode
219 definition and alter the copy---or use @code{define-derived-mode} to
220 define a @dfn{derived mode} (@pxref{Derived Modes}). For example,
221 Rmail Edit mode is a major mode that is very similar to Text mode
222 except that it provides two additional commands. Its definition is
223 distinct from that of Text mode, but uses that of Text mode.
225 Even if the new mode is not an obvious derivative of any other mode,
226 it is convenient to use @code{define-derived-mode} with a @code{nil}
227 parent argument, since it automatically enforces the most important
228 coding conventions for you.
230 For a very simple programming language major mode that handles
231 comments and fontification, you can use @code{define-generic-mode}.
232 @xref{Generic Modes}.
234 Rmail Edit mode offers an example of changing the major mode
235 temporarily for a buffer, so it can be edited in a different way (with
236 ordinary Emacs commands rather than Rmail commands). In such cases, the
237 temporary major mode usually provides a command to switch back to the
238 buffer's usual mode (Rmail mode, in this case). You might be tempted to
239 present the temporary redefinitions inside a recursive edit and restore
240 the usual ones when the user exits; but this is a bad idea because it
241 constrains the user's options when it is done in more than one buffer:
242 recursive edits must be exited most-recently-entered first. Using an
243 alternative major mode avoids this limitation. @xref{Recursive
246 The standard GNU Emacs Lisp library directory tree contains the code
247 for several major modes, in files such as @file{text-mode.el},
248 @file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
249 @file{rmail.el}. They are found in various subdirectories of the
250 @file{lisp} directory. You can study these libraries to see how modes
251 are written. Text mode is perhaps the simplest major mode aside from
252 Fundamental mode. Rmail mode is a complicated and specialized mode.
254 @node Major Mode Conventions
255 @subsection Major Mode Conventions
257 The code for existing major modes follows various coding conventions,
258 including conventions for local keymap and syntax table initialization,
259 global names, and hooks. Please follow these conventions when you
260 define a new major mode.
262 This list of conventions is only partial, because each major mode
263 should aim for consistency in general with other Emacs major modes.
264 This makes Emacs as a whole more coherent. It is impossible to list
265 here all the possible points where this issue might come up; if the
266 Emacs developers point out an area where your major mode deviates from
267 the usual conventions, please make it compatible.
271 Define a command whose name ends in @samp{-mode}, with no arguments,
272 that switches to the new mode in the current buffer. This command
273 should set up the keymap, syntax table, and buffer-local variables in an
274 existing buffer, without changing the buffer's contents.
277 Write a documentation string for this command that describes the
278 special commands available in this mode. @kbd{C-h m}
279 (@code{describe-mode}) in your mode will display this string.
281 The documentation string may include the special documentation
282 substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
283 @samp{\<@var{keymap}>}, which enable the documentation to adapt
284 automatically to the user's own key bindings. @xref{Keys in
288 The major mode command should start by calling
289 @code{kill-all-local-variables}. This runs the normal hook
290 @code{change-major-mode-hook}, then gets rid of the buffer-local
291 variables of the major mode previously in effect. @xref{Creating
295 The major mode command should set the variable @code{major-mode} to the
296 major mode command symbol. This is how @code{describe-mode} discovers
297 which documentation to print.
300 The major mode command should set the variable @code{mode-name} to the
301 ``pretty'' name of the mode, as a string. This string appears in the
305 @cindex functions in modes
306 Since all global names are in the same name space, all the global
307 variables, constants, and functions that are part of the mode should
308 have names that start with the major mode name (or with an abbreviation
309 of it if the name is long). @xref{Coding Conventions}.
312 In a major mode for editing some kind of structured text, such as a
313 programming language, indentation of text according to structure is
314 probably useful. So the mode should set @code{indent-line-function}
315 to a suitable function, and probably customize other variables
319 @cindex keymaps in modes
320 The major mode should usually have its own keymap, which is used as the
321 local keymap in all buffers in that mode. The major mode command should
322 call @code{use-local-map} to install this local map. @xref{Active
323 Keymaps}, for more information.
325 This keymap should be stored permanently in a global variable named
326 @code{@var{modename}-mode-map}. Normally the library that defines the
327 mode sets this variable.
329 @xref{Tips for Defining}, for advice about how to write the code to set
330 up the mode's keymap variable.
333 The key sequences bound in a major mode keymap should usually start with
334 @kbd{C-c}, followed by a control character, a digit, or @kbd{@{},
335 @kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}. The other punctuation
336 characters are reserved for minor modes, and ordinary letters are
339 A major mode can also rebind the keys @kbd{M-n}, @kbd{M-p} and
340 @kbd{M-s}. The bindings for @kbd{M-n} and @kbd{M-p} should normally
341 be some kind of ``moving forward and backward,'' but this does not
342 necessarily mean cursor motion.
344 It is legitimate for a major mode to rebind a standard key sequence if
345 it provides a command that does ``the same job'' in a way better
346 suited to the text this mode is used for. For example, a major mode
347 for editing a programming language might redefine @kbd{C-M-a} to
348 ``move to the beginning of a function'' in a way that works better for
351 It is also legitimate for a major mode to rebind a standard key
352 sequence whose standard meaning is rarely useful in that mode. For
353 instance, minibuffer modes rebind @kbd{M-r}, whose standard meaning is
354 rarely of any use in the minibuffer. Major modes such as Dired or
355 Rmail that do not allow self-insertion of text can reasonably redefine
356 letters and other printing characters as special commands.
359 Major modes modes for editing text should not define @key{RET} to do
360 anything other than insert a newline. The command to insert a newline
361 and then indent is @kbd{C-j}. It is ok for more specialized modes,
362 such as Info mode, to redefine @key{RET} to something else.
365 Major modes should not alter options that are primarily a matter of user
366 preference, such as whether Auto-Fill mode is enabled. Leave this to
367 each user to decide. However, a major mode should customize other
368 variables so that Auto-Fill mode will work usefully @emph{if} the user
372 @cindex syntax tables in modes
373 The mode may have its own syntax table or may share one with other
374 related modes. If it has its own syntax table, it should store this in
375 a variable named @code{@var{modename}-mode-syntax-table}. @xref{Syntax
379 If the mode handles a language that has a syntax for comments, it should
380 set the variables that define the comment syntax. @xref{Options for
381 Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}.
384 @cindex abbrev tables in modes
385 The mode may have its own abbrev table or may share one with other
386 related modes. If it has its own abbrev table, it should store this
387 in a variable named @code{@var{modename}-mode-abbrev-table}. If the
388 major mode command defines any abbrevs itself, it should pass @code{t}
389 for the @var{system-flag} argument to @code{define-abbrev}.
390 @xref{Defining Abbrevs}.
393 The mode should specify how to do highlighting for Font Lock mode, by
394 setting up a buffer-local value for the variable
395 @code{font-lock-defaults} (@pxref{Font Lock Mode}).
398 The mode should specify how Imenu should find the definitions or
399 sections of a buffer, by setting up a buffer-local value for the
400 variable @code{imenu-generic-expression}, for the two variables
401 @code{imenu-prev-index-position-function} and
402 @code{imenu-extract-index-name-function}, or for the variable
403 @code{imenu-create-index-function} (@pxref{Imenu}).
406 The mode can specify a local value for
407 @code{eldoc-documentation-function} to tell ElDoc mode how to handle
411 Use @code{defvar} or @code{defcustom} to set mode-related variables, so
412 that they are not reinitialized if they already have a value. (Such
413 reinitialization could discard customizations made by the user.)
416 @cindex buffer-local variables in modes
417 To make a buffer-local binding for an Emacs customization variable, use
418 @code{make-local-variable} in the major mode command, not
419 @code{make-variable-buffer-local}. The latter function would make the
420 variable local to every buffer in which it is subsequently set, which
421 would affect buffers that do not use this mode. It is undesirable for a
422 mode to have such global effects. @xref{Buffer-Local Variables}.
424 With rare exceptions, the only reasonable way to use
425 @code{make-variable-buffer-local} in a Lisp package is for a variable
426 which is used only within that package. Using it on a variable used by
427 other packages would interfere with them.
431 @cindex major mode hook
432 Each major mode should have a normal @dfn{mode hook} named
433 @code{@var{modename}-mode-hook}. The very last thing the major mode command
434 should do is to call @code{run-mode-hooks}. This runs the mode hook,
435 and then runs the normal hook @code{after-change-major-mode-hook}.
439 The major mode command may start by calling some other major mode
440 command (called the @dfn{parent mode}) and then alter some of its
441 settings. A mode that does this is called a @dfn{derived mode}. The
442 recommended way to define one is to use @code{define-derived-mode},
443 but this is not required. Such a mode should call the parent mode
444 command inside a @code{delay-mode-hooks} form. (Using
445 @code{define-derived-mode} does this automatically.) @xref{Derived
446 Modes}, and @ref{Mode Hooks}.
449 If something special should be done if the user switches a buffer from
450 this mode to any other major mode, this mode can set up a buffer-local
451 value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}).
454 If this mode is appropriate only for specially-prepared text, then the
455 major mode command symbol should have a property named @code{mode-class}
456 with value @code{special}, put on as follows:
458 @kindex mode-class @r{(property)}
459 @cindex @code{special}
461 (put 'funny-mode 'mode-class 'special)
465 This tells Emacs that new buffers created while the current buffer is
466 in Funny mode should not inherit Funny mode, in case
467 @code{default-major-mode} is @code{nil}. Modes such as Dired, Rmail,
468 and Buffer List use this feature.
471 If you want to make the new mode the default for files with certain
472 recognizable names, add an element to @code{auto-mode-alist} to select
473 the mode for those file names (@pxref{Auto Major Mode}). If you
474 define the mode command to autoload, you should add this element in
475 the same file that calls @code{autoload}. If you use an autoload
476 cookie for the mode command, you can also use an autoload cookie for
477 the form that adds the element (@pxref{autoload cookie}). If you do
478 not autoload the mode command, it is sufficient to add the element in
479 the file that contains the mode definition.
482 In the comments that document the file, you should provide a sample
483 @code{autoload} form and an example of how to add to
484 @code{auto-mode-alist}, that users can include in their init files
489 The top-level forms in the file defining the mode should be written so
490 that they may be evaluated more than once without adverse consequences.
491 Even if you never load the file more than once, someone else will.
494 @node Auto Major Mode
495 @subsection How Emacs Chooses a Major Mode
497 Based on information in the file name or in the file itself, Emacs
498 automatically selects a major mode for the new buffer when a file is
499 visited. It also processes local variables specified in the file text.
501 @deffn Command fundamental-mode
502 Fundamental mode is a major mode that is not specialized for anything
503 in particular. Other major modes are defined in effect by comparison
504 with this one---their definitions say what to change, starting from
505 Fundamental mode. The @code{fundamental-mode} function does @emph{not}
506 run any mode hooks; you're not supposed to customize it. (If you want Emacs
507 to behave differently in Fundamental mode, change the @emph{global}
511 @deffn Command normal-mode &optional find-file
512 This function establishes the proper major mode and buffer-local variable
513 bindings for the current buffer. First it calls @code{set-auto-mode}
514 (see below), then it runs @code{hack-local-variables} to parse, and
515 bind or evaluate as appropriate, the file's local variables
516 (@pxref{File Local Variables}).
518 If the @var{find-file} argument to @code{normal-mode} is non-@code{nil},
519 @code{normal-mode} assumes that the @code{find-file} function is calling
520 it. In this case, it may process local variables in the @samp{-*-}
521 line or at the end of the file. The variable
522 @code{enable-local-variables} controls whether to do so. @xref{File
523 Variables, , Local Variables in Files, emacs, The GNU Emacs Manual},
524 for the syntax of the local variables section of a file.
526 If you run @code{normal-mode} interactively, the argument
527 @var{find-file} is normally @code{nil}. In this case,
528 @code{normal-mode} unconditionally processes any file local variables.
530 If @code{normal-mode} processes the local variables list and this list
531 specifies a major mode, that mode overrides any mode chosen by
532 @code{set-auto-mode}. If neither @code{set-auto-mode} nor
533 @code{hack-local-variables} specify a major mode, the buffer stays in
534 the major mode determined by @code{default-major-mode} (see below).
536 @cindex file mode specification error
537 @code{normal-mode} uses @code{condition-case} around the call to the
538 major mode function, so errors are caught and reported as a @samp{File
539 mode specification error}, followed by the original error message.
542 @defun set-auto-mode &optional keep-mode-if-same
543 @cindex visited file mode
544 This function selects the major mode that is appropriate for the
545 current buffer. It bases its decision (in order of precedence) on
546 the @w{@samp{-*-}} line, on the @w{@samp{#!}} line (using
547 @code{interpreter-mode-alist}), on the text at the beginning of the
548 buffer (using @code{magic-mode-alist}), and finally on the visited
549 file name (using @code{auto-mode-alist}). @xref{Choosing Modes, , How
550 Major Modes are Chosen, emacs, The GNU Emacs Manual}. However, this
551 function does not look for the @samp{mode:} local variable near the
552 end of a file; the @code{hack-local-variables} function does that.
553 If @code{enable-local-variables} is @code{nil}, @code{set-auto-mode}
554 does not check the @w{@samp{-*-}} line for a mode tag either.
556 If @var{keep-mode-if-same} is non-@code{nil}, this function does not
557 call the mode command if the buffer is already in the proper major
558 mode. For instance, @code{set-visited-file-name} sets this to
559 @code{t} to avoid killing buffer local variables that the user may
563 @defopt default-major-mode
564 This variable holds the default major mode for new buffers. The
565 standard value is @code{fundamental-mode}.
567 If the value of @code{default-major-mode} is @code{nil}, Emacs uses
568 the (previously) current buffer's major mode as the default major mode
569 of a new buffer. However, if that major mode symbol has a @code{mode-class}
570 property with value @code{special}, then it is not used for new buffers;
571 Fundamental mode is used instead. The modes that have this property are
572 those such as Dired and Rmail that are useful only with text that has
573 been specially prepared.
576 @defun set-buffer-major-mode buffer
577 This function sets the major mode of @var{buffer} to the value of
578 @code{default-major-mode}; if that variable is @code{nil}, it uses the
579 current buffer's major mode (if that is suitable). As an exception,
580 if @var{buffer}'s name is @samp{*scratch*}, it sets the mode to
581 @code{initial-major-mode}.
583 The low-level primitives for creating buffers do not use this function,
584 but medium-level commands such as @code{switch-to-buffer} and
585 @code{find-file-noselect} use it whenever they create buffers.
588 @defopt initial-major-mode
589 @cindex @samp{*scratch*}
590 The value of this variable determines the major mode of the initial
591 @samp{*scratch*} buffer. The value should be a symbol that is a major
592 mode command. The default value is @code{lisp-interaction-mode}.
595 @defvar interpreter-mode-alist
596 This variable specifies major modes to use for scripts that specify a
597 command interpreter in a @samp{#!} line. Its value is an alist with
598 elements of the form @code{(@var{interpreter} . @var{mode})}; for
599 example, @code{("perl" . perl-mode)} is one element present by
600 default. The element says to use mode @var{mode} if the file
601 specifies an interpreter which matches @var{interpreter}.
604 @defvar magic-mode-alist
605 This variable's value is an alist with elements of the form
606 @code{(@var{regexp} . @var{function})}, where @var{regexp} is a
607 regular expression and @var{function} is a function or @code{nil}.
608 After visiting a file, @code{set-auto-mode} calls @var{function} if
609 the text at the beginning of the buffer matches @var{regexp} and
610 @var{function} is non-@code{nil}; if @var{function} is @code{nil},
611 @code{auto-mode-alist} gets to decide the mode.
614 @defvar auto-mode-alist
615 This variable contains an association list of file name patterns
616 (regular expressions) and corresponding major mode commands. Usually,
617 the file name patterns test for suffixes, such as @samp{.el} and
618 @samp{.c}, but this need not be the case. An ordinary element of the
619 alist looks like @code{(@var{regexp} . @var{mode-function})}.
625 (("\\`/tmp/fol/" . text-mode)
626 ("\\.texinfo\\'" . texinfo-mode)
627 ("\\.texi\\'" . texinfo-mode)
630 ("\\.el\\'" . emacs-lisp-mode)
637 When you visit a file whose expanded file name (@pxref{File Name
638 Expansion}), with version numbers and backup suffixes removed using
639 @code{file-name-sans-versions} (@pxref{File Name Components}), matches
640 a @var{regexp}, @code{set-auto-mode} calls the corresponding
641 @var{mode-function}. This feature enables Emacs to select the proper
642 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))
672 @subsection Getting Help about a Major Mode
674 @cindex help for major mode
675 @cindex documentation for major mode
677 The @code{describe-mode} function is used to provide information
678 about major modes. It is normally called with @kbd{C-h m}. The
679 @code{describe-mode} function uses the value of @code{major-mode},
680 which is why every major mode function needs to set the
681 @code{major-mode} variable.
683 @deffn Command describe-mode
684 This function displays the documentation of the current major mode.
686 The @code{describe-mode} function calls the @code{documentation}
687 function using the value of @code{major-mode} as an argument. Thus, it
688 displays the documentation string of the major mode function.
689 (@xref{Accessing Documentation}.)
693 This buffer-local variable holds the symbol for the current buffer's
694 major mode. This symbol should have a function definition that is the
695 command to switch to that major mode. The @code{describe-mode}
696 function uses the documentation string of the function as the
697 documentation of the major mode.
701 @subsection Defining Derived Modes
704 It's often useful to define a new major mode in terms of an existing
705 one. An easy way to do this is to use @code{define-derived-mode}.
707 @defmac define-derived-mode variant parent name docstring keyword-args@dots{} body@dots{}
708 This construct defines @var{variant} as a major mode command, using
709 @var{name} as the string form of the mode name. @var{variant} and
710 @var{parent} should be unquoted symbols.
712 The new command @var{variant} is defined to call the function
713 @var{parent}, then override certain aspects of that parent mode:
717 The new mode has its own sparse keymap, named
718 @code{@var{variant}-map}. @code{define-derived-mode}
719 makes the parent mode's keymap the parent of the new map, unless
720 @code{@var{variant}-map} is already set and already has a parent.
723 The new mode has its own syntax table, kept in the variable
724 @code{@var{variant}-syntax-table}, unless you override this using the
725 @code{:syntax-table} keyword (see below). @code{define-derived-mode}
726 makes the parent mode's syntax-table the parent of
727 @code{@var{variant}-syntax-table}, unless the latter is already set
728 and already has a parent different from the standard syntax table.
731 The new mode has its own abbrev table, kept in the variable
732 @code{@var{variant}-abbrev-table}, unless you override this using the
733 @code{:abbrev-table} keyword (see below).
736 The new mode has its own mode hook, @code{@var{variant}-hook}. It
737 runs this hook, after running the hooks of its ancestor modes, with
738 @code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}.
741 In addition, you can specify how to override other aspects of
742 @var{parent} with @var{body}. The command @var{variant}
743 evaluates the forms in @var{body} after setting up all its usual
744 overrides, just before running the mode hooks.
746 You can also specify @code{nil} for @var{parent}. This gives the new
747 mode no parent. Then @code{define-derived-mode} behaves as described
748 above, but, of course, omits all actions connected with @var{parent}.
750 The argument @var{docstring} specifies the documentation string for
751 the new mode. @code{define-derived-mode} adds some general
752 information about the mode's hook, followed by the mode's keymap, at
753 the end of this docstring. If you omit @var{docstring},
754 @code{define-derived-mode} generates a documentation string.
756 The @var{keyword-args} are pairs of keywords and values. The values
757 are evaluated. The following keywords are currently supported:
761 You can use this to explicitly specify a syntax table for the new
762 mode. If you specify a @code{nil} value, the new mode uses the same
763 syntax table as @var{parent}, or the standard syntax table if
764 @var{parent} is @code{nil}. (Note that this does @emph{not} follow
765 the convention used for non-keyword arguments that a @code{nil} value
766 is equivalent with not specifying the argument.)
769 You can use this to explicitly specify an abbrev table for the new
770 mode. If you specify a @code{nil} value, the new mode uses the same
771 abbrev table as @var{parent}, or @code{fundamental-mode-abbrev-table}
772 if @var{parent} is @code{nil}. (Again, a @code{nil} value is
773 @emph{not} equivalent to not specifying this keyword.)
776 If this is specified, the value should be the customization group for
777 this mode. (Not all major modes have one.) Only the (still
778 experimental and unadvertised) command @code{customize-mode} currently
779 uses this. @code{define-derived-mode} does @emph{not} automatically
780 define the specified customization group.
783 Here is a hypothetical example:
786 (define-derived-mode hypertext-mode
787 text-mode "Hypertext"
788 "Major mode for hypertext.
789 \\@{hypertext-mode-map@}"
790 (setq case-fold-search nil))
792 (define-key hypertext-mode-map
793 [down-mouse-3] 'do-hyper-link)
796 Do not write an @code{interactive} spec in the definition;
797 @code{define-derived-mode} does that automatically.
801 @subsection Generic Modes
804 @dfn{Generic modes} are simple major modes with basic support for
805 comment syntax and Font Lock mode. To define a generic mode, use the
806 macro @code{define-generic-mode}. See the file @file{generic-x.el}
807 for some examples of the use of @code{define-generic-mode}.
809 @defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring
810 This macro creates a new generic mode. The argument @var{mode} (an
811 unquoted symbol) is the major mode command. The optional argument
812 @var{docstring} is the documentation for the mode command. If you do
813 not supply it, @code{define-generic-mode} uses a default documentation
816 @var{comment-list} is a list in which each element is either a
817 character, a string of one or two characters, or a cons cell. A
818 character or a string is set up in the mode's syntax table as a
819 ``comment starter.'' If the entry is a cons cell, the @sc{car} is set
820 up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.''
821 (Use @code{nil} for the latter if you want comments to end at the end
822 of the line.) Note that the syntax table has limitations about what
823 comment starters and enders are actually possible. @xref{Syntax
826 @var{keyword-list} is a list of keywords to highlight with
827 @code{font-lock-keyword-face}. Each keyword should be a string.
828 @var{font-lock-list} is a list of additional expressions to highlight.
829 Each element of this list should have the same form as an element of
830 @code{font-lock-keywords}. @xref{Search-based Fontification}.
832 @var{auto-mode-list} is a list of regular expressions to add to the
833 variable @code{auto-mode-alist}. These regular expressions are added
834 when Emacs runs the macro expansion.
836 @var{function-list} is a list of functions to call to do some
837 additional setup. The mode command calls these functions just before
838 it runs the mode hook variable @code{@var{mode}-hook}.
842 @subsection Mode Hooks
844 The two last things a major mode function should do is run its mode
845 hook and finally the mode independent normal hook
846 @code{after-change-major-mode-hook}. If the major mode is a derived
847 mode, that is if it calls another major mode (the parent mode) in its
848 body, then the parent's mode hook is run just before the derived
849 mode's hook. Neither the parent's mode hook nor
850 @code{after-change-major-mode-hook} are run at the end of the actual
851 call to the parent mode. This applies recursively if the parent mode
852 has itself a parent. That is, the mode hooks of all major modes
853 called directly or indirectly by the major mode function are all run
854 in sequence at the end, just before
855 @code{after-change-major-mode-hook}.
857 These conventions are new in Emacs 22, and some major modes
858 implemented by users do not follow them yet. So if you put a function
859 onto @code{after-change-major-mode-hook}, keep in mind that some modes
860 will fail to run it. If a user complains about that, you can respond,
861 ``That major mode fails to follow Emacs conventions, and that's why it
862 fails to work. Please fix the major mode.'' In most cases, that is
863 good enough, so go ahead and use @code{after-change-major-mode-hook}.
864 However, if a certain feature needs to be completely reliable,
865 it should not use @code{after-change-major-mode-hook} as of yet.
867 When you defined a major mode using @code{define-derived-mode}, it
868 automatically makes sure these conventions are followed. If you
869 define a major mode ``from scratch,'' not using
870 @code{define-derived-mode}, make sure the major mode command follows
871 these and other conventions. @xref{Major Mode Conventions}. You use
872 these functions to do it properly.
874 @defun run-mode-hooks &rest hookvars
875 Major modes should run their mode hook using this function. It is
876 similar to @code{run-hooks} (@pxref{Hooks}), but it also runs
877 @code{after-change-major-mode-hook}.
879 When the call to this function is dynamically inside a
880 @code{delay-mode-hooks} form, this function does not run any hooks.
881 Instead, it arranges for the next call to @code{run-mode-hooks} to run
885 @defmac delay-mode-hooks body@dots{}
886 This macro executes @var{body} like @code{progn}, but all calls to
887 @code{run-mode-hooks} inside @var{body} delay running their hooks.
888 They will be run by the first call to @code{run-mode-hooks} after exit
889 from @code{delay-mode-hooks}. This is the proper way for a major mode
890 command to invoke its parent mode.
893 @defvar after-change-major-mode-hook
894 Every major mode function should run this normal hook at its very end.
895 It normally does not need to do so explicitly. Indeed, a major mode
896 function should normally run its mode hook with @code{run-mode-hooks}
897 as the very last thing it does, and the last thing
898 @code{run-mode-hooks} does is run @code{after-change-major-mode-hook}.
901 @node Example Major Modes
902 @subsection Major Mode Examples
904 Text mode is perhaps the simplest mode besides Fundamental mode.
905 Here are excerpts from @file{text-mode.el} that illustrate many of
906 the conventions listed above:
910 ;; @r{Create the syntax table for this mode.}
911 (defvar text-mode-syntax-table
912 (let ((st (make-syntax-table)))
913 (modify-syntax-entry ?\" ". " st)
914 (modify-syntax-entry ?\\ ". " st)
915 ;; Add `p' so M-c on `hello' leads to `Hello', not `hello'.
916 (modify-syntax-entry ?' "w p" st)
918 "Syntax table used while in `text-mode'.")
921 ;; @r{Create the keymap for this mode.}
923 (defvar text-mode-map
924 (let ((map (make-sparse-keymap)))
925 (define-key map "\e\t" 'ispell-complete-word)
926 (define-key map "\es" 'center-line)
927 (define-key map "\eS" 'center-paragraph)
929 "Keymap for `text-mode'.
930 Many other modes, such as Mail mode, Outline mode
931 and Indented Text mode, inherit all the commands
932 defined in this map.")
936 Here is how the actual mode command is defined now:
940 (define-derived-mode text-mode nil "Text"
941 "Major mode for editing text written for humans to read.
942 In this mode, paragraphs are delimited only by blank or white lines.
943 You can thus get the full benefit of adaptive filling
944 (see the variable `adaptive-fill-mode').
946 Turning on Text mode runs the normal hook `text-mode-hook'."
949 (make-local-variable 'text-mode-variant)
950 (setq text-mode-variant t)
951 ;; @r{These two lines are a feature added recently.}
952 (set (make-local-variable 'require-final-newline)
953 mode-require-final-newline)
954 (set (make-local-variable 'indent-line-function) 'indent-relative))
958 But here is how it was defined formerly, before
959 @code{define-derived-mode} existed:
963 ;; @r{This isn't needed nowadays, since @code{define-derived-mode} does it.}
964 (defvar text-mode-abbrev-table nil
965 "Abbrev table used while in text mode.")
966 (define-abbrev-table 'text-mode-abbrev-table ())
971 "Major mode for editing text intended for humans to read...
972 Special commands: \\@{text-mode-map@}
975 Turning on text-mode runs the hook `text-mode-hook'."
977 (kill-all-local-variables)
978 (use-local-map text-mode-map)
981 (setq local-abbrev-table text-mode-abbrev-table)
982 (set-syntax-table text-mode-syntax-table)
985 ;; @r{These four lines are absent from the current version}
986 ;; @r{not because this is done some other way, but rather}
987 ;; @r{because nowadays Text mode uses the normal definition of paragraphs.}
988 (make-local-variable 'paragraph-start)
989 (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter))
990 (make-local-variable 'paragraph-separate)
991 (setq paragraph-separate paragraph-start)
992 (make-local-variable 'indent-line-function)
993 (setq indent-line-function 'indent-relative-maybe)
996 (setq mode-name "Text")
997 (setq major-mode 'text-mode)
998 (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
999 ; @r{customize the mode with a hook.}
1003 @cindex @file{lisp-mode.el}
1004 The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
1005 Interaction mode) have more features than Text mode and the code is
1006 correspondingly more complicated. Here are excerpts from
1007 @file{lisp-mode.el} that illustrate how these modes are written.
1009 @cindex syntax table example
1012 ;; @r{Create mode-specific table variables.}
1013 (defvar lisp-mode-syntax-table nil "")
1014 (defvar lisp-mode-abbrev-table nil "")
1018 (defvar emacs-lisp-mode-syntax-table
1019 (let ((table (make-syntax-table)))
1024 ;; @r{Set syntax of chars up to @samp{0} to say they are}
1025 ;; @r{part of symbol names but not words.}
1026 ;; @r{(The digit @samp{0} is @code{48} in the @acronym{ASCII} character set.)}
1028 (modify-syntax-entry i "_ " table)
1030 ;; @r{@dots{} similar code follows for other character ranges.}
1033 ;; @r{Then set the syntax codes for characters that are special in Lisp.}
1034 (modify-syntax-entry ? " " table)
1035 (modify-syntax-entry ?\t " " table)
1036 (modify-syntax-entry ?\f " " table)
1037 (modify-syntax-entry ?\n "> " table)
1040 ;; @r{Give CR the same syntax as newline, for selective-display.}
1041 (modify-syntax-entry ?\^m "> " table)
1042 (modify-syntax-entry ?\; "< " table)
1043 (modify-syntax-entry ?` "' " table)
1044 (modify-syntax-entry ?' "' " table)
1045 (modify-syntax-entry ?, "' " table)
1048 ;; @r{@dots{}likewise for many other characters@dots{}}
1049 (modify-syntax-entry ?\( "() " table)
1050 (modify-syntax-entry ?\) ")( " table)
1051 (modify-syntax-entry ?\[ "(] " table)
1052 (modify-syntax-entry ?\] ")[ " table))
1056 ;; @r{Create an abbrev table for lisp-mode.}
1057 (define-abbrev-table 'lisp-mode-abbrev-table ())
1061 Much code is shared among the three Lisp modes. The following
1062 function sets various variables; it is called by each of the major Lisp
1067 (defun lisp-mode-variables (lisp-syntax)
1069 (set-syntax-table lisp-mode-syntax-table))
1070 (setq local-abbrev-table lisp-mode-abbrev-table)
1075 Functions such as @code{forward-paragraph} use the value of the
1076 @code{paragraph-start} variable. Since Lisp code is different from
1077 ordinary text, the @code{paragraph-start} variable needs to be set
1078 specially to handle Lisp. Also, comments are indented in a special
1079 fashion in Lisp and the Lisp modes need their own mode-specific
1080 @code{comment-indent-function}. The code to set these variables is the
1081 rest of @code{lisp-mode-variables}.
1085 (make-local-variable 'paragraph-start)
1086 (setq paragraph-start (concat page-delimiter "\\|$" ))
1087 (make-local-variable 'paragraph-separate)
1088 (setq paragraph-separate paragraph-start)
1092 (make-local-variable 'comment-indent-function)
1093 (setq comment-indent-function 'lisp-comment-indent))
1098 Each of the different Lisp modes has a slightly different keymap. For
1099 example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other
1100 Lisp modes do not. However, all Lisp modes have some commands in
1101 common. The following code sets up the common commands:
1105 (defvar shared-lisp-mode-map ()
1106 "Keymap for commands shared by all sorts of Lisp modes.")
1108 ;; @r{Putting this @code{if} after the @code{defvar} is an older style.}
1109 (if shared-lisp-mode-map
1111 (setq shared-lisp-mode-map (make-sparse-keymap))
1112 (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp)
1113 (define-key shared-lisp-mode-map "\177"
1114 'backward-delete-char-untabify))
1119 And here is the code to set up the keymap for Lisp mode:
1123 (defvar lisp-mode-map ()
1124 "Keymap for ordinary Lisp mode...")
1128 (setq lisp-mode-map (make-sparse-keymap))
1129 (set-keymap-parent lisp-mode-map shared-lisp-mode-map)
1130 (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun)
1131 (define-key lisp-mode-map "\C-c\C-z" 'run-lisp))
1135 Finally, here is the complete major mode function definition for
1141 "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
1143 Delete converts tabs to spaces as it moves back.
1144 Blank lines separate paragraphs. Semicolons start comments.
1146 Note that `run-lisp' may be used either to start an inferior Lisp job
1147 or to switch back to an existing one.
1151 Entry to this mode calls the value of `lisp-mode-hook'
1152 if that value is non-nil."
1154 (kill-all-local-variables)
1157 (use-local-map lisp-mode-map) ; @r{Select the mode's keymap.}
1158 (setq major-mode 'lisp-mode) ; @r{This is how @code{describe-mode}}
1159 ; @r{finds out what to describe.}
1160 (setq mode-name "Lisp") ; @r{This goes into the mode line.}
1161 (lisp-mode-variables t) ; @r{This defines various variables.}
1162 (make-local-variable 'comment-start-skip)
1163 (setq comment-start-skip
1164 "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *")
1165 (make-local-variable 'font-lock-keywords-case-fold-search)
1166 (setq font-lock-keywords-case-fold-search t)
1169 (setq imenu-case-fold-search t)
1170 (set-syntax-table lisp-mode-syntax-table)
1171 (run-mode-hooks 'lisp-mode-hook)) ; @r{This permits the user to use a}
1172 ; @r{hook to customize the mode.}
1177 @section Minor Modes
1180 A @dfn{minor mode} provides features that users may enable or disable
1181 independently of the choice of major mode. Minor modes can be enabled
1182 individually or in combination. Minor modes would be better named
1183 ``generally available, optional feature modes,'' except that such a name
1186 A minor mode is not usually meant as a variation of a single major mode.
1187 Usually they are general and can apply to many major modes. For
1188 example, Auto Fill mode works with any major mode that permits text
1189 insertion. To be general, a minor mode must be effectively independent
1190 of the things major modes do.
1192 A minor mode is often much more difficult to implement than a major
1193 mode. One reason is that you should be able to activate and deactivate
1194 minor modes in any order. A minor mode should be able to have its
1195 desired effect regardless of the major mode and regardless of the other
1196 minor modes in effect.
1198 Often the biggest problem in implementing a minor mode is finding a
1199 way to insert the necessary hook into the rest of Emacs. Minor mode
1200 keymaps make this easier than it used to be.
1202 @defvar minor-mode-list
1203 The value of this variable is a list of all minor mode commands.
1207 * Minor Mode Conventions:: Tips for writing a minor mode.
1208 * Keymaps and Minor Modes:: How a minor mode can have its own keymap.
1209 * Defining Minor Modes:: A convenient facility for defining minor modes.
1212 @node Minor Mode Conventions
1213 @subsection Conventions for Writing Minor Modes
1214 @cindex minor mode conventions
1215 @cindex conventions for writing minor modes
1217 There are conventions for writing minor modes just as there are for
1218 major modes. Several of the major mode conventions apply to minor
1219 modes as well: those regarding the name of the mode initialization
1220 function, the names of global symbols, the use of a hook at the end of
1221 the initialization function, and the use of keymaps and other tables.
1223 In addition, there are several conventions that are specific to
1224 minor modes. (The easiest way to follow all the conventions is to use
1225 the macro @code{define-minor-mode}; @ref{Defining Minor Modes}.)
1229 @cindex mode variable
1230 Make a variable whose name ends in @samp{-mode} to control the minor
1231 mode. We call this the @dfn{mode variable}. The minor mode command
1232 should set this variable (@code{nil} to disable; anything else to
1235 If possible, implement the mode so that setting the variable
1236 automatically enables or disables the mode. Then the minor mode command
1237 does not need to do anything except set the variable.
1239 This variable is used in conjunction with the @code{minor-mode-alist} to
1240 display the minor mode name in the mode line. It can also enable
1241 or disable a minor mode keymap. Individual commands or hooks can also
1242 check the variable's value.
1244 If you want the minor mode to be enabled separately in each buffer,
1245 make the variable buffer-local.
1248 Define a command whose name is the same as the mode variable.
1249 Its job is to enable and disable the mode by setting the variable.
1251 The command should accept one optional argument. If the argument is
1252 @code{nil}, it should toggle the mode (turn it on if it is off, and
1253 off if it is on). It should turn the mode on if the argument is a
1254 positive integer, the symbol @code{t}, or a list whose @sc{car} is one
1255 of those. It should turn the mode off if the argument is a negative
1256 integer or zero, the symbol @code{-}, or a list whose @sc{car} is a
1257 negative integer or zero. The meaning of other arguments is not
1260 Here is an example taken from the definition of @code{transient-mark-mode}.
1261 It shows the use of @code{transient-mark-mode} as a variable that enables or
1262 disables the mode's behavior, and also shows the proper way to toggle,
1263 enable or disable the minor mode based on the raw prefix argument value.
1267 (setq transient-mark-mode
1268 (if (null arg) (not transient-mark-mode)
1269 (> (prefix-numeric-value arg) 0)))
1274 Add an element to @code{minor-mode-alist} for each minor mode
1275 (@pxref{Definition of minor-mode-alist}), if you want to indicate the
1276 minor mode in the mode line. This element should be a list of the
1280 (@var{mode-variable} @var{string})
1283 Here @var{mode-variable} is the variable that controls enabling of the
1284 minor mode, and @var{string} is a short string, starting with a space,
1285 to represent the mode in the mode line. These strings must be short so
1286 that there is room for several of them at once.
1288 When you add an element to @code{minor-mode-alist}, use @code{assq} to
1289 check for an existing element, to avoid duplication. For example:
1293 (unless (assq 'leif-mode minor-mode-alist)
1294 (setq minor-mode-alist
1295 (cons '(leif-mode " Leif") minor-mode-alist)))
1300 or like this, using @code{add-to-list} (@pxref{List Variables}):
1304 (add-to-list 'minor-mode-alist '(leif-mode " Leif"))
1309 Global minor modes distributed with Emacs should if possible support
1310 enabling and disabling via Custom (@pxref{Customization}). To do this,
1311 the first step is to define the mode variable with @code{defcustom}, and
1312 specify @code{:type boolean}.
1314 If just setting the variable is not sufficient to enable the mode, you
1315 should also specify a @code{:set} method which enables the mode by
1316 invoking the mode command. Note in the variable's documentation string that
1317 setting the variable other than via Custom may not take effect.
1319 Also mark the definition with an autoload cookie (@pxref{autoload cookie}),
1320 and specify a @code{:require} so that customizing the variable will load
1321 the library that defines the mode. This will copy suitable definitions
1322 into @file{loaddefs.el} so that users can use @code{customize-option} to
1323 enable the mode. For example:
1329 (defcustom msb-mode nil
1331 Setting this variable directly does not take effect;
1332 use either \\[customize] or the function `msb-mode'."
1333 :set 'custom-set-minor-mode
1334 :initialize 'custom-initialize-default
1342 @node Keymaps and Minor Modes
1343 @subsection Keymaps and Minor Modes
1345 Each minor mode can have its own keymap, which is active when the mode
1346 is enabled. To set up a keymap for a minor mode, add an element to the
1347 alist @code{minor-mode-map-alist}. @xref{Definition of minor-mode-map-alist}.
1349 @cindex @code{self-insert-command}, minor modes
1350 One use of minor mode keymaps is to modify the behavior of certain
1351 self-inserting characters so that they do something else as well as
1352 self-insert. In general, this is the only way to do that, since the
1353 facilities for customizing @code{self-insert-command} are limited to
1354 special cases (designed for abbrevs and Auto Fill mode). (Do not try
1355 substituting your own definition of @code{self-insert-command} for the
1356 standard one. The editor command loop handles this function specially.)
1358 The key sequences bound in a minor mode should consist of @kbd{C-c}
1359 followed by one of @kbd{.,/?`'"[]\|~!#$%^&*()-_+=}. (The other
1360 punctuation characters are reserved for major modes.)
1362 @node Defining Minor Modes
1363 @subsection Defining Minor Modes
1365 The macro @code{define-minor-mode} offers a convenient way of
1366 implementing a mode in one self-contained definition.
1368 @defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args@dots{} body@dots{}
1369 This macro defines a new minor mode whose name is @var{mode} (a
1370 symbol). It defines a command named @var{mode} to toggle the minor
1371 mode, with @var{doc} as its documentation string. It also defines a
1372 variable named @var{mode}, which is set to @code{t} or @code{nil} by
1373 enabling or disabling the mode. The variable is initialized to
1374 @var{init-value}. Except in unusual circumstances (see below), this
1375 value must be @code{nil}.
1377 The string @var{lighter} says what to display in the mode line
1378 when the mode is enabled; if it is @code{nil}, the mode is not displayed
1381 The optional argument @var{keymap} specifies the keymap for the minor mode.
1382 It can be a variable name, whose value is the keymap, or it can be an alist
1383 specifying bindings in this form:
1386 (@var{key-sequence} . @var{definition})
1389 The above three arguments @var{init-value}, @var{lighter}, and
1390 @var{keymap} can be (partially) omitted when @var{keyword-args} are
1391 used. The @var{keyword-args} consist of keywords followed by
1392 corresponding values. A few keywords have special meanings:
1395 @item :group @var{group}
1396 Custom group name to use in all generated @code{defcustom} forms.
1397 Defaults to @var{mode} without the possible trailing @samp{-mode}.
1398 @strong{Warning:} don't use this default group name unless you have
1399 written a @code{defgroup} to define that group properly. @xref{Group
1402 @item :global @var{global}
1403 If non-@code{nil} specifies that the minor mode should be global. By
1404 default, minor modes defined with @code{define-minor-mode} are
1407 @item :init-value @var{init-value}
1408 This is equivalent to specifying @var{init-value} positionally.
1410 @item :lighter @var{lighter}
1411 This is equivalent to specifying @var{lighter} positionally.
1413 @item :keymap @var{keymap}
1414 This is equivalent to specifying @var{keymap} positionally.
1417 Any other keyword arguments are passed directly to the
1418 @code{defcustom} generated for the variable @var{mode}.
1420 The command named @var{mode} first performs the standard actions such
1421 as setting the variable named @var{mode} and then executes the
1422 @var{body} forms, if any. It finishes by running the mode hook
1423 variable @code{@var{mode}-hook}.
1426 The initial value must be @code{nil} except in cases where (1) the
1427 mode is preloaded in Emacs, or (2) it is painless for loading to
1428 enable the mode even though the user did not request it. For
1429 instance, if the mode has no effect unless something else is enabled,
1430 and will always be loaded by that time, enabling it by default is
1431 harmless. But these are unusual circumstances. Normally, the
1432 initial value must be @code{nil}.
1434 @findex easy-mmode-define-minor-mode
1435 The name @code{easy-mmode-define-minor-mode} is an alias
1438 Here is an example of using @code{define-minor-mode}:
1441 (define-minor-mode hungry-mode
1442 "Toggle Hungry mode.
1443 With no argument, this command toggles the mode.
1444 Non-null prefix argument turns on the mode.
1445 Null prefix argument turns off the mode.
1447 When Hungry mode is enabled, the control delete key
1448 gobbles all preceding whitespace except the last.
1449 See the command \\[hungry-electric-delete]."
1450 ;; The initial value.
1452 ;; The indicator for the mode line.
1454 ;; The minor mode bindings.
1455 '(("\C-\^?" . hungry-electric-delete))
1460 This defines a minor mode named ``Hungry mode,'' a command named
1461 @code{hungry-mode} to toggle it, a variable named @code{hungry-mode}
1462 which indicates whether the mode is enabled, and a variable named
1463 @code{hungry-mode-map} which holds the keymap that is active when the
1464 mode is enabled. It initializes the keymap with a key binding for
1465 @kbd{C-@key{DEL}}. It puts the variable @code{hungry-mode} into
1466 custom group @code{hunger}. There are no @var{body} forms---many
1467 minor modes don't need any.
1469 Here's an equivalent way to write it:
1472 (define-minor-mode hungry-mode
1473 "Toggle Hungry mode.
1474 With no argument, this command toggles the mode.
1475 Non-null prefix argument turns on the mode.
1476 Null prefix argument turns off the mode.
1478 When Hungry mode is enabled, the control delete key
1479 gobbles all preceding whitespace except the last.
1480 See the command \\[hungry-electric-delete]."
1481 ;; The initial value.
1483 ;; The indicator for the mode line.
1485 ;; The minor mode bindings.
1487 '(("\C-\^?" . hungry-electric-delete)
1491 (hungry-electric-delete t))))
1495 @defmac define-global-minor-mode global-mode mode turn-on keyword-args@dots{}
1496 This defines a global minor mode named @var{global-mode} whose meaning
1497 is to enable the buffer-local minor mode @var{mode} in every buffer.
1498 To turn on the minor mode in a buffer, it uses the function
1499 @var{turn-on}; to turn off the minor mode, it calls @code{mode} with
1500 @minus{}1 as argument.
1502 Use @code{:group @var{group}} in @var{keyword-args} to specify the
1503 custom group for the mode variable of the global minor mode.
1506 @node Mode Line Format
1507 @section Mode-Line Format
1510 Each Emacs window (aside from minibuffer windows) typically has a mode
1511 line at the bottom, which displays status information about the buffer
1512 displayed in the window. The mode line contains information about the
1513 buffer, such as its name, associated file, depth of recursive editing,
1514 and major and minor modes. A window can also have a @dfn{header
1515 line}, which is much like the mode line but appears at the top of the
1518 This section describes how to control the contents of the mode line
1519 and header line. We include it in this chapter because much of the
1520 information displayed in the mode line relates to the enabled major and
1524 * Base: Mode Line Basics. Basic ideas of mode line control.
1525 * Data: Mode Line Data. The data structure that controls the mode line.
1526 * Top: Mode Line Top. The top level variable, mode-line-format.
1527 * Mode Line Variables:: Variables used in that data structure.
1528 * %-Constructs:: Putting information into a mode line.
1529 * Properties in Mode:: Using text properties in the mode line.
1530 * Header Lines:: Like a mode line, but at the top.
1531 * Emulating Mode Line:: Formatting text as the mode line would.
1534 @node Mode Line Basics
1535 @subsection Mode Line Basics
1537 @code{mode-line-format} is a buffer-local variable that holds a
1538 @dfn{mode line construct}, a kind of template, which controls what is
1539 displayed on the mode line of the current buffer. The value of
1540 @code{header-line-format} specifies the buffer's header line in the
1541 same way. All windows for the same buffer use the same
1542 @code{mode-line-format} and @code{header-line-format}.
1544 For efficiency, Emacs does not continuously recompute the mode
1545 line and header line of a window. It does so when circumstances
1546 appear to call for it---for instance, if you change the window
1547 configuration, switch buffers, narrow or widen the buffer, scroll, or
1548 change the buffer's modification status. If you modify any of the
1549 variables referenced by @code{mode-line-format} (@pxref{Mode Line
1550 Variables}), or any other variables and data structures that affect
1551 how text is displayed (@pxref{Display}), you may want to force an
1552 update of the mode line so as to display the new information or
1553 display it in the new way.
1555 @defun force-mode-line-update &optional all
1556 Force redisplay of the current buffer's mode line and header line.
1557 The next redisplay will update the mode line and header line based on
1558 the latest values of all relevant variables. With optional
1559 non-@code{nil} @var{all}, force redisplay of all mode lines and header
1562 This function also forces recomputation of the menu bar menus
1563 and the frame title.
1566 The selected window's mode line is usually displayed in a different
1567 color using the face @code{mode-line}. Other windows' mode lines
1568 appear in the face @code{mode-line-inactive} instead. @xref{Faces}.
1570 @node Mode Line Data
1571 @subsection The Data Structure of the Mode Line
1572 @cindex mode-line construct
1574 The mode-line contents are controlled by a data structure called a
1575 @dfn{mode-line construct}, made up of lists, strings, symbols, and
1576 numbers kept in buffer-local variables. Each data type has a specific
1577 meaning for the mode-line appearance, as described below. The same
1578 data structure is used for constructing frame titles (@pxref{Frame
1579 Titles}) and header lines (@pxref{Header Lines}).
1581 A mode-line construct may be as simple as a fixed string of text,
1582 but it usually specifies how to combine fixed strings with variables'
1583 values to construct the text. Many of these variables are themselves
1584 defined to have mode-line constructs as their values.
1586 Here are the meanings of various data types as mode-line constructs:
1589 @cindex percent symbol in mode line
1591 A string as a mode-line construct appears verbatim except for
1592 @dfn{@code{%}-constructs} in it. These stand for substitution of
1593 other data; see @ref{%-Constructs}.
1595 If parts of the string have @code{face} properties, they control
1596 display of the text just as they would text in the buffer. Any
1597 characters which have no @code{face} properties are displayed, by
1598 default, in the face @code{mode-line} or @code{mode-line-inactive}
1599 (@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}). The
1600 @code{help-echo} and @code{local-map} properties in @var{string} have
1601 special meanings. @xref{Properties in Mode}.
1604 A symbol as a mode-line construct stands for its value. The value of
1605 @var{symbol} is used as a mode-line construct, in place of @var{symbol}.
1606 However, the symbols @code{t} and @code{nil} are ignored, as is any
1607 symbol whose value is void.
1609 There is one exception: if the value of @var{symbol} is a string, it is
1610 displayed verbatim: the @code{%}-constructs are not recognized.
1612 Unless @var{symbol} is marked as ``risky'' (i.e., it has a
1613 non-@code{nil} @code{risky-local-variable} property), all text
1614 properties specified in @var{symbol}'s value are ignored. This
1615 includes the text properties of strings in @var{symbol}'s value, as
1616 well as all @code{:eval} and @code{:propertize} forms in it. (The
1617 reason for this is security: non-risky variables could be set
1618 automatically from file variables without prompting the user.)
1620 @item (@var{string} @var{rest}@dots{})
1621 @itemx (@var{list} @var{rest}@dots{})
1622 A list whose first element is a string or list means to process all the
1623 elements recursively and concatenate the results. This is the most
1624 common form of mode-line construct.
1626 @item (:eval @var{form})
1627 A list whose first element is the symbol @code{:eval} says to evaluate
1628 @var{form}, and use the result as a string to display. Make sure this
1629 evaluation cannot load any files, as doing so could cause infinite
1632 @item (:propertize @var{elt} @var{props}@dots{})
1633 A list whose first element is the symbol @code{:propertize} says to
1634 process the mode-line construct @var{elt} recursively, then add the text
1635 properties specified by @var{props} to the result. The argument
1636 @var{props} should consist of zero or more pairs @var{text-property}
1637 @var{value}. (This feature is new as of Emacs 22.1.)
1639 @item (@var{symbol} @var{then} @var{else})
1640 A list whose first element is a symbol that is not a keyword specifies
1641 a conditional. Its meaning depends on the value of @var{symbol}. If
1642 @var{symbol} has a non-@code{nil} value, the second element,
1643 @var{then}, is processed recursively as a mode-line element.
1644 Otherwise, the third element, @var{else}, is processed recursively.
1645 You may omit @var{else}; then the mode-line element displays nothing
1646 if the value of @var{symbol} is @code{nil} or void.
1648 @item (@var{width} @var{rest}@dots{})
1649 A list whose first element is an integer specifies truncation or
1650 padding of the results of @var{rest}. The remaining elements
1651 @var{rest} are processed recursively as mode-line constructs and
1652 concatenated together. When @var{width} is positive, the result is
1653 space filled on the right if its width is less than @var{width}. When
1654 @var{width} is negative, the result is truncated on the right to
1655 @minus{}@var{width} columns if its width exceeds @minus{}@var{width}.
1657 For example, the usual way to show what percentage of a buffer is above
1658 the top of the window is to use a list like this: @code{(-3 "%p")}.
1662 @subsection The Top Level of Mode Line Control
1664 The variable in overall control of the mode line is
1665 @code{mode-line-format}.
1667 @defvar mode-line-format
1668 The value of this variable is a mode-line construct that controls the
1669 contents of the mode-line. It is always buffer-local in all buffers.
1671 If you set this variable to @code{nil} in a buffer, that buffer does
1672 not have a mode line. (A window that is just one line tall never
1673 displays a mode line.)
1676 The default value of @code{mode-line-format} is designed to use the
1677 values of other variables such as @code{mode-line-position} and
1678 @code{mode-line-modes} (which in turn incorporates the values of the
1679 variables @code{mode-name} and @code{minor-mode-alist}). Very few
1680 modes need to alter @code{mode-line-format} itself. For most
1681 purposes, it is sufficient to alter some of the variables that
1682 @code{mode-line-format} either directly or indirectly refers to.
1684 If you do alter @code{mode-line-format} itself, the new value should
1685 use the same variables that appear in the default value (@pxref{Mode
1686 Line Variables}), rather than duplicating their contents or displaying
1687 the information in another fashion. This way, customizations made by
1688 the user or by Lisp programs (such as @code{display-time} and major
1689 modes) via changes to those variables remain effective.
1691 @cindex Shell mode @code{mode-line-format}
1692 Here is an example of a @code{mode-line-format} that might be
1693 useful for @code{shell-mode}, since it contains the host name and default
1698 (setq mode-line-format
1700 'mode-line-mule-info
1702 'mode-line-frame-identification
1706 ;; @r{Note that this is evaluated while making the list.}
1707 ;; @r{It makes a mode-line construct which is just a string.}
1715 '(:eval (mode-line-mode-name))
1721 '(which-func-mode ("" which-func-format "--"))
1722 '(line-number-mode "L%l--")
1723 '(column-number-mode "C%c--")
1730 (The variables @code{line-number-mode}, @code{column-number-mode}
1731 and @code{which-func-mode} enable particular minor modes; as usual,
1732 these variable names are also the minor mode command names.)
1734 @node Mode Line Variables
1735 @subsection Variables Used in the Mode Line
1737 This section describes variables incorporated by the standard value
1738 of @code{mode-line-format} into the text of the mode line. There is
1739 nothing inherently special about these variables; any other variables
1740 could have the same effects on the mode line if
1741 @code{mode-line-format}'s value were changed to use them. However,
1742 various parts of Emacs set these variables on the understanding that
1743 they will control parts of the mode line; therefore, practically
1744 speaking, it is essential for the mode line to use them.
1746 @defvar mode-line-mule-info
1747 This variable holds the value of the mode-line construct that displays
1748 information about the language environment, buffer coding system, and
1749 current input method. @xref{Non-ASCII Characters}.
1752 @defvar mode-line-modified
1753 This variable holds the value of the mode-line construct that displays
1754 whether the current buffer is modified.
1756 The default value of @code{mode-line-modified} is @code{("%1*%1+")}.
1757 This means that the mode line displays @samp{**} if the buffer is
1758 modified, @samp{--} if the buffer is not modified, @samp{%%} if the
1759 buffer is read only, and @samp{%*} if the buffer is read only and
1762 Changing this variable does not force an update of the mode line.
1765 @defvar mode-line-frame-identification
1766 This variable identifies the current frame. The default value is
1767 @code{" "} if you are using a window system which can show multiple
1768 frames, or @code{"-%F "} on an ordinary terminal which shows only one
1772 @defvar mode-line-buffer-identification
1773 This variable identifies the buffer being displayed in the window. Its
1774 default value is @code{("%12b")}, which displays the buffer name, padded
1775 with spaces to at least 12 columns.
1778 @defvar mode-line-position
1779 This variable indicates the position in the buffer. Here is a
1780 simplified version of its default value. The actual default value
1781 also specifies addition of the @code{help-echo} text property.
1786 (size-indication-mode (8 " of %I"))
1790 ((column-number-mode
1793 ((column-number-mode
1798 This means that @code{mode-line-position} displays at least the buffer
1799 percentage and possibly the buffer size, the line number and the column
1804 The variable @code{vc-mode}, buffer-local in each buffer, records
1805 whether the buffer's visited file is maintained with version control,
1806 and, if so, which kind. Its value is a string that appears in the mode
1807 line, or @code{nil} for no version control.
1810 @defvar mode-line-modes
1811 This variable displays the buffer's major and minor modes. Here is a
1812 simplified version of its default value. The real default value also
1813 specifies addition of text properties.
1818 mode-line-process minor-mode-alist
1823 So @code{mode-line-modes} normally also displays the recursive editing
1824 level, information on the process status and whether narrowing is in
1828 The following three variables are used in @code{mode-line-modes}:
1831 This buffer-local variable holds the ``pretty'' name of the current
1832 buffer's major mode. Each major mode should set this variable so that the
1833 mode name will appear in the mode line.
1836 @defvar mode-line-process
1837 This buffer-local variable contains the mode-line information on process
1838 status in modes used for communicating with subprocesses. It is
1839 displayed immediately following the major mode name, with no intervening
1840 space. For example, its value in the @samp{*shell*} buffer is
1841 @code{(":%s")}, which allows the shell to display its status along
1842 with the major mode as: @samp{(Shell:run)}. Normally this variable
1846 @defvar minor-mode-alist
1847 @anchor{Definition of minor-mode-alist}
1848 This variable holds an association list whose elements specify how the
1849 mode line should indicate that a minor mode is active. Each element of
1850 the @code{minor-mode-alist} should be a two-element list:
1853 (@var{minor-mode-variable} @var{mode-line-string})
1856 More generally, @var{mode-line-string} can be any mode-line spec. It
1857 appears in the mode line when the value of @var{minor-mode-variable}
1858 is non-@code{nil}, and not otherwise. These strings should begin with
1859 spaces so that they don't run together. Conventionally, the
1860 @var{minor-mode-variable} for a specific mode is set to a
1861 non-@code{nil} value when that minor mode is activated.
1863 @code{minor-mode-alist} itself is not buffer-local. Each variable
1864 mentioned in the alist should be buffer-local if its minor mode can be
1865 enabled separately in each buffer.
1868 @defvar global-mode-string
1869 This variable holds a mode-line spec that, by default, appears in the
1870 mode line just after the @code{which-func-mode} minor mode if set,
1871 else after @code{mode-line-modes}. The command @code{display-time}
1872 sets @code{global-mode-string} to refer to the variable
1873 @code{display-time-string}, which holds a string containing the time
1874 and load information.
1876 The @samp{%M} construct substitutes the value of
1877 @code{global-mode-string}, but that is obsolete, since the variable is
1878 included in the mode line from @code{mode-line-format}.
1881 The variable @code{default-mode-line-format} is where
1882 @code{mode-line-format} usually gets its value:
1884 @defvar default-mode-line-format
1885 This variable holds the default @code{mode-line-format} for buffers
1886 that do not override it. This is the same as @code{(default-value
1887 'mode-line-format)}.
1889 Here is a simplified version of the default value of
1890 @code{default-mode-line-format}. The real default value also
1891 specifies addition of text properties.
1898 mode-line-frame-identification
1899 mode-line-buffer-identification
1907 (which-func-mode ("" which-func-format "--"))
1908 (global-mode-string ("--" global-mode-string))
1915 @subsection @code{%}-Constructs in the Mode Line
1917 Strings used as mode-line constructs can use certain
1918 @code{%}-constructs to substitute various kinds of data. Here is a
1919 list of the defined @code{%}-constructs, and what they mean. In any
1920 construct except @samp{%%}, you can add a decimal integer after the
1921 @samp{%} to specify a minimum field width. If the width is less, the
1922 field is padded with spaces to the right.
1926 The current buffer name, obtained with the @code{buffer-name} function.
1927 @xref{Buffer Names}.
1930 The current column number of point.
1933 When Emacs is nearly out of memory for Lisp objects, a brief message
1934 saying so. Otherwise, this is empty.
1937 The visited file name, obtained with the @code{buffer-file-name}
1938 function. @xref{Buffer File Name}.
1941 The title (only on a window system) or the name of the selected frame.
1942 @xref{Basic Parameters}.
1945 The size of the accessible part of the current buffer; basically
1946 @code{(- (point-max) (point-min))}.
1949 Like @samp{%i}, but the size is printed in a more readable way by using
1950 @samp{k} for 10^3, @samp{M} for 10^6, @samp{G} for 10^9, etc., to
1954 The current line number of point, counting within the accessible portion
1958 @samp{Narrow} when narrowing is in effect; nothing otherwise (see
1959 @code{narrow-to-region} in @ref{Narrowing}).
1962 The percentage of the buffer text above the @strong{top} of window, or
1963 @samp{Top}, @samp{Bottom} or @samp{All}. Note that the default
1964 mode-line specification truncates this to three characters.
1967 The percentage of the buffer text that is above the @strong{bottom} of
1968 the window (which includes the text visible in the window, as well as
1969 the text above the top), plus @samp{Top} if the top of the buffer is
1970 visible on screen; or @samp{Bottom} or @samp{All}.
1973 The status of the subprocess belonging to the current buffer, obtained with
1974 @code{process-status}. @xref{Process Information}.
1977 Whether the visited file is a text file or a binary file. This is a
1978 meaningful distinction only on certain operating systems (@pxref{MS-DOS
1982 The mnemonics of buffer, terminal, and keyboard coding systems.
1985 Like @samp{%z}, but including the end-of-line format.
1988 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
1989 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
1990 @samp{-} otherwise. @xref{Buffer Modification}.
1993 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
1994 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
1995 @samp{-} otherwise. This differs from @samp{%*} only for a modified
1996 read-only buffer. @xref{Buffer Modification}.
1999 @samp{*} if the buffer is modified, and @samp{-} otherwise.
2002 An indication of the depth of recursive editing levels (not counting
2003 minibuffer levels): one @samp{[} for each editing level.
2004 @xref{Recursive Editing}.
2007 One @samp{]} for each recursive editing level (not counting minibuffer
2011 Dashes sufficient to fill the remainder of the mode line.
2014 The character @samp{%}---this is how to include a literal @samp{%} in a
2015 string in which @code{%}-constructs are allowed.
2018 The following two @code{%}-constructs are still supported, but they are
2019 obsolete, since you can get the same results with the variables
2020 @code{mode-name} and @code{global-mode-string}.
2024 The value of @code{mode-name}.
2027 The value of @code{global-mode-string}.
2030 @node Properties in Mode
2031 @subsection Properties in the Mode Line
2032 @cindex text properties in the mode line
2034 Certain text properties are meaningful in the
2035 mode line. The @code{face} property affects the appearance of text; the
2036 @code{help-echo} property associates help strings with the text, and
2037 @code{local-map} can make the text mouse-sensitive.
2039 There are four ways to specify text properties for text in the mode
2044 Put a string with a text property directly into the mode-line data
2048 Put a text property on a mode-line %-construct such as @samp{%12b}; then
2049 the expansion of the %-construct will have that same text property.
2052 Use a @code{(:propertize @var{elt} @var{props}@dots{})} construct to
2053 give @var{elt} a text property specified by @var{props}.
2056 Use a list containing @code{:eval @var{form}} in the mode-line data
2057 structure, and make @var{form} evaluate to a string that has a text
2061 You can use the @code{local-map} property to specify a keymap. This
2062 keymap only takes real effect for mouse clicks; binding character keys
2063 and function keys to it has no effect, since it is impossible to move
2064 point into the mode line.
2066 When the mode line refers to a variable which does not have a
2067 non-@code{nil} @code{risky-local-variable} property, any text
2068 properties given or specified within that variable's values are
2069 ignored. This is because such properties could otherwise specify
2070 functions to be called, and those functions could come from file
2074 @subsection Window Header Lines
2075 @cindex header line (of a window)
2076 @cindex window header line
2078 A window can have a @dfn{header line} at the
2079 top, just as it can have a mode line at the bottom. The header line
2080 feature works just like the mode-line feature, except that it's
2081 controlled by different variables.
2083 @defvar header-line-format
2084 This variable, local in every buffer, specifies how to display the
2085 header line, for windows displaying the buffer. The format of the value
2086 is the same as for @code{mode-line-format} (@pxref{Mode Line Data}).
2089 @defvar default-header-line-format
2090 This variable holds the default @code{header-line-format} for buffers
2091 that do not override it. This is the same as @code{(default-value
2092 'header-line-format)}.
2094 It is normally @code{nil}, so that ordinary buffers have no header line.
2097 A window that is just one line tall never displays a header line. A
2098 window that is two lines tall cannot display both a mode line and a
2099 header line at once; if it has a mode line, then it does not display a
2102 @node Emulating Mode Line
2103 @subsection Emulating Mode-Line Formatting
2105 You can use the function @code{format-mode-line} to compute
2106 the text that would appear in a mode line or header line
2107 based on a certain mode-line specification.
2109 @defun format-mode-line format &optional face window buffer
2110 This function formats a line of text according to @var{format} as if
2111 it were generating the mode line for @var{window}, but instead of
2112 displaying the text in the mode line or the header line, it returns
2113 the text as a string. The argument @var{window} defaults to the
2114 selected window. If @var{buffer} is non-@code{nil}, all the
2115 information used is taken from @var{buffer}; by default, it comes from
2116 @var{window}'s buffer.
2118 The value string normally has text properties that correspond to the
2119 faces, keymaps, etc., that the mode line would have. And any character
2120 for which no @code{face} property is specified gets a default
2121 value which is usually @var{face}. (If @var{face} is @code{t},
2122 that stands for either @code{mode-line} if @var{window} is selected,
2123 otherwise @code{mode-line-inactive}. If @var{face} is @code{nil} or
2124 omitted, that stands for no face property.)
2126 However, if @var{face} is an integer, the value has no text properties.
2128 For example, @code{(format-mode-line header-line-format)} returns the
2129 text that would appear in the selected window's header line (@code{""}
2130 if it has no header line). @code{(format-mode-line header-line-format
2131 'header-line)} returns the same text, with each character
2132 carrying the face that it will have in the header line itself.
2139 @dfn{Imenu} is a feature that lets users select a definition or
2140 section in the buffer, from a menu which lists all of them, to go
2141 directly to that location in the buffer. Imenu works by constructing
2142 a buffer index which lists the names and buffer positions of the
2143 definitions, or other named portions of the buffer; then the user can
2144 choose one of them and move point to it. Major modes can add a menu
2145 bar item to use Imenu using @code{imenu-add-to-menubar}.
2147 @defun imenu-add-to-menubar name
2148 This function defines a local menu bar item named @var{name}
2152 The user-level commands for using Imenu are described in the Emacs
2153 Manual (@pxref{Imenu,, Imenu, emacs, the Emacs Manual}). This section
2154 explains how to customize Imenu's method of finding definitions or
2155 buffer portions for a particular major mode.
2157 The usual and simplest way is to set the variable
2158 @code{imenu-generic-expression}:
2160 @defvar imenu-generic-expression
2161 This variable, if non-@code{nil}, is a list that specifies regular
2162 expressions for finding definitions for Imenu. Simple elements of
2163 @code{imenu-generic-expression} look like this:
2166 (@var{menu-title} @var{regexp} @var{index})
2169 Here, if @var{menu-title} is non-@code{nil}, it says that the matches
2170 for this element should go in a submenu of the buffer index;
2171 @var{menu-title} itself specifies the name for the submenu. If
2172 @var{menu-title} is @code{nil}, the matches for this element go directly
2173 in the top level of the buffer index.
2175 The second item in the list, @var{regexp}, is a regular expression
2176 (@pxref{Regular Expressions}); anything in the buffer that it matches
2177 is considered a definition, something to mention in the buffer index.
2178 The third item, @var{index}, is a non-negative integer that indicates
2179 which subexpression in @var{regexp} matches the definition's name.
2181 An element can also look like this:
2184 (@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{})
2187 Each match for this element creates an index item, and when the index
2188 item is selected by the user, it calls @var{function} with arguments
2189 consisting of the item name, the buffer position, and @var{arguments}.
2191 For Emacs Lisp mode, @code{imenu-generic-expression} could look like
2194 @c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]
2197 ((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
2198 \\s-+\\([-A-Za-z0-9+]+\\)" 2)
2201 ("*Vars*" "^\\s-*(def\\(var\\|const\\)\
2202 \\s-+\\([-A-Za-z0-9+]+\\)" 2)
2207 (def\\(type\\|struct\\|class\\|ine-condition\\)\
2208 \\s-+\\([-A-Za-z0-9+]+\\)" 2))
2212 Setting this variable makes it buffer-local in the current buffer.
2215 @defvar imenu-case-fold-search
2216 This variable controls whether matching against the regular
2217 expressions in the value of @code{imenu-generic-expression} is
2218 case-sensitive: @code{t}, the default, means matching should ignore
2221 Setting this variable makes it buffer-local in the current buffer.
2224 @defvar imenu-syntax-alist
2225 This variable is an alist of syntax table modifiers to use while
2226 processing @code{imenu-generic-expression}, to override the syntax table
2227 of the current buffer. Each element should have this form:
2230 (@var{characters} . @var{syntax-description})
2233 The @sc{car}, @var{characters}, can be either a character or a string.
2234 The element says to give that character or characters the syntax
2235 specified by @var{syntax-description}, which is passed to
2236 @code{modify-syntax-entry} (@pxref{Syntax Table Functions}).
2238 This feature is typically used to give word syntax to characters which
2239 normally have symbol syntax, and thus to simplify
2240 @code{imenu-generic-expression} and speed up matching.
2241 For example, Fortran mode uses it this way:
2244 (setq imenu-syntax-alist '(("_$" . "w")))
2247 The @code{imenu-generic-expression} regular expressions can then use
2248 @samp{\\sw+} instead of @samp{\\(\\sw\\|\\s_\\)+}. Note that this
2249 technique may be inconvenient when the mode needs to limit the initial
2250 character of a name to a smaller set of characters than are allowed in
2253 Setting this variable makes it buffer-local in the current buffer.
2256 Another way to customize Imenu for a major mode is to set the
2257 variables @code{imenu-prev-index-position-function} and
2258 @code{imenu-extract-index-name-function}:
2260 @defvar imenu-prev-index-position-function
2261 If this variable is non-@code{nil}, its value should be a function that
2262 finds the next ``definition'' to put in the buffer index, scanning
2263 backward in the buffer from point. It should return @code{nil} if it
2264 doesn't find another ``definition'' before point. Otherwise it should
2265 leave point at the place it finds a ``definition'' and return any
2266 non-@code{nil} value.
2268 Setting this variable makes it buffer-local in the current buffer.
2271 @defvar imenu-extract-index-name-function
2272 If this variable is non-@code{nil}, its value should be a function to
2273 return the name for a definition, assuming point is in that definition
2274 as the @code{imenu-prev-index-position-function} function would leave
2277 Setting this variable makes it buffer-local in the current buffer.
2280 The last way to customize Imenu for a major mode is to set the
2281 variable @code{imenu-create-index-function}:
2283 @defvar imenu-create-index-function
2284 This variable specifies the function to use for creating a buffer
2285 index. The function should take no arguments, and return an index
2286 alist for the current buffer. It is called within
2287 @code{save-excursion}, so where it leaves point makes no difference.
2289 The index alist can have three types of elements. Simple elements
2293 (@var{index-name} . @var{index-position})
2296 Selecting a simple element has the effect of moving to position
2297 @var{index-position} in the buffer. Special elements look like this:
2300 (@var{index-name} @var{index-position} @var{function} @var{arguments}@dots{})
2303 Selecting a special element performs:
2306 (funcall @var{function}
2307 @var{index-name} @var{index-position} @var{arguments}@dots{})
2310 A nested sub-alist element looks like this:
2313 (@var{menu-title} @var{sub-alist})
2316 It creates the submenu @var{menu-title} specified by @var{sub-alist}.
2318 The default value of @code{imenu-create-index-function} is
2319 @code{imenu-default-create-index-function}. This function calls the
2320 value of @code{imenu-prev-index-position-function} and the value of
2321 @code{imenu-extract-index-name-function} to produce the index alist.
2322 However, if either of these two variables is @code{nil}, the default
2323 function uses @code{imenu-generic-expression} instead.
2325 Setting this variable makes it buffer-local in the current buffer.
2328 @node Font Lock Mode
2329 @section Font Lock Mode
2330 @cindex Font Lock Mode
2332 @dfn{Font Lock mode} is a feature that automatically attaches
2333 @code{face} properties to certain parts of the buffer based on their
2334 syntactic role. How it parses the buffer depends on the major mode;
2335 most major modes define syntactic criteria for which faces to use in
2336 which contexts. This section explains how to customize Font Lock for a
2337 particular major mode.
2339 Font Lock mode finds text to highlight in two ways: through
2340 syntactic parsing based on the syntax table, and through searching
2341 (usually for regular expressions). Syntactic fontification happens
2342 first; it finds comments and string constants and highlights them.
2343 Search-based fontification happens second.
2346 * Font Lock Basics:: Overview of customizing Font Lock.
2347 * Search-based Fontification:: Fontification based on regexps.
2348 * Customizing Keywords:: Customizing search-based fontification.
2349 * Other Font Lock Variables:: Additional customization facilities.
2350 * Levels of Font Lock:: Each mode can define alternative levels
2351 so that the user can select more or less.
2352 * Precalculated Fontification:: How Lisp programs that produce the buffer
2353 contents can also specify how to fontify it.
2354 * Faces for Font Lock:: Special faces specifically for Font Lock.
2355 * Syntactic Font Lock:: Fontification based on syntax tables.
2356 * Setting Syntax Properties:: Defining character syntax based on context
2357 using the Font Lock mechanism.
2358 * Multiline Font Lock:: How to coerce Font Lock into properly
2359 highlighting multiline constructs.
2362 @node Font Lock Basics
2363 @subsection Font Lock Basics
2365 There are several variables that control how Font Lock mode highlights
2366 text. But major modes should not set any of these variables directly.
2367 Instead, they should set @code{font-lock-defaults} as a buffer-local
2368 variable. The value assigned to this variable is used, if and when Font
2369 Lock mode is enabled, to set all the other variables.
2371 @defvar font-lock-defaults
2372 This variable is set by major modes, as a buffer-local variable, to
2373 specify how to fontify text in that mode. It automatically becomes
2374 buffer-local when you set it. The value should look like this:
2377 (@var{keywords} [@var{keywords-only} [@var{case-fold}
2378 [@var{syntax-alist} [@var{syntax-begin} @var{other-vars}@dots{}]]]])
2381 The first element, @var{keywords}, indirectly specifies the value of
2382 @code{font-lock-keywords} which directs search-based fontification.
2383 It can be a symbol, a variable or a function whose value is the list
2384 to use for @code{font-lock-keywords}. It can also be a list of
2385 several such symbols, one for each possible level of fontification.
2386 The first symbol specifies how to do level 1 fontification, the second
2387 symbol how to do level 2, and so on. @xref{Levels of Font Lock}.
2389 The second element, @var{keywords-only}, specifies the value of the
2390 variable @code{font-lock-keywords-only}. If this is non-@code{nil},
2391 syntactic fontification (of strings and comments) is not performed.
2392 @xref{Syntactic Font Lock}.
2394 The third element, @var{case-fold}, specifies the value of
2395 @code{font-lock-keywords-case-fold-search}. If it is non-@code{nil},
2396 Font Lock mode ignores case when searching as directed by
2397 @code{font-lock-keywords}.
2399 If the fourth element, @var{syntax-alist}, is non-@code{nil}, it
2400 should be a list of cons cells of the form @code{(@var{char-or-string}
2401 . @var{string})}. These are used to set up a syntax table for
2402 syntactic fontification (@pxref{Syntax Table Functions}). The
2403 resulting syntax table is stored in @code{font-lock-syntax-table}.
2405 The fifth element, @var{syntax-begin}, specifies the value of
2406 @code{font-lock-beginning-of-syntax-function}. We recommend setting
2407 this variable to @code{nil} and using @code{syntax-begin-function}
2410 All the remaining elements (if any) are collectively called
2411 @var{other-vars}. Each of these elements should have the form
2412 @code{(@var{variable} . @var{value})}---which means, make
2413 @var{variable} buffer-local and then set it to @var{value}. You can
2414 use these @var{other-vars} to set other variables that affect
2415 fontification, aside from those you can control with the first five
2416 elements. @xref{Other Font Lock Variables}.
2419 @node Search-based Fontification
2420 @subsection Search-based Fontification
2422 The most important variable for customizing Font Lock mode is
2423 @code{font-lock-keywords}. It specifies the search criteria for
2424 search-based fontification. You should specify the value of this
2425 variable with @var{keywords} in @code{font-lock-defaults}.
2427 @defvar font-lock-keywords
2428 This variable's value is a list of the keywords to highlight. Be
2429 careful when composing regular expressions for this list; a poorly
2430 written pattern can dramatically slow things down!
2433 Each element of @code{font-lock-keywords} specifies how to find
2434 certain cases of text, and how to highlight those cases. Font Lock mode
2435 processes the elements of @code{font-lock-keywords} one by one, and for
2436 each element, it finds and handles all matches. Ordinarily, once
2437 part of the text has been fontified already, this cannot be overridden
2438 by a subsequent match in the same text; but you can specify different
2439 behavior using the @var{override} element of a @var{subexp-highlighter}.
2441 Each element of @code{font-lock-keywords} should have one of these
2446 Highlight all matches for @var{regexp} using
2447 @code{font-lock-keyword-face}. For example,
2450 ;; @r{Highlight occurrences of the word @samp{foo}}
2451 ;; @r{using @code{font-lock-keyword-face}.}
2455 The function @code{regexp-opt} (@pxref{Regexp Functions}) is useful
2456 for calculating optimal regular expressions to match a number of
2459 @item @var{function}
2460 Find text by calling @var{function}, and highlight the matches
2461 it finds using @code{font-lock-keyword-face}.
2463 When @var{function} is called, it receives one argument, the limit of
2464 the search; it should begin searching at point, and not search beyond the
2465 limit. It should return non-@code{nil} if it succeeds, and set the
2466 match data to describe the match that was found. Returning @code{nil}
2467 indicates failure of the search.
2469 Fontification will call @var{function} repeatedly with the same limit,
2470 and with point where the previous invocation left it, until
2471 @var{function} fails. On failure, @var{function} need not reset point
2472 in any particular way.
2474 @item (@var{matcher} . @var{subexp})
2475 In this kind of element, @var{matcher} is either a regular
2476 expression or a function, as described above. The @sc{cdr},
2477 @var{subexp}, specifies which subexpression of @var{matcher} should be
2478 highlighted (instead of the entire text that @var{matcher} matched).
2481 ;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},}
2482 ;; @r{using @code{font-lock-keyword-face}.}
2486 If you use @code{regexp-opt} to produce the regular expression
2487 @var{matcher}, you can use @code{regexp-opt-depth} (@pxref{Regexp
2488 Functions}) to calculate the value for @var{subexp}.
2490 @item (@var{matcher} . @var{facespec})
2491 In this kind of element, @var{facespec} is an expression whose value
2492 specifies the face to use for highlighting. In the simplest case,
2493 @var{facespec} is a Lisp variable (a symbol) whose value is a face
2497 ;; @r{Highlight occurrences of @samp{fubar},}
2498 ;; @r{using the face which is the value of @code{fubar-face}.}
2499 ("fubar" . fubar-face)
2502 However, @var{facespec} can also evaluate to a list of this form:
2505 (face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{})
2509 to specify the face @var{face} and various additional text properties
2510 to put on the text that matches. If you do this, be sure to add the
2511 other text property names that you set in this way to the value of
2512 @code{font-lock-extra-managed-props} so that the properties will also
2513 be cleared out when they are no longer appropriate. Alternatively,
2514 you can set the variable @code{font-lock-unfontify-region-function} to
2515 a function that clears these properties. @xref{Other Font Lock
2518 @item (@var{matcher} . @var{subexp-highlighter})
2519 In this kind of element, @var{subexp-highlighter} is a list
2520 which specifies how to highlight matches found by @var{matcher}.
2524 (@var{subexp} @var{facespec} [[@var{override} [@var{laxmatch}]])
2527 The @sc{car}, @var{subexp}, is an integer specifying which subexpression
2528 of the match to fontify (0 means the entire matching text). The second
2529 subelement, @var{facespec}, is an expression whose value specifies the
2530 face, as described above.
2532 The last two values in @var{subexp-highlighter}, @var{override} and
2533 @var{laxmatch}, are optional flags. If @var{override} is @code{t},
2534 this element can override existing fontification made by previous
2535 elements of @code{font-lock-keywords}. If it is @code{keep}, then
2536 each character is fontified if it has not been fontified already by
2537 some other element. If it is @code{prepend}, the face specified by
2538 @var{facespec} is added to the beginning of the @code{font-lock-face}
2539 property. If it is @code{append}, the face is added to the end of the
2540 @code{font-lock-face} property.
2542 If @var{laxmatch} is non-@code{nil}, it means there should be no error
2543 if there is no subexpression numbered @var{subexp} in @var{matcher}.
2544 Obviously, fontification of the subexpression numbered @var{subexp} will
2545 not occur. However, fontification of other subexpressions (and other
2546 regexps) will continue. If @var{laxmatch} is @code{nil}, and the
2547 specified subexpression is missing, then an error is signaled which
2548 terminates search-based fontification.
2550 Here are some examples of elements of this kind, and what they do:
2553 ;; @r{Highlight occurrences of either @samp{foo} or @samp{bar}, using}
2554 ;; @r{@code{foo-bar-face}, even if they have already been highlighted.}
2555 ;; @r{@code{foo-bar-face} should be a variable whose value is a face.}
2556 ("foo\\|bar" 0 foo-bar-face t)
2558 ;; @r{Highlight the first subexpression within each occurrence}
2559 ;; @r{that the function @code{fubar-match} finds,}
2560 ;; @r{using the face which is the value of @code{fubar-face}.}
2561 (fubar-match 1 fubar-face)
2564 @item (@var{matcher} . @var{anchored-highlighter})
2565 In this kind of element, @var{anchored-highlighter} specifies how to
2566 highlight text that follows a match found by @var{matcher}. So a
2567 match found by @var{matcher} acts as the anchor for further searches
2568 specified by @var{anchored-highlighter}. @var{anchored-highlighter}
2569 is a list of the following form:
2572 (@var{anchored-matcher} @var{pre-form} @var{post-form}
2573 @var{subexp-highlighters}@dots{})
2576 Here, @var{anchored-matcher}, like @var{matcher}, is either a regular
2577 expression or a function. After a match of @var{matcher} is found,
2578 point is at the end of the match. Now, Font Lock evaluates the form
2579 @var{pre-form}. Then it searches for matches of
2580 @var{anchored-matcher} and uses @var{subexp-highlighters} to highlight
2581 these. A @var{subexp-highlighter} is as described above. Finally,
2582 Font Lock evaluates @var{post-form}.
2584 The forms @var{pre-form} and @var{post-form} can be used to initialize
2585 before, and cleanup after, @var{anchored-matcher} is used. Typically,
2586 @var{pre-form} is used to move point to some position relative to the
2587 match of @var{matcher}, before starting with @var{anchored-matcher}.
2588 @var{post-form} might be used to move back, before resuming with
2591 After Font Lock evaluates @var{pre-form}, it does not search for
2592 @var{anchored-matcher} beyond the end of the line. However, if
2593 @var{pre-form} returns a buffer position that is greater than the
2594 position of point after @var{pre-form} is evaluated, then the position
2595 returned by @var{pre-form} is used as the limit of the search instead.
2596 It is generally a bad idea to return a position greater than the end
2597 of the line; in other words, the @var{anchored-matcher} search should
2603 ;; @r{Highlight occurrences of the word @samp{item} following}
2604 ;; @r{an occurrence of the word @samp{anchor} (on the same line)}
2605 ;; @r{in the value of @code{item-face}.}
2606 ("\\<anchor\\>" "\\<item\\>" nil nil (0 item-face))
2609 Here, @var{pre-form} and @var{post-form} are @code{nil}. Therefore
2610 searching for @samp{item} starts at the end of the match of
2611 @samp{anchor}, and searching for subsequent instances of @samp{anchor}
2612 resumes from where searching for @samp{item} concluded.
2614 @item (@var{matcher} @var{highlighters}@dots{})
2615 This sort of element specifies several @var{highlighter} lists for a
2616 single @var{matcher}. A @var{highlighter} list can be of the type
2617 @var{subexp-highlighter} or @var{anchored-highlighter} as described
2623 ;; @r{Highlight occurrences of the word @samp{anchor} in the value}
2624 ;; @r{of @code{anchor-face}, and subsequent occurrences of the word}
2625 ;; @r{@samp{item} (on the same line) in the value of @code{item-face}.}
2626 ("\\<anchor\\>" (0 anchor-face)
2627 ("\\<item\\>" nil nil (0 item-face)))
2630 @item (eval . @var{form})
2631 Here @var{form} is an expression to be evaluated the first time
2632 this value of @code{font-lock-keywords} is used in a buffer.
2633 Its value should have one of the forms described in this table.
2636 @strong{Warning:} Do not design an element of @code{font-lock-keywords}
2637 to match text which spans lines; this does not work reliably.
2638 For details, see @xref{Multiline Font Lock}.
2640 You can use @var{case-fold} in @code{font-lock-defaults} to specify
2641 the value of @code{font-lock-keywords-case-fold-search} which says
2642 whether search-based fontification should be case-insensitive.
2644 @defvar font-lock-keywords-case-fold-search
2645 Non-@code{nil} means that regular expression matching for the sake of
2646 @code{font-lock-keywords} should be case-insensitive.
2649 @node Customizing Keywords
2650 @subsection Customizing Search-Based Fontification
2652 You can use @code{font-lock-add-keywords} to add additional
2653 search-based fontification rules to a major mode, and
2654 @code{font-lock-remove-keywords} to removes rules.
2656 @defun font-lock-add-keywords mode keywords &optional how
2657 This function adds highlighting @var{keywords}, for the current buffer
2658 or for major mode @var{mode}. The argument @var{keywords} should be a
2659 list with the same format as the variable @code{font-lock-keywords}.
2661 If @var{mode} is a symbol which is a major mode command name, such as
2662 @code{c-mode}, the effect is that enabling Font Lock mode in
2663 @var{mode} will add @var{keywords} to @code{font-lock-keywords}.
2664 Calling with a non-@code{nil} value of @var{mode} is correct only in
2665 your @file{~/.emacs} file.
2667 If @var{mode} is @code{nil}, this function adds @var{keywords} to
2668 @code{font-lock-keywords} in the current buffer. This way of calling
2669 @code{font-lock-add-keywords} is usually used in mode hook functions.
2671 By default, @var{keywords} are added at the beginning of
2672 @code{font-lock-keywords}. If the optional argument @var{how} is
2673 @code{set}, they are used to replace the value of
2674 @code{font-lock-keywords}. If @var{how} is any other non-@code{nil}
2675 value, they are added at the end of @code{font-lock-keywords}.
2677 Some modes provide specialized support you can use in additional
2678 highlighting patterns. See the variables
2679 @code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types},
2680 and @code{java-font-lock-extra-types}, for example.
2682 @strong{Warning:} major mode functions must not call
2683 @code{font-lock-add-keywords} under any circumstances, either directly
2684 or indirectly, except through their mode hooks. (Doing so would lead
2685 to incorrect behavior for some minor modes.) They should set up their
2686 rules for search-based fontification by setting
2687 @code{font-lock-keywords}.
2690 @defun font-lock-remove-keywords mode keywords
2691 This function removes @var{keywords} from @code{font-lock-keywords}
2692 for the current buffer or for major mode @var{mode}. As in
2693 @code{font-lock-add-keywords}, @var{mode} should be a major mode
2694 command name or @code{nil}. All the caveats and requirements for
2695 @code{font-lock-add-keywords} apply here too.
2698 For example, this code
2701 (font-lock-add-keywords 'c-mode
2702 '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
2703 ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face)))
2707 adds two fontification patterns for C mode: one to fontify the word
2708 @samp{FIXME}, even in comments, and another to fontify the words
2709 @samp{and}, @samp{or} and @samp{not} as keywords.
2712 That example affects only C mode proper. To add the same patterns to
2713 C mode @emph{and} all modes derived from it, do this instead:
2716 (add-hook 'c-mode-hook
2718 (font-lock-add-keywords nil
2719 '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
2720 ("\\<\\(and\\|or\\|not\\)\\>" .
2721 font-lock-keyword-face)))))
2724 @node Other Font Lock Variables
2725 @subsection Other Font Lock Variables
2727 This section describes additional variables that a major mode can
2728 set by means of @var{other-vars} in @code{font-lock-defaults}
2729 (@pxref{Font Lock Basics}).
2731 @defvar font-lock-mark-block-function
2732 If this variable is non-@code{nil}, it should be a function that is
2733 called with no arguments, to choose an enclosing range of text for
2734 refontification for the command @kbd{M-o M-o}
2735 (@code{font-lock-fontify-block}).
2737 The function should report its choice by placing the region around it.
2738 A good choice is a range of text large enough to give proper results,
2739 but not too large so that refontification becomes slow. Typical values
2740 are @code{mark-defun} for programming modes or @code{mark-paragraph} for
2744 @defvar font-lock-extra-managed-props
2745 This variable specifies additional properties (other than
2746 @code{font-lock-face}) that are being managed by Font Lock mode. It
2747 is used by @code{font-lock-default-unfontify-region}, which normally
2748 only manages the @code{font-lock-face} property. If you want Font
2749 Lock to manage other properties as well, you must specify them in a
2750 @var{facespec} in @code{font-lock-keywords} as well as add them to
2751 this list. @xref{Search-based Fontification}.
2754 @defvar font-lock-fontify-buffer-function
2755 Function to use for fontifying the buffer. The default value is
2756 @code{font-lock-default-fontify-buffer}.
2759 @defvar font-lock-unfontify-buffer-function
2760 Function to use for unfontifying the buffer. This is used when
2761 turning off Font Lock mode. The default value is
2762 @code{font-lock-default-unfontify-buffer}.
2765 @defvar font-lock-fontify-region-function
2766 Function to use for fontifying a region. It should take two
2767 arguments, the beginning and end of the region, and an optional third
2768 argument @var{verbose}. If @var{verbose} is non-@code{nil}, the
2769 function should print status messages. The default value is
2770 @code{font-lock-default-fontify-region}.
2773 @defvar font-lock-unfontify-region-function
2774 Function to use for unfontifying a region. It should take two
2775 arguments, the beginning and end of the region. The default value is
2776 @code{font-lock-default-unfontify-region}.
2780 @defvar font-lock-inhibit-thing-lock
2781 List of Font Lock mode related modes that should not be turned on.
2782 Currently, valid mode names are @code{fast-lock-mode},
2783 @code{jit-lock-mode} and @code{lazy-lock-mode}.
2787 @node Levels of Font Lock
2788 @subsection Levels of Font Lock
2790 Many major modes offer three different levels of fontification. You
2791 can define multiple levels by using a list of symbols for @var{keywords}
2792 in @code{font-lock-defaults}. Each symbol specifies one level of
2793 fontification; it is up to the user to choose one of these levels. The
2794 chosen level's symbol value is used to initialize
2795 @code{font-lock-keywords}.
2797 Here are the conventions for how to define the levels of
2802 Level 1: highlight function declarations, file directives (such as include or
2803 import directives), strings and comments. The idea is speed, so only
2804 the most important and top-level components are fontified.
2807 Level 2: in addition to level 1, highlight all language keywords,
2808 including type names that act like keywords, as well as named constant
2809 values. The idea is that all keywords (either syntactic or semantic)
2810 should be fontified appropriately.
2813 Level 3: in addition to level 2, highlight the symbols being defined in
2814 function and variable declarations, and all builtin function names,
2815 wherever they appear.
2818 @node Precalculated Fontification
2819 @subsection Precalculated Fontification
2821 In addition to using @code{font-lock-defaults} for search-based
2822 fontification, you may use the special character property
2823 @code{font-lock-face} (@pxref{Special Properties}). This property
2824 acts just like the explicit @code{face} property, but its activation
2825 is toggled when the user calls @kbd{M-x font-lock-mode}. Using
2826 @code{font-lock-face} is especially convenient for special modes
2827 which construct their text programmatically, such as
2828 @code{list-buffers} and @code{occur}.
2830 If your mode does not use any of the other machinery of Font Lock
2831 (i.e. it only uses the @code{font-lock-face} property), it should not
2832 set the variable @code{font-lock-defaults}. That way, it will not
2833 cause loading of the @file{font-lock} library.
2835 @node Faces for Font Lock
2836 @subsection Faces for Font Lock
2838 You can make Font Lock mode use any face, but several faces are
2839 defined specifically for Font Lock mode. Each of these symbols is both
2840 a face name, and a variable whose default value is the symbol itself.
2841 Thus, the default value of @code{font-lock-comment-face} is
2842 @code{font-lock-comment-face}. This means you can write
2843 @code{font-lock-comment-face} in a context such as
2844 @code{font-lock-keywords} where a face-name-valued expression is used.
2847 @item font-lock-comment-face
2848 @vindex font-lock-comment-face
2849 Used (typically) for comments.
2851 @item font-lock-comment-delimiter-face
2852 @vindex font-lock-comment-delimiter-face
2853 Used (typically) for comments delimiters.
2855 @item font-lock-doc-face
2856 @vindex font-lock-doc-face
2857 Used (typically) for documentation strings in the code.
2859 @item font-lock-string-face
2860 @vindex font-lock-string-face
2861 Used (typically) for string constants.
2863 @item font-lock-keyword-face
2864 @vindex font-lock-keyword-face
2865 Used (typically) for keywords---names that have special syntactic
2866 significance, like @code{for} and @code{if} in C.
2868 @item font-lock-builtin-face
2869 @vindex font-lock-builtin-face
2870 Used (typically) for built-in function names.
2872 @item font-lock-function-name-face
2873 @vindex font-lock-function-name-face
2874 Used (typically) for the name of a function being defined or declared,
2875 in a function definition or declaration.
2877 @item font-lock-variable-name-face
2878 @vindex font-lock-variable-name-face
2879 Used (typically) for the name of a variable being defined or declared,
2880 in a variable definition or declaration.
2882 @item font-lock-type-face
2883 @vindex font-lock-type-face
2884 Used (typically) for names of user-defined data types,
2885 where they are defined and where they are used.
2887 @item font-lock-constant-face
2888 @vindex font-lock-constant-face
2889 Used (typically) for constant names.
2891 @item font-lock-preprocessor-face
2892 @vindex font-lock-preprocessor-face
2893 Used (typically) for preprocessor commands.
2895 @item font-lock-negation-char-face
2896 @vindex font-lock-negation-char-face
2897 Used (typically) for easily-overlooked negation characters.
2899 @item font-lock-warning-face
2900 @vindex font-lock-warning-face
2901 Used (typically) for constructs that are peculiar, or that greatly
2902 change the meaning of other text. For example, this is used for
2903 @samp{;;;###autoload} cookies in Emacs Lisp, and for @code{#error}
2907 @node Syntactic Font Lock
2908 @subsection Syntactic Font Lock
2910 Syntactic fontification uses the syntax table to find comments and
2911 string constants (@pxref{Syntax Tables}). It highlights them using
2912 @code{font-lock-comment-face} and @code{font-lock-string-face}
2913 (@pxref{Faces for Font Lock}). There are several variables that
2914 affect syntactic fontification; you should set them by means of
2915 @code{font-lock-defaults} (@pxref{Font Lock Basics}).
2917 @defvar font-lock-keywords-only
2918 Non-@code{nil} means Font Lock should not do syntactic fontification;
2919 it should only fontify based on @code{font-lock-keywords}. The normal
2920 way for a mode to set this variable to @code{t} is with
2921 @var{keywords-only} in @code{font-lock-defaults}.
2924 @defvar font-lock-syntax-table
2925 This variable holds the syntax table to use for fontification of
2926 comments and strings. Specify it using @var{syntax-alist} in
2927 @code{font-lock-defaults}. If this is @code{nil}, fontification uses
2928 the buffer's syntax table.
2931 @defvar font-lock-beginning-of-syntax-function
2932 If this variable is non-@code{nil}, it should be a function to move
2933 point back to a position that is syntactically at ``top level'' and
2934 outside of strings or comments. Font Lock uses this when necessary
2935 to get the right results for syntactic fontification.
2937 This function is called with no arguments. It should leave point at
2938 the beginning of any enclosing syntactic block. Typical values are
2939 @code{beginning-of-line} (used when the start of the line is known to
2940 be outside a syntactic block), or @code{beginning-of-defun} for
2941 programming modes, or @code{backward-paragraph} for textual modes.
2943 If the value is @code{nil}, Font Lock uses
2944 @code{syntax-begin-function} to move back outside of any comment,
2945 string, or sexp. This variable is semi-obsolete; we recommend setting
2946 @code{syntax-begin-function} instead.
2948 Specify this variable using @var{syntax-begin} in
2949 @code{font-lock-defaults}.
2952 @defvar font-lock-syntactic-face-function
2953 A function to determine which face to use for a given syntactic
2954 element (a string or a comment). The function is called with one
2955 argument, the parse state at point returned by
2956 @code{parse-partial-sexp}, and should return a face. The default
2957 value returns @code{font-lock-comment-face} for comments and
2958 @code{font-lock-string-face} for strings.
2960 This can be used to highlighting different kinds of strings or
2961 comments differently. It is also sometimes abused together with
2962 @code{font-lock-syntactic-keywords} to highlight constructs that span
2963 multiple lines, but this is too esoteric to document here.
2965 Specify this variable using @var{other-vars} in
2966 @code{font-lock-defaults}.
2969 @node Setting Syntax Properties
2970 @subsection Setting Syntax Properties
2972 Font Lock mode can be used to update @code{syntax-table} properties
2973 automatically (@pxref{Syntax Properties}). This is useful in
2974 languages for which a single syntax table by itself is not sufficient.
2976 @defvar font-lock-syntactic-keywords
2977 This variable enables and controls updating @code{syntax-table}
2978 properties by Font Lock. Its value should be a list of elements of
2982 (@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch})
2985 The parts of this element have the same meanings as in the corresponding
2986 sort of element of @code{font-lock-keywords},
2989 (@var{matcher} @var{subexp} @var{facespec} @var{override} @var{laxmatch})
2992 However, instead of specifying the value @var{facespec} to use for the
2993 @code{face} property, it specifies the value @var{syntax} to use for
2994 the @code{syntax-table} property. Here, @var{syntax} can be a string
2995 (as taken by @code{modify-syntax-entry}), a syntax table, a cons cell
2996 (as returned by @code{string-to-syntax}), or an expression whose value
2997 is one of those two types. @var{override} cannot be @code{prepend} or
3000 For example, an element of the form:
3003 ("\\$\\(#\\)" 1 ".")
3006 highlights syntactically a hash character when following a dollar
3007 character, with a SYNTAX of @code{"."} (meaning punctuation syntax).
3008 Assuming that the buffer syntax table specifies hash characters to
3009 have comment start syntax, the element will only highlight hash
3010 characters that do not follow dollar characters as comments
3013 An element of the form:
3021 highlights syntactically both single quotes which surround a single
3022 character, with a SYNTAX of @code{"\""} (meaning string quote syntax).
3023 Assuming that the buffer syntax table does not specify single quotes
3024 to have quote syntax, the element will only highlight single quotes of
3025 the form @samp{'@var{c}'} as strings syntactically. Other forms, such
3026 as @samp{foo'bar} or @samp{'fubar'}, will not be highlighted as
3029 Major modes normally set this variable with @var{other-vars} in
3030 @code{font-lock-defaults}.
3033 @node Multiline Font Lock
3034 @subsection Multiline Font Lock Constructs
3035 @cindex multiline font lock
3037 Normally, elements of @code{font-lock-keywords} should not match
3038 across multiple lines; that doesn't work reliably, because Font Lock
3039 usually scans just part of the buffer, and it can miss a multi-line
3040 construct that crosses the line boundary where the scan starts. (The
3041 scan normally starts at the beginning of a line.)
3043 Making elements that match multiline constructs work properly has
3044 two aspects: correct @emph{identification} and correct
3045 @emph{rehighlighting}. The first means that Font Lock finds all
3046 multiline constructs. The second means that Font Lock will correctly
3047 rehighlight all the relevant text when a multiline construct is
3048 changed---for example, if some of the text that was previously part of
3049 a multiline construct ceases to be part of it. The two aspects are
3050 closely related, and often getting one of them to work will appear to
3051 make the other also work. However, for reliable results you must
3052 attend explicitly to both aspects.
3054 There are three ways to ensure correct identification of multiline
3059 Place a @code{font-lock-multiline}
3060 property on the construct when it is added to the buffer.
3062 Use @code{font-lock-fontify-region-function} hook to extend the scan
3063 so that the scanned text never starts or ends in the middle of a
3064 multiline construct.
3066 Add a function to @code{font-lock-extend-region-functions} that does
3067 the @emph{identification} and extends the scan so that the scanned
3068 text never starts or ends in the middle of a multiline construct.
3071 There are three ways to do rehighlighting of multiline constructs:
3075 Place a @code{font-lock-multiline} property on the construct. This
3076 will rehighlight the whole construct if any part of it is changed. In
3077 some cases you can do this automatically by setting the
3078 @code{font-lock-multiline} variable.
3080 Use @code{jit-lock-contextually}. This will only rehighlight the part
3081 of the construct that follows the actual change, and will do it after
3082 a short delay. This only works if the highlighting of the various
3083 parts of your multiline construct never depends on text in subsequent
3084 lines. Since @code{jit-lock-contextually} is activated by default,
3085 this can be an attractive solution.
3087 Place a @code{jit-lock-defer-multiline} property on the construct.
3088 This works only if @code{jit-lock-contextually} is used, but it can
3089 handle the case where highlighting depends on subsequent lines.
3093 * Font Lock Multiline:: Marking multiline chunks with a text property
3094 * Region to Fontify:: Controlling which region gets refontified
3095 after a buffer change.
3098 @node Font Lock Multiline
3099 @subsubsection Font Lock Multiline
3101 One way to ensure reliable rehighlighting of multiline Font Lock
3102 constructs is to put on the text property @code{font-lock-multiline}.
3103 It should be present and non-@code{nil} for text that is part of a
3104 multiline construct.
3106 When Font Lock is about to highlight a range of text, it first
3107 extends the boundaries of the range as necessary so that they do not
3108 fall within text marked with the @code{font-lock-multiline} property.
3109 Then it removes any @code{font-lock-multiline} properties from the
3110 range, and highlights it. The highlighting specification (mostly
3111 @code{font-lock-keywords}) must reinstall this property each time,
3112 whenever it is appropriate.
3114 @strong{Warning:} don't use the @code{font-lock-multiline} property
3115 on large ranges of text, because that will make rehighlighting slow.
3117 @defvar font-lock-multiline
3118 If the @code{font-lock-multiline} variable is set to @code{t}, Font
3119 Lock will try to add the @code{font-lock-multiline} property
3120 automatically on multiline constructs. This is not a universal
3121 solution, however, since it slows down Font Lock somewhat. It can
3122 miss some multiline constructs, or make the property larger or smaller
3125 For elements whose @var{matcher} is a function, the function should
3126 ensure that submatch 0 covers the whole relevant multiline construct,
3127 even if only a small subpart will be highlighted. It is often just as
3128 easy to add the @code{font-lock-multiline} property by hand.
3131 The @code{font-lock-multiline} property is meant to ensure proper
3132 refontification; it does not automatically identify new multiline
3133 constructs. Identifying the requires that Font-Lock operate on large
3134 enough chunks at a time. This will happen by accident on many cases,
3135 which may give the impression that multiline constructs magically work.
3136 If you set the @code{font-lock-multiline} variable non-@code{nil},
3137 this impression will be even stronger, since the highlighting of those
3138 constructs which are found will be properly updated from then on.
3139 But that does not work reliably.
3141 To find multiline constructs reliably, you must either manually
3142 place the @code{font-lock-multiline} property on the text before
3143 Font-Lock looks at it, or use
3144 @code{font-lock-fontify-region-function}.
3146 @node Region to Fontify
3147 @subsubsection Region to Fontify after a Buffer Change
3149 When a buffer is changed, the region that Font Lock refontifies is
3150 by default the smallest sequence of whole lines that spans the change.
3151 While this works well most of the time, sometimes it doesn't---for
3152 example, when a change alters the syntactic meaning of text on an
3155 You can enlarge (or even reduce) the region to fontify by setting
3156 one the following variables:
3158 @defvar font-lock-extend-after-change-region-function
3159 This buffer-local variable is either @code{nil} or a function for
3160 Font-Lock to call to determine the region to scan and fontify.
3162 The function is given three parameters, the standard @var{beg},
3163 @var{end}, and @var{old-len} from after-change-functions
3164 (@pxref{Change Hooks}). It should return either a cons of the
3165 beginning and end buffer positions (in that order) of the region to
3166 fontify, or @code{nil} (which means choose the region in the standard
3167 way). This function needs to preserve point, the match-data, and the
3168 current restriction. The region it returns may start or end in the
3171 Since this function is called after every buffer change, it should be
3175 @node Desktop Save Mode
3176 @section Desktop Save Mode
3177 @cindex desktop save mode
3179 @dfn{Desktop Save Mode} is a feature to save the state of Emacs from
3180 one session to another. The user-level commands for using Desktop
3181 Save Mode are described in the GNU Emacs Manual (@pxref{Saving Emacs
3182 Sessions,,, emacs, the GNU Emacs Manual}). Modes whose buffers visit
3183 a file, don't have to do anything to use this feature.
3185 For buffers not visiting a file to have their state saved, the major
3186 mode must bind the buffer local variable @code{desktop-save-buffer} to
3187 a non-@code{nil} value.
3189 @defvar desktop-save-buffer
3190 If this buffer-local variable is non-@code{nil}, the buffer will have
3191 its state saved in the desktop file at desktop save. If the value is
3192 a function, it is called at desktop save with argument
3193 @var{desktop-dirname}, and its value is saved in the desktop file along
3194 with the state of the buffer for which it was called. When file names
3195 are returned as part of the auxiliary information, they should be
3196 formatted using the call
3199 (desktop-file-name @var{file-name} @var{desktop-dirname})
3204 For buffers not visiting a file to be restored, the major mode must
3205 define a function to do the job, and that function must be listed in
3206 the alist @code{desktop-buffer-mode-handlers}.
3208 @defvar desktop-buffer-mode-handlers
3212 (@var{major-mode} . @var{restore-buffer-function})
3215 The function @var{restore-buffer-function} will be called with
3219 (@var{buffer-file-name} @var{buffer-name} @var{desktop-buffer-misc})
3222 and it should return the restored buffer.
3223 Here @var{desktop-buffer-misc} is the value returned by the function
3224 optionally bound to @code{desktop-save-buffer}.
3228 arch-tag: 4c7bff41-36e6-4da6-9e7f-9b9289e27c8e