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 mode functions also run a mode hook at the end.
56 But 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}. That means the hook
70 functions are called with arguments, or their return values are used
71 in some way. The hook's documentation says how the functions are
72 called. You can use @code{add-hook} to add a function to an abnormal
73 hook, but you must write the function to follow the hook's calling
76 By convention, abnormal hook names end in @samp{-functions} or
77 @samp{-hooks}. If the variable's name ends in @samp{-function}, then
78 its value is just a single function, not a list of functions.
80 Here's an example that uses a mode hook to turn on Auto Fill mode when
81 in Lisp Interaction mode:
84 (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
87 At the appropriate time, Emacs uses the @code{run-hooks} function to
90 @defun run-hooks &rest hookvars
91 This function takes one or more normal hook variable names as
92 arguments, and runs each hook in turn. Each argument should be a
93 symbol that is a normal hook variable. These arguments are processed
94 in the order specified.
96 If a hook variable has a non-@code{nil} value, that value should be a
97 list of functions. @code{run-hooks} calls all the functions, one by
98 one, with no arguments.
100 The hook variable's value can also be a single function---either a
101 lambda expression or a symbol with a function definition---which
102 @code{run-hooks} calls. But this usage is obsolete.
105 @defun run-hook-with-args hook &rest args
106 This function is the way to run an abnormal hook and always call all
107 of the hook functions. It calls each of the hook functions one by
108 one, passing each of them the arguments @var{args}.
111 @defun run-hook-with-args-until-failure hook &rest args
112 This function is the way to run an abnormal hook until one of the hook
113 functions fails. It calls each of the hook functions, passing each of
114 them the arguments @var{args}, until some hook function returns
115 @code{nil}. It then stops and returns @code{nil}. If none of the
116 hook functions return @code{nil}, it returns a non-@code{nil} value.
119 @defun run-hook-with-args-until-success hook &rest args
120 This function is the way to run an abnormal hook until a hook function
121 succeeds. It calls each of the hook functions, passing each of them
122 the arguments @var{args}, until some hook function returns
123 non-@code{nil}. Then it stops, and returns whatever was returned by
124 the last hook function that was called. If all hook functions return
125 @code{nil}, it returns @code{nil} as well.
128 @defun add-hook hook function &optional append local
129 This function is the handy way to add function @var{function} to hook
130 variable @var{hook}. You can use it for abnormal hooks as well as for
131 normal hooks. @var{function} can be any Lisp function that can accept
132 the proper number of arguments for @var{hook}. For example,
135 (add-hook 'text-mode-hook 'my-text-hook-function)
139 adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
141 If @var{function} is already present in @var{hook} (comparing using
142 @code{equal}), then @code{add-hook} does not add it a second time.
144 It is best to design your hook functions so that the order in which they
145 are executed does not matter. Any dependence on the order is ``asking
146 for trouble.'' However, the order is predictable: normally,
147 @var{function} goes at the front of the hook list, so it will be
148 executed first (barring another @code{add-hook} call). If the optional
149 argument @var{append} is non-@code{nil}, the new hook function goes at
150 the end of the hook list and will be executed last.
152 @code{add-hook} can handle the cases where @var{hook} is void or its
153 value is a single function; it sets or changes the value to a list of
156 If @var{local} is non-@code{nil}, that says to add @var{function} to
157 the buffer-local hook list instead of to the global hook list. If
158 needed, this makes the hook buffer-local and adds @code{t} to the
159 buffer-local value. The latter acts as a flag to run the hook
160 functions in the default value as well as in the local value.
163 @defun remove-hook hook function &optional local
164 This function removes @var{function} from the hook variable
165 @var{hook}. It compares @var{function} with elements of @var{hook}
166 using @code{equal}, so it works for both symbols and lambda
169 If @var{local} is non-@code{nil}, that says to remove @var{function}
170 from the buffer-local hook list instead of from the global hook list.
177 Major modes specialize Emacs for editing particular kinds of text.
178 Each buffer has only one major mode at a time. For each major mode
179 there is a function to switch to that mode in the current buffer; its
180 name should end in @samp{-mode}. These functions work by setting
181 buffer-local variable bindings and other data associated with the
182 buffer, such as a local keymap. The effect lasts until you switch
183 to another major mode in the same buffer.
186 * Major Mode Basics::
187 * Major Mode Conventions:: Coding conventions for keymaps, etc.
188 * Auto Major Mode:: How Emacs chooses the major mode automatically.
189 * Mode Help:: Finding out how to use a mode.
190 * Derived Modes:: Defining a new major mode based on another major
192 * Generic Modes:: Defining a simple major mode that supports
193 comment syntax and Font Lock mode.
194 * Mode Hooks:: Hooks run at the end of major mode functions.
195 * Example Major Modes:: Text mode and Lisp modes.
198 @node Major Mode Basics
199 @subsection Major Mode Basics
200 @cindex Fundamental mode
202 The least specialized major mode is called @dfn{Fundamental mode}.
203 This mode has no mode-specific definitions or variable settings, so each
204 Emacs command behaves in its default manner, and each option is in its
205 default state. All other major modes redefine various keys and options.
206 For example, Lisp Interaction mode provides special key bindings for
207 @kbd{C-j} (@code{eval-print-last-sexp}), @key{TAB}
208 (@code{lisp-indent-line}), and other keys.
210 When you need to write several editing commands to help you perform a
211 specialized editing task, creating a new major mode is usually a good
212 idea. In practice, writing a major mode is easy (in contrast to
213 writing a minor mode, which is often difficult).
215 If the new mode is similar to an old one, it is often unwise to
216 modify the old one to serve two purposes, since it may become harder
217 to use and maintain. Instead, copy and rename an existing major mode
218 definition and alter the copy---or use @code{define-derived-mode} to
219 define a @dfn{derived mode} (@pxref{Derived Modes}). For example,
220 Rmail Edit mode is a major mode that is very similar to Text mode
221 except that it provides two additional commands. Its definition is
222 distinct from that of Text mode, but uses that of Text mode.
224 Even if the new mode is not an obvious derivative of any other mode,
225 it is convenient to use @code{define-derived-mode} with a @code{nil}
226 parent argument, since it automatically enforces the most important
227 coding conventions for you.
229 For a very simple programming language major mode that handles
230 comments and fontification, you can use @code{define-generic-mode}.
231 @xref{Generic Modes}.
233 Rmail Edit mode offers an example of changing the major mode
234 temporarily for a buffer, so it can be edited in a different way (with
235 ordinary Emacs commands rather than Rmail commands). In such cases, the
236 temporary major mode usually provides a command to switch back to the
237 buffer's usual mode (Rmail mode, in this case). You might be tempted to
238 present the temporary redefinitions inside a recursive edit and restore
239 the usual ones when the user exits; but this is a bad idea because it
240 constrains the user's options when it is done in more than one buffer:
241 recursive edits must be exited most-recently-entered first. Using an
242 alternative major mode avoids this limitation. @xref{Recursive
245 The standard GNU Emacs Lisp library directory tree contains the code
246 for several major modes, in files such as @file{text-mode.el},
247 @file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
248 @file{rmail.el}. They are found in various subdirectories of the
249 @file{lisp} directory. You can study these libraries to see how modes
250 are written. Text mode is perhaps the simplest major mode aside from
251 Fundamental mode. Rmail mode is a complicated and specialized mode.
253 @node Major Mode Conventions
254 @subsection Major Mode Conventions
256 The code for existing major modes follows various coding conventions,
257 including conventions for local keymap and syntax table initialization,
258 global names, and hooks. Please follow these conventions when you
259 define a new major mode.
261 This list of conventions is only partial, because each major mode
262 should aim for consistency in general with other Emacs major modes.
263 This makes Emacs as a whole more coherent. It is impossible to list
264 here all the possible points where this issue might come up; if the
265 Emacs developers point out an area where your major mode deviates from
266 the usual conventions, please make it compatible.
270 Define a command whose name ends in @samp{-mode}, with no arguments,
271 that switches to the new mode in the current buffer. This command
272 should set up the keymap, syntax table, and buffer-local variables in an
273 existing buffer, without changing the buffer's contents.
276 Write a documentation string for this command that describes the
277 special commands available in this mode. @kbd{C-h m}
278 (@code{describe-mode}) in your mode will display this string.
280 The documentation string may include the special documentation
281 substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
282 @samp{\<@var{keymap}>}, which enable the documentation to adapt
283 automatically to the user's own key bindings. @xref{Keys in
287 The major mode command should start by calling
288 @code{kill-all-local-variables}. This runs the normal hook
289 @code{change-major-mode-hook}, then gets rid of the buffer-local
290 variables of the major mode previously in effect. @xref{Creating
294 The major mode command should set the variable @code{major-mode} to the
295 major mode command symbol. This is how @code{describe-mode} discovers
296 which documentation to print.
299 The major mode command should set the variable @code{mode-name} to the
300 ``pretty'' name of the mode, as a string. This string appears in the
304 @cindex functions in modes
305 Since all global names are in the same name space, all the global
306 variables, constants, and functions that are part of the mode should
307 have names that start with the major mode name (or with an abbreviation
308 of it if the name is long). @xref{Coding Conventions}.
311 In a major mode for editing some kind of structured text, such as a
312 programming language, indentation of text according to structure is
313 probably useful. So the mode should set @code{indent-line-function}
314 to a suitable function, and probably customize other variables
318 @cindex keymaps in modes
319 The major mode should usually have its own keymap, which is used as the
320 local keymap in all buffers in that mode. The major mode command should
321 call @code{use-local-map} to install this local map. @xref{Active
322 Keymaps}, for more information.
324 This keymap should be stored permanently in a global variable named
325 @code{@var{modename}-mode-map}. Normally the library that defines the
326 mode sets this variable.
328 @xref{Tips for Defining}, for advice about how to write the code to set
329 up the mode's keymap variable.
332 The key sequences bound in a major mode keymap should usually start with
333 @kbd{C-c}, followed by a control character, a digit, or @kbd{@{},
334 @kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}. The other punctuation
335 characters are reserved for minor modes, and ordinary letters are
338 A major mode can also rebind the keys @kbd{M-n}, @kbd{M-p} and
339 @kbd{M-s}. The bindings for @kbd{M-n} and @kbd{M-p} should normally
340 be some kind of ``moving forward and backward,'' but this does not
341 necessarily mean cursor motion.
343 It is legitimate for a major mode to rebind a standard key sequence if
344 it provides a command that does ``the same job'' in a way better
345 suited to the text this mode is used for. For example, a major mode
346 for editing a programming language might redefine @kbd{C-M-a} to
347 ``move to the beginning of a function'' in a way that works better for
350 It is also legitimate for a major mode to rebind a standard key
351 sequence whose standard meaning is rarely useful in that mode. For
352 instance, minibuffer modes rebind @kbd{M-r}, whose standard meaning is
353 rarely of any use in the minibuffer. Major modes such as Dired or
354 Rmail that do not allow self-insertion of text can reasonably redefine
355 letters and other printing characters as special commands.
358 Major modes modes for editing text should not define @key{RET} to do
359 anything other than insert a newline. However, it is ok for
360 specialized modes for text that users don't directly edit, such as
361 Dired and Info modes, to redefine @key{RET} to do something entirely
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 defines a generic mode command named @var{mode} (a symbol,
811 not quoted). The optional argument @var{docstring} is the
812 documentation for the mode command. If you do not supply it,
813 @code{define-generic-mode} generates one by default.
815 The argument @var{comment-list} is a list in which each element is
816 either a character, a string of one or two characters, or a cons cell.
817 A character or a string is set up in the mode's syntax table as a
818 ``comment starter.'' If the entry is a cons cell, the @sc{car} is set
819 up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.''
820 (Use @code{nil} for the latter if you want comments to end at the end
821 of the line.) Note that the syntax table mechanism has limitations
822 about what comment starters and enders are actually possible.
823 @xref{Syntax Tables}.
825 The argument @var{keyword-list} is a list of keywords to highlight
826 with @code{font-lock-keyword-face}. Each keyword should be a string.
827 Meanwhile, @var{font-lock-list} is a list of additional expressions to
828 highlight. Each element of this list should have the same form as an
829 element of @code{font-lock-keywords}. @xref{Search-based
832 The argument @var{auto-mode-list} is a list of regular expressions to
833 add to the variable @code{auto-mode-alist}. They are added by the execution
834 of the @code{define-generic-mode} form, not by expanding the macro call.
836 Finally, @var{function-list} is a list of functions for the mode
837 command to call for additional setup. It calls these functions just
838 before it runs the mode hook variable @code{@var{mode}-hook}.
842 @subsection Mode Hooks
844 Every major mode function should finish by running its mode hook and
845 the mode-independent normal hook @code{after-change-major-mode-hook}.
846 It does this by calling @code{run-mode-hooks}. If the major mode is a
847 derived mode, that is if it calls another major mode (the parent mode)
848 in its body, it should do this inside @code{delay-mode-hooks} so that
849 the parent won't run these hooks itself. Instead, the derived mode's
850 call to @code{run-mode-hooks} runs the parent's mode hook too.
851 @xref{Major Mode Conventions}.
853 Emacs versions before Emacs 22 did not have @code{delay-mode-hooks}.
854 When user-implemented major modes have not been updated to use it,
855 they won't entirely follow these conventions: they may run the
856 parent's mode hook too early, or fail to run
857 @code{after-change-major-mode-hook}. If you encounter such a major
858 mode, please correct it to follow these conventions.
860 When you defined a major mode using @code{define-derived-mode}, it
861 automatically makes sure these conventions are followed. If you
862 define a major mode ``by hand,'' not using @code{define-derived-mode},
863 use the following functions to handle these conventions automatically.
865 @defun run-mode-hooks &rest hookvars
866 Major modes should run their mode hook using this function. It is
867 similar to @code{run-hooks} (@pxref{Hooks}), but it also runs
868 @code{after-change-major-mode-hook}.
870 When this function is called during the execution of a
871 @code{delay-mode-hooks} form, it does not run the hooks immediately.
872 Instead, it arranges for the next call to @code{run-mode-hooks} to run
876 @defmac delay-mode-hooks body@dots{}
877 When one major mode command calls another, it should do so inside of
878 @code{delay-mode-hooks}.
880 This macro executes @var{body}, but tells all @code{run-mode-hooks}
881 calls during the execution of @var{body} to delay running their hooks.
882 The hooks will actually run during the next call to
883 @code{run-mode-hooks} after the end of the @code{delay-mode-hooks}
887 @defvar after-change-major-mode-hook
888 This is a normal hook run by @code{run-mode-hooks}. It is run at the
889 very end of every properly-written major mode function.
892 @node Example Major Modes
893 @subsection Major Mode Examples
895 Text mode is perhaps the simplest mode besides Fundamental mode.
896 Here are excerpts from @file{text-mode.el} that illustrate many of
897 the conventions listed above:
901 ;; @r{Create the syntax table for this mode.}
902 (defvar text-mode-syntax-table
903 (let ((st (make-syntax-table)))
904 (modify-syntax-entry ?\" ". " st)
905 (modify-syntax-entry ?\\ ". " st)
906 ;; Add `p' so M-c on `hello' leads to `Hello', not `hello'.
907 (modify-syntax-entry ?' "w p" st)
909 "Syntax table used while in `text-mode'.")
912 ;; @r{Create the keymap for this mode.}
914 (defvar text-mode-map
915 (let ((map (make-sparse-keymap)))
916 (define-key map "\e\t" 'ispell-complete-word)
917 (define-key map "\es" 'center-line)
918 (define-key map "\eS" 'center-paragraph)
920 "Keymap for `text-mode'.
921 Many other modes, such as Mail mode, Outline mode
922 and Indented Text mode, inherit all the commands
923 defined in this map.")
927 Here is how the actual mode command is defined now:
931 (define-derived-mode text-mode nil "Text"
932 "Major mode for editing text written for humans to read.
933 In this mode, paragraphs are delimited only by blank or white lines.
934 You can thus get the full benefit of adaptive filling
935 (see the variable `adaptive-fill-mode').
937 Turning on Text mode runs the normal hook `text-mode-hook'."
940 (make-local-variable 'text-mode-variant)
941 (setq text-mode-variant t)
942 ;; @r{These two lines are a feature added recently.}
943 (set (make-local-variable 'require-final-newline)
944 mode-require-final-newline)
945 (set (make-local-variable 'indent-line-function) 'indent-relative))
949 But here is how it was defined formerly, before
950 @code{define-derived-mode} existed:
954 ;; @r{This isn't needed nowadays, since @code{define-derived-mode} does it.}
955 (defvar text-mode-abbrev-table nil
956 "Abbrev table used while in text mode.")
957 (define-abbrev-table 'text-mode-abbrev-table ())
962 "Major mode for editing text intended for humans to read...
963 Special commands: \\@{text-mode-map@}
966 Turning on text-mode runs the hook `text-mode-hook'."
968 (kill-all-local-variables)
969 (use-local-map text-mode-map)
972 (setq local-abbrev-table text-mode-abbrev-table)
973 (set-syntax-table text-mode-syntax-table)
976 ;; @r{These four lines are absent from the current version}
977 ;; @r{not because this is done some other way, but rather}
978 ;; @r{because nowadays Text mode uses the normal definition of paragraphs.}
979 (make-local-variable 'paragraph-start)
980 (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter))
981 (make-local-variable 'paragraph-separate)
982 (setq paragraph-separate paragraph-start)
983 (make-local-variable 'indent-line-function)
984 (setq indent-line-function 'indent-relative-maybe)
987 (setq mode-name "Text")
988 (setq major-mode 'text-mode)
989 (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
990 ; @r{customize the mode with a hook.}
994 @cindex @file{lisp-mode.el}
995 The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
996 Interaction mode) have more features than Text mode and the code is
997 correspondingly more complicated. Here are excerpts from
998 @file{lisp-mode.el} that illustrate how these modes are written.
1000 @cindex syntax table example
1003 ;; @r{Create mode-specific table variables.}
1004 (defvar lisp-mode-syntax-table nil "")
1005 (defvar lisp-mode-abbrev-table nil "")
1009 (defvar emacs-lisp-mode-syntax-table
1010 (let ((table (make-syntax-table)))
1015 ;; @r{Set syntax of chars up to @samp{0} to say they are}
1016 ;; @r{part of symbol names but not words.}
1017 ;; @r{(The digit @samp{0} is @code{48} in the @acronym{ASCII} character set.)}
1019 (modify-syntax-entry i "_ " table)
1021 ;; @r{@dots{} similar code follows for other character ranges.}
1024 ;; @r{Then set the syntax codes for characters that are special in Lisp.}
1025 (modify-syntax-entry ? " " table)
1026 (modify-syntax-entry ?\t " " table)
1027 (modify-syntax-entry ?\f " " table)
1028 (modify-syntax-entry ?\n "> " table)
1031 ;; @r{Give CR the same syntax as newline, for selective-display.}
1032 (modify-syntax-entry ?\^m "> " table)
1033 (modify-syntax-entry ?\; "< " table)
1034 (modify-syntax-entry ?` "' " table)
1035 (modify-syntax-entry ?' "' " table)
1036 (modify-syntax-entry ?, "' " table)
1039 ;; @r{@dots{}likewise for many other characters@dots{}}
1040 (modify-syntax-entry ?\( "() " table)
1041 (modify-syntax-entry ?\) ")( " table)
1042 (modify-syntax-entry ?\[ "(] " table)
1043 (modify-syntax-entry ?\] ")[ " table))
1047 ;; @r{Create an abbrev table for lisp-mode.}
1048 (define-abbrev-table 'lisp-mode-abbrev-table ())
1052 The three modes for Lisp share much of their code. For instance,
1053 each calls the following function to set various variables:
1057 (defun lisp-mode-variables (lisp-syntax)
1059 (set-syntax-table lisp-mode-syntax-table))
1060 (setq local-abbrev-table lisp-mode-abbrev-table)
1065 In Lisp and most programming languages, we want the paragraph
1066 commands to treat only blank lines as paragraph separators. And the
1067 modes should undestand the Lisp conventions for comments. The rest of
1068 @code{lisp-mode-variables} sets this up:
1072 (make-local-variable 'paragraph-start)
1073 (setq paragraph-start (concat page-delimiter "\\|$" ))
1074 (make-local-variable 'paragraph-separate)
1075 (setq paragraph-separate paragraph-start)
1079 (make-local-variable 'comment-indent-function)
1080 (setq comment-indent-function 'lisp-comment-indent))
1085 Each of the different Lisp modes has a slightly different keymap. For
1086 example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other
1087 Lisp modes do not. However, all Lisp modes have some commands in
1088 common. The following code sets up the common commands:
1092 (defvar shared-lisp-mode-map ()
1093 "Keymap for commands shared by all sorts of Lisp modes.")
1095 ;; @r{Putting this @code{if} after the @code{defvar} is an older style.}
1096 (if shared-lisp-mode-map
1098 (setq shared-lisp-mode-map (make-sparse-keymap))
1099 (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp)
1100 (define-key shared-lisp-mode-map "\177"
1101 'backward-delete-char-untabify))
1106 And here is the code to set up the keymap for Lisp mode:
1110 (defvar lisp-mode-map ()
1111 "Keymap for ordinary Lisp mode...")
1115 (setq lisp-mode-map (make-sparse-keymap))
1116 (set-keymap-parent lisp-mode-map shared-lisp-mode-map)
1117 (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun)
1118 (define-key lisp-mode-map "\C-c\C-z" 'run-lisp))
1122 Finally, here is the complete major mode function definition for
1128 "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
1130 Delete converts tabs to spaces as it moves back.
1131 Blank lines separate paragraphs. Semicolons start comments.
1133 Note that `run-lisp' may be used either to start an inferior Lisp job
1134 or to switch back to an existing one.
1138 Entry to this mode calls the value of `lisp-mode-hook'
1139 if that value is non-nil."
1141 (kill-all-local-variables)
1144 (use-local-map lisp-mode-map) ; @r{Select the mode's keymap.}
1145 (setq major-mode 'lisp-mode) ; @r{This is how @code{describe-mode}}
1146 ; @r{finds out what to describe.}
1147 (setq mode-name "Lisp") ; @r{This goes into the mode line.}
1148 (lisp-mode-variables t) ; @r{This defines various variables.}
1149 (make-local-variable 'comment-start-skip)
1150 (setq comment-start-skip
1151 "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *")
1152 (make-local-variable 'font-lock-keywords-case-fold-search)
1153 (setq font-lock-keywords-case-fold-search t)
1156 (setq imenu-case-fold-search t)
1157 (set-syntax-table lisp-mode-syntax-table)
1158 (run-mode-hooks 'lisp-mode-hook)) ; @r{This permits the user to use a}
1159 ; @r{hook to customize the mode.}
1164 @section Minor Modes
1167 A @dfn{minor mode} provides features that users may enable or disable
1168 independently of the choice of major mode. Minor modes can be enabled
1169 individually or in combination. Minor modes would be better named
1170 ``generally available, optional feature modes,'' except that such a name
1173 A minor mode is not usually meant as a variation of a single major mode.
1174 Usually they are general and can apply to many major modes. For
1175 example, Auto Fill mode works with any major mode that permits text
1176 insertion. To be general, a minor mode must be effectively independent
1177 of the things major modes do.
1179 A minor mode is often much more difficult to implement than a major
1180 mode. One reason is that you should be able to activate and deactivate
1181 minor modes in any order. A minor mode should be able to have its
1182 desired effect regardless of the major mode and regardless of the other
1183 minor modes in effect.
1185 Often the biggest problem in implementing a minor mode is finding a
1186 way to insert the necessary hook into the rest of Emacs. Minor mode
1187 keymaps make this easier than it used to be.
1189 @defvar minor-mode-list
1190 The value of this variable is a list of all minor mode commands.
1194 * Minor Mode Conventions:: Tips for writing a minor mode.
1195 * Keymaps and Minor Modes:: How a minor mode can have its own keymap.
1196 * Defining Minor Modes:: A convenient facility for defining minor modes.
1199 @node Minor Mode Conventions
1200 @subsection Conventions for Writing Minor Modes
1201 @cindex minor mode conventions
1202 @cindex conventions for writing minor modes
1204 There are conventions for writing minor modes just as there are for
1205 major modes. Several of the major mode conventions apply to minor
1206 modes as well: those regarding the name of the mode initialization
1207 function, the names of global symbols, the use of a hook at the end of
1208 the initialization function, and the use of keymaps and other tables.
1210 In addition, there are several conventions that are specific to
1211 minor modes. (The easiest way to follow all the conventions is to use
1212 the macro @code{define-minor-mode}; @ref{Defining Minor Modes}.)
1216 @cindex mode variable
1217 Make a variable whose name ends in @samp{-mode} to control the minor
1218 mode. We call this the @dfn{mode variable}. The minor mode command
1219 should set this variable (@code{nil} to disable; anything else to
1222 If possible, implement the mode so that setting the variable
1223 automatically enables or disables the mode. Then the minor mode command
1224 does not need to do anything except set the variable.
1226 This variable is used in conjunction with the @code{minor-mode-alist} to
1227 display the minor mode name in the mode line. It can also enable
1228 or disable a minor mode keymap. Individual commands or hooks can also
1229 check the variable's value.
1231 If you want the minor mode to be enabled separately in each buffer,
1232 make the variable buffer-local.
1235 Define a command whose name is the same as the mode variable.
1236 Its job is to enable and disable the mode by setting the variable.
1238 The command should accept one optional argument. If the argument is
1239 @code{nil}, it should toggle the mode (turn it on if it is off, and
1240 off if it is on). It should turn the mode on if the argument is a
1241 positive integer, the symbol @code{t}, or a list whose @sc{car} is one
1242 of those. It should turn the mode off if the argument is a negative
1243 integer or zero, the symbol @code{-}, or a list whose @sc{car} is a
1244 negative integer or zero. The meaning of other arguments is not
1247 Here is an example taken from the definition of @code{transient-mark-mode}.
1248 It shows the use of @code{transient-mark-mode} as a variable that enables or
1249 disables the mode's behavior, and also shows the proper way to toggle,
1250 enable or disable the minor mode based on the raw prefix argument value.
1254 (setq transient-mark-mode
1255 (if (null arg) (not transient-mark-mode)
1256 (> (prefix-numeric-value arg) 0)))
1261 Add an element to @code{minor-mode-alist} for each minor mode
1262 (@pxref{Definition of minor-mode-alist}), if you want to indicate the
1263 minor mode in the mode line. This element should be a list of the
1267 (@var{mode-variable} @var{string})
1270 Here @var{mode-variable} is the variable that controls enabling of the
1271 minor mode, and @var{string} is a short string, starting with a space,
1272 to represent the mode in the mode line. These strings must be short so
1273 that there is room for several of them at once.
1275 When you add an element to @code{minor-mode-alist}, use @code{assq} to
1276 check for an existing element, to avoid duplication. For example:
1280 (unless (assq 'leif-mode minor-mode-alist)
1281 (setq minor-mode-alist
1282 (cons '(leif-mode " Leif") minor-mode-alist)))
1287 or like this, using @code{add-to-list} (@pxref{List Variables}):
1291 (add-to-list 'minor-mode-alist '(leif-mode " Leif"))
1296 Global minor modes distributed with Emacs should if possible support
1297 enabling and disabling via Custom (@pxref{Customization}). To do this,
1298 the first step is to define the mode variable with @code{defcustom}, and
1299 specify @code{:type boolean}.
1301 If just setting the variable is not sufficient to enable the mode, you
1302 should also specify a @code{:set} method which enables the mode by
1303 invoking the mode command. Note in the variable's documentation string that
1304 setting the variable other than via Custom may not take effect.
1306 Also mark the definition with an autoload cookie (@pxref{autoload cookie}),
1307 and specify a @code{:require} so that customizing the variable will load
1308 the library that defines the mode. This will copy suitable definitions
1309 into @file{loaddefs.el} so that users can use @code{customize-option} to
1310 enable the mode. For example:
1316 (defcustom msb-mode nil
1318 Setting this variable directly does not take effect;
1319 use either \\[customize] or the function `msb-mode'."
1320 :set 'custom-set-minor-mode
1321 :initialize 'custom-initialize-default
1329 @node Keymaps and Minor Modes
1330 @subsection Keymaps and Minor Modes
1332 Each minor mode can have its own keymap, which is active when the mode
1333 is enabled. To set up a keymap for a minor mode, add an element to the
1334 alist @code{minor-mode-map-alist}. @xref{Definition of minor-mode-map-alist}.
1336 @cindex @code{self-insert-command}, minor modes
1337 One use of minor mode keymaps is to modify the behavior of certain
1338 self-inserting characters so that they do something else as well as
1339 self-insert. In general, this is the only way to do that, since the
1340 facilities for customizing @code{self-insert-command} are limited to
1341 special cases (designed for abbrevs and Auto Fill mode). (Do not try
1342 substituting your own definition of @code{self-insert-command} for the
1343 standard one. The editor command loop handles this function specially.)
1345 The key sequences bound in a minor mode should consist of @kbd{C-c}
1346 followed by one of @kbd{.,/?`'"[]\|~!#$%^&*()-_+=}. (The other
1347 punctuation characters are reserved for major modes.)
1349 @node Defining Minor Modes
1350 @subsection Defining Minor Modes
1352 The macro @code{define-minor-mode} offers a convenient way of
1353 implementing a mode in one self-contained definition.
1355 @defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args@dots{} body@dots{}
1356 This macro defines a new minor mode whose name is @var{mode} (a
1357 symbol). It defines a command named @var{mode} to toggle the minor
1358 mode, with @var{doc} as its documentation string. It also defines a
1359 variable named @var{mode}, which is set to @code{t} or @code{nil} by
1360 enabling or disabling the mode. The variable is initialized to
1361 @var{init-value}. Except in unusual circumstances (see below), this
1362 value must be @code{nil}.
1364 The string @var{lighter} says what to display in the mode line
1365 when the mode is enabled; if it is @code{nil}, the mode is not displayed
1368 The optional argument @var{keymap} specifies the keymap for the minor mode.
1369 It can be a variable name, whose value is the keymap, or it can be an alist
1370 specifying bindings in this form:
1373 (@var{key-sequence} . @var{definition})
1376 The above three arguments @var{init-value}, @var{lighter}, and
1377 @var{keymap} can be (partially) omitted when @var{keyword-args} are
1378 used. The @var{keyword-args} consist of keywords followed by
1379 corresponding values. A few keywords have special meanings:
1382 @item :group @var{group}
1383 Custom group name to use in all generated @code{defcustom} forms.
1384 Defaults to @var{mode} without the possible trailing @samp{-mode}.
1385 @strong{Warning:} don't use this default group name unless you have
1386 written a @code{defgroup} to define that group properly. @xref{Group
1389 @item :global @var{global}
1390 If non-@code{nil} specifies that the minor mode should be global. By
1391 default, minor modes defined with @code{define-minor-mode} are
1394 @item :init-value @var{init-value}
1395 This is equivalent to specifying @var{init-value} positionally.
1397 @item :lighter @var{lighter}
1398 This is equivalent to specifying @var{lighter} positionally.
1400 @item :keymap @var{keymap}
1401 This is equivalent to specifying @var{keymap} positionally.
1404 Any other keyword arguments are passed directly to the
1405 @code{defcustom} generated for the variable @var{mode}.
1407 The command named @var{mode} first performs the standard actions such
1408 as setting the variable named @var{mode} and then executes the
1409 @var{body} forms, if any. It finishes by running the mode hook
1410 variable @code{@var{mode}-hook}.
1413 The initial value must be @code{nil} except in cases where (1) the
1414 mode is preloaded in Emacs, or (2) it is painless for loading to
1415 enable the mode even though the user did not request it. For
1416 instance, if the mode has no effect unless something else is enabled,
1417 and will always be loaded by that time, enabling it by default is
1418 harmless. But these are unusual circumstances. Normally, the
1419 initial value must be @code{nil}.
1421 @findex easy-mmode-define-minor-mode
1422 The name @code{easy-mmode-define-minor-mode} is an alias
1425 Here is an example of using @code{define-minor-mode}:
1428 (define-minor-mode hungry-mode
1429 "Toggle Hungry mode.
1430 With no argument, this command toggles the mode.
1431 Non-null prefix argument turns on the mode.
1432 Null prefix argument turns off the mode.
1434 When Hungry mode is enabled, the control delete key
1435 gobbles all preceding whitespace except the last.
1436 See the command \\[hungry-electric-delete]."
1437 ;; The initial value.
1439 ;; The indicator for the mode line.
1441 ;; The minor mode bindings.
1442 '(("\C-\^?" . hungry-electric-delete))
1447 This defines a minor mode named ``Hungry mode,'' a command named
1448 @code{hungry-mode} to toggle it, a variable named @code{hungry-mode}
1449 which indicates whether the mode is enabled, and a variable named
1450 @code{hungry-mode-map} which holds the keymap that is active when the
1451 mode is enabled. It initializes the keymap with a key binding for
1452 @kbd{C-@key{DEL}}. It puts the variable @code{hungry-mode} into
1453 custom group @code{hunger}. There are no @var{body} forms---many
1454 minor modes don't need any.
1456 Here's an equivalent way to write it:
1459 (define-minor-mode hungry-mode
1460 "Toggle Hungry mode.
1461 With no argument, this command toggles the mode.
1462 Non-null prefix argument turns on the mode.
1463 Null prefix argument turns off the mode.
1465 When Hungry mode is enabled, the control delete key
1466 gobbles all preceding whitespace except the last.
1467 See the command \\[hungry-electric-delete]."
1468 ;; The initial value.
1470 ;; The indicator for the mode line.
1472 ;; The minor mode bindings.
1474 '(("\C-\^?" . hungry-electric-delete)
1478 (hungry-electric-delete t))))
1482 @defmac define-global-minor-mode global-mode mode turn-on keyword-args@dots{}
1483 This defines a global minor mode named @var{global-mode} whose meaning
1484 is to enable the buffer-local minor mode @var{mode} in every buffer.
1485 To turn on the minor mode in a buffer, it uses the function
1486 @var{turn-on}; to turn off the minor mode, it calls @code{mode} with
1487 @minus{}1 as argument.
1489 Use @code{:group @var{group}} in @var{keyword-args} to specify the
1490 custom group for the mode variable of the global minor mode.
1493 @node Mode Line Format
1494 @section Mode-Line Format
1497 Each Emacs window (aside from minibuffer windows) typically has a mode
1498 line at the bottom, which displays status information about the buffer
1499 displayed in the window. The mode line contains information about the
1500 buffer, such as its name, associated file, depth of recursive editing,
1501 and major and minor modes. A window can also have a @dfn{header
1502 line}, which is much like the mode line but appears at the top of the
1505 This section describes how to control the contents of the mode line
1506 and header line. We include it in this chapter because much of the
1507 information displayed in the mode line relates to the enabled major and
1511 * Base: Mode Line Basics. Basic ideas of mode line control.
1512 * Data: Mode Line Data. The data structure that controls the mode line.
1513 * Top: Mode Line Top. The top level variable, mode-line-format.
1514 * Mode Line Variables:: Variables used in that data structure.
1515 * %-Constructs:: Putting information into a mode line.
1516 * Properties in Mode:: Using text properties in the mode line.
1517 * Header Lines:: Like a mode line, but at the top.
1518 * Emulating Mode Line:: Formatting text as the mode line would.
1521 @node Mode Line Basics
1522 @subsection Mode Line Basics
1524 @code{mode-line-format} is a buffer-local variable that holds a
1525 @dfn{mode line construct}, a kind of template, which controls what is
1526 displayed on the mode line of the current buffer. The value of
1527 @code{header-line-format} specifies the buffer's header line in the
1528 same way. All windows for the same buffer use the same
1529 @code{mode-line-format} and @code{header-line-format}.
1531 For efficiency, Emacs does not continuously recompute the mode
1532 line and header line of a window. It does so when circumstances
1533 appear to call for it---for instance, if you change the window
1534 configuration, switch buffers, narrow or widen the buffer, scroll, or
1535 change the buffer's modification status. If you modify any of the
1536 variables referenced by @code{mode-line-format} (@pxref{Mode Line
1537 Variables}), or any other variables and data structures that affect
1538 how text is displayed (@pxref{Display}), you may want to force an
1539 update of the mode line so as to display the new information or
1540 display it in the new way.
1542 @defun force-mode-line-update &optional all
1543 Force redisplay of the current buffer's mode line and header line.
1544 The next redisplay will update the mode line and header line based on
1545 the latest values of all relevant variables. With optional
1546 non-@code{nil} @var{all}, force redisplay of all mode lines and header
1549 This function also forces recomputation of the menu bar menus
1550 and the frame title.
1553 The selected window's mode line is usually displayed in a different
1554 color using the face @code{mode-line}. Other windows' mode lines
1555 appear in the face @code{mode-line-inactive} instead. @xref{Faces}.
1557 @node Mode Line Data
1558 @subsection The Data Structure of the Mode Line
1559 @cindex mode-line construct
1561 The mode-line contents are controlled by a data structure called a
1562 @dfn{mode-line construct}, made up of lists, strings, symbols, and
1563 numbers kept in buffer-local variables. Each data type has a specific
1564 meaning for the mode-line appearance, as described below. The same
1565 data structure is used for constructing frame titles (@pxref{Frame
1566 Titles}) and header lines (@pxref{Header Lines}).
1568 A mode-line construct may be as simple as a fixed string of text,
1569 but it usually specifies how to combine fixed strings with variables'
1570 values to construct the text. Many of these variables are themselves
1571 defined to have mode-line constructs as their values.
1573 Here are the meanings of various data types as mode-line constructs:
1576 @cindex percent symbol in mode line
1578 A string as a mode-line construct appears verbatim except for
1579 @dfn{@code{%}-constructs} in it. These stand for substitution of
1580 other data; see @ref{%-Constructs}.
1582 If parts of the string have @code{face} properties, they control
1583 display of the text just as they would text in the buffer. Any
1584 characters which have no @code{face} properties are displayed, by
1585 default, in the face @code{mode-line} or @code{mode-line-inactive}
1586 (@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}). The
1587 @code{help-echo} and @code{local-map} properties in @var{string} have
1588 special meanings. @xref{Properties in Mode}.
1591 A symbol as a mode-line construct stands for its value. The value of
1592 @var{symbol} is used as a mode-line construct, in place of @var{symbol}.
1593 However, the symbols @code{t} and @code{nil} are ignored, as is any
1594 symbol whose value is void.
1596 There is one exception: if the value of @var{symbol} is a string, it is
1597 displayed verbatim: the @code{%}-constructs are not recognized.
1599 Unless @var{symbol} is marked as ``risky'' (i.e., it has a
1600 non-@code{nil} @code{risky-local-variable} property), all text
1601 properties specified in @var{symbol}'s value are ignored. This
1602 includes the text properties of strings in @var{symbol}'s value, as
1603 well as all @code{:eval} and @code{:propertize} forms in it. (The
1604 reason for this is security: non-risky variables could be set
1605 automatically from file variables without prompting the user.)
1607 @item (@var{string} @var{rest}@dots{})
1608 @itemx (@var{list} @var{rest}@dots{})
1609 A list whose first element is a string or list means to process all the
1610 elements recursively and concatenate the results. This is the most
1611 common form of mode-line construct.
1613 @item (:eval @var{form})
1614 A list whose first element is the symbol @code{:eval} says to evaluate
1615 @var{form}, and use the result as a string to display. Make sure this
1616 evaluation cannot load any files, as doing so could cause infinite
1619 @item (:propertize @var{elt} @var{props}@dots{})
1620 A list whose first element is the symbol @code{:propertize} says to
1621 process the mode-line construct @var{elt} recursively, then add the text
1622 properties specified by @var{props} to the result. The argument
1623 @var{props} should consist of zero or more pairs @var{text-property}
1624 @var{value}. (This feature is new as of Emacs 22.1.)
1626 @item (@var{symbol} @var{then} @var{else})
1627 A list whose first element is a symbol that is not a keyword specifies
1628 a conditional. Its meaning depends on the value of @var{symbol}. If
1629 @var{symbol} has a non-@code{nil} value, the second element,
1630 @var{then}, is processed recursively as a mode-line element.
1631 Otherwise, the third element, @var{else}, is processed recursively.
1632 You may omit @var{else}; then the mode-line element displays nothing
1633 if the value of @var{symbol} is @code{nil} or void.
1635 @item (@var{width} @var{rest}@dots{})
1636 A list whose first element is an integer specifies truncation or
1637 padding of the results of @var{rest}. The remaining elements
1638 @var{rest} are processed recursively as mode-line constructs and
1639 concatenated together. When @var{width} is positive, the result is
1640 space filled on the right if its width is less than @var{width}. When
1641 @var{width} is negative, the result is truncated on the right to
1642 @minus{}@var{width} columns if its width exceeds @minus{}@var{width}.
1644 For example, the usual way to show what percentage of a buffer is above
1645 the top of the window is to use a list like this: @code{(-3 "%p")}.
1649 @subsection The Top Level of Mode Line Control
1651 The variable in overall control of the mode line is
1652 @code{mode-line-format}.
1654 @defvar mode-line-format
1655 The value of this variable is a mode-line construct that controls the
1656 contents of the mode-line. It is always buffer-local in all buffers.
1658 If you set this variable to @code{nil} in a buffer, that buffer does
1659 not have a mode line. (A window that is just one line tall never
1660 displays a mode line.)
1663 The default value of @code{mode-line-format} is designed to use the
1664 values of other variables such as @code{mode-line-position} and
1665 @code{mode-line-modes} (which in turn incorporates the values of the
1666 variables @code{mode-name} and @code{minor-mode-alist}). Very few
1667 modes need to alter @code{mode-line-format} itself. For most
1668 purposes, it is sufficient to alter some of the variables that
1669 @code{mode-line-format} either directly or indirectly refers to.
1671 If you do alter @code{mode-line-format} itself, the new value should
1672 use the same variables that appear in the default value (@pxref{Mode
1673 Line Variables}), rather than duplicating their contents or displaying
1674 the information in another fashion. This way, customizations made by
1675 the user or by Lisp programs (such as @code{display-time} and major
1676 modes) via changes to those variables remain effective.
1678 @cindex Shell mode @code{mode-line-format}
1679 Here is an example of a @code{mode-line-format} that might be
1680 useful for @code{shell-mode}, since it contains the host name and default
1685 (setq mode-line-format
1687 'mode-line-mule-info
1689 'mode-line-frame-identification
1693 ;; @r{Note that this is evaluated while making the list.}
1694 ;; @r{It makes a mode-line construct which is just a string.}
1702 '(:eval (mode-line-mode-name))
1708 '(which-func-mode ("" which-func-format "--"))
1709 '(line-number-mode "L%l--")
1710 '(column-number-mode "C%c--")
1717 (The variables @code{line-number-mode}, @code{column-number-mode}
1718 and @code{which-func-mode} enable particular minor modes; as usual,
1719 these variable names are also the minor mode command names.)
1721 @node Mode Line Variables
1722 @subsection Variables Used in the Mode Line
1724 This section describes variables incorporated by the standard value
1725 of @code{mode-line-format} into the text of the mode line. There is
1726 nothing inherently special about these variables; any other variables
1727 could have the same effects on the mode line if
1728 @code{mode-line-format}'s value were changed to use them. However,
1729 various parts of Emacs set these variables on the understanding that
1730 they will control parts of the mode line; therefore, practically
1731 speaking, it is essential for the mode line to use them.
1733 @defvar mode-line-mule-info
1734 This variable holds the value of the mode-line construct that displays
1735 information about the language environment, buffer coding system, and
1736 current input method. @xref{Non-ASCII Characters}.
1739 @defvar mode-line-modified
1740 This variable holds the value of the mode-line construct that displays
1741 whether the current buffer is modified.
1743 The default value of @code{mode-line-modified} is @code{("%1*%1+")}.
1744 This means that the mode line displays @samp{**} if the buffer is
1745 modified, @samp{--} if the buffer is not modified, @samp{%%} if the
1746 buffer is read only, and @samp{%*} if the buffer is read only and
1749 Changing this variable does not force an update of the mode line.
1752 @defvar mode-line-frame-identification
1753 This variable identifies the current frame. The default value is
1754 @code{" "} if you are using a window system which can show multiple
1755 frames, or @code{"-%F "} on an ordinary terminal which shows only one
1759 @defvar mode-line-buffer-identification
1760 This variable identifies the buffer being displayed in the window. Its
1761 default value is @code{("%12b")}, which displays the buffer name, padded
1762 with spaces to at least 12 columns.
1765 @defvar mode-line-position
1766 This variable indicates the position in the buffer. Here is a
1767 simplified version of its default value. The actual default value
1768 also specifies addition of the @code{help-echo} text property.
1773 (size-indication-mode (8 " of %I"))
1777 ((column-number-mode
1780 ((column-number-mode
1785 This means that @code{mode-line-position} displays at least the buffer
1786 percentage and possibly the buffer size, the line number and the column
1791 The variable @code{vc-mode}, buffer-local in each buffer, records
1792 whether the buffer's visited file is maintained with version control,
1793 and, if so, which kind. Its value is a string that appears in the mode
1794 line, or @code{nil} for no version control.
1797 @defvar mode-line-modes
1798 This variable displays the buffer's major and minor modes. Here is a
1799 simplified version of its default value. The real default value also
1800 specifies addition of text properties.
1805 mode-line-process minor-mode-alist
1810 So @code{mode-line-modes} normally also displays the recursive editing
1811 level, information on the process status and whether narrowing is in
1815 The following three variables are used in @code{mode-line-modes}:
1818 This buffer-local variable holds the ``pretty'' name of the current
1819 buffer's major mode. Each major mode should set this variable so that the
1820 mode name will appear in the mode line.
1823 @defvar mode-line-process
1824 This buffer-local variable contains the mode-line information on process
1825 status in modes used for communicating with subprocesses. It is
1826 displayed immediately following the major mode name, with no intervening
1827 space. For example, its value in the @samp{*shell*} buffer is
1828 @code{(":%s")}, which allows the shell to display its status along
1829 with the major mode as: @samp{(Shell:run)}. Normally this variable
1833 @defvar minor-mode-alist
1834 @anchor{Definition of minor-mode-alist}
1835 This variable holds an association list whose elements specify how the
1836 mode line should indicate that a minor mode is active. Each element of
1837 the @code{minor-mode-alist} should be a two-element list:
1840 (@var{minor-mode-variable} @var{mode-line-string})
1843 More generally, @var{mode-line-string} can be any mode-line spec. It
1844 appears in the mode line when the value of @var{minor-mode-variable}
1845 is non-@code{nil}, and not otherwise. These strings should begin with
1846 spaces so that they don't run together. Conventionally, the
1847 @var{minor-mode-variable} for a specific mode is set to a
1848 non-@code{nil} value when that minor mode is activated.
1850 @code{minor-mode-alist} itself is not buffer-local. Each variable
1851 mentioned in the alist should be buffer-local if its minor mode can be
1852 enabled separately in each buffer.
1855 @defvar global-mode-string
1856 This variable holds a mode-line spec that, by default, appears in the
1857 mode line just after the @code{which-func-mode} minor mode if set,
1858 else after @code{mode-line-modes}. The command @code{display-time}
1859 sets @code{global-mode-string} to refer to the variable
1860 @code{display-time-string}, which holds a string containing the time
1861 and load information.
1863 The @samp{%M} construct substitutes the value of
1864 @code{global-mode-string}, but that is obsolete, since the variable is
1865 included in the mode line from @code{mode-line-format}.
1868 The variable @code{default-mode-line-format} is where
1869 @code{mode-line-format} usually gets its value:
1871 @defvar default-mode-line-format
1872 This variable holds the default @code{mode-line-format} for buffers
1873 that do not override it. This is the same as @code{(default-value
1874 'mode-line-format)}.
1876 Here is a simplified version of the default value of
1877 @code{default-mode-line-format}. The real default value also
1878 specifies addition of text properties.
1885 mode-line-frame-identification
1886 mode-line-buffer-identification
1894 (which-func-mode ("" which-func-format "--"))
1895 (global-mode-string ("--" global-mode-string))
1902 @subsection @code{%}-Constructs in the Mode Line
1904 Strings used as mode-line constructs can use certain
1905 @code{%}-constructs to substitute various kinds of data. Here is a
1906 list of the defined @code{%}-constructs, and what they mean. In any
1907 construct except @samp{%%}, you can add a decimal integer after the
1908 @samp{%} to specify a minimum field width. If the width is less, the
1909 field is padded with spaces to the right.
1913 The current buffer name, obtained with the @code{buffer-name} function.
1914 @xref{Buffer Names}.
1917 The current column number of point.
1920 When Emacs is nearly out of memory for Lisp objects, a brief message
1921 saying so. Otherwise, this is empty.
1924 The visited file name, obtained with the @code{buffer-file-name}
1925 function. @xref{Buffer File Name}.
1928 The title (only on a window system) or the name of the selected frame.
1929 @xref{Basic Parameters}.
1932 The size of the accessible part of the current buffer; basically
1933 @code{(- (point-max) (point-min))}.
1936 Like @samp{%i}, but the size is printed in a more readable way by using
1937 @samp{k} for 10^3, @samp{M} for 10^6, @samp{G} for 10^9, etc., to
1941 The current line number of point, counting within the accessible portion
1945 @samp{Narrow} when narrowing is in effect; nothing otherwise (see
1946 @code{narrow-to-region} in @ref{Narrowing}).
1949 The percentage of the buffer text above the @strong{top} of window, or
1950 @samp{Top}, @samp{Bottom} or @samp{All}. Note that the default
1951 mode-line specification truncates this to three characters.
1954 The percentage of the buffer text that is above the @strong{bottom} of
1955 the window (which includes the text visible in the window, as well as
1956 the text above the top), plus @samp{Top} if the top of the buffer is
1957 visible on screen; or @samp{Bottom} or @samp{All}.
1960 The status of the subprocess belonging to the current buffer, obtained with
1961 @code{process-status}. @xref{Process Information}.
1964 Whether the visited file is a text file or a binary file. This is a
1965 meaningful distinction only on certain operating systems (@pxref{MS-DOS
1969 The mnemonics of buffer, terminal, and keyboard coding systems.
1972 Like @samp{%z}, but including the end-of-line format.
1975 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
1976 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
1977 @samp{-} otherwise. @xref{Buffer Modification}.
1980 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
1981 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
1982 @samp{-} otherwise. This differs from @samp{%*} only for a modified
1983 read-only buffer. @xref{Buffer Modification}.
1986 @samp{*} if the buffer is modified, and @samp{-} otherwise.
1989 An indication of the depth of recursive editing levels (not counting
1990 minibuffer levels): one @samp{[} for each editing level.
1991 @xref{Recursive Editing}.
1994 One @samp{]} for each recursive editing level (not counting minibuffer
1998 Dashes sufficient to fill the remainder of the mode line.
2001 The character @samp{%}---this is how to include a literal @samp{%} in a
2002 string in which @code{%}-constructs are allowed.
2005 The following two @code{%}-constructs are still supported, but they are
2006 obsolete, since you can get the same results with the variables
2007 @code{mode-name} and @code{global-mode-string}.
2011 The value of @code{mode-name}.
2014 The value of @code{global-mode-string}.
2017 @node Properties in Mode
2018 @subsection Properties in the Mode Line
2019 @cindex text properties in the mode line
2021 Certain text properties are meaningful in the
2022 mode line. The @code{face} property affects the appearance of text; the
2023 @code{help-echo} property associates help strings with the text, and
2024 @code{local-map} can make the text mouse-sensitive.
2026 There are four ways to specify text properties for text in the mode
2031 Put a string with a text property directly into the mode-line data
2035 Put a text property on a mode-line %-construct such as @samp{%12b}; then
2036 the expansion of the %-construct will have that same text property.
2039 Use a @code{(:propertize @var{elt} @var{props}@dots{})} construct to
2040 give @var{elt} a text property specified by @var{props}.
2043 Use a list containing @code{:eval @var{form}} in the mode-line data
2044 structure, and make @var{form} evaluate to a string that has a text
2048 You can use the @code{local-map} property to specify a keymap. This
2049 keymap only takes real effect for mouse clicks; binding character keys
2050 and function keys to it has no effect, since it is impossible to move
2051 point into the mode line.
2053 When the mode line refers to a variable which does not have a
2054 non-@code{nil} @code{risky-local-variable} property, any text
2055 properties given or specified within that variable's values are
2056 ignored. This is because such properties could otherwise specify
2057 functions to be called, and those functions could come from file
2061 @subsection Window Header Lines
2062 @cindex header line (of a window)
2063 @cindex window header line
2065 A window can have a @dfn{header line} at the
2066 top, just as it can have a mode line at the bottom. The header line
2067 feature works just like the mode-line feature, except that it's
2068 controlled by different variables.
2070 @defvar header-line-format
2071 This variable, local in every buffer, specifies how to display the
2072 header line, for windows displaying the buffer. The format of the value
2073 is the same as for @code{mode-line-format} (@pxref{Mode Line Data}).
2076 @defvar default-header-line-format
2077 This variable holds the default @code{header-line-format} for buffers
2078 that do not override it. This is the same as @code{(default-value
2079 'header-line-format)}.
2081 It is normally @code{nil}, so that ordinary buffers have no header line.
2084 A window that is just one line tall never displays a header line. A
2085 window that is two lines tall cannot display both a mode line and a
2086 header line at once; if it has a mode line, then it does not display a
2089 @node Emulating Mode Line
2090 @subsection Emulating Mode-Line Formatting
2092 You can use the function @code{format-mode-line} to compute
2093 the text that would appear in a mode line or header line
2094 based on a certain mode-line specification.
2096 @defun format-mode-line format &optional face window buffer
2097 This function formats a line of text according to @var{format} as if
2098 it were generating the mode line for @var{window}, but instead of
2099 displaying the text in the mode line or the header line, it returns
2100 the text as a string. The argument @var{window} defaults to the
2101 selected window. If @var{buffer} is non-@code{nil}, all the
2102 information used is taken from @var{buffer}; by default, it comes from
2103 @var{window}'s buffer.
2105 The value string normally has text properties that correspond to the
2106 faces, keymaps, etc., that the mode line would have. And any character
2107 for which no @code{face} property is specified gets a default
2108 value which is usually @var{face}. (If @var{face} is @code{t},
2109 that stands for either @code{mode-line} if @var{window} is selected,
2110 otherwise @code{mode-line-inactive}. If @var{face} is @code{nil} or
2111 omitted, that stands for no face property.)
2113 However, if @var{face} is an integer, the value has no text properties.
2115 For example, @code{(format-mode-line header-line-format)} returns the
2116 text that would appear in the selected window's header line (@code{""}
2117 if it has no header line). @code{(format-mode-line header-line-format
2118 'header-line)} returns the same text, with each character
2119 carrying the face that it will have in the header line itself.
2126 @dfn{Imenu} is a feature that lets users select a definition or
2127 section in the buffer, from a menu which lists all of them, to go
2128 directly to that location in the buffer. Imenu works by constructing
2129 a buffer index which lists the names and buffer positions of the
2130 definitions, or other named portions of the buffer; then the user can
2131 choose one of them and move point to it. Major modes can add a menu
2132 bar item to use Imenu using @code{imenu-add-to-menubar}.
2134 @defun imenu-add-to-menubar name
2135 This function defines a local menu bar item named @var{name}
2139 The user-level commands for using Imenu are described in the Emacs
2140 Manual (@pxref{Imenu,, Imenu, emacs, the Emacs Manual}). This section
2141 explains how to customize Imenu's method of finding definitions or
2142 buffer portions for a particular major mode.
2144 The usual and simplest way is to set the variable
2145 @code{imenu-generic-expression}:
2147 @defvar imenu-generic-expression
2148 This variable, if non-@code{nil}, is a list that specifies regular
2149 expressions for finding definitions for Imenu. Simple elements of
2150 @code{imenu-generic-expression} look like this:
2153 (@var{menu-title} @var{regexp} @var{index})
2156 Here, if @var{menu-title} is non-@code{nil}, it says that the matches
2157 for this element should go in a submenu of the buffer index;
2158 @var{menu-title} itself specifies the name for the submenu. If
2159 @var{menu-title} is @code{nil}, the matches for this element go directly
2160 in the top level of the buffer index.
2162 The second item in the list, @var{regexp}, is a regular expression
2163 (@pxref{Regular Expressions}); anything in the buffer that it matches
2164 is considered a definition, something to mention in the buffer index.
2165 The third item, @var{index}, is a non-negative integer that indicates
2166 which subexpression in @var{regexp} matches the definition's name.
2168 An element can also look like this:
2171 (@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{})
2174 Each match for this element creates an index item, and when the index
2175 item is selected by the user, it calls @var{function} with arguments
2176 consisting of the item name, the buffer position, and @var{arguments}.
2178 For Emacs Lisp mode, @code{imenu-generic-expression} could look like
2181 @c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]
2184 ((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
2185 \\s-+\\([-A-Za-z0-9+]+\\)" 2)
2188 ("*Vars*" "^\\s-*(def\\(var\\|const\\)\
2189 \\s-+\\([-A-Za-z0-9+]+\\)" 2)
2194 (def\\(type\\|struct\\|class\\|ine-condition\\)\
2195 \\s-+\\([-A-Za-z0-9+]+\\)" 2))
2199 Setting this variable makes it buffer-local in the current buffer.
2202 @defvar imenu-case-fold-search
2203 This variable controls whether matching against the regular
2204 expressions in the value of @code{imenu-generic-expression} is
2205 case-sensitive: @code{t}, the default, means matching should ignore
2208 Setting this variable makes it buffer-local in the current buffer.
2211 @defvar imenu-syntax-alist
2212 This variable is an alist of syntax table modifiers to use while
2213 processing @code{imenu-generic-expression}, to override the syntax table
2214 of the current buffer. Each element should have this form:
2217 (@var{characters} . @var{syntax-description})
2220 The @sc{car}, @var{characters}, can be either a character or a string.
2221 The element says to give that character or characters the syntax
2222 specified by @var{syntax-description}, which is passed to
2223 @code{modify-syntax-entry} (@pxref{Syntax Table Functions}).
2225 This feature is typically used to give word syntax to characters which
2226 normally have symbol syntax, and thus to simplify
2227 @code{imenu-generic-expression} and speed up matching.
2228 For example, Fortran mode uses it this way:
2231 (setq imenu-syntax-alist '(("_$" . "w")))
2234 The @code{imenu-generic-expression} regular expressions can then use
2235 @samp{\\sw+} instead of @samp{\\(\\sw\\|\\s_\\)+}. Note that this
2236 technique may be inconvenient when the mode needs to limit the initial
2237 character of a name to a smaller set of characters than are allowed in
2240 Setting this variable makes it buffer-local in the current buffer.
2243 Another way to customize Imenu for a major mode is to set the
2244 variables @code{imenu-prev-index-position-function} and
2245 @code{imenu-extract-index-name-function}:
2247 @defvar imenu-prev-index-position-function
2248 If this variable is non-@code{nil}, its value should be a function that
2249 finds the next ``definition'' to put in the buffer index, scanning
2250 backward in the buffer from point. It should return @code{nil} if it
2251 doesn't find another ``definition'' before point. Otherwise it should
2252 leave point at the place it finds a ``definition'' and return any
2253 non-@code{nil} value.
2255 Setting this variable makes it buffer-local in the current buffer.
2258 @defvar imenu-extract-index-name-function
2259 If this variable is non-@code{nil}, its value should be a function to
2260 return the name for a definition, assuming point is in that definition
2261 as the @code{imenu-prev-index-position-function} function would leave
2264 Setting this variable makes it buffer-local in the current buffer.
2267 The last way to customize Imenu for a major mode is to set the
2268 variable @code{imenu-create-index-function}:
2270 @defvar imenu-create-index-function
2271 This variable specifies the function to use for creating a buffer
2272 index. The function should take no arguments, and return an index
2273 alist for the current buffer. It is called within
2274 @code{save-excursion}, so where it leaves point makes no difference.
2276 The index alist can have three types of elements. Simple elements
2280 (@var{index-name} . @var{index-position})
2283 Selecting a simple element has the effect of moving to position
2284 @var{index-position} in the buffer. Special elements look like this:
2287 (@var{index-name} @var{index-position} @var{function} @var{arguments}@dots{})
2290 Selecting a special element performs:
2293 (funcall @var{function}
2294 @var{index-name} @var{index-position} @var{arguments}@dots{})
2297 A nested sub-alist element looks like this:
2300 (@var{menu-title} @var{sub-alist})
2303 It creates the submenu @var{menu-title} specified by @var{sub-alist}.
2305 The default value of @code{imenu-create-index-function} is
2306 @code{imenu-default-create-index-function}. This function calls the
2307 value of @code{imenu-prev-index-position-function} and the value of
2308 @code{imenu-extract-index-name-function} to produce the index alist.
2309 However, if either of these two variables is @code{nil}, the default
2310 function uses @code{imenu-generic-expression} instead.
2312 Setting this variable makes it buffer-local in the current buffer.
2315 @node Font Lock Mode
2316 @section Font Lock Mode
2317 @cindex Font Lock Mode
2319 @dfn{Font Lock mode} is a feature that automatically attaches
2320 @code{face} properties to certain parts of the buffer based on their
2321 syntactic role. How it parses the buffer depends on the major mode;
2322 most major modes define syntactic criteria for which faces to use in
2323 which contexts. This section explains how to customize Font Lock for a
2324 particular major mode.
2326 Font Lock mode finds text to highlight in two ways: through
2327 syntactic parsing based on the syntax table, and through searching
2328 (usually for regular expressions). Syntactic fontification happens
2329 first; it finds comments and string constants and highlights them.
2330 Search-based fontification happens second.
2333 * Font Lock Basics:: Overview of customizing Font Lock.
2334 * Search-based Fontification:: Fontification based on regexps.
2335 * Customizing Keywords:: Customizing search-based fontification.
2336 * Other Font Lock Variables:: Additional customization facilities.
2337 * Levels of Font Lock:: Each mode can define alternative levels
2338 so that the user can select more or less.
2339 * Precalculated Fontification:: How Lisp programs that produce the buffer
2340 contents can also specify how to fontify it.
2341 * Faces for Font Lock:: Special faces specifically for Font Lock.
2342 * Syntactic Font Lock:: Fontification based on syntax tables.
2343 * Setting Syntax Properties:: Defining character syntax based on context
2344 using the Font Lock mechanism.
2345 * Multiline Font Lock:: How to coerce Font Lock into properly
2346 highlighting multiline constructs.
2349 @node Font Lock Basics
2350 @subsection Font Lock Basics
2352 There are several variables that control how Font Lock mode highlights
2353 text. But major modes should not set any of these variables directly.
2354 Instead, they should set @code{font-lock-defaults} as a buffer-local
2355 variable. The value assigned to this variable is used, if and when Font
2356 Lock mode is enabled, to set all the other variables.
2358 @defvar font-lock-defaults
2359 This variable is set by major modes, as a buffer-local variable, to
2360 specify how to fontify text in that mode. It automatically becomes
2361 buffer-local when you set it. The value should look like this:
2364 (@var{keywords} [@var{keywords-only} [@var{case-fold}
2365 [@var{syntax-alist} [@var{syntax-begin} @var{other-vars}@dots{}]]]])
2368 The first element, @var{keywords}, indirectly specifies the value of
2369 @code{font-lock-keywords} which directs search-based fontification.
2370 It can be a symbol, a variable or a function whose value is the list
2371 to use for @code{font-lock-keywords}. It can also be a list of
2372 several such symbols, one for each possible level of fontification.
2373 The first symbol specifies how to do level 1 fontification, the second
2374 symbol how to do level 2, and so on. @xref{Levels of Font Lock}.
2376 The second element, @var{keywords-only}, specifies the value of the
2377 variable @code{font-lock-keywords-only}. If this is non-@code{nil},
2378 syntactic fontification (of strings and comments) is not performed.
2379 @xref{Syntactic Font Lock}.
2381 The third element, @var{case-fold}, specifies the value of
2382 @code{font-lock-keywords-case-fold-search}. If it is non-@code{nil},
2383 Font Lock mode ignores case when searching as directed by
2384 @code{font-lock-keywords}.
2386 If the fourth element, @var{syntax-alist}, is non-@code{nil}, it
2387 should be a list of cons cells of the form @code{(@var{char-or-string}
2388 . @var{string})}. These are used to set up a syntax table for
2389 syntactic fontification (@pxref{Syntax Table Functions}). The
2390 resulting syntax table is stored in @code{font-lock-syntax-table}.
2392 The fifth element, @var{syntax-begin}, specifies the value of
2393 @code{font-lock-beginning-of-syntax-function}. We recommend setting
2394 this variable to @code{nil} and using @code{syntax-begin-function}
2397 All the remaining elements (if any) are collectively called
2398 @var{other-vars}. Each of these elements should have the form
2399 @code{(@var{variable} . @var{value})}---which means, make
2400 @var{variable} buffer-local and then set it to @var{value}. You can
2401 use these @var{other-vars} to set other variables that affect
2402 fontification, aside from those you can control with the first five
2403 elements. @xref{Other Font Lock Variables}.
2406 @node Search-based Fontification
2407 @subsection Search-based Fontification
2409 The most important variable for customizing Font Lock mode is
2410 @code{font-lock-keywords}. It specifies the search criteria for
2411 search-based fontification. You should specify the value of this
2412 variable with @var{keywords} in @code{font-lock-defaults}.
2414 @defvar font-lock-keywords
2415 This variable's value is a list of the keywords to highlight. Be
2416 careful when composing regular expressions for this list; a poorly
2417 written pattern can dramatically slow things down!
2420 Each element of @code{font-lock-keywords} specifies how to find
2421 certain cases of text, and how to highlight those cases. Font Lock mode
2422 processes the elements of @code{font-lock-keywords} one by one, and for
2423 each element, it finds and handles all matches. Ordinarily, once
2424 part of the text has been fontified already, this cannot be overridden
2425 by a subsequent match in the same text; but you can specify different
2426 behavior using the @var{override} element of a @var{subexp-highlighter}.
2428 Each element of @code{font-lock-keywords} should have one of these
2433 Highlight all matches for @var{regexp} using
2434 @code{font-lock-keyword-face}. For example,
2437 ;; @r{Highlight occurrences of the word @samp{foo}}
2438 ;; @r{using @code{font-lock-keyword-face}.}
2442 The function @code{regexp-opt} (@pxref{Regexp Functions}) is useful
2443 for calculating optimal regular expressions to match a number of
2446 @item @var{function}
2447 Find text by calling @var{function}, and highlight the matches
2448 it finds using @code{font-lock-keyword-face}.
2450 When @var{function} is called, it receives one argument, the limit of
2451 the search; it should begin searching at point, and not search beyond the
2452 limit. It should return non-@code{nil} if it succeeds, and set the
2453 match data to describe the match that was found. Returning @code{nil}
2454 indicates failure of the search.
2456 Fontification will call @var{function} repeatedly with the same limit,
2457 and with point where the previous invocation left it, until
2458 @var{function} fails. On failure, @var{function} need not reset point
2459 in any particular way.
2461 @item (@var{matcher} . @var{subexp})
2462 In this kind of element, @var{matcher} is either a regular
2463 expression or a function, as described above. The @sc{cdr},
2464 @var{subexp}, specifies which subexpression of @var{matcher} should be
2465 highlighted (instead of the entire text that @var{matcher} matched).
2468 ;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},}
2469 ;; @r{using @code{font-lock-keyword-face}.}
2473 If you use @code{regexp-opt} to produce the regular expression
2474 @var{matcher}, you can use @code{regexp-opt-depth} (@pxref{Regexp
2475 Functions}) to calculate the value for @var{subexp}.
2477 @item (@var{matcher} . @var{facespec})
2478 In this kind of element, @var{facespec} is an expression whose value
2479 specifies the face to use for highlighting. In the simplest case,
2480 @var{facespec} is a Lisp variable (a symbol) whose value is a face
2484 ;; @r{Highlight occurrences of @samp{fubar},}
2485 ;; @r{using the face which is the value of @code{fubar-face}.}
2486 ("fubar" . fubar-face)
2489 However, @var{facespec} can also evaluate to a list of this form:
2492 (face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{})
2496 to specify the face @var{face} and various additional text properties
2497 to put on the text that matches. If you do this, be sure to add the
2498 other text property names that you set in this way to the value of
2499 @code{font-lock-extra-managed-props} so that the properties will also
2500 be cleared out when they are no longer appropriate. Alternatively,
2501 you can set the variable @code{font-lock-unfontify-region-function} to
2502 a function that clears these properties. @xref{Other Font Lock
2505 @item (@var{matcher} . @var{subexp-highlighter})
2506 In this kind of element, @var{subexp-highlighter} is a list
2507 which specifies how to highlight matches found by @var{matcher}.
2511 (@var{subexp} @var{facespec} [[@var{override} [@var{laxmatch}]])
2514 The @sc{car}, @var{subexp}, is an integer specifying which subexpression
2515 of the match to fontify (0 means the entire matching text). The second
2516 subelement, @var{facespec}, is an expression whose value specifies the
2517 face, as described above.
2519 The last two values in @var{subexp-highlighter}, @var{override} and
2520 @var{laxmatch}, are optional flags. If @var{override} is @code{t},
2521 this element can override existing fontification made by previous
2522 elements of @code{font-lock-keywords}. If it is @code{keep}, then
2523 each character is fontified if it has not been fontified already by
2524 some other element. If it is @code{prepend}, the face specified by
2525 @var{facespec} is added to the beginning of the @code{font-lock-face}
2526 property. If it is @code{append}, the face is added to the end of the
2527 @code{font-lock-face} property.
2529 If @var{laxmatch} is non-@code{nil}, it means there should be no error
2530 if there is no subexpression numbered @var{subexp} in @var{matcher}.
2531 Obviously, fontification of the subexpression numbered @var{subexp} will
2532 not occur. However, fontification of other subexpressions (and other
2533 regexps) will continue. If @var{laxmatch} is @code{nil}, and the
2534 specified subexpression is missing, then an error is signaled which
2535 terminates search-based fontification.
2537 Here are some examples of elements of this kind, and what they do:
2540 ;; @r{Highlight occurrences of either @samp{foo} or @samp{bar}, using}
2541 ;; @r{@code{foo-bar-face}, even if they have already been highlighted.}
2542 ;; @r{@code{foo-bar-face} should be a variable whose value is a face.}
2543 ("foo\\|bar" 0 foo-bar-face t)
2545 ;; @r{Highlight the first subexpression within each occurrence}
2546 ;; @r{that the function @code{fubar-match} finds,}
2547 ;; @r{using the face which is the value of @code{fubar-face}.}
2548 (fubar-match 1 fubar-face)
2551 @item (@var{matcher} . @var{anchored-highlighter})
2552 In this kind of element, @var{anchored-highlighter} specifies how to
2553 highlight text that follows a match found by @var{matcher}. So a
2554 match found by @var{matcher} acts as the anchor for further searches
2555 specified by @var{anchored-highlighter}. @var{anchored-highlighter}
2556 is a list of the following form:
2559 (@var{anchored-matcher} @var{pre-form} @var{post-form}
2560 @var{subexp-highlighters}@dots{})
2563 Here, @var{anchored-matcher}, like @var{matcher}, is either a regular
2564 expression or a function. After a match of @var{matcher} is found,
2565 point is at the end of the match. Now, Font Lock evaluates the form
2566 @var{pre-form}. Then it searches for matches of
2567 @var{anchored-matcher} and uses @var{subexp-highlighters} to highlight
2568 these. A @var{subexp-highlighter} is as described above. Finally,
2569 Font Lock evaluates @var{post-form}.
2571 The forms @var{pre-form} and @var{post-form} can be used to initialize
2572 before, and cleanup after, @var{anchored-matcher} is used. Typically,
2573 @var{pre-form} is used to move point to some position relative to the
2574 match of @var{matcher}, before starting with @var{anchored-matcher}.
2575 @var{post-form} might be used to move back, before resuming with
2578 After Font Lock evaluates @var{pre-form}, it does not search for
2579 @var{anchored-matcher} beyond the end of the line. However, if
2580 @var{pre-form} returns a buffer position that is greater than the
2581 position of point after @var{pre-form} is evaluated, then the position
2582 returned by @var{pre-form} is used as the limit of the search instead.
2583 It is generally a bad idea to return a position greater than the end
2584 of the line; in other words, the @var{anchored-matcher} search should
2590 ;; @r{Highlight occurrences of the word @samp{item} following}
2591 ;; @r{an occurrence of the word @samp{anchor} (on the same line)}
2592 ;; @r{in the value of @code{item-face}.}
2593 ("\\<anchor\\>" "\\<item\\>" nil nil (0 item-face))
2596 Here, @var{pre-form} and @var{post-form} are @code{nil}. Therefore
2597 searching for @samp{item} starts at the end of the match of
2598 @samp{anchor}, and searching for subsequent instances of @samp{anchor}
2599 resumes from where searching for @samp{item} concluded.
2601 @item (@var{matcher} @var{highlighters}@dots{})
2602 This sort of element specifies several @var{highlighter} lists for a
2603 single @var{matcher}. A @var{highlighter} list can be of the type
2604 @var{subexp-highlighter} or @var{anchored-highlighter} as described
2610 ;; @r{Highlight occurrences of the word @samp{anchor} in the value}
2611 ;; @r{of @code{anchor-face}, and subsequent occurrences of the word}
2612 ;; @r{@samp{item} (on the same line) in the value of @code{item-face}.}
2613 ("\\<anchor\\>" (0 anchor-face)
2614 ("\\<item\\>" nil nil (0 item-face)))
2617 @item (eval . @var{form})
2618 Here @var{form} is an expression to be evaluated the first time
2619 this value of @code{font-lock-keywords} is used in a buffer.
2620 Its value should have one of the forms described in this table.
2623 @strong{Warning:} Do not design an element of @code{font-lock-keywords}
2624 to match text which spans lines; this does not work reliably.
2625 For details, see @xref{Multiline Font Lock}.
2627 You can use @var{case-fold} in @code{font-lock-defaults} to specify
2628 the value of @code{font-lock-keywords-case-fold-search} which says
2629 whether search-based fontification should be case-insensitive.
2631 @defvar font-lock-keywords-case-fold-search
2632 Non-@code{nil} means that regular expression matching for the sake of
2633 @code{font-lock-keywords} should be case-insensitive.
2636 @node Customizing Keywords
2637 @subsection Customizing Search-Based Fontification
2639 You can use @code{font-lock-add-keywords} to add additional
2640 search-based fontification rules to a major mode, and
2641 @code{font-lock-remove-keywords} to removes rules.
2643 @defun font-lock-add-keywords mode keywords &optional how
2644 This function adds highlighting @var{keywords}, for the current buffer
2645 or for major mode @var{mode}. The argument @var{keywords} should be a
2646 list with the same format as the variable @code{font-lock-keywords}.
2648 If @var{mode} is a symbol which is a major mode command name, such as
2649 @code{c-mode}, the effect is that enabling Font Lock mode in
2650 @var{mode} will add @var{keywords} to @code{font-lock-keywords}.
2651 Calling with a non-@code{nil} value of @var{mode} is correct only in
2652 your @file{~/.emacs} file.
2654 If @var{mode} is @code{nil}, this function adds @var{keywords} to
2655 @code{font-lock-keywords} in the current buffer. This way of calling
2656 @code{font-lock-add-keywords} is usually used in mode hook functions.
2658 By default, @var{keywords} are added at the beginning of
2659 @code{font-lock-keywords}. If the optional argument @var{how} is
2660 @code{set}, they are used to replace the value of
2661 @code{font-lock-keywords}. If @var{how} is any other non-@code{nil}
2662 value, they are added at the end of @code{font-lock-keywords}.
2664 Some modes provide specialized support you can use in additional
2665 highlighting patterns. See the variables
2666 @code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types},
2667 and @code{java-font-lock-extra-types}, for example.
2669 @strong{Warning:} major mode functions must not call
2670 @code{font-lock-add-keywords} under any circumstances, either directly
2671 or indirectly, except through their mode hooks. (Doing so would lead
2672 to incorrect behavior for some minor modes.) They should set up their
2673 rules for search-based fontification by setting
2674 @code{font-lock-keywords}.
2677 @defun font-lock-remove-keywords mode keywords
2678 This function removes @var{keywords} from @code{font-lock-keywords}
2679 for the current buffer or for major mode @var{mode}. As in
2680 @code{font-lock-add-keywords}, @var{mode} should be a major mode
2681 command name or @code{nil}. All the caveats and requirements for
2682 @code{font-lock-add-keywords} apply here too.
2685 For example, this code
2688 (font-lock-add-keywords 'c-mode
2689 '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
2690 ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face)))
2694 adds two fontification patterns for C mode: one to fontify the word
2695 @samp{FIXME}, even in comments, and another to fontify the words
2696 @samp{and}, @samp{or} and @samp{not} as keywords.
2699 That example affects only C mode proper. To add the same patterns to
2700 C mode @emph{and} all modes derived from it, do this instead:
2703 (add-hook 'c-mode-hook
2705 (font-lock-add-keywords nil
2706 '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
2707 ("\\<\\(and\\|or\\|not\\)\\>" .
2708 font-lock-keyword-face)))))
2711 @node Other Font Lock Variables
2712 @subsection Other Font Lock Variables
2714 This section describes additional variables that a major mode can
2715 set by means of @var{other-vars} in @code{font-lock-defaults}
2716 (@pxref{Font Lock Basics}).
2718 @defvar font-lock-mark-block-function
2719 If this variable is non-@code{nil}, it should be a function that is
2720 called with no arguments, to choose an enclosing range of text for
2721 refontification for the command @kbd{M-o M-o}
2722 (@code{font-lock-fontify-block}).
2724 The function should report its choice by placing the region around it.
2725 A good choice is a range of text large enough to give proper results,
2726 but not too large so that refontification becomes slow. Typical values
2727 are @code{mark-defun} for programming modes or @code{mark-paragraph} for
2731 @defvar font-lock-extra-managed-props
2732 This variable specifies additional properties (other than
2733 @code{font-lock-face}) that are being managed by Font Lock mode. It
2734 is used by @code{font-lock-default-unfontify-region}, which normally
2735 only manages the @code{font-lock-face} property. If you want Font
2736 Lock to manage other properties as well, you must specify them in a
2737 @var{facespec} in @code{font-lock-keywords} as well as add them to
2738 this list. @xref{Search-based Fontification}.
2741 @defvar font-lock-fontify-buffer-function
2742 Function to use for fontifying the buffer. The default value is
2743 @code{font-lock-default-fontify-buffer}.
2746 @defvar font-lock-unfontify-buffer-function
2747 Function to use for unfontifying the buffer. This is used when
2748 turning off Font Lock mode. The default value is
2749 @code{font-lock-default-unfontify-buffer}.
2752 @defvar font-lock-fontify-region-function
2753 Function to use for fontifying a region. It should take two
2754 arguments, the beginning and end of the region, and an optional third
2755 argument @var{verbose}. If @var{verbose} is non-@code{nil}, the
2756 function should print status messages. The default value is
2757 @code{font-lock-default-fontify-region}.
2760 @defvar font-lock-unfontify-region-function
2761 Function to use for unfontifying a region. It should take two
2762 arguments, the beginning and end of the region. The default value is
2763 @code{font-lock-default-unfontify-region}.
2767 @defvar font-lock-inhibit-thing-lock
2768 List of Font Lock mode related modes that should not be turned on.
2769 Currently, valid mode names are @code{fast-lock-mode},
2770 @code{jit-lock-mode} and @code{lazy-lock-mode}.
2774 @node Levels of Font Lock
2775 @subsection Levels of Font Lock
2777 Many major modes offer three different levels of fontification. You
2778 can define multiple levels by using a list of symbols for @var{keywords}
2779 in @code{font-lock-defaults}. Each symbol specifies one level of
2780 fontification; it is up to the user to choose one of these levels. The
2781 chosen level's symbol value is used to initialize
2782 @code{font-lock-keywords}.
2784 Here are the conventions for how to define the levels of
2789 Level 1: highlight function declarations, file directives (such as include or
2790 import directives), strings and comments. The idea is speed, so only
2791 the most important and top-level components are fontified.
2794 Level 2: in addition to level 1, highlight all language keywords,
2795 including type names that act like keywords, as well as named constant
2796 values. The idea is that all keywords (either syntactic or semantic)
2797 should be fontified appropriately.
2800 Level 3: in addition to level 2, highlight the symbols being defined in
2801 function and variable declarations, and all builtin function names,
2802 wherever they appear.
2805 @node Precalculated Fontification
2806 @subsection Precalculated Fontification
2808 In addition to using @code{font-lock-defaults} for search-based
2809 fontification, you may use the special character property
2810 @code{font-lock-face} (@pxref{Special Properties}). This property
2811 acts just like the explicit @code{face} property, but its activation
2812 is toggled when the user calls @kbd{M-x font-lock-mode}. Using
2813 @code{font-lock-face} is especially convenient for special modes
2814 which construct their text programmatically, such as
2815 @code{list-buffers} and @code{occur}.
2817 If your mode does not use any of the other machinery of Font Lock
2818 (i.e. it only uses the @code{font-lock-face} property), it should not
2819 set the variable @code{font-lock-defaults}. That way, it will not
2820 cause loading of the @file{font-lock} library.
2822 @node Faces for Font Lock
2823 @subsection Faces for Font Lock
2825 You can make Font Lock mode use any face, but several faces are
2826 defined specifically for Font Lock mode. Each of these symbols is both
2827 a face name, and a variable whose default value is the symbol itself.
2828 Thus, the default value of @code{font-lock-comment-face} is
2829 @code{font-lock-comment-face}. This means you can write
2830 @code{font-lock-comment-face} in a context such as
2831 @code{font-lock-keywords} where a face-name-valued expression is used.
2834 @item font-lock-comment-face
2835 @vindex font-lock-comment-face
2836 Used (typically) for comments.
2838 @item font-lock-comment-delimiter-face
2839 @vindex font-lock-comment-delimiter-face
2840 Used (typically) for comments delimiters.
2842 @item font-lock-doc-face
2843 @vindex font-lock-doc-face
2844 Used (typically) for documentation strings in the code.
2846 @item font-lock-string-face
2847 @vindex font-lock-string-face
2848 Used (typically) for string constants.
2850 @item font-lock-keyword-face
2851 @vindex font-lock-keyword-face
2852 Used (typically) for keywords---names that have special syntactic
2853 significance, like @code{for} and @code{if} in C.
2855 @item font-lock-builtin-face
2856 @vindex font-lock-builtin-face
2857 Used (typically) for built-in function names.
2859 @item font-lock-function-name-face
2860 @vindex font-lock-function-name-face
2861 Used (typically) for the name of a function being defined or declared,
2862 in a function definition or declaration.
2864 @item font-lock-variable-name-face
2865 @vindex font-lock-variable-name-face
2866 Used (typically) for the name of a variable being defined or declared,
2867 in a variable definition or declaration.
2869 @item font-lock-type-face
2870 @vindex font-lock-type-face
2871 Used (typically) for names of user-defined data types,
2872 where they are defined and where they are used.
2874 @item font-lock-constant-face
2875 @vindex font-lock-constant-face
2876 Used (typically) for constant names.
2878 @item font-lock-preprocessor-face
2879 @vindex font-lock-preprocessor-face
2880 Used (typically) for preprocessor commands.
2882 @item font-lock-negation-char-face
2883 @vindex font-lock-negation-char-face
2884 Used (typically) for easily-overlooked negation characters.
2886 @item font-lock-warning-face
2887 @vindex font-lock-warning-face
2888 Used (typically) for constructs that are peculiar, or that greatly
2889 change the meaning of other text. For example, this is used for
2890 @samp{;;;###autoload} cookies in Emacs Lisp, and for @code{#error}
2894 @node Syntactic Font Lock
2895 @subsection Syntactic Font Lock
2897 Syntactic fontification uses the syntax table to find comments and
2898 string constants (@pxref{Syntax Tables}). It highlights them using
2899 @code{font-lock-comment-face} and @code{font-lock-string-face}
2900 (@pxref{Faces for Font Lock}), or whatever
2901 @code{font-lock-syntactic-face-function} chooses. There are several
2902 variables that affect syntactic fontification; you should set them by
2903 means of @code{font-lock-defaults} (@pxref{Font Lock Basics}).
2905 @defvar font-lock-keywords-only
2906 Non-@code{nil} means Font Lock should not do syntactic fontification;
2907 it should only fontify based on @code{font-lock-keywords}. The normal
2908 way for a mode to set this variable to @code{t} is with
2909 @var{keywords-only} in @code{font-lock-defaults}.
2912 @defvar font-lock-syntax-table
2913 This variable holds the syntax table to use for fontification of
2914 comments and strings. Specify it using @var{syntax-alist} in
2915 @code{font-lock-defaults}. If this is @code{nil}, fontification uses
2916 the buffer's syntax table.
2919 @defvar font-lock-beginning-of-syntax-function
2920 If this variable is non-@code{nil}, it should be a function to move
2921 point back to a position that is syntactically at ``top level'' and
2922 outside of strings or comments. Font Lock uses this when necessary
2923 to get the right results for syntactic fontification.
2925 This function is called with no arguments. It should leave point at
2926 the beginning of any enclosing syntactic block. Typical values are
2927 @code{beginning-of-line} (used when the start of the line is known to
2928 be outside a syntactic block), or @code{beginning-of-defun} for
2929 programming modes, or @code{backward-paragraph} for textual modes.
2931 If the value is @code{nil}, Font Lock uses
2932 @code{syntax-begin-function} to move back outside of any comment,
2933 string, or sexp. This variable is semi-obsolete; we recommend setting
2934 @code{syntax-begin-function} instead.
2936 Specify this variable using @var{syntax-begin} in
2937 @code{font-lock-defaults}.
2940 @defvar font-lock-syntactic-face-function
2941 A function to determine which face to use for a given syntactic
2942 element (a string or a comment). The function is called with one
2943 argument, the parse state at point returned by
2944 @code{parse-partial-sexp}, and should return a face. The default
2945 value returns @code{font-lock-comment-face} for comments and
2946 @code{font-lock-string-face} for strings.
2948 This can be used to highlighting different kinds of strings or
2949 comments differently. It is also sometimes abused together with
2950 @code{font-lock-syntactic-keywords} to highlight constructs that span
2951 multiple lines, but this is too esoteric to document here.
2953 Specify this variable using @var{other-vars} in
2954 @code{font-lock-defaults}.
2957 @node Setting Syntax Properties
2958 @subsection Setting Syntax Properties
2960 Font Lock mode can be used to update @code{syntax-table} properties
2961 automatically (@pxref{Syntax Properties}). This is useful in
2962 languages for which a single syntax table by itself is not sufficient.
2964 @defvar font-lock-syntactic-keywords
2965 This variable enables and controls updating @code{syntax-table}
2966 properties by Font Lock. Its value should be a list of elements of
2970 (@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch})
2973 The parts of this element have the same meanings as in the corresponding
2974 sort of element of @code{font-lock-keywords},
2977 (@var{matcher} @var{subexp} @var{facespec} @var{override} @var{laxmatch})
2980 However, instead of specifying the value @var{facespec} to use for the
2981 @code{face} property, it specifies the value @var{syntax} to use for
2982 the @code{syntax-table} property. Here, @var{syntax} can be a string
2983 (as taken by @code{modify-syntax-entry}), a syntax table, a cons cell
2984 (as returned by @code{string-to-syntax}), or an expression whose value
2985 is one of those two types. @var{override} cannot be @code{prepend} or
2988 For example, an element of the form:
2991 ("\\$\\(#\\)" 1 ".")
2994 highlights syntactically a hash character when following a dollar
2995 character, with a SYNTAX of @code{"."} (meaning punctuation syntax).
2996 Assuming that the buffer syntax table specifies hash characters to
2997 have comment start syntax, the element will only highlight hash
2998 characters that do not follow dollar characters as comments
3001 An element of the form:
3009 highlights syntactically both single quotes which surround a single
3010 character, with a SYNTAX of @code{"\""} (meaning string quote syntax).
3011 Assuming that the buffer syntax table does not specify single quotes
3012 to have quote syntax, the element will only highlight single quotes of
3013 the form @samp{'@var{c}'} as strings syntactically. Other forms, such
3014 as @samp{foo'bar} or @samp{'fubar'}, will not be highlighted as
3017 Major modes normally set this variable with @var{other-vars} in
3018 @code{font-lock-defaults}.
3021 @node Multiline Font Lock
3022 @subsection Multiline Font Lock Constructs
3023 @cindex multiline font lock
3025 Normally, elements of @code{font-lock-keywords} should not match
3026 across multiple lines; that doesn't work reliably, because Font Lock
3027 usually scans just part of the buffer, and it can miss a multi-line
3028 construct that crosses the line boundary where the scan starts. (The
3029 scan normally starts at the beginning of a line.)
3031 Making elements that match multiline constructs work properly has
3032 two aspects: correct @emph{identification} and correct
3033 @emph{rehighlighting}. The first means that Font Lock finds all
3034 multiline constructs. The second means that Font Lock will correctly
3035 rehighlight all the relevant text when a multiline construct is
3036 changed---for example, if some of the text that was previously part of
3037 a multiline construct ceases to be part of it. The two aspects are
3038 closely related, and often getting one of them to work will appear to
3039 make the other also work. However, for reliable results you must
3040 attend explicitly to both aspects.
3042 There are three ways to ensure correct identification of multiline
3047 Place a @code{font-lock-multiline}
3048 property on the construct when it is added to the buffer.
3050 Use @code{font-lock-fontify-region-function} hook to extend the scan
3051 so that the scanned text never starts or ends in the middle of a
3052 multiline construct.
3054 Add a function to @code{font-lock-extend-region-functions} that does
3055 the @emph{identification} and extends the scan so that the scanned
3056 text never starts or ends in the middle of a multiline construct.
3059 There are three ways to do rehighlighting of multiline constructs:
3063 Place a @code{font-lock-multiline} property on the construct. This
3064 will rehighlight the whole construct if any part of it is changed. In
3065 some cases you can do this automatically by setting the
3066 @code{font-lock-multiline} variable.
3068 Use @code{jit-lock-contextually}. This will only rehighlight the part
3069 of the construct that follows the actual change, and will do it after
3070 a short delay. This only works if the highlighting of the various
3071 parts of your multiline construct never depends on text in subsequent
3072 lines. Since @code{jit-lock-contextually} is activated by default,
3073 this can be an attractive solution.
3075 Place a @code{jit-lock-defer-multiline} property on the construct.
3076 This works only if @code{jit-lock-contextually} is used, but it can
3077 handle the case where highlighting depends on subsequent lines.
3081 * Font Lock Multiline:: Marking multiline chunks with a text property
3082 * Region to Fontify:: Controlling which region gets refontified
3083 after a buffer change.
3086 @node Font Lock Multiline
3087 @subsubsection Font Lock Multiline
3089 One way to ensure reliable rehighlighting of multiline Font Lock
3090 constructs is to put on the text property @code{font-lock-multiline}.
3091 It should be present and non-@code{nil} for text that is part of a
3092 multiline construct.
3094 When Font Lock is about to highlight a range of text, it first
3095 extends the boundaries of the range as necessary so that they do not
3096 fall within text marked with the @code{font-lock-multiline} property.
3097 Then it removes any @code{font-lock-multiline} properties from the
3098 range, and highlights it. The highlighting specification (mostly
3099 @code{font-lock-keywords}) must reinstall this property each time,
3100 whenever it is appropriate.
3102 @strong{Warning:} don't use the @code{font-lock-multiline} property
3103 on large ranges of text, because that will make rehighlighting slow.
3105 @defvar font-lock-multiline
3106 If the @code{font-lock-multiline} variable is set to @code{t}, Font
3107 Lock will try to add the @code{font-lock-multiline} property
3108 automatically on multiline constructs. This is not a universal
3109 solution, however, since it slows down Font Lock somewhat. It can
3110 miss some multiline constructs, or make the property larger or smaller
3113 For elements whose @var{matcher} is a function, the function should
3114 ensure that submatch 0 covers the whole relevant multiline construct,
3115 even if only a small subpart will be highlighted. It is often just as
3116 easy to add the @code{font-lock-multiline} property by hand.
3119 The @code{font-lock-multiline} property is meant to ensure proper
3120 refontification; it does not automatically identify new multiline
3121 constructs. Identifying the requires that Font-Lock operate on large
3122 enough chunks at a time. This will happen by accident on many cases,
3123 which may give the impression that multiline constructs magically work.
3124 If you set the @code{font-lock-multiline} variable non-@code{nil},
3125 this impression will be even stronger, since the highlighting of those
3126 constructs which are found will be properly updated from then on.
3127 But that does not work reliably.
3129 To find multiline constructs reliably, you must either manually
3130 place the @code{font-lock-multiline} property on the text before
3131 Font-Lock looks at it, or use
3132 @code{font-lock-fontify-region-function}.
3134 @node Region to Fontify
3135 @subsubsection Region to Fontify after a Buffer Change
3137 When a buffer is changed, the region that Font Lock refontifies is
3138 by default the smallest sequence of whole lines that spans the change.
3139 While this works well most of the time, sometimes it doesn't---for
3140 example, when a change alters the syntactic meaning of text on an
3143 You can enlarge (or even reduce) the region to fontify by setting
3144 one the following variables:
3146 @defvar font-lock-extend-after-change-region-function
3147 This buffer-local variable is either @code{nil} or a function for
3148 Font-Lock to call to determine the region to scan and fontify.
3150 The function is given three parameters, the standard @var{beg},
3151 @var{end}, and @var{old-len} from after-change-functions
3152 (@pxref{Change Hooks}). It should return either a cons of the
3153 beginning and end buffer positions (in that order) of the region to
3154 fontify, or @code{nil} (which means choose the region in the standard
3155 way). This function needs to preserve point, the match-data, and the
3156 current restriction. The region it returns may start or end in the
3159 Since this function is called after every buffer change, it should be
3163 @node Desktop Save Mode
3164 @section Desktop Save Mode
3165 @cindex desktop save mode
3167 @dfn{Desktop Save Mode} is a feature to save the state of Emacs from
3168 one session to another. The user-level commands for using Desktop
3169 Save Mode are described in the GNU Emacs Manual (@pxref{Saving Emacs
3170 Sessions,,, emacs, the GNU Emacs Manual}). Modes whose buffers visit
3171 a file, don't have to do anything to use this feature.
3173 For buffers not visiting a file to have their state saved, the major
3174 mode must bind the buffer local variable @code{desktop-save-buffer} to
3175 a non-@code{nil} value.
3177 @defvar desktop-save-buffer
3178 If this buffer-local variable is non-@code{nil}, the buffer will have
3179 its state saved in the desktop file at desktop save. If the value is
3180 a function, it is called at desktop save with argument
3181 @var{desktop-dirname}, and its value is saved in the desktop file along
3182 with the state of the buffer for which it was called. When file names
3183 are returned as part of the auxiliary information, they should be
3184 formatted using the call
3187 (desktop-file-name @var{file-name} @var{desktop-dirname})
3192 For buffers not visiting a file to be restored, the major mode must
3193 define a function to do the job, and that function must be listed in
3194 the alist @code{desktop-buffer-mode-handlers}.
3196 @defvar desktop-buffer-mode-handlers
3200 (@var{major-mode} . @var{restore-buffer-function})
3203 The function @var{restore-buffer-function} will be called with
3207 (@var{buffer-file-name} @var{buffer-name} @var{desktop-buffer-misc})
3210 and it should return the restored buffer.
3211 Here @var{desktop-buffer-misc} is the value returned by the function
3212 optionally bound to @code{desktop-save-buffer}.
3216 arch-tag: 4c7bff41-36e6-4da6-9e7f-9b9289e27c8e