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. When the
47 hook name ends in @samp{-hook}, that tells you it is normal. We try to
48 make all hooks normal, as much as possible, so that you can use them in
51 Every major mode function is supposed to run a normal hook called the
52 @dfn{mode hook} as the last step of initialization. This makes it easy
53 for a user to customize the behavior of the mode, by overriding the
54 buffer-local variable assignments already made by the mode. Most
55 minor modes also run a mode hook at their end. But hooks are used in
56 other contexts too. For example, the hook @code{suspend-hook} runs
57 just before Emacs suspends itself (@pxref{Suspending Emacs}).
59 The recommended way to add a hook function to a normal hook is by
60 calling @code{add-hook} (see below). The hook functions may be any of
61 the valid kinds of functions that @code{funcall} accepts (@pxref{What
62 Is a Function}). Most normal hook variables are initially void;
63 @code{add-hook} knows how to deal with this. You can add hooks either
64 globally or buffer-locally with @code{add-hook}.
67 If the hook variable's name does not end with @samp{-hook}, that
68 indicates it is probably an @dfn{abnormal hook}. Then you should look at its
69 documentation to see how to use the hook properly.
71 If the variable's name ends in @samp{-functions} or @samp{-hooks},
72 then the value is a list of functions, but it is abnormal in that either
73 these functions are called with arguments or their values are used in
74 some way. You can use @code{add-hook} to add a function to the list,
75 but you must take care in writing the function. (A few of these
76 variables, notably those ending in @samp{-hooks}, are actually
77 normal hooks which were named before we established the convention of
78 using @samp{-hook} for them.)
80 If the variable's name ends in @samp{-function}, then its value
81 is just a single function, not a list of functions.
83 Here's an example that uses a mode hook to turn on Auto Fill mode when
84 in Lisp Interaction mode:
87 (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
90 At the appropriate time, Emacs uses the @code{run-hooks} function to
93 @defun run-hooks &rest hookvars
94 This function takes one or more normal hook variable names as
95 arguments, and runs each hook in turn. Each argument should be a
96 symbol that is a normal hook variable. These arguments are processed
97 in the order specified.
99 If a hook variable has a non-@code{nil} value, that value may be a
100 function or a list of functions. (The former option is considered
101 obsolete.) If the value is a function (either a lambda expression or
102 a symbol with a function definition), it is called. If it is a list
103 that isn't a function, its elements are called, consecutively. All
104 the hook functions are called with no arguments.
107 @defun run-hook-with-args hook &rest args
108 This function is the way to run an abnormal hook and always call all
109 of the hook functions. It calls each of the hook functions one by
110 one, passing each of them the arguments @var{args}.
113 @defun run-hook-with-args-until-failure hook &rest args
114 This function is the way to run an abnormal hook until one of the hook
115 functions fails. It calls each of the hook functions, passing each of
116 them the arguments @var{args}, until some hook function returns
117 @code{nil}. It then stops and returns @code{nil}. If none of the
118 hook functions return @code{nil}, it returns a non-@code{nil} value.
121 @defun run-hook-with-args-until-success hook &rest args
122 This function is the way to run an abnormal hook until a hook function
123 succeeds. It calls each of the hook functions, passing each of them
124 the arguments @var{args}, until some hook function returns
125 non-@code{nil}. Then it stops, and returns whatever was returned by
126 the last hook function that was called. If all hook functions return
127 @code{nil}, it returns @code{nil} as well.
130 @defun add-hook hook function &optional append local
131 This function is the handy way to add function @var{function} to hook
132 variable @var{hook}. You can use it for abnormal hooks as well as for
133 normal hooks. @var{function} can be any Lisp function that can accept
134 the proper number of arguments for @var{hook}. For example,
137 (add-hook 'text-mode-hook 'my-text-hook-function)
141 adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
143 If @var{function} is already present in @var{hook} (comparing using
144 @code{equal}), then @code{add-hook} does not add it a second time.
146 It is best to design your hook functions so that the order in which they
147 are executed does not matter. Any dependence on the order is ``asking
148 for trouble''. However, the order is predictable: normally,
149 @var{function} goes at the front of the hook list, so it will be
150 executed first (barring another @code{add-hook} call). If the optional
151 argument @var{append} is non-@code{nil}, the new hook function goes at
152 the end of the hook list and will be executed last.
154 @code{add-hook} can handle the cases where @var{hook} is void or its
155 value is a single function; it sets or changes the value to a list of
158 If @var{local} is non-@code{nil}, that says to add @var{function} to
159 the buffer-local hook list instead of to the global hook list. If
160 needed, this makes the hook buffer-local and adds @code{t} to the
161 buffer-local value. The latter acts as a flag to run the hook
162 functions in the default value as well as in the local value.
165 @defun remove-hook hook function &optional local
166 This function removes @var{function} from the hook variable
167 @var{hook}. It compares @var{function} with elements of @var{hook}
168 using @code{equal}, so it works for both symbols and lambda
171 If @var{local} is non-@code{nil}, that says to remove @var{function}
172 from the buffer-local hook list instead of from the global hook list.
179 Major modes specialize Emacs for editing particular kinds of text.
180 Each buffer has only one major mode at a time. For each major mode
181 there is a function to switch to that mode in the current buffer; its
182 name should end in @samp{-mode}. These functions work by setting
183 buffer-local variable bindings and other data associated with the
184 buffer, such as a local keymap. The effect lasts until you switch
185 to another major mode in the same buffer.
188 * Major Mode Basics::
189 * Major Mode Conventions:: Coding conventions for keymaps, etc.
190 * Example Major Modes:: Text mode and Lisp modes.
191 * Auto Major Mode:: How Emacs chooses the major mode automatically.
192 * Mode Help:: Finding out how to use a mode.
193 * Derived Modes:: Defining a new major mode based on another major
195 * Generic Modes:: Defining a simple major mode that supports
196 comment syntax and Font Lock mode.
197 * Mode Hooks:: Hooks run at the end of major mode functions.
200 @node Major Mode Basics
201 @subsection Major Mode Basics
202 @cindex Fundamental mode
204 The least specialized major mode is called @dfn{Fundamental mode}.
205 This mode has no mode-specific definitions or variable settings, so each
206 Emacs command behaves in its default manner, and each option is in its
207 default state. All other major modes redefine various keys and options.
208 For example, Lisp Interaction mode provides special key bindings for
209 @kbd{C-j} (@code{eval-print-last-sexp}), @key{TAB}
210 (@code{lisp-indent-line}), and other keys.
212 When you need to write several editing commands to help you perform a
213 specialized editing task, creating a new major mode is usually a good
214 idea. In practice, writing a major mode is easy (in contrast to
215 writing a minor mode, which is often difficult).
217 If the new mode is similar to an old one, it is often unwise to modify
218 the old one to serve two purposes, since it may become harder to use and
219 maintain. Instead, copy and rename an existing major mode definition
220 and alter the copy---or define a @dfn{derived mode} (@pxref{Derived
221 Modes}). For example, Rmail Edit mode, which is in
222 @file{emacs/lisp/mail/rmailedit.el}, is a major mode that is very similar to
223 Text mode except that it provides two additional commands. Its
224 definition is distinct from that of Text mode, but uses that of Text mode.
226 Even if the new mode is not an obvious derivative of any other mode,
227 it is convenient to use @code{define-derived-mode} with a @code{nil}
228 parent argument, since it automatically enforces the most important
229 coding conventions for you.
231 For a very simple programming language major mode that handles
232 comments and fontification, you can use @code{define-generic-mode}.
233 @xref{Generic Modes}.
235 Rmail Edit mode offers an example of changing the major mode
236 temporarily for a buffer, so it can be edited in a different way (with
237 ordinary Emacs commands rather than Rmail commands). In such cases, the
238 temporary major mode usually provides a command to switch back to the
239 buffer's usual mode (Rmail mode, in this case). You might be tempted to
240 present the temporary redefinitions inside a recursive edit and restore
241 the usual ones when the user exits; but this is a bad idea because it
242 constrains the user's options when it is done in more than one buffer:
243 recursive edits must be exited most-recently-entered first. Using an
244 alternative major mode avoids this limitation. @xref{Recursive
247 The standard GNU Emacs Lisp library directory tree contains the code
248 for several major modes, in files such as @file{text-mode.el},
249 @file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
250 @file{rmail.el}. They are found in various subdirectories of the
251 @file{lisp} directory. You can study these libraries to see how modes
252 are written. Text mode is perhaps the simplest major mode aside from
253 Fundamental mode. Rmail mode is a complicated and specialized mode.
255 @node Major Mode Conventions
256 @subsection Major Mode Conventions
258 The code for existing major modes follows various coding conventions,
259 including conventions for local keymap and syntax table initialization,
260 global names, and hooks. Please follow these conventions when you
261 define a new major mode.
263 This list of conventions is only partial, because each major mode
264 should aim for consistency in general with other Emacs major modes.
265 This makes Emacs as a whole more coherent. It is impossible to list
266 here all the possible points where this issue might come up; if the
267 Emacs developers point out an area where your major mode deviates from
268 the usual conventions, please make it compatible.
272 Define a command whose name ends in @samp{-mode}, with no arguments,
273 that switches to the new mode in the current buffer. This command
274 should set up the keymap, syntax table, and buffer-local variables in an
275 existing buffer, without changing the buffer's contents.
278 Write a documentation string for this command that describes the
279 special commands available in this mode. @kbd{C-h m}
280 (@code{describe-mode}) in your mode will display this string.
282 The documentation string may include the special documentation
283 substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
284 @samp{\<@var{keymap}>}, which enable the documentation to adapt
285 automatically to the user's own key bindings. @xref{Keys in
289 The major mode command should start by calling
290 @code{kill-all-local-variables}. This is what gets rid of the
291 buffer-local variables of the major mode previously in effect.
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 must not define @key{RET} to do anything other than insert
359 a newline. The command to insert a newline and then indent is
360 @kbd{C-j}. Please keep this distinction uniform for all major modes.
363 Major modes should not alter options that are primarily a matter of user
364 preference, such as whether Auto-Fill mode is enabled. Leave this to
365 each user to decide. However, a major mode should customize other
366 variables so that Auto-Fill mode will work usefully @emph{if} the user
370 @cindex syntax tables in modes
371 The mode may have its own syntax table or may share one with other
372 related modes. If it has its own syntax table, it should store this in
373 a variable named @code{@var{modename}-mode-syntax-table}. @xref{Syntax
377 If the mode handles a language that has a syntax for comments, it should
378 set the variables that define the comment syntax. @xref{Options for
379 Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}.
382 @cindex abbrev tables in modes
383 The mode may have its own abbrev table or may share one with other
384 related modes. If it has its own abbrev table, it should store this
385 in a variable named @code{@var{modename}-mode-abbrev-table}. If the
386 major mode command defines any abbrevs itself, it should pass @code{t}
387 for the @var{system-flag} argument to @code{define-abbrev}.
388 @xref{Defining Abbrevs}.
391 The mode should specify how to do highlighting for Font Lock mode, by
392 setting up a buffer-local value for the variable
393 @code{font-lock-defaults} (@pxref{Font Lock Mode}).
396 The mode should specify how Imenu should find the definitions or
397 sections of a buffer, by setting up a buffer-local value for the
398 variable @code{imenu-generic-expression}, for the two variables
399 @code{imenu-prev-index-position-function} and
400 @code{imenu-extract-index-name-function}, or for the variable
401 @code{imenu-create-index-function} (@pxref{Imenu}).
404 The mode can specify a local value for
405 @code{eldoc-documentation-function} to tell ElDoc mode how to handle
409 Use @code{defvar} or @code{defcustom} to set mode-related variables, so
410 that they are not reinitialized if they already have a value. (Such
411 reinitialization could discard customizations made by the user.)
414 @cindex buffer-local variables in modes
415 To make a buffer-local binding for an Emacs customization variable, use
416 @code{make-local-variable} in the major mode command, not
417 @code{make-variable-buffer-local}. The latter function would make the
418 variable local to every buffer in which it is subsequently set, which
419 would affect buffers that do not use this mode. It is undesirable for a
420 mode to have such global effects. @xref{Buffer-Local Variables}.
422 With rare exceptions, the only reasonable way to use
423 @code{make-variable-buffer-local} in a Lisp package is for a variable
424 which is used only within that package. Using it on a variable used by
425 other packages would interfere with them.
429 @cindex major mode hook
430 Each major mode should have a @dfn{mode hook} named
431 @code{@var{modename}-mode-hook}. The major mode command should run that
432 hook, with @code{run-mode-hooks}, as the very last thing it
433 does. @xref{Mode Hooks}.
436 The major mode command may start by calling some other major mode
437 command (called the @dfn{parent mode}) and then alter some of its
438 settings. A mode that does this is called a @dfn{derived mode}. The
439 recommended way to define one is to use @code{define-derived-mode},
440 but this is not required. Such a mode should call the parent mode
441 command inside a @code{delay-mode-hooks} form. (Using
442 @code{define-derived-mode} does this automatically.) @xref{Derived
443 Modes}, and @ref{Mode Hooks}.
446 If something special should be done if the user switches a buffer from
447 this mode to any other major mode, this mode can set up a buffer-local
448 value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}).
451 If this mode is appropriate only for specially-prepared text, then the
452 major mode command symbol should have a property named @code{mode-class}
453 with value @code{special}, put on as follows:
455 @kindex mode-class @r{(property)}
456 @cindex @code{special}
458 (put 'funny-mode 'mode-class 'special)
462 This tells Emacs that new buffers created while the current buffer is
463 in Funny mode should not inherit Funny mode, in case
464 @code{default-major-mode} is @code{nil}. Modes such as Dired, Rmail,
465 and Buffer List use this feature.
468 If you want to make the new mode the default for files with certain
469 recognizable names, add an element to @code{auto-mode-alist} to select
470 the mode for those file names (@pxref{Auto Major Mode}). If you
471 define the mode command to autoload, you should add this element in
472 the same file that calls @code{autoload}. If you use an autoload
473 cookie for the mode command, you can also use an autoload cookie for
474 the form that adds the element (@pxref{autoload cookie}). If you do
475 not autoload the mode command, it is sufficient to add the element in
476 the file that contains the mode definition.
479 In the comments that document the file, you should provide a sample
480 @code{autoload} form and an example of how to add to
481 @code{auto-mode-alist}, that users can include in their init files
486 The top-level forms in the file defining the mode should be written so
487 that they may be evaluated more than once without adverse consequences.
488 Even if you never load the file more than once, someone else will.
491 @node Example Major Modes
492 @subsection Major Mode Examples
494 Text mode is perhaps the simplest mode besides Fundamental mode.
495 Here are excerpts from @file{text-mode.el} that illustrate many of
496 the conventions listed above:
500 ;; @r{Create the syntax table for this mode.}
501 (defvar text-mode-syntax-table
502 (let ((st (make-syntax-table)))
503 (modify-syntax-entry ?\" ". " st)
504 (modify-syntax-entry ?\\ ". " st)
505 ;; We add `p' so that M-c on 'hello' leads to 'Hello' rather than 'hello'.
506 (modify-syntax-entry ?' "w p" st)
508 "Syntax table used while in `text-mode'.")
511 ;; @r{Create the keymap for this mode.}
513 (defvar text-mode-map
514 (let ((map (make-sparse-keymap)))
515 (define-key map "\e\t" 'ispell-complete-word)
516 (define-key map "\es" 'center-line)
517 (define-key map "\eS" 'center-paragraph)
519 "Keymap for `text-mode'.
520 Many other modes, such as `mail-mode', `outline-mode' and `indented-text-mode',
521 inherit all the commands defined in this map.")
525 Here is how the actual mode command is defined now:
529 (define-derived-mode text-mode nil "Text"
530 "Major mode for editing text written for humans to read.
531 In this mode, paragraphs are delimited only by blank or white lines.
532 You can thus get the full benefit of adaptive filling
533 (see the variable `adaptive-fill-mode').
535 Turning on Text mode runs the normal hook `text-mode-hook'."
538 (make-local-variable 'text-mode-variant)
539 (setq text-mode-variant t)
540 ;; @r{These two lines are a feature added recently.}
541 (set (make-local-variable 'require-final-newline)
542 mode-require-final-newline)
543 (set (make-local-variable 'indent-line-function) 'indent-relative))
547 But here is how it was defined formerly, before
548 @code{define-derived-mode} existed:
552 ;; @r{This isn't needed nowadays, since @code{define-derived-mode} does it.}
553 (defvar text-mode-abbrev-table nil
554 "Abbrev table used while in text mode.")
555 (define-abbrev-table 'text-mode-abbrev-table ())
560 "Major mode for editing text intended for humans to read...
561 Special commands: \\@{text-mode-map@}
564 Turning on text-mode runs the hook `text-mode-hook'."
566 (kill-all-local-variables)
567 (use-local-map text-mode-map)
570 (setq local-abbrev-table text-mode-abbrev-table)
571 (set-syntax-table text-mode-syntax-table)
574 ;; @r{These four lines are absent from the current version}
575 ;; @r{not because this is done some other way, but rather}
576 ;; @r{because nowadays Text mode uses the normal definition of paragraphs.}
577 (make-local-variable 'paragraph-start)
578 (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter))
579 (make-local-variable 'paragraph-separate)
580 (setq paragraph-separate paragraph-start)
581 (make-local-variable 'indent-line-function)
582 (setq indent-line-function 'indent-relative-maybe)
585 (setq mode-name "Text")
586 (setq major-mode 'text-mode)
587 (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
588 ; @r{customize the mode with a hook.}
592 @cindex @file{lisp-mode.el}
593 The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
594 Interaction mode) have more features than Text mode and the code is
595 correspondingly more complicated. Here are excerpts from
596 @file{lisp-mode.el} that illustrate how these modes are written.
598 @cindex syntax table example
601 ;; @r{Create mode-specific table variables.}
602 (defvar lisp-mode-syntax-table nil "")
603 (defvar lisp-mode-abbrev-table nil "")
607 (defvar emacs-lisp-mode-syntax-table
608 (let ((table (make-syntax-table)))
613 ;; @r{Set syntax of chars up to @samp{0} to say they are}
614 ;; @r{part of symbol names but not words.}
615 ;; @r{(The digit @samp{0} is @code{48} in the @acronym{ASCII} character set.)}
617 (modify-syntax-entry i "_ " table)
619 ;; @r{@dots{} similar code follows for other character ranges.}
622 ;; @r{Then set the syntax codes for characters that are special in Lisp.}
623 (modify-syntax-entry ? " " table)
624 (modify-syntax-entry ?\t " " table)
625 (modify-syntax-entry ?\f " " table)
626 (modify-syntax-entry ?\n "> " table)
629 ;; @r{Give CR the same syntax as newline, for selective-display.}
630 (modify-syntax-entry ?\^m "> " table)
631 (modify-syntax-entry ?\; "< " table)
632 (modify-syntax-entry ?` "' " table)
633 (modify-syntax-entry ?' "' " table)
634 (modify-syntax-entry ?, "' " table)
637 ;; @r{@dots{}likewise for many other characters@dots{}}
638 (modify-syntax-entry ?\( "() " table)
639 (modify-syntax-entry ?\) ")( " table)
640 (modify-syntax-entry ?\[ "(] " table)
641 (modify-syntax-entry ?\] ")[ " table))
645 ;; @r{Create an abbrev table for lisp-mode.}
646 (define-abbrev-table 'lisp-mode-abbrev-table ())
650 Much code is shared among the three Lisp modes. The following
651 function sets various variables; it is called by each of the major Lisp
656 (defun lisp-mode-variables (lisp-syntax)
658 (set-syntax-table lisp-mode-syntax-table))
659 (setq local-abbrev-table lisp-mode-abbrev-table)
664 Functions such as @code{forward-paragraph} use the value of the
665 @code{paragraph-start} variable. Since Lisp code is different from
666 ordinary text, the @code{paragraph-start} variable needs to be set
667 specially to handle Lisp. Also, comments are indented in a special
668 fashion in Lisp and the Lisp modes need their own mode-specific
669 @code{comment-indent-function}. The code to set these variables is the
670 rest of @code{lisp-mode-variables}.
674 (make-local-variable 'paragraph-start)
675 (setq paragraph-start (concat page-delimiter "\\|$" ))
676 (make-local-variable 'paragraph-separate)
677 (setq paragraph-separate paragraph-start)
681 (make-local-variable 'comment-indent-function)
682 (setq comment-indent-function 'lisp-comment-indent))
687 Each of the different Lisp modes has a slightly different keymap. For
688 example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other
689 Lisp modes do not. However, all Lisp modes have some commands in
690 common. The following code sets up the common commands:
694 (defvar shared-lisp-mode-map ()
695 "Keymap for commands shared by all sorts of Lisp modes.")
697 ;; @r{Putting this @code{if} after the @code{defvar} is an older style.}
698 (if shared-lisp-mode-map
700 (setq shared-lisp-mode-map (make-sparse-keymap))
701 (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp)
702 (define-key shared-lisp-mode-map "\177"
703 'backward-delete-char-untabify))
708 And here is the code to set up the keymap for Lisp mode:
712 (defvar lisp-mode-map ()
713 "Keymap for ordinary Lisp mode...")
717 (setq lisp-mode-map (make-sparse-keymap))
718 (set-keymap-parent lisp-mode-map shared-lisp-mode-map)
719 (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun)
720 (define-key lisp-mode-map "\C-c\C-z" 'run-lisp))
724 Finally, here is the complete major mode function definition for
730 "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
732 Delete converts tabs to spaces as it moves back.
733 Blank lines separate paragraphs. Semicolons start comments.
735 Note that `run-lisp' may be used either to start an inferior Lisp job
736 or to switch back to an existing one.
740 Entry to this mode calls the value of `lisp-mode-hook'
741 if that value is non-nil."
743 (kill-all-local-variables)
746 (use-local-map lisp-mode-map) ; @r{Select the mode's keymap.}
747 (setq major-mode 'lisp-mode) ; @r{This is how @code{describe-mode}}
748 ; @r{finds out what to describe.}
749 (setq mode-name "Lisp") ; @r{This goes into the mode line.}
750 (lisp-mode-variables t) ; @r{This defines various variables.}
751 (make-local-variable 'comment-start-skip)
752 (setq comment-start-skip
753 "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *")
754 (make-local-variable 'font-lock-keywords-case-fold-search)
755 (setq font-lock-keywords-case-fold-search t)
758 (setq imenu-case-fold-search t)
759 (set-syntax-table lisp-mode-syntax-table)
760 (run-mode-hooks 'lisp-mode-hook)) ; @r{This permits the user to use a}
761 ; @r{hook to customize the mode.}
765 @node Auto Major Mode
766 @subsection How Emacs Chooses a Major Mode
768 Based on information in the file name or in the file itself, Emacs
769 automatically selects a major mode for the new buffer when a file is
770 visited. It also processes local variables specified in the file text.
772 @deffn Command fundamental-mode
773 Fundamental mode is a major mode that is not specialized for anything
774 in particular. Other major modes are defined in effect by comparison
775 with this one---their definitions say what to change, starting from
776 Fundamental mode. The @code{fundamental-mode} function does @emph{not}
777 run any mode hooks; you're not supposed to customize it. (If you want Emacs
778 to behave differently in Fundamental mode, change the @emph{global}
782 @deffn Command normal-mode &optional find-file
783 This function establishes the proper major mode and buffer-local variable
784 bindings for the current buffer. First it calls @code{set-auto-mode}
785 (see below), then it runs @code{hack-local-variables} to parse, and
786 bind or evaluate as appropriate, the file's local variables
787 (@pxref{File Local Variables}).
789 If the @var{find-file} argument to @code{normal-mode} is non-@code{nil},
790 @code{normal-mode} assumes that the @code{find-file} function is calling
791 it. In this case, it may process local variables in the @samp{-*-}
792 line or at the end of the file. The variable
793 @code{enable-local-variables} controls whether to do so. @xref{File
794 Variables, , Local Variables in Files, emacs, The GNU Emacs Manual},
795 for the syntax of the local variables section of a file.
797 If you run @code{normal-mode} interactively, the argument
798 @var{find-file} is normally @code{nil}. In this case,
799 @code{normal-mode} unconditionally processes any file local variables.
801 If @code{normal-mode} processes the local variables list and this list
802 specifies a major mode, that mode overrides any mode chosen by
803 @code{set-auto-mode}. If neither @code{set-auto-mode} nor
804 @code{hack-local-variables} specify a major mode, the buffer stays in
805 the major mode determined by @code{default-major-mode} (see below).
807 @cindex file mode specification error
808 @code{normal-mode} uses @code{condition-case} around the call to the
809 major mode function, so errors are caught and reported as a @samp{File
810 mode specification error}, followed by the original error message.
813 @defun set-auto-mode &optional keep-mode-if-same
814 @cindex visited file mode
815 This function selects the major mode that is appropriate for the
816 current buffer. It bases its decision (in order of precedence) on
817 the @w{@samp{-*-}} line, on the @w{@samp{#!}} line (using
818 @code{interpreter-mode-alist}), on the text at the beginning of the
819 buffer (using @code{magic-mode-alist}), and finally on the visited
820 file name (using @code{auto-mode-alist}). @xref{Choosing Modes, , How
821 Major Modes are Chosen, emacs, The GNU Emacs Manual}. However, this
822 function does not look for the @samp{mode:} local variable near the
823 end of a file; the @code{hack-local-variables} function does that.
824 If @code{enable-local-variables} is @code{nil}, @code{set-auto-mode}
825 does not check the @w{@samp{-*-}} line for a mode tag either.
827 If @var{keep-mode-if-same} is non-@code{nil}, this function does not
828 call the mode command if the buffer is already in the proper major
829 mode. For instance, @code{set-visited-file-name} sets this to
830 @code{t} to avoid killing buffer local variables that the user may
834 @defopt default-major-mode
835 This variable holds the default major mode for new buffers. The
836 standard value is @code{fundamental-mode}.
838 If the value of @code{default-major-mode} is @code{nil}, Emacs uses
839 the (previously) current buffer's major mode as the default major mode
840 of a new buffer. However, if that major mode symbol has a @code{mode-class}
841 property with value @code{special}, then it is not used for new buffers;
842 Fundamental mode is used instead. The modes that have this property are
843 those such as Dired and Rmail that are useful only with text that has
844 been specially prepared.
847 @defun set-buffer-major-mode buffer
848 This function sets the major mode of @var{buffer} to the value of
849 @code{default-major-mode}; if that variable is @code{nil}, it uses the
850 current buffer's major mode (if that is suitable). As an exception,
851 if @var{buffer}'s name is @samp{*scratch*}, it sets the mode to
852 @code{initial-major-mode}.
854 The low-level primitives for creating buffers do not use this function,
855 but medium-level commands such as @code{switch-to-buffer} and
856 @code{find-file-noselect} use it whenever they create buffers.
859 @defopt initial-major-mode
860 @cindex @samp{*scratch*}
861 The value of this variable determines the major mode of the initial
862 @samp{*scratch*} buffer. The value should be a symbol that is a major
863 mode command. The default value is @code{lisp-interaction-mode}.
866 @defvar interpreter-mode-alist
867 This variable specifies major modes to use for scripts that specify a
868 command interpreter in a @samp{#!} line. Its value is an alist with
869 elements of the form @code{(@var{interpreter} . @var{mode})}; for
870 example, @code{("perl" . perl-mode)} is one element present by
871 default. The element says to use mode @var{mode} if the file
872 specifies an interpreter which matches @var{interpreter}.
875 @defvar magic-mode-alist
876 This variable's value is an alist with elements of the form
877 @code{(@var{regexp} . @var{function})}, where @var{regexp} is a
878 regular expression and @var{function} is a function or @code{nil}.
879 After visiting a file, @code{set-auto-mode} calls @var{function} if
880 the text at the beginning of the buffer matches @var{regexp} and
881 @var{function} is non-@code{nil}; if @var{function} is @code{nil},
882 @code{auto-mode-alist} gets to decide the mode.
885 @defvar auto-mode-alist
886 This variable contains an association list of file name patterns
887 (regular expressions) and corresponding major mode commands. Usually,
888 the file name patterns test for suffixes, such as @samp{.el} and
889 @samp{.c}, but this need not be the case. An ordinary element of the
890 alist looks like @code{(@var{regexp} . @var{mode-function})}.
896 (("\\`/tmp/fol/" . text-mode)
897 ("\\.texinfo\\'" . texinfo-mode)
898 ("\\.texi\\'" . texinfo-mode)
901 ("\\.el\\'" . emacs-lisp-mode)
908 When you visit a file whose expanded file name (@pxref{File Name
909 Expansion}), with version numbers and backup suffixes removed using
910 @code{file-name-sans-versions} (@pxref{File Name Components}), matches
911 a @var{regexp}, @code{set-auto-mode} calls the corresponding
912 @var{mode-function}. This feature enables Emacs to select the proper
913 major mode for most files.
915 If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
916 @var{function} t)}, then after calling @var{function}, Emacs searches
917 @code{auto-mode-alist} again for a match against the portion of the file
918 name that did not match before. This feature is useful for
919 uncompression packages: an entry of the form @code{("\\.gz\\'"
920 @var{function} t)} can uncompress the file and then put the uncompressed
921 file in the proper mode according to the name sans @samp{.gz}.
923 Here is an example of how to prepend several pattern pairs to
924 @code{auto-mode-alist}. (You might use this sort of expression in your
929 (setq auto-mode-alist
931 ;; @r{File name (within directory) starts with a dot.}
932 '(("/\\.[^/]*\\'" . fundamental-mode)
933 ;; @r{File name has no dot.}
934 ("[^\\./]*\\'" . fundamental-mode)
935 ;; @r{File name ends in @samp{.C}.}
936 ("\\.C\\'" . c++-mode))
943 @subsection Getting Help about a Major Mode
945 @cindex help for major mode
946 @cindex documentation for major mode
948 The @code{describe-mode} function is used to provide information
949 about major modes. It is normally called with @kbd{C-h m}. The
950 @code{describe-mode} function uses the value of @code{major-mode},
951 which is why every major mode function needs to set the
952 @code{major-mode} variable.
954 @deffn Command describe-mode
955 This function displays the documentation of the current major mode.
957 The @code{describe-mode} function calls the @code{documentation}
958 function using the value of @code{major-mode} as an argument. Thus, it
959 displays the documentation string of the major mode function.
960 (@xref{Accessing Documentation}.)
964 This buffer-local variable holds the symbol for the current buffer's
965 major mode. This symbol should have a function definition that is the
966 command to switch to that major mode. The @code{describe-mode}
967 function uses the documentation string of the function as the
968 documentation of the major mode.
972 @subsection Defining Derived Modes
975 It's often useful to define a new major mode in terms of an existing
976 one. An easy way to do this is to use @code{define-derived-mode}.
978 @defmac define-derived-mode variant parent name docstring keyword-args@dots{} body@dots{}
979 This construct defines @var{variant} as a major mode command, using
980 @var{name} as the string form of the mode name. @var{variant} and
981 @var{parent} should be unquoted symbols.
983 The new command @var{variant} is defined to call the function
984 @var{parent}, then override certain aspects of that parent mode:
988 The new mode has its own sparse keymap, named
989 @code{@var{variant}-map}. @code{define-derived-mode}
990 makes the parent mode's keymap the parent of the new map, unless
991 @code{@var{variant}-map} is already set and already has a parent.
994 The new mode has its own syntax table, kept in the variable
995 @code{@var{variant}-syntax-table}, unless you override this using the
996 @code{:syntax-table} keyword (see below). @code{define-derived-mode}
997 makes the parent mode's syntax-table the parent of
998 @code{@var{variant}-syntax-table}, unless the latter is already set
999 and already has a parent different from the standard syntax table.
1002 The new mode has its own abbrev table, kept in the variable
1003 @code{@var{variant}-abbrev-table}, unless you override this using the
1004 @code{:abbrev-table} keyword (see below).
1007 The new mode has its own mode hook, @code{@var{variant}-hook}. It
1008 runs this hook, after running the hooks of its ancestor modes, with
1009 @code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}.
1012 In addition, you can specify how to override other aspects of
1013 @var{parent} with @var{body}. The command @var{variant}
1014 evaluates the forms in @var{body} after setting up all its usual
1015 overrides, just before running the mode hooks.
1017 You can also specify @code{nil} for @var{parent}. This gives the new
1018 mode no parent. Then @code{define-derived-mode} behaves as described
1019 above, but, of course, omits all actions connected with @var{parent}.
1021 The argument @var{docstring} specifies the documentation string for
1022 the new mode. @code{define-derived-mode} adds some general
1023 information about the mode's hook, followed by the mode's keymap, at
1024 the end of this docstring. If you omit @var{docstring},
1025 @code{define-derived-mode} generates a documentation string.
1027 The @var{keyword-args} are pairs of keywords and values. The values
1028 are evaluated. The following keywords are currently supported:
1032 You can use this to explicitly specify a syntax table for the new
1033 mode. If you specify a @code{nil} value, the new mode uses the same
1034 syntax table as @var{parent}, or the standard syntax table if
1035 @var{parent} is @code{nil}. (Note that this does @emph{not} follow
1036 the convention used for non-keyword arguments that a @code{nil} value
1037 is equivalent with not specifying the argument.)
1040 You can use this to explicitly specify an abbrev table for the new
1041 mode. If you specify a @code{nil} value, the new mode uses the same
1042 abbrev table as @var{parent}, or @code{fundamental-mode-abbrev-table}
1043 if @var{parent} is @code{nil}. (Again, a @code{nil} value is
1044 @emph{not} equivalent to not specifying this keyword.)
1047 If this is specified, the value should be the customization group for
1048 this mode. (Not all major modes have one.) Only the (still
1049 experimental and unadvertised) command @code{customize-mode} currently
1050 uses this. @code{define-derived-mode} does @emph{not} automatically
1051 define the specified customization group.
1054 Here is a hypothetical example:
1057 (define-derived-mode hypertext-mode
1058 text-mode "Hypertext"
1059 "Major mode for hypertext.
1060 \\@{hypertext-mode-map@}"
1061 (setq case-fold-search nil))
1063 (define-key hypertext-mode-map
1064 [down-mouse-3] 'do-hyper-link)
1067 Do not write an @code{interactive} spec in the definition;
1068 @code{define-derived-mode} does that automatically.
1072 @subsection Generic Modes
1073 @cindex generic mode
1075 @dfn{Generic modes} are simple major modes with basic support for
1076 comment syntax and Font Lock mode. They are primarily useful for
1077 configuration files. To define a generic mode, use the macro
1078 @code{define-generic-mode}. See the file @file{generic-x.el} for some
1079 examples of the use of @code{define-generic-mode}.
1081 @defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring
1082 This macro creates a new generic mode. The argument @var{mode} (an
1083 unquoted symbol) is the major mode command. The optional argument
1084 @var{docstring} is the documentation for the mode command. If you do
1085 not supply it, @code{define-generic-mode} uses a default documentation
1088 @var{comment-list} is a list in which each element is either a
1089 character, a string of one or two characters, or a cons cell. A
1090 character or a string is set up in the mode's syntax table as a
1091 ``comment starter.'' If the entry is a cons cell, the @sc{car} is set
1092 up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.''
1093 (Use @code{nil} for the latter if you want comments to end at the end
1094 of the line.) Note that the syntax table has limitations about what
1095 comment starters and enders are actually possible. @xref{Syntax
1098 @var{keyword-list} is a list of keywords to highlight with
1099 @code{font-lock-keyword-face}. Each keyword should be a string.
1100 @var{font-lock-list} is a list of additional expressions to highlight.
1101 Each element of this list should have the same form as an element of
1102 @code{font-lock-keywords}. @xref{Search-based Fontification}.
1104 @var{auto-mode-list} is a list of regular expressions to add to the
1105 variable @code{auto-mode-alist}. These regular expressions are added
1106 when Emacs runs the macro expansion.
1108 @var{function-list} is a list of functions to call to do some
1109 additional setup. The mode command calls these functions just before
1110 it runs the mode hook variable @code{@var{mode}-hook}.
1114 @subsection Mode Hooks
1116 The two last things a major mode function should do is run its mode
1117 hook and finally the mode independent normal hook
1118 @code{after-change-major-mode-hook}. If the major mode is a derived
1119 mode, that is if it calls another major mode (the parent mode) in its
1120 body, then the parent's mode hook is run just before the derived
1121 mode's hook. Neither the parent's mode hook nor
1122 @code{after-change-major-mode-hook} are run at the end of the actual
1123 call to the parent mode. This applies recursively if the parent mode
1124 has itself a parent. That is, the mode hooks of all major modes
1125 called directly or indirectly by the major mode function are all run
1126 in sequence at the end, just before
1127 @code{after-change-major-mode-hook}.
1129 These conventions are new in Emacs 22, and some major modes
1130 implemented by users do not follow them yet. So if you put a function
1131 onto @code{after-change-major-mode-hook}, keep in mind that some modes
1132 will fail to run it. If a user complains about that, you can respond,
1133 ``That major mode fails to follow Emacs conventions, and that's why it
1134 fails to work. Please fix the major mode.'' In most cases, that is
1135 good enough, so go ahead and use @code{after-change-major-mode-hook}.
1136 However, if a certain feature needs to be completely reliable,
1137 it should not use @code{after-change-major-mode-hook} as of yet.
1139 When you defined a major mode using @code{define-derived-mode}, it
1140 automatically makes sure these conventions are followed. If you
1141 define a major mode ``from scratch'', not using
1142 @code{define-derived-mode}, make sure the major mode command follows
1143 these and other conventions. @xref{Major Mode Conventions}. You use
1144 these functions to do it properly.
1146 @defun run-mode-hooks &rest hookvars
1147 Major modes should run their mode hook using this function. It is
1148 similar to @code{run-hooks} (@pxref{Hooks}), but it also runs
1149 @code{after-change-major-mode-hook}.
1151 When the call to this function is dynamically inside a
1152 @code{delay-mode-hooks} form, this function does not run any hooks.
1153 Instead, it arranges for the next call to @code{run-mode-hooks} to run
1157 @defmac delay-mode-hooks body@dots{}
1158 This macro executes @var{body} like @code{progn}, but all calls to
1159 @code{run-mode-hooks} inside @var{body} delay running their hooks.
1160 They will be run by the first call to @code{run-mode-hooks} after exit
1161 from @code{delay-mode-hooks}. This is the proper way for a major mode
1162 command to invoke its parent mode.
1165 @defvar after-change-major-mode-hook
1166 Every major mode function should run this normal hook at its very end.
1167 It normally does not need to do so explicitly. Indeed, a major mode
1168 function should normally run its mode hook with @code{run-mode-hooks}
1169 as the very last thing it does, and the last thing
1170 @code{run-mode-hooks} does is run @code{after-change-major-mode-hook}.
1174 @section Minor Modes
1177 A @dfn{minor mode} provides features that users may enable or disable
1178 independently of the choice of major mode. Minor modes can be enabled
1179 individually or in combination. Minor modes would be better named
1180 ``generally available, optional feature modes,'' except that such a name
1183 A minor mode is not usually meant as a variation of a single major mode.
1184 Usually they are general and can apply to many major modes. For
1185 example, Auto Fill mode works with any major mode that permits text
1186 insertion. To be general, a minor mode must be effectively independent
1187 of the things major modes do.
1189 A minor mode is often much more difficult to implement than a major
1190 mode. One reason is that you should be able to activate and deactivate
1191 minor modes in any order. A minor mode should be able to have its
1192 desired effect regardless of the major mode and regardless of the other
1193 minor modes in effect.
1195 Often the biggest problem in implementing a minor mode is finding a
1196 way to insert the necessary hook into the rest of Emacs. Minor mode
1197 keymaps make this easier than it used to be.
1199 @defvar minor-mode-list
1200 The value of this variable is a list of all minor mode commands.
1204 * Minor Mode Conventions:: Tips for writing a minor mode.
1205 * Keymaps and Minor Modes:: How a minor mode can have its own keymap.
1206 * Defining Minor Modes:: A convenient facility for defining minor modes.
1209 @node Minor Mode Conventions
1210 @subsection Conventions for Writing Minor Modes
1211 @cindex minor mode conventions
1212 @cindex conventions for writing minor modes
1214 There are conventions for writing minor modes just as there are for
1215 major modes. Several of the major mode conventions apply to minor
1216 modes as well: those regarding the name of the mode initialization
1217 function, the names of global symbols, the use of a hook at the end of
1218 the initialization function, and the use of keymaps and other tables.
1220 In addition, there are several conventions that are specific to
1221 minor modes. (The easiest way to follow all the conventions is to use
1222 the macro @code{define-minor-mode}; @ref{Defining Minor Modes}.)
1226 @cindex mode variable
1227 Make a variable whose name ends in @samp{-mode} to control the minor
1228 mode. We call this the @dfn{mode variable}. The minor mode command
1229 should set this variable (@code{nil} to disable; anything else to
1232 If possible, implement the mode so that setting the variable
1233 automatically enables or disables the mode. Then the minor mode command
1234 does not need to do anything except set the variable.
1236 This variable is used in conjunction with the @code{minor-mode-alist} to
1237 display the minor mode name in the mode line. It can also enable
1238 or disable a minor mode keymap. Individual commands or hooks can also
1239 check the variable's value.
1241 If you want the minor mode to be enabled separately in each buffer,
1242 make the variable buffer-local.
1245 Define a command whose name is the same as the mode variable.
1246 Its job is to enable and disable the mode by setting the variable.
1248 The command should accept one optional argument. If the argument is
1249 @code{nil}, it should toggle the mode (turn it on if it is off, and
1250 off if it is on). It should turn the mode on if the argument is a
1251 positive integer, the symbol @code{t}, or a list whose @sc{car} is one
1252 of those. It should turn the mode off if the argument is a negative
1253 integer or zero, the symbol @code{-}, or a list whose @sc{car} is a
1254 negative integer or zero. The meaning of other arguments is not
1257 Here is an example taken from the definition of @code{transient-mark-mode}.
1258 It shows the use of @code{transient-mark-mode} as a variable that enables or
1259 disables the mode's behavior, and also shows the proper way to toggle,
1260 enable or disable the minor mode based on the raw prefix argument value.
1264 (setq transient-mark-mode
1265 (if (null arg) (not transient-mark-mode)
1266 (> (prefix-numeric-value arg) 0)))
1271 Add an element to @code{minor-mode-alist} for each minor mode
1272 (@pxref{Definition of minor-mode-alist}), if you want to indicate the
1273 minor mode in the mode line. This element should be a list of the
1277 (@var{mode-variable} @var{string})
1280 Here @var{mode-variable} is the variable that controls enabling of the
1281 minor mode, and @var{string} is a short string, starting with a space,
1282 to represent the mode in the mode line. These strings must be short so
1283 that there is room for several of them at once.
1285 When you add an element to @code{minor-mode-alist}, use @code{assq} to
1286 check for an existing element, to avoid duplication. For example:
1290 (unless (assq 'leif-mode minor-mode-alist)
1291 (setq minor-mode-alist
1292 (cons '(leif-mode " Leif") minor-mode-alist)))
1297 or like this, using @code{add-to-list} (@pxref{Setting Variables}):
1301 (add-to-list 'minor-mode-alist '(leif-mode " Leif"))
1306 Global minor modes distributed with Emacs should if possible support
1307 enabling and disabling via Custom (@pxref{Customization}). To do this,
1308 the first step is to define the mode variable with @code{defcustom}, and
1309 specify @code{:type boolean}.
1311 If just setting the variable is not sufficient to enable the mode, you
1312 should also specify a @code{:set} method which enables the mode by
1313 invoking the mode command. Note in the variable's documentation string that
1314 setting the variable other than via Custom may not take effect.
1316 Also mark the definition with an autoload cookie (@pxref{autoload cookie}),
1317 and specify a @code{:require} so that customizing the variable will load
1318 the library that defines the mode. This will copy suitable definitions
1319 into @file{loaddefs.el} so that users can use @code{customize-option} to
1320 enable the mode. For example:
1326 (defcustom msb-mode nil
1328 Setting this variable directly does not take effect;
1329 use either \\[customize] or the function `msb-mode'."
1330 :set 'custom-set-minor-mode
1331 :initialize 'custom-initialize-default
1339 @node Keymaps and Minor Modes
1340 @subsection Keymaps and Minor Modes
1342 Each minor mode can have its own keymap, which is active when the mode
1343 is enabled. To set up a keymap for a minor mode, add an element to the
1344 alist @code{minor-mode-map-alist}. @xref{Definition of minor-mode-map-alist}.
1346 @cindex @code{self-insert-command}, minor modes
1347 One use of minor mode keymaps is to modify the behavior of certain
1348 self-inserting characters so that they do something else as well as
1349 self-insert. In general, this is the only way to do that, since the
1350 facilities for customizing @code{self-insert-command} are limited to
1351 special cases (designed for abbrevs and Auto Fill mode). (Do not try
1352 substituting your own definition of @code{self-insert-command} for the
1353 standard one. The editor command loop handles this function specially.)
1355 The key sequences bound in a minor mode should consist of @kbd{C-c}
1356 followed by a punctuation character @emph{other than} @kbd{@{},
1357 @kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:}, and @kbd{;}. (Those few punctuation
1358 characters are reserved for major modes.)
1360 @node Defining Minor Modes
1361 @subsection Defining Minor Modes
1363 The macro @code{define-minor-mode} offers a convenient way of
1364 implementing a mode in one self-contained definition.
1366 @defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args@dots{} body@dots{}
1367 @tindex define-minor-mode
1368 This macro defines a new minor mode whose name is @var{mode} (a
1369 symbol). It defines a command named @var{mode} to toggle the minor
1370 mode, with @var{doc} as its documentation string. It also defines a
1371 variable named @var{mode}, which is set to @code{t} or @code{nil} by
1372 enabling or disabling the mode. The variable is initialized to
1373 @var{init-value}. Except in unusual circumstances (see below), this
1374 value must be @code{nil}.
1376 The string @var{lighter} says what to display in the mode line
1377 when the mode is enabled; if it is @code{nil}, the mode is not displayed
1380 The optional argument @var{keymap} specifies the keymap for the minor mode.
1381 It can be a variable name, whose value is the keymap, or it can be an alist
1382 specifying bindings in this form:
1385 (@var{key-sequence} . @var{definition})
1388 The above three arguments @var{init-value}, @var{lighter}, and
1389 @var{keymap} can be (partially) omitted when @var{keyword-args} are
1390 used. The @var{keyword-args} consist of keywords followed by
1391 corresponding values. A few keywords have special meanings:
1394 @item :group @var{group}
1395 Custom group name to use in all generated @code{defcustom} forms.
1396 Defaults to @var{mode} without the possible trailing @samp{-mode}.
1397 @strong{Warning:} don't use this default group name unless you have
1398 written a @code{defgroup} to define that group properly. @xref{Group
1401 @item :global @var{global}
1402 If non-@code{nil} specifies that the minor mode should be global. By
1403 default, minor modes defined with @code{define-minor-mode} are
1406 @item :init-value @var{init-value}
1407 This is equivalent to specifying @var{init-value} positionally.
1409 @item :lighter @var{lighter}
1410 This is equivalent to specifying @var{lighter} positionally.
1412 @item :keymap @var{keymap}
1413 This is equivalent to specifying @var{keymap} positionally.
1416 Any other keyword arguments are passed directly to the
1417 @code{defcustom} generated for the variable @var{mode}.
1419 The command named @var{mode} first performs the standard actions such
1420 as setting the variable named @var{mode} and then executes the
1421 @var{body} forms, if any. It finishes by running the mode hook
1422 variable @code{@var{mode}-hook}.
1425 The initial value must be @code{nil} except in cases where (1) the
1426 mode is preloaded in Emacs, or (2) it is painless for loading to
1427 enable the mode even though the user did not request it. For
1428 instance, if the mode has no effect unless something else is enabled,
1429 and will always be loaded by that time, enabling it by default is
1430 harmless. But these are unusual circumstances. Normally, the
1431 initial value must be @code{nil}.
1433 @findex easy-mmode-define-minor-mode
1434 The name @code{easy-mmode-define-minor-mode} is an alias
1437 Here is an example of using @code{define-minor-mode}:
1440 (define-minor-mode hungry-mode
1441 "Toggle Hungry mode.
1442 With no argument, this command toggles the mode.
1443 Non-null prefix argument turns on the mode.
1444 Null prefix argument turns off the mode.
1446 When Hungry mode is enabled, the control delete key
1447 gobbles all preceding whitespace except the last.
1448 See the command \\[hungry-electric-delete]."
1449 ;; The initial value.
1451 ;; The indicator for the mode line.
1453 ;; The minor mode bindings.
1454 '(("\C-\^?" . hungry-electric-delete))
1459 This defines a minor mode named ``Hungry mode'', a command named
1460 @code{hungry-mode} to toggle it, a variable named @code{hungry-mode}
1461 which indicates whether the mode is enabled, and a variable named
1462 @code{hungry-mode-map} which holds the keymap that is active when the
1463 mode is enabled. It initializes the keymap with a key binding for
1464 @kbd{C-@key{DEL}}. It puts the variable @code{hungry-mode} into
1465 custom group @code{hunger}. There are no @var{body} forms---many
1466 minor modes don't need any.
1468 Here's an equivalent way to write it:
1471 (define-minor-mode hungry-mode
1472 "Toggle Hungry mode.
1473 With no argument, this command toggles the mode.
1474 Non-null prefix argument turns on the mode.
1475 Null prefix argument turns off the mode.
1477 When Hungry mode is enabled, the control delete key
1478 gobbles all preceding whitespace except the last.
1479 See the command \\[hungry-electric-delete]."
1480 ;; The initial value.
1482 ;; The indicator for the mode line.
1484 ;; The minor mode bindings.
1486 '(("\C-\^?" . hungry-electric-delete)
1490 (hungry-electric-delete t))))
1494 @defmac define-global-minor-mode global-mode mode turn-on keyword-args@dots{}
1495 This defines a global minor mode named @var{global-mode} whose meaning
1496 is to enable the buffer-local minor mode @var{mode} in every buffer.
1497 To turn on the minor mode in a buffer, it uses the function
1498 @var{turn-on}; to turn off the minor mode, it calls @code{mode} with
1499 @minus{}1 as argument.
1501 Use @code{:group @var{group}} in @var{keyword-args} to specify the
1502 custom group for the mode variable of the global minor mode.
1505 @node Mode Line Format
1506 @section Mode-Line Format
1509 Each Emacs window (aside from minibuffer windows) typically has a mode
1510 line at the bottom, which displays status information about the buffer
1511 displayed in the window. The mode line contains information about the
1512 buffer, such as its name, associated file, depth of recursive editing,
1513 and major and minor modes. A window can also have a @dfn{header
1514 line}, which is much like the mode line but appears at the top of the
1517 This section describes how to control the contents of the mode line
1518 and header line. We include it in this chapter because much of the
1519 information displayed in the mode line relates to the enabled major and
1523 * Base: Mode Line Basics. Basic ideas of mode line control.
1524 * Data: Mode Line Data. The data structure that controls the mode line.
1525 * Top: Mode Line Top. The top level variable, mode-line-format.
1526 * Mode Line Variables:: Variables used in that data structure.
1527 * %-Constructs:: Putting information into a mode line.
1528 * Properties in Mode:: Using text properties in the mode line.
1529 * Header Lines:: Like a mode line, but at the top.
1530 * Emulating Mode Line:: Formatting text as the mode line would.
1533 @node Mode Line Basics
1534 @subsection Mode Line Basics
1536 @code{mode-line-format} is a buffer-local variable that holds a
1537 @dfn{mode line construct}, a kind of template, which controls the
1538 display the mode line of the current buffer. All windows for the same
1539 buffer use the same @code{mode-line-format}, so their mode lines
1540 appear the same---except for scrolling percentages, and line and
1541 column numbers, since those depend on point and on how the window is
1542 scrolled. The value of @code{header-line-format} specifies the
1543 buffer's header line in the same way, with a mode line construct.
1545 For efficiency, Emacs does not recompute the mode line and header
1546 line of a window in every redisplay. It does so when circumstances
1547 appear to call for it---for instance, if you change the window
1548 configuration, switch buffers, narrow or widen the buffer, scroll, or
1549 change the buffer's modification status. If you modify any of the
1550 variables referenced by @code{mode-line-format} (@pxref{Mode Line
1551 Variables}), or any other variables and data structures that affect
1552 how text is displayed (@pxref{Display}), you may want to force an
1553 update of the mode line so as to display the new information or
1554 display it in the new way.
1557 @defun force-mode-line-update &optional all
1558 Force redisplay of the current buffer's mode line and header line.
1559 The next redisplay will update the mode line and header line based on
1560 the latest values of all relevant variables. With optional
1561 non-@code{nil} @var{all}, force redisplay of all mode lines and header
1564 This function also forces recomputation of the menu bar menus
1565 and the frame title.
1568 The selected window's mode line is usually displayed in a different
1569 color using the face @code{mode-line}. Other windows' mode lines
1570 appear in the face @code{mode-line-inactive} instead. @xref{Faces}.
1572 @node Mode Line Data
1573 @subsection The Data Structure of the Mode Line
1574 @cindex mode-line construct
1576 The mode-line contents are controlled by a data structure called a
1577 @dfn{mode-line construct}, made up of lists, strings, symbols, and
1578 numbers kept in buffer-local variables. Each data type has a specific
1579 meaning for the mode-line appearance, as described below. The same
1580 data structure is used for constructing frame titles (@pxref{Frame
1581 Titles}) and header lines (@pxref{Header Lines}).
1583 A mode-line construct may be as simple as a fixed string of text,
1584 but it usually specifies how to combine fixed strings with variables'
1585 values to construct the text. Many of these variables are themselves
1586 defined to have mode-line constructs as their values.
1588 Here are the meanings of various data types as mode-line constructs:
1591 @cindex percent symbol in mode line
1593 A string as a mode-line construct appears verbatim in the mode line
1594 except for @dfn{@code{%}-constructs} in it. These stand for
1595 substitution of other data; see @ref{%-Constructs}.
1597 If the string has @code{face} properties, they are copied into the
1598 mode line contents too (@pxref{Properties in Mode}). Any characters
1599 in the mode line which have no @code{face} properties are displayed,
1600 by default, in the face @code{mode-line} or @code{mode-line-inactive}
1601 (@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}).
1604 A symbol as a mode-line construct stands for its value. The value of
1605 @var{symbol} is used as a mode-line construct, in place of @var{symbol}.
1606 However, the symbols @code{t} and @code{nil} are ignored, as is any
1607 symbol whose value is void.
1609 There is one exception: if the value of @var{symbol} is a string, it is
1610 displayed verbatim: the @code{%}-constructs are not recognized.
1612 Unless @var{symbol} is marked as ``risky'' (i.e., it has a
1613 non-@code{nil} @code{risky-local-variable} property), all text
1614 properties specified in @var{symbol}'s value are ignored. This
1615 includes the text properties of strings in @var{symbol}'s value, as
1616 well as all @code{:eval} and @code{:propertize} forms in it.
1618 @item (@var{string} @var{rest}@dots{})
1619 @itemx (@var{list} @var{rest}@dots{})
1620 A list whose first element is a string or list means to process all the
1621 elements recursively and concatenate the results. This is the most
1622 common form of mode-line construct.
1624 @item (:eval @var{form})
1625 A list whose first element is the symbol @code{:eval} says to evaluate
1626 @var{form}, and use the result as a string to display. Make sure this
1627 evaluation cannot load any files, as doing so could cause infinite
1630 @item (:propertize @var{elt} @var{props}@dots{})
1631 A list whose first element is the symbol @code{:propertize} says to
1632 process the mode-line construct @var{elt} recursively, then add the text
1633 properties specified by @var{props} to the result. The argument
1634 @var{props} should consist of zero or more pairs @var{text-property}
1635 @var{value}. (This feature is new as of Emacs 22.1.)
1637 @item (@var{symbol} @var{then} @var{else})
1638 A list whose first element is a symbol that is not a keyword specifies
1639 a conditional. Its meaning depends on the value of @var{symbol}. If
1640 @var{symbol} has a non-@code{nil} value, the second element,
1641 @var{then}, is processed recursively as a mode-line element.
1642 Otherwise, the third element, @var{else}, is processed recursively.
1643 You may omit @var{else}; then the mode-line element displays nothing
1644 if the value of @var{symbol} is @code{nil} or void.
1646 @item (@var{width} @var{rest}@dots{})
1647 A list whose first element is an integer specifies truncation or
1648 padding of the results of @var{rest}. The remaining elements
1649 @var{rest} are processed recursively as mode-line constructs and
1650 concatenated together. When @var{width} is positive, the result is
1651 space filled on the right if its width is less than @var{width}. When
1652 @var{width} is negative, the result is truncated on the right to
1653 @minus{}@var{width} columns if its width exceeds @minus{}@var{width}.
1655 For example, the usual way to show what percentage of a buffer is above
1656 the top of the window is to use a list like this: @code{(-3 "%p")}.
1660 @subsection The Top Level of Mode Line Control
1662 The variable in overall control of the mode line is
1663 @code{mode-line-format}.
1665 @defvar mode-line-format
1666 The value of this variable is a mode-line construct that controls the
1667 contents of the mode-line. It is always buffer-local in all buffers.
1669 If you set this variable to @code{nil} in a buffer, that buffer does
1670 not have a mode line. (A window that is just one line tall never
1671 displays a mode line.)
1674 The default value of @code{mode-line-format} is designed to use the
1675 values of other variables such as @code{mode-line-position} and
1676 @code{mode-line-modes} (which in turn incorporates the values of the
1677 variables @code{mode-name} and @code{minor-mode-alist}). Very few
1678 modes need to alter @code{mode-line-format} itself. For most
1679 purposes, it is sufficient to alter some of the variables that
1680 @code{mode-line-format} either directly or indirectly refers to.
1682 If you do alter @code{mode-line-format} itself, the new value should
1683 use the same variables that appear in the default value (@pxref{Mode
1684 Line Variables}), rather than duplicating their contents or displaying
1685 the information in another fashion. This way, customizations made by
1686 the user or by Lisp programs (such as @code{display-time} and major
1687 modes) via changes to those variables remain effective.
1689 @cindex Shell mode @code{mode-line-format}
1690 Here is an example of a @code{mode-line-format} that might be
1691 useful for @code{shell-mode}, since it contains the host name and default
1696 (setq mode-line-format
1698 'mode-line-mule-info
1700 'mode-line-frame-identification
1704 ;; @r{Note that this is evaluated while making the list.}
1705 ;; @r{It makes a mode-line construct which is just a string.}
1713 '(:eval (mode-line-mode-name))
1719 '(which-func-mode ("" which-func-format "--"))
1720 '(line-number-mode "L%l--")
1721 '(column-number-mode "C%c--")
1728 (The variables @code{line-number-mode}, @code{column-number-mode}
1729 and @code{which-func-mode} enable particular minor modes; as usual,
1730 these variable names are also the minor mode command names.)
1732 @node Mode Line Variables
1733 @subsection Variables Used in the Mode Line
1735 This section describes variables incorporated by the standard value
1736 of @code{mode-line-format} into the text of the mode line. There is
1737 nothing inherently special about these variables; any other variables
1738 could have the same effects on the mode line if
1739 @code{mode-line-format}'s value were changed to use them. However,
1740 various parts of Emacs set these variables on the understanding that
1741 they will control parts of the mode line; therefore, practically
1742 speaking, it is essential for the mode line to use them.
1744 @defvar mode-line-mule-info
1745 This variable holds the value of the mode-line construct that displays
1746 information about the language environment, buffer coding system, and
1747 current input method. @xref{Non-ASCII Characters}.
1750 @defvar mode-line-modified
1751 This variable holds the value of the mode-line construct that displays
1752 whether the current buffer is modified.
1754 The default value of @code{mode-line-modified} is @code{("%1*%1+")}.
1755 This means that the mode line displays @samp{**} if the buffer is
1756 modified, @samp{--} if the buffer is not modified, @samp{%%} if the
1757 buffer is read only, and @samp{%*} if the buffer is read only and
1760 Changing this variable does not force an update of the mode line.
1763 @defvar mode-line-frame-identification
1764 This variable identifies the current frame. The default value is
1765 @code{" "} if you are using a window system which can show multiple
1766 frames, or @code{"-%F "} on an ordinary terminal which shows only one
1770 @defvar mode-line-buffer-identification
1771 This variable identifies the buffer being displayed in the window. Its
1772 default value is @code{("%12b")}, which displays the buffer name, padded
1773 with spaces to at least 12 columns.
1776 @defvar mode-line-position
1777 This variable indicates the position in the buffer. Here is a
1778 simplified version of its default value. The actual default value
1779 also specifies addition of the @code{help-echo} text property.
1784 (size-indication-mode (8 " of %I"))
1788 ((column-number-mode
1791 ((column-number-mode
1796 This means that @code{mode-line-position} displays at least the buffer
1797 percentage and possibly the buffer size, the line number and the column
1802 The variable @code{vc-mode}, buffer-local in each buffer, records
1803 whether the buffer's visited file is maintained with version control,
1804 and, if so, which kind. Its value is a string that appears in the mode
1805 line, or @code{nil} for no version control.
1808 @defvar mode-line-modes
1809 This variable displays the buffer's major and minor modes. Here is a
1810 simplified version of its default value. The real default value also
1811 specifies addition of text properties.
1816 mode-line-process minor-mode-alist
1821 So @code{mode-line-modes} normally also displays the recursive editing
1822 level, information on the process status and whether narrowing is in
1826 The following three variables are used in @code{mode-line-modes}:
1829 This buffer-local variable holds the ``pretty'' name of the current
1830 buffer's major mode. Each major mode should set this variable so that the
1831 mode name will appear in the mode line.
1834 @defvar mode-line-process
1835 This buffer-local variable contains the mode-line information on process
1836 status in modes used for communicating with subprocesses. It is
1837 displayed immediately following the major mode name, with no intervening
1838 space. For example, its value in the @samp{*shell*} buffer is
1839 @code{(":%s")}, which allows the shell to display its status along
1840 with the major mode as: @samp{(Shell:run)}. Normally this variable
1844 @defvar minor-mode-alist
1845 @anchor{Definition of minor-mode-alist}
1846 This variable holds an association list whose elements specify how the
1847 mode line should indicate that a minor mode is active. Each element of
1848 the @code{minor-mode-alist} should be a two-element list:
1851 (@var{minor-mode-variable} @var{mode-line-string})
1854 More generally, @var{mode-line-string} can be any mode-line spec. It
1855 appears in the mode line when the value of @var{minor-mode-variable}
1856 is non-@code{nil}, and not otherwise. These strings should begin with
1857 spaces so that they don't run together. Conventionally, the
1858 @var{minor-mode-variable} for a specific mode is set to a
1859 non-@code{nil} value when that minor mode is activated.
1861 @code{minor-mode-alist} itself is not buffer-local. Each variable
1862 mentioned in the alist should be buffer-local if its minor mode can be
1863 enabled separately in each buffer.
1866 @defvar global-mode-string
1867 This variable holds a mode-line spec that, by default, appears in the
1868 mode line just after the @code{which-func-mode} minor mode if set,
1869 else after @code{mode-line-modes}. The command @code{display-time}
1870 sets @code{global-mode-string} to refer to the variable
1871 @code{display-time-string}, which holds a string containing the time
1872 and load information.
1874 The @samp{%M} construct substitutes the value of
1875 @code{global-mode-string}, but that is obsolete, since the variable is
1876 included in the mode line from @code{mode-line-format}.
1879 The variable @code{default-mode-line-format} is where
1880 @code{mode-line-format} usually gets its value:
1882 @defvar default-mode-line-format
1883 This variable holds the default @code{mode-line-format} for buffers
1884 that do not override it. This is the same as @code{(default-value
1885 'mode-line-format)}.
1887 Here is a simplified version of the default value of
1888 @code{default-mode-line-format}. The real default value also
1889 specifies addition of text properties.
1896 mode-line-frame-identification
1897 mode-line-buffer-identification
1905 (which-func-mode ("" which-func-format "--"))
1906 (global-mode-string ("--" global-mode-string))
1913 @subsection @code{%}-Constructs in the Mode Line
1915 Strings used as mode-line constructs can use certain
1916 @code{%}-constructs to substitute various kinds of data. Here is a
1917 list of the defined @code{%}-constructs, and what they mean. In any
1918 construct except @samp{%%}, you can add a decimal integer after the
1919 @samp{%} to specify a minimum field width. If the width is less, the
1920 field is padded with spaces to the right.
1924 The current buffer name, obtained with the @code{buffer-name} function.
1925 @xref{Buffer Names}.
1928 The current column number of point.
1931 The visited file name, obtained with the @code{buffer-file-name}
1932 function. @xref{Buffer File Name}.
1935 The title (only on a window system) or the name of the selected frame.
1936 @xref{Basic Parameters}.
1939 The size of the accessible part of the current buffer; basically
1940 @code{(- (point-max) (point-min))}.
1943 Like @samp{%i}, but the size is printed in a more readable way by using
1944 @samp{k} for 10^3, @samp{M} for 10^6, @samp{G} for 10^9, etc., to
1948 The current line number of point, counting within the accessible portion
1952 @samp{Narrow} when narrowing is in effect; nothing otherwise (see
1953 @code{narrow-to-region} in @ref{Narrowing}).
1956 The percentage of the buffer text above the @strong{top} of window, or
1957 @samp{Top}, @samp{Bottom} or @samp{All}. Note that the default
1958 mode-line specification truncates this to three characters.
1961 The percentage of the buffer text that is above the @strong{bottom} of
1962 the window (which includes the text visible in the window, as well as
1963 the text above the top), plus @samp{Top} if the top of the buffer is
1964 visible on screen; or @samp{Bottom} or @samp{All}.
1967 The status of the subprocess belonging to the current buffer, obtained with
1968 @code{process-status}. @xref{Process Information}.
1971 Whether the visited file is a text file or a binary file. This is a
1972 meaningful distinction only on certain operating systems (@pxref{MS-DOS
1976 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
1977 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
1978 @samp{-} otherwise. @xref{Buffer Modification}.
1981 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
1982 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
1983 @samp{-} otherwise. This differs from @samp{%*} only for a modified
1984 read-only buffer. @xref{Buffer Modification}.
1987 @samp{*} if the buffer is modified, and @samp{-} otherwise.
1990 An indication of the depth of recursive editing levels (not counting
1991 minibuffer levels): one @samp{[} for each editing level.
1992 @xref{Recursive Editing}.
1995 One @samp{]} for each recursive editing level (not counting minibuffer
1999 Dashes sufficient to fill the remainder of the mode line.
2002 The character @samp{%}---this is how to include a literal @samp{%} in a
2003 string in which @code{%}-constructs are allowed.
2006 The following two @code{%}-constructs are still supported, but they are
2007 obsolete, since you can get the same results with the variables
2008 @code{mode-name} and @code{global-mode-string}.
2012 The value of @code{mode-name}.
2015 The value of @code{global-mode-string}.
2018 @node Properties in Mode
2019 @subsection Properties in the Mode Line
2020 @cindex text properties in the mode line
2022 Certain text properties are meaningful in the
2023 mode line. The @code{face} property affects the appearance of text; the
2024 @code{help-echo} property associates help strings with the text, and
2025 @code{local-map} can make the text mouse-sensitive.
2027 There are four ways to specify text properties for text in the mode
2032 Put a string with a text property directly into the mode-line data
2036 Put a text property on a mode-line %-construct such as @samp{%12b}; then
2037 the expansion of the %-construct will have that same text property.
2040 Use a @code{(:propertize @var{elt} @var{props}@dots{})} construct to
2041 give @var{elt} a text property specified by @var{props}.
2044 Use a list containing @code{:eval @var{form}} in the mode-line data
2045 structure, and make @var{form} evaluate to a string that has a text
2049 You use the @code{local-map} property to specify a keymap. Like any
2050 keymap, it can bind character keys and function keys; but that has no
2051 effect, since it is impossible to move point into the mode line. This
2052 keymap can only take real effect for mouse clicks.
2054 When the mode line refers to a variable which does not have a
2055 non-@code{nil} @code{risky-local-variable} property, any text
2056 properties given or specified within that variable's values are
2057 ignored. This is because such properties could otherwise specify
2058 functions to be called, and those functions could come from file
2062 @subsection Window Header Lines
2063 @cindex header line (of a window)
2064 @cindex window header line
2066 A window can have a @dfn{header line} at the
2067 top, just as it can have a mode line at the bottom. The header line
2068 feature works just like the mode-line feature, except that it's
2069 controlled by different variables.
2071 @tindex header-line-format
2072 @defvar header-line-format
2073 This variable, local in every buffer, specifies how to display the
2074 header line, for windows displaying the buffer. The format of the value
2075 is the same as for @code{mode-line-format} (@pxref{Mode Line Data}).
2078 @tindex default-header-line-format
2079 @defvar default-header-line-format
2080 This variable holds the default @code{header-line-format} for buffers
2081 that do not override it. This is the same as @code{(default-value
2082 'header-line-format)}.
2084 It is normally @code{nil}, so that ordinary buffers have no header line.
2087 A window that is just one line tall never displays a header line. A
2088 window that is two lines tall cannot display both a mode line and a
2089 header line at once; if it has a mode line, then it does not display a
2092 @node Emulating Mode Line
2093 @subsection Emulating Mode-Line Formatting
2095 You can use the function @code{format-mode-line} to compute
2096 the text that would appear in a mode line or header line
2097 based on a certain mode-line specification.
2099 @defun format-mode-line format &optional face window buffer
2100 This function formats a line of text according to @var{format} as if
2101 it were generating the mode line for @var{window}, but instead of
2102 displaying the text in the mode line or the header line, it returns
2103 the text as a string. The argument @var{window} defaults to the
2104 selected window. If @var{buffer} is non-@code{nil}, all the
2105 information used is taken from @var{buffer}; by default, it comes from
2106 @var{window}'s buffer.
2108 The value string normally has text properties that correspond to the
2109 faces, keymaps, etc., that the mode line would have. And any character
2110 for which no @code{face} property is specified gets a default
2111 value which is usually @var{face}. (If @var{face} is @code{t},
2112 that stands for either @code{mode-line} if @var{window} is selected,
2113 otherwise @code{mode-line-inactive}. If @var{face} is @code{nil} or
2114 omitted, that stands for no face property.)
2116 However, if @var{face} is an integer, the value has no text properties.
2118 For example, @code{(format-mode-line header-line-format)} returns the
2119 text that would appear in the selected window's header line (@code{""}
2120 if it has no header line). @code{(format-mode-line header-line-format
2121 'header-line)} returns the same text, with each character
2122 carrying the face that it will have in the header line itself.
2129 @dfn{Imenu} is a feature that lets users select a definition or
2130 section in the buffer, from a menu which lists all of them, to go
2131 directly to that location in the buffer. Imenu works by constructing
2132 a buffer index which lists the names and buffer positions of the
2133 definitions, or other named portions of the buffer; then the user can
2134 choose one of them and move point to it. Major modes can add a menu
2135 bar item to use Imenu using @code{imenu-add-to-menubar}.
2137 @defun imenu-add-to-menubar name
2138 This function defines a local menu bar item named @var{name}
2142 The user-level commands for using Imenu are described in the Emacs
2143 Manual (@pxref{Imenu,, Imenu, emacs, the Emacs Manual}). This section
2144 explains how to customize Imenu's method of finding definitions or
2145 buffer portions for a particular major mode.
2147 The usual and simplest way is to set the variable
2148 @code{imenu-generic-expression}:
2150 @defvar imenu-generic-expression
2151 This variable, if non-@code{nil}, is a list that specifies regular
2152 expressions for finding definitions for Imenu. Simple elements of
2153 @code{imenu-generic-expression} look like this:
2156 (@var{menu-title} @var{regexp} @var{index})
2159 Here, if @var{menu-title} is non-@code{nil}, it says that the matches
2160 for this element should go in a submenu of the buffer index;
2161 @var{menu-title} itself specifies the name for the submenu. If
2162 @var{menu-title} is @code{nil}, the matches for this element go directly
2163 in the top level of the buffer index.
2165 The second item in the list, @var{regexp}, is a regular expression
2166 (@pxref{Regular Expressions}); anything in the buffer that it matches
2167 is considered a definition, something to mention in the buffer index.
2168 The third item, @var{index}, is a non-negative integer that indicates
2169 which subexpression in @var{regexp} matches the definition's name.
2171 An element can also look like this:
2174 (@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{})
2177 Like in the previous case, each match for this element creates an
2178 index item. However, if this index item is selected by the user, it
2179 calls @var{function} with arguments consisting of the item name, the
2180 buffer position, and @var{arguments}.
2182 For Emacs Lisp mode, @code{imenu-generic-expression} could look like
2185 @c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]
2188 ((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
2189 \\s-+\\([-A-Za-z0-9+]+\\)" 2)
2192 ("*Vars*" "^\\s-*(def\\(var\\|const\\)\
2193 \\s-+\\([-A-Za-z0-9+]+\\)" 2)
2198 (def\\(type\\|struct\\|class\\|ine-condition\\)\
2199 \\s-+\\([-A-Za-z0-9+]+\\)" 2))
2203 Setting this variable makes it buffer-local in the current buffer.
2206 @defvar imenu-case-fold-search
2207 This variable controls whether matching against the regular
2208 expressions in the value of @code{imenu-generic-expression} is
2209 case-sensitive: @code{t}, the default, means matching should ignore
2212 Setting this variable makes it buffer-local in the current buffer.
2215 @defvar imenu-syntax-alist
2216 This variable is an alist of syntax table modifiers to use while
2217 processing @code{imenu-generic-expression}, to override the syntax table
2218 of the current buffer. Each element should have this form:
2221 (@var{characters} . @var{syntax-description})
2224 The @sc{car}, @var{characters}, can be either a character or a string.
2225 The element says to give that character or characters the syntax
2226 specified by @var{syntax-description}, which is passed to
2227 @code{modify-syntax-entry} (@pxref{Syntax Table Functions}).
2229 This feature is typically used to give word syntax to characters which
2230 normally have symbol syntax, and thus to simplify
2231 @code{imenu-generic-expression} and speed up matching.
2232 For example, Fortran mode uses it this way:
2235 (setq imenu-syntax-alist '(("_$" . "w")))
2238 The @code{imenu-generic-expression} regular expressions can then use
2239 @samp{\\sw+} instead of @samp{\\(\\sw\\|\\s_\\)+}. Note that this
2240 technique may be inconvenient when the mode needs to limit the initial
2241 character of a name to a smaller set of characters than are allowed in
2244 Setting this variable makes it buffer-local in the current buffer.
2247 Another way to customize Imenu for a major mode is to set the
2248 variables @code{imenu-prev-index-position-function} and
2249 @code{imenu-extract-index-name-function}:
2251 @defvar imenu-prev-index-position-function
2252 If this variable is non-@code{nil}, its value should be a function that
2253 finds the next ``definition'' to put in the buffer index, scanning
2254 backward in the buffer from point. It should return @code{nil} if it
2255 doesn't find another ``definition'' before point. Otherwise it should
2256 leave point at the place it finds a ``definition'' and return any
2257 non-@code{nil} value.
2259 Setting this variable makes it buffer-local in the current buffer.
2262 @defvar imenu-extract-index-name-function
2263 If this variable is non-@code{nil}, its value should be a function to
2264 return the name for a definition, assuming point is in that definition
2265 as the @code{imenu-prev-index-position-function} function would leave
2268 Setting this variable makes it buffer-local in the current buffer.
2271 The last way to customize Imenu for a major mode is to set the
2272 variable @code{imenu-create-index-function}:
2274 @defvar imenu-create-index-function
2275 This variable specifies the function to use for creating a buffer
2276 index. The function should take no arguments, and return an index
2277 alist for the current buffer. It is called within
2278 @code{save-excursion}, so where it leaves point makes no difference.
2280 The index alist can have three types of elements. Simple elements
2284 (@var{index-name} . @var{index-position})
2287 Selecting a simple element has the effect of moving to position
2288 @var{index-position} in the buffer. Special elements look like this:
2291 (@var{index-name} @var{index-position} @var{function} @var{arguments}@dots{})
2294 Selecting a special element performs:
2297 (funcall @var{function}
2298 @var{index-name} @var{index-position} @var{arguments}@dots{})
2301 A nested sub-alist element looks like this:
2304 (@var{menu-title} @var{sub-alist})
2307 It creates the submenu @var{menu-title} specified by @var{sub-alist}.
2309 The default value of @code{imenu-create-index-function} is
2310 @code{imenu-default-create-index-function}. This function calls the
2311 value of @code{imenu-prev-index-position-function} and the value of
2312 @code{imenu-extract-index-name-function} to produce the index alist.
2313 However, if either of these two variables is @code{nil}, the default
2314 function uses @code{imenu-generic-expression} instead.
2316 Setting this variable makes it buffer-local in the current buffer.
2319 @node Font Lock Mode
2320 @section Font Lock Mode
2321 @cindex Font Lock Mode
2323 @dfn{Font Lock mode} is a feature that automatically attaches
2324 @code{face} properties to certain parts of the buffer based on their
2325 syntactic role. How it parses the buffer depends on the major mode;
2326 most major modes define syntactic criteria for which faces to use in
2327 which contexts. This section explains how to customize Font Lock for a
2328 particular major mode.
2330 Font Lock mode finds text to highlight in two ways: through
2331 syntactic parsing based on the syntax table, and through searching
2332 (usually for regular expressions). Syntactic fontification happens
2333 first; it finds comments and string constants and highlights them.
2334 Search-based fontification happens second.
2337 * Font Lock Basics:: Overview of customizing Font Lock.
2338 * Search-based Fontification:: Fontification based on regexps.
2339 * Customizing Keywords:: Customizing search-based fontification.
2340 * Region to Fontify:: Controlling which region gets refontified
2341 after a buffer change.
2342 * Other Font Lock Variables:: Additional customization facilities.
2343 * Levels of Font Lock:: Each mode can define alternative levels
2344 so that the user can select more or less.
2345 * Precalculated Fontification:: How Lisp programs that produce the buffer
2346 contents can also specify how to fontify it.
2347 * Faces for Font Lock:: Special faces specifically for Font Lock.
2348 * Syntactic Font Lock:: Fontification based on syntax tables.
2349 * Setting Syntax Properties:: Defining character syntax based on context
2350 using the Font Lock mechanism.
2353 @node Font Lock Basics
2354 @subsection Font Lock Basics
2356 There are several variables that control how Font Lock mode highlights
2357 text. But major modes should not set any of these variables directly.
2358 Instead, they should set @code{font-lock-defaults} as a buffer-local
2359 variable. The value assigned to this variable is used, if and when Font
2360 Lock mode is enabled, to set all the other variables.
2362 @defvar font-lock-defaults
2363 This variable is set by major modes, as a buffer-local variable, to
2364 specify how to fontify text in that mode. It automatically becomes
2365 buffer-local when you set it. The value should look like this:
2368 (@var{keywords} [@var{keywords-only} [@var{case-fold}
2369 [@var{syntax-alist} [@var{syntax-begin} @var{other-vars}@dots{}]]]])
2372 The first element, @var{keywords}, indirectly specifies the value of
2373 @code{font-lock-keywords} which directs search-based fontification.
2374 It can be a symbol, a variable or a function whose value is the list
2375 to use for @code{font-lock-keywords}. It can also be a list of
2376 several such symbols, one for each possible level of fontification.
2377 The first symbol specifies how to do level 1 fontification, the second
2378 symbol how to do level 2, and so on. @xref{Levels of Font Lock}.
2380 The second element, @var{keywords-only}, specifies the value of the
2381 variable @code{font-lock-keywords-only}. If this is non-@code{nil},
2382 syntactic fontification (of strings and comments) is not performed.
2383 @xref{Syntactic Font Lock}.
2385 The third element, @var{case-fold}, specifies the value of
2386 @code{font-lock-keywords-case-fold-search}. If it is non-@code{nil},
2387 Font Lock mode ignores case when searching as directed by
2388 @code{font-lock-keywords}.
2390 If the fourth element, @var{syntax-alist}, is non-@code{nil}, it
2391 should be a list of cons cells of the form @code{(@var{char-or-string}
2392 . @var{string})}. These are used to set up a syntax table for
2393 syntactic fontification (@pxref{Syntax Table Functions}). The
2394 resulting syntax table is stored in @code{font-lock-syntax-table}.
2396 The fifth element, @var{syntax-begin}, specifies the value of
2397 @code{font-lock-beginning-of-syntax-function}. We recommend setting
2398 this variable to @code{nil} and using @code{syntax-begin-function}
2401 All the remaining elements (if any) are collectively called
2402 @var{other-vars}. Each of these elements should have the form
2403 @code{(@var{variable} . @var{value})}---which means, make
2404 @var{variable} buffer-local and then set it to @var{value}. You can
2405 use these @var{other-vars} to set other variables that affect
2406 fontification, aside from those you can control with the first five
2407 elements. @xref{Other Font Lock Variables}.
2410 @node Search-based Fontification
2411 @subsection Search-based Fontification
2413 The most important variable for customizing Font Lock mode is
2414 @code{font-lock-keywords}. It specifies the search criteria for
2415 search-based fontification. You should specify the value of this
2416 variable with @var{keywords} in @code{font-lock-defaults}.
2418 @defvar font-lock-keywords
2419 This variable's value is a list of the keywords to highlight. Be
2420 careful when composing regular expressions for this list; a poorly
2421 written pattern can dramatically slow things down!
2424 Each element of @code{font-lock-keywords} specifies how to find
2425 certain cases of text, and how to highlight those cases. Font Lock mode
2426 processes the elements of @code{font-lock-keywords} one by one, and for
2427 each element, it finds and handles all matches. Ordinarily, once
2428 part of the text has been fontified already, this cannot be overridden
2429 by a subsequent match in the same text; but you can specify different
2430 behavior using the @var{override} element of a @var{subexp-highlighter}.
2432 Each element of @code{font-lock-keywords} should have one of these
2437 Highlight all matches for @var{regexp} using
2438 @code{font-lock-keyword-face}. For example,
2441 ;; @r{Highlight occurrences of the word @samp{foo}}
2442 ;; @r{using @code{font-lock-keyword-face}.}
2446 The function @code{regexp-opt} (@pxref{Regexp Functions}) is useful
2447 for calculating optimal regular expressions to match a number of
2450 @item @var{function}
2451 Find text by calling @var{function}, and highlight the matches
2452 it finds using @code{font-lock-keyword-face}.
2454 When @var{function} is called, it receives one argument, the limit of
2455 the search; it should begin searching at point, and not search beyond the
2456 limit. It should return non-@code{nil} if it succeeds, and set the
2457 match data to describe the match that was found. Returning @code{nil}
2458 indicates failure of the search.
2460 Fontification will call @var{function} repeatedly with the same limit,
2461 and with point where the previous invocation left it, until
2462 @var{function} fails. On failure, @var{function} need not reset point
2463 in any particular way.
2465 @item (@var{matcher} . @var{subexp})
2466 In this kind of element, @var{matcher} is either a regular
2467 expression or a function, as described above. The @sc{cdr},
2468 @var{subexp}, specifies which subexpression of @var{matcher} should be
2469 highlighted (instead of the entire text that @var{matcher} matched).
2472 ;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},}
2473 ;; @r{using @code{font-lock-keyword-face}.}
2477 If you use @code{regexp-opt} to produce the regular expression
2478 @var{matcher}, you can use @code{regexp-opt-depth} (@pxref{Regexp
2479 Functions}) to calculate the value for @var{subexp}.
2481 @item (@var{matcher} . @var{facespec})
2482 In this kind of element, @var{facespec} is an expression whose value
2483 specifies the face to use for highlighting. In the simplest case,
2484 @var{facespec} is a Lisp variable (a symbol) whose value is a face
2488 ;; @r{Highlight occurrences of @samp{fubar},}
2489 ;; @r{using the face which is the value of @code{fubar-face}.}
2490 ("fubar" . fubar-face)
2493 However, @var{facespec} can also evaluate to a list of this form:
2496 (face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{})
2500 to specify the face @var{face} and various additional text properties
2501 to put on the text that matches. If you do this, be sure to add the
2502 other text property names that you set in this way to the value of
2503 @code{font-lock-extra-managed-props} so that the properties will also
2504 be cleared out when they are no longer appropriate. Alternatively,
2505 you can set the variable @code{font-lock-unfontify-region-function} to
2506 a function that clears these properties. @xref{Other Font Lock
2509 @item (@var{matcher} . @var{subexp-highlighter})
2510 In this kind of element, @var{subexp-highlighter} is a list
2511 which specifies how to highlight matches found by @var{matcher}.
2515 (@var{subexp} @var{facespec} [[@var{override} [@var{laxmatch}]])
2518 The @sc{car}, @var{subexp}, is an integer specifying which subexpression
2519 of the match to fontify (0 means the entire matching text). The second
2520 subelement, @var{facespec}, is an expression whose value specifies the
2521 face, as described above.
2523 The last two values in @var{subexp-highlighter}, @var{override} and
2524 @var{laxmatch}, are optional flags. If @var{override} is @code{t},
2525 this element can override existing fontification made by previous
2526 elements of @code{font-lock-keywords}. If it is @code{keep}, then
2527 each character is fontified if it has not been fontified already by
2528 some other element. If it is @code{prepend}, the face specified by
2529 @var{facespec} is added to the beginning of the @code{font-lock-face}
2530 property. If it is @code{append}, the face is added to the end of the
2531 @code{font-lock-face} property.
2533 If @var{laxmatch} is non-@code{nil}, it means there should be no error
2534 if there is no subexpression numbered @var{subexp} in @var{matcher}.
2535 Obviously, fontification of the subexpression numbered @var{subexp} will
2536 not occur. However, fontification of other subexpressions (and other
2537 regexps) will continue. If @var{laxmatch} is @code{nil}, and the
2538 specified subexpression is missing, then an error is signaled which
2539 terminates search-based fontification.
2541 Here are some examples of elements of this kind, and what they do:
2544 ;; @r{Highlight occurrences of either @samp{foo} or @samp{bar}, using}
2545 ;; @r{@code{foo-bar-face}, even if they have already been highlighted.}
2546 ;; @r{@code{foo-bar-face} should be a variable whose value is a face.}
2547 ("foo\\|bar" 0 foo-bar-face t)
2549 ;; @r{Highlight the first subexpression within each occurrence}
2550 ;; @r{that the function @code{fubar-match} finds,}
2551 ;; @r{using the face which is the value of @code{fubar-face}.}
2552 (fubar-match 1 fubar-face)
2555 @item (@var{matcher} . @var{anchored-highlighter})
2556 In this kind of element, @var{anchored-highlighter} specifies how to
2557 highlight text that follows a match found by @var{matcher}. So a
2558 match found by @var{matcher} acts as the anchor for further searches
2559 specified by @var{anchored-highlighter}. @var{anchored-highlighter}
2560 is a list of the following form:
2563 (@var{anchored-matcher} @var{pre-form} @var{post-form}
2564 @var{subexp-highlighters}@dots{})
2567 Here, @var{anchored-matcher}, like @var{matcher}, is either a regular
2568 expression or a function. After a match of @var{matcher} is found,
2569 point is at the end of the match. Now, Font Lock evaluates the form
2570 @var{pre-form}. Then it searches for matches of
2571 @var{anchored-matcher} and uses @var{subexp-highlighters} to highlight
2572 these. A @var{subexp-highlighter} is as described above. Finally,
2573 Font Lock evaluates @var{post-form}.
2575 The forms @var{pre-form} and @var{post-form} can be used to initialize
2576 before, and cleanup after, @var{anchored-matcher} is used. Typically,
2577 @var{pre-form} is used to move point to some position relative to the
2578 match of @var{matcher}, before starting with @var{anchored-matcher}.
2579 @var{post-form} might be used to move back, before resuming with
2582 After Font Lock evaluates @var{pre-form}, it does not search for
2583 @var{anchored-matcher} beyond the end of the line. However, if
2584 @var{pre-form} returns a buffer position that is greater than the
2585 position of point after @var{pre-form} is evaluated, then the position
2586 returned by @var{pre-form} is used as the limit of the search instead.
2587 It is generally a bad idea to return a position greater than the end
2588 of the line; in other words, the @var{anchored-matcher} search should
2594 ;; @r{Highlight occurrences of the word @samp{item} following}
2595 ;; @r{an occurrence of the word @samp{anchor} (on the same line)}
2596 ;; @r{in the value of @code{item-face}.}
2597 ("\\<anchor\\>" "\\<item\\>" nil nil (0 item-face))
2600 Here, @var{pre-form} and @var{post-form} are @code{nil}. Therefore
2601 searching for @samp{item} starts at the end of the match of
2602 @samp{anchor}, and searching for subsequent instances of @samp{anchor}
2603 resumes from where searching for @samp{item} concluded.
2605 @item (@var{matcher} @var{highlighters}@dots{})
2606 This sort of element specifies several @var{highlighter} lists for a
2607 single @var{matcher}. A @var{highlighter} list can be of the type
2608 @var{subexp-highlighter} or @var{anchored-highlighter} as described
2614 ;; @r{Highlight occurrences of the word @samp{anchor} in the value}
2615 ;; @r{of @code{anchor-face}, and subsequent occurrences of the word}
2616 ;; @r{@samp{item} (on the same line) in the value of @code{item-face}.}
2617 ("\\<anchor\\>" (0 anchor-face)
2618 ("\\<item\\>" nil nil (0 item-face)))
2621 @item (eval . @var{form})
2622 Here @var{form} is an expression to be evaluated the first time
2623 this value of @code{font-lock-keywords} is used in a buffer.
2624 Its value should have one of the forms described in this table.
2627 @vindex font-lock-multiline
2628 @strong{Warning:} Do not design an element of @code{font-lock-keywords}
2629 to match text which spans lines; this does not work reliably. While
2630 @code{font-lock-fontify-buffer} handles multi-line patterns correctly,
2631 updating when you edit the buffer does not, since it considers text one
2632 line at a time. If you have patterns that typically only span one
2633 line but can occasionally span two or three, such as
2634 @samp{<title>...</title>}, you can ask Font Lock to be more careful by
2635 setting @code{font-lock-multiline} to @code{t}. But it still will not
2638 You can use @var{case-fold} in @code{font-lock-defaults} to specify
2639 the value of @code{font-lock-keywords-case-fold-search} which says
2640 whether search-based fontification should be case-insensitive.
2642 @defvar font-lock-keywords-case-fold-search
2643 Non-@code{nil} means that regular expression matching for the sake of
2644 @code{font-lock-keywords} should be case-insensitive.
2647 @node Customizing Keywords
2648 @subsection Customizing Search-Based Fontification
2650 You can use @code{font-lock-add-keywords} to add additional
2651 search-based fontification rules to a major mode, and
2652 @code{font-lock-remove-keywords} to removes rules.
2654 @defun font-lock-add-keywords mode keywords &optional how
2655 This function adds highlighting @var{keywords}, for the current buffer
2656 or for major mode @var{mode}. The argument @var{keywords} should be a
2657 list with the same format as the variable @code{font-lock-keywords}.
2659 If @var{mode} is a symbol which is a major mode command name, such as
2660 @code{c-mode}, the effect is that enabling Font Lock mode in
2661 @var{mode} will add @var{keywords} to @code{font-lock-keywords}.
2662 Calling with a non-@code{nil} value of @var{mode} is correct only in
2663 your @file{~/.emacs} file.
2665 If @var{mode} is @code{nil}, this function adds @var{keywords} to
2666 @code{font-lock-keywords} in the current buffer. This way of calling
2667 @code{font-lock-add-keywords} is usually used in mode hook functions.
2669 By default, @var{keywords} are added at the beginning of
2670 @code{font-lock-keywords}. If the optional argument @var{how} is
2671 @code{set}, they are used to replace the value of
2672 @code{font-lock-keywords}. If @var{how} is any other non-@code{nil}
2673 value, they are added at the end of @code{font-lock-keywords}.
2675 Some modes provide specialized support you can use in additional
2676 highlighting patterns. See the variables
2677 @code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types},
2678 and @code{java-font-lock-extra-types}, for example.
2680 @strong{Warning:} major mode functions must not call
2681 @code{font-lock-add-keywords} under any circumstances, either directly
2682 or indirectly, except through their mode hooks. (Doing so would lead
2683 to incorrect behavior for some minor modes.) They should set up their
2684 rules for search-based fontification by setting
2685 @code{font-lock-keywords}.
2688 @defun font-lock-remove-keywords mode keywords
2689 This function removes @var{keywords} from @code{font-lock-keywords}
2690 for the current buffer or for major mode @var{mode}. As in
2691 @code{font-lock-add-keywords}, @var{mode} should be a major mode
2692 command name or @code{nil}. All the caveats and requirements for
2693 @code{font-lock-add-keywords} apply here too.
2696 For example, this code
2699 (font-lock-add-keywords 'c-mode
2700 '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
2701 ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face)))
2705 adds two fontification patterns for C mode: one to fontify the word
2706 @samp{FIXME}, even in comments, and another to fontify the words
2707 @samp{and}, @samp{or} and @samp{not} as keywords.
2710 That example affects only C mode proper. To add the same patterns to
2711 C mode @emph{and} all modes derived from it, do this instead:
2714 (add-hook 'c-mode-hook
2716 (font-lock-add-keywords nil
2717 '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
2718 ("\\<\\(and\\|or\\|not\\)\\>" .
2719 font-lock-keyword-face)))))
2722 @node Region to Fontify
2723 @subsection Region to Fontify after a Buffer Change
2725 When a buffer is changed, the region that Font Lock refontifies is by
2726 default the smallest sequence of whole lines that spans the change.
2727 While this works well most of the time, sometimes it doesn't---for
2728 example, when a buffer change has changed the syntactic meaning of text
2731 You can enlarge (or even reduce) the region to fontify by setting either
2732 of the following variables:
2734 @defvar font-lock-extend-region-function
2735 This buffer-local variable is either @code{nil} or is a function that
2736 determines the region to fontify, which Emacs then calls after each
2739 The function is given three parameters, the standard @var{beg},
2740 @var{end}, and @var{old-len} from after-change-functions (@pxref{Change
2741 Hooks}). It should return either a cons of the beginning and end buffer
2742 positions (in that order) of the region to fontify, or @code{nil} (which
2743 directs the caller to fontify the default region). This function need
2744 not preserve point or the match-data, but must preserve the current
2745 restriction. The region it returns may start or end in the middle of a
2748 Since this function is called after every buffer change, it should be
2752 @node Other Font Lock Variables
2753 @subsection Other Font Lock Variables
2755 This section describes additional variables that a major mode can
2756 set by means of @var{other-vars} in @code{font-lock-defaults}
2757 (@pxref{Font Lock Basics}).
2759 @defvar font-lock-mark-block-function
2760 If this variable is non-@code{nil}, it should be a function that is
2761 called with no arguments, to choose an enclosing range of text for
2762 refontification for the command @kbd{M-o M-o}
2763 (@code{font-lock-fontify-block}).
2765 The function should report its choice by placing the region around it.
2766 A good choice is a range of text large enough to give proper results,
2767 but not too large so that refontification becomes slow. Typical values
2768 are @code{mark-defun} for programming modes or @code{mark-paragraph} for
2772 @defvar font-lock-extra-managed-props
2773 This variable specifies additional properties (other than
2774 @code{font-lock-face}) that are being managed by Font Lock mode. It
2775 is used by @code{font-lock-default-unfontify-region}, which normally
2776 only manages the @code{font-lock-face} property. If you want Font
2777 Lock to manage other properties as well, you must specify them in a
2778 @var{facespec} in @code{font-lock-keywords} as well as add them to
2779 this list. @xref{Search-based Fontification}.
2782 @defvar font-lock-fontify-buffer-function
2783 Function to use for fontifying the buffer. The default value is
2784 @code{font-lock-default-fontify-buffer}.
2787 @defvar font-lock-unfontify-buffer-function
2788 Function to use for unfontifying the buffer. This is used when
2789 turning off Font Lock mode. The default value is
2790 @code{font-lock-default-unfontify-buffer}.
2793 @defvar font-lock-fontify-region-function
2794 Function to use for fontifying a region. It should take two
2795 arguments, the beginning and end of the region, and an optional third
2796 argument @var{verbose}. If @var{verbose} is non-@code{nil}, the
2797 function should print status messages. The default value is
2798 @code{font-lock-default-fontify-region}.
2801 @defvar font-lock-unfontify-region-function
2802 Function to use for unfontifying a region. It should take two
2803 arguments, the beginning and end of the region. The default value is
2804 @code{font-lock-default-unfontify-region}.
2808 @defvar font-lock-inhibit-thing-lock
2809 List of Font Lock mode related modes that should not be turned on.
2810 Currently, valid mode names are @code{fast-lock-mode},
2811 @code{jit-lock-mode} and @code{lazy-lock-mode}.
2815 @node Levels of Font Lock
2816 @subsection Levels of Font Lock
2818 Many major modes offer three different levels of fontification. You
2819 can define multiple levels by using a list of symbols for @var{keywords}
2820 in @code{font-lock-defaults}. Each symbol specifies one level of
2821 fontification; it is up to the user to choose one of these levels. The
2822 chosen level's symbol value is used to initialize
2823 @code{font-lock-keywords}.
2825 Here are the conventions for how to define the levels of
2830 Level 1: highlight function declarations, file directives (such as include or
2831 import directives), strings and comments. The idea is speed, so only
2832 the most important and top-level components are fontified.
2835 Level 2: in addition to level 1, highlight all language keywords,
2836 including type names that act like keywords, as well as named constant
2837 values. The idea is that all keywords (either syntactic or semantic)
2838 should be fontified appropriately.
2841 Level 3: in addition to level 2, highlight the symbols being defined in
2842 function and variable declarations, and all builtin function names,
2843 wherever they appear.
2846 @node Precalculated Fontification
2847 @subsection Precalculated Fontification
2849 In addition to using @code{font-lock-defaults} for search-based
2850 fontification, you may use the special character property
2851 @code{font-lock-face} (@pxref{Special Properties}). This property
2852 acts just like the explicit @code{face} property, but its activation
2853 is toggled when the user calls @kbd{M-x font-lock-mode}. Using
2854 @code{font-lock-face} is especially convenient for special modes
2855 which construct their text programmatically, such as
2856 @code{list-buffers} and @code{occur}.
2858 If your mode does not use any of the other machinery of Font Lock
2859 (i.e. it only uses the @code{font-lock-face} property), it should not
2860 set the variable @code{font-lock-defaults}. That way, it will not
2861 cause loading of the @file{font-lock} library.
2863 @node Faces for Font Lock
2864 @subsection Faces for Font Lock
2866 You can make Font Lock mode use any face, but several faces are
2867 defined specifically for Font Lock mode. Each of these symbols is both
2868 a face name, and a variable whose default value is the symbol itself.
2869 Thus, the default value of @code{font-lock-comment-face} is
2870 @code{font-lock-comment-face}. This means you can write
2871 @code{font-lock-comment-face} in a context such as
2872 @code{font-lock-keywords} where a face-name-valued expression is used.
2875 @item font-lock-comment-face
2876 @vindex font-lock-comment-face
2877 Used (typically) for comments.
2879 @item font-lock-comment-delimiter-face
2880 @vindex font-lock-comment-delimiter-face
2881 Used (typically) for comments delimiters.
2883 @item font-lock-doc-face
2884 @vindex font-lock-doc-face
2885 Used (typically) for documentation strings in the code.
2887 @item font-lock-string-face
2888 @vindex font-lock-string-face
2889 Used (typically) for string constants.
2891 @item font-lock-keyword-face
2892 @vindex font-lock-keyword-face
2893 Used (typically) for keywords---names that have special syntactic
2894 significance, like @code{for} and @code{if} in C.
2896 @item font-lock-builtin-face
2897 @vindex font-lock-builtin-face
2898 Used (typically) for built-in function names.
2900 @item font-lock-function-name-face
2901 @vindex font-lock-function-name-face
2902 Used (typically) for the name of a function being defined or declared,
2903 in a function definition or declaration.
2905 @item font-lock-variable-name-face
2906 @vindex font-lock-variable-name-face
2907 Used (typically) for the name of a variable being defined or declared,
2908 in a variable definition or declaration.
2910 @item font-lock-type-face
2911 @vindex font-lock-type-face
2912 Used (typically) for names of user-defined data types,
2913 where they are defined and where they are used.
2915 @item font-lock-constant-face
2916 @vindex font-lock-constant-face
2917 Used (typically) for constant names.
2919 @item font-lock-preprocessor-face
2920 @vindex font-lock-preprocessor-face
2921 Used (typically) for preprocessor commands.
2923 @item font-lock-warning-face
2924 @vindex font-lock-warning-face
2925 Used (typically) for constructs that are peculiar, or that greatly
2926 change the meaning of other text. For example, this is used for
2927 @samp{;;;###autoload} cookies in Emacs Lisp, and for @code{#error}
2931 @node Syntactic Font Lock
2932 @subsection Syntactic Font Lock
2934 Syntactic fontification uses the syntax table to find comments and
2935 string constants (@pxref{Syntax Tables}). It highlights them using
2936 @code{font-lock-comment-face} and @code{font-lock-string-face}
2937 (@pxref{Faces for Font Lock}). There are several variables that
2938 affect syntactic fontification; you should set them by means of
2939 @code{font-lock-defaults} (@pxref{Font Lock Basics}).
2941 @defvar font-lock-keywords-only
2942 Non-@code{nil} means Font Lock should not do syntactic fontification;
2943 it should only fontify based on @code{font-lock-keywords}. The normal
2944 way for a mode to set this variable to @code{t} is with
2945 @var{keywords-only} in @code{font-lock-defaults}.
2948 @defvar font-lock-syntax-table
2949 This variable holds the syntax table to use for fontification of
2950 comments and strings. Specify it using @var{syntax-alist} in
2951 @code{font-lock-defaults}.
2954 @defvar font-lock-beginning-of-syntax-function
2955 If this variable is non-@code{nil}, it should be a function to move
2956 point back to a position that is syntactically at ``top level'' and
2957 outside of strings or comments. Font Lock uses this when necessary
2958 to get the right results for syntactic fontification.
2960 This function is called with no arguments. It should leave point at
2961 the beginning of any enclosing syntactic block. Typical values are
2962 @code{beginning-of-line} (used when the start of the line is known to
2963 be outside a syntactic block), or @code{beginning-of-defun} for
2964 programming modes, or @code{backward-paragraph} for textual modes.
2966 If the value is @code{nil}, Font Lock uses
2967 @code{syntax-begin-function} to move back outside of any comment,
2968 string, or sexp. This variable is semi-obsolete; we recommend setting
2969 @code{syntax-begin-function} instead.
2971 Specify this variable using @var{syntax-begin} in
2972 @code{font-lock-defaults}.
2975 @defvar font-lock-syntactic-face-function
2976 A function to determine which face to use for a given syntactic
2977 element (a string or a comment). The function is called with one
2978 argument, the parse state at point returned by
2979 @code{parse-partial-sexp}, and should return a face. The default
2980 value returns @code{font-lock-comment-face} for comments and
2981 @code{font-lock-string-face} for strings.
2983 This can be used to highlighting different kinds of strings or
2984 comments differently. It is also sometimes abused together with
2985 @code{font-lock-syntactic-keywords} to highlight elements that span
2986 multiple lines, but this is too obscure to document in this manual.
2988 Specify this variable using @var{other-vars} in
2989 @code{font-lock-defaults}.
2992 @node Setting Syntax Properties
2993 @subsection Setting Syntax Properties
2995 Font Lock mode can be used to update @code{syntax-table} properties
2996 automatically (@pxref{Syntax Properties}). This is useful in
2997 languages for which a single syntax table by itself is not sufficient.
2999 @defvar font-lock-syntactic-keywords
3000 This variable enables and controls updating @code{syntax-table}
3001 properties by Font Lock. Its value should be a list of elements of
3005 (@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch})
3008 The parts of this element have the same meanings as in the corresponding
3009 sort of element of @code{font-lock-keywords},
3012 (@var{matcher} @var{subexp} @var{facespec} @var{override} @var{laxmatch})
3015 However, instead of specifying the value @var{facespec} to use for the
3016 @code{face} property, it specifies the value @var{syntax} to use for
3017 the @code{syntax-table} property. Here, @var{syntax} can be a string
3018 (as taken by @code{modify-syntax-entry}), a syntax table, a cons cell
3019 (as returned by @code{string-to-syntax}), or an expression whose value
3020 is one of those two types. @var{override} cannot be @code{prepend} or
3023 For example, an element of the form:
3026 ("\\$\\(#\\)" 1 ".")
3029 highlights syntactically a hash character when following a dollar
3030 character, with a SYNTAX of @code{"."} (meaning punctuation syntax).
3031 Assuming that the buffer syntax table specifies hash characters to
3032 have comment start syntax, the element will only highlight hash
3033 characters that do not follow dollar characters as comments
3036 An element of the form:
3044 highlights syntactically both single quotes which surround a single
3045 character, with a SYNTAX of @code{"\""} (meaning string quote syntax).
3046 Assuming that the buffer syntax table does not specify single quotes
3047 to have quote syntax, the element will only highlight single quotes of
3048 the form @samp{'@var{c}'} as strings syntactically. Other forms, such
3049 as @samp{foo'bar} or @samp{'fubar'}, will not be highlighted as
3052 Major modes normally set this variable with @var{other-vars} in
3053 @code{font-lock-defaults}.
3056 @node Desktop Save Mode
3057 @section Desktop Save Mode
3058 @cindex desktop save mode
3060 @dfn{Desktop Save Mode} is a feature to save the state of Emacs from
3061 one session to another. The user-level commands for using Desktop
3062 Save Mode are described in the GNU Emacs Manual (@pxref{Saving Emacs
3063 Sessions,,, emacs, the GNU Emacs Manual}). Modes whose buffers visit
3064 a file, don't have to do anything to use this feature.
3066 For buffers not visiting a file to have their state saved, the major
3067 mode must bind the buffer local variable @code{desktop-save-buffer} to
3068 a non-@code{nil} value.
3070 @defvar desktop-save-buffer
3071 If this buffer-local variable is non-@code{nil}, the buffer will have
3072 its state saved in the desktop file at desktop save. If the value is
3073 a function, it is called at desktop save with argument
3074 @var{desktop-dirname}, and its value is saved in the desktop file along
3075 with the state of the buffer for which it was called. When file names
3076 are returned as part of the auxiliary information, they should be
3077 formatted using the call
3080 (desktop-file-name @var{file-name} @var{desktop-dirname})
3085 For buffers not visiting a file to be restored, the major mode must
3086 define a function to do the job, and that function must be listed in
3087 the alist @code{desktop-buffer-mode-handlers}.
3089 @defvar desktop-buffer-mode-handlers
3093 (@var{major-mode} . @var{restore-buffer-function})
3096 The function @var{restore-buffer-function} will be called with
3100 (@var{buffer-file-name} @var{buffer-name} @var{desktop-buffer-misc})
3103 and it should return the restored buffer.
3104 Here @var{desktop-buffer-misc} is the value returned by the function
3105 optionally bound to @code{desktop-save-buffer}.
3109 arch-tag: 4c7bff41-36e6-4da6-9e7f-9b9289e27c8e