2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999,
4 @c 2003, 2004, 2005 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 pair of 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 use
441 @code{delay-mode-hooks} around its entire body (including the call to
442 the parent mode command) @emph{except} for the final call to
443 @code{run-mode-hooks}, which runs the derived mode's hook. (Using
444 @code{define-derived-mode} does this automatically.) @xref{Derived
445 Modes}, and @ref{Mode Hooks}.
448 If something special should be done if the user switches a buffer from
449 this mode to any other major mode, this mode can set up a buffer-local
450 value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}).
453 If this mode is appropriate only for specially-prepared text, then the
454 major mode command symbol should have a property named @code{mode-class}
455 with value @code{special}, put on as follows:
457 @kindex mode-class @r{(property)}
458 @cindex @code{special}
460 (put 'funny-mode 'mode-class 'special)
464 This tells Emacs that new buffers created while the current buffer is
465 in Funny mode should not inherit Funny mode, in case
466 @code{default-major-mode} is @code{nil}. Modes such as Dired, Rmail,
467 and Buffer List use this feature.
470 If you want to make the new mode the default for files with certain
471 recognizable names, add an element to @code{auto-mode-alist} to select
472 the mode for those file names (@pxref{Auto Major Mode}). If you
473 define the mode command to autoload, you should add this element in
474 the same file that calls @code{autoload}. If you use an autoload
475 cookie for the mode command, you can also use an autoload cookie for
476 the form that adds the element (@pxref{autoload cookie}). If you do
477 not autoload the mode command, it is sufficient to add the element in
478 the file that contains the mode definition.
481 In the comments that document the file, you should provide a sample
482 @code{autoload} form and an example of how to add to
483 @code{auto-mode-alist}, that users can include in their init files
488 The top-level forms in the file defining the mode should be written so
489 that they may be evaluated more than once without adverse consequences.
490 Even if you never load the file more than once, someone else will.
493 @node Example Major Modes
494 @subsection Major Mode Examples
496 Text mode is perhaps the simplest mode besides Fundamental mode.
497 Here are excerpts from @file{text-mode.el} that illustrate many of
498 the conventions listed above:
502 ;; @r{Create the syntax table for this mode.}
503 (defvar text-mode-syntax-table
504 (let ((st (make-syntax-table)))
505 (modify-syntax-entry ?\" ". " st)
506 (modify-syntax-entry ?\\ ". " st)
507 ;; We add `p' so that M-c on 'hello' leads to 'Hello' rather than 'hello'.
508 (modify-syntax-entry ?' "w p" st)
510 "Syntax table used while in `text-mode'.")
513 ;; @r{Create the keymap for this mode.}
515 (defvar text-mode-map
516 (let ((map (make-sparse-keymap)))
517 (define-key map "\e\t" 'ispell-complete-word)
518 (define-key map "\es" 'center-line)
519 (define-key map "\eS" 'center-paragraph)
521 "Keymap for `text-mode'.
522 Many other modes, such as `mail-mode', `outline-mode' and `indented-text-mode',
523 inherit all the commands defined in this map.")
527 Here is how the actual mode command is defined now:
531 (define-derived-mode text-mode nil "Text"
532 "Major mode for editing text written for humans to read.
533 In this mode, paragraphs are delimited only by blank or white lines.
534 You can thus get the full benefit of adaptive filling
535 (see the variable `adaptive-fill-mode').
537 Turning on Text mode runs the normal hook `text-mode-hook'."
540 (make-local-variable 'text-mode-variant)
541 (setq text-mode-variant t)
542 ;; @r{These two lines are a feature added recently.}
543 (set (make-local-variable 'require-final-newline)
544 mode-require-final-newline)
545 (set (make-local-variable 'indent-line-function) 'indent-relative))
549 But here is how it was defined formerly, before
550 @code{define-derived-mode} existed:
554 ;; @r{This isn't needed nowadays, since @code{define-derived-mode} does it.}
555 (defvar text-mode-abbrev-table nil
556 "Abbrev table used while in text mode.")
557 (define-abbrev-table 'text-mode-abbrev-table ())
562 "Major mode for editing text intended for humans to read...
563 Special commands: \\@{text-mode-map@}
566 Turning on text-mode runs the hook `text-mode-hook'."
568 (kill-all-local-variables)
569 (use-local-map text-mode-map)
572 (setq local-abbrev-table text-mode-abbrev-table)
573 (set-syntax-table text-mode-syntax-table)
576 ;; @r{These four lines are absent from the current version}
577 ;; @r{not because this is done some other way, but rather}
578 ;; @r{because nowadays Text mode uses the normal definition of paragraphs.}
579 (make-local-variable 'paragraph-start)
580 (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter))
581 (make-local-variable 'paragraph-separate)
582 (setq paragraph-separate paragraph-start)
583 (make-local-variable 'indent-line-function)
584 (setq indent-line-function 'indent-relative-maybe)
587 (setq mode-name "Text")
588 (setq major-mode 'text-mode)
589 (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
590 ; @r{customize the mode with a hook.}
594 @cindex @file{lisp-mode.el}
595 The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
596 Interaction mode) have more features than Text mode and the code is
597 correspondingly more complicated. Here are excerpts from
598 @file{lisp-mode.el} that illustrate how these modes are written.
600 @cindex syntax table example
603 ;; @r{Create mode-specific table variables.}
604 (defvar lisp-mode-syntax-table nil "")
605 (defvar lisp-mode-abbrev-table nil "")
609 (defvar emacs-lisp-mode-syntax-table
610 (let ((table (make-syntax-table)))
615 ;; @r{Set syntax of chars up to @samp{0} to say they are}
616 ;; @r{part of symbol names but not words.}
617 ;; @r{(The digit @samp{0} is @code{48} in the @acronym{ASCII} character set.)}
619 (modify-syntax-entry i "_ " table)
621 ;; @r{@dots{} similar code follows for other character ranges.}
624 ;; @r{Then set the syntax codes for characters that are special in Lisp.}
625 (modify-syntax-entry ? " " table)
626 (modify-syntax-entry ?\t " " table)
627 (modify-syntax-entry ?\f " " table)
628 (modify-syntax-entry ?\n "> " table)
631 ;; @r{Give CR the same syntax as newline, for selective-display.}
632 (modify-syntax-entry ?\^m "> " table)
633 (modify-syntax-entry ?\; "< " table)
634 (modify-syntax-entry ?` "' " table)
635 (modify-syntax-entry ?' "' " table)
636 (modify-syntax-entry ?, "' " table)
639 ;; @r{@dots{}likewise for many other characters@dots{}}
640 (modify-syntax-entry ?\( "() " table)
641 (modify-syntax-entry ?\) ")( " table)
642 (modify-syntax-entry ?\[ "(] " table)
643 (modify-syntax-entry ?\] ")[ " table))
647 ;; @r{Create an abbrev table for lisp-mode.}
648 (define-abbrev-table 'lisp-mode-abbrev-table ())
652 Much code is shared among the three Lisp modes. The following
653 function sets various variables; it is called by each of the major Lisp
658 (defun lisp-mode-variables (lisp-syntax)
660 (set-syntax-table lisp-mode-syntax-table))
661 (setq local-abbrev-table lisp-mode-abbrev-table)
666 Functions such as @code{forward-paragraph} use the value of the
667 @code{paragraph-start} variable. Since Lisp code is different from
668 ordinary text, the @code{paragraph-start} variable needs to be set
669 specially to handle Lisp. Also, comments are indented in a special
670 fashion in Lisp and the Lisp modes need their own mode-specific
671 @code{comment-indent-function}. The code to set these variables is the
672 rest of @code{lisp-mode-variables}.
676 (make-local-variable 'paragraph-start)
677 (setq paragraph-start (concat page-delimiter "\\|$" ))
678 (make-local-variable 'paragraph-separate)
679 (setq paragraph-separate paragraph-start)
683 (make-local-variable 'comment-indent-function)
684 (setq comment-indent-function 'lisp-comment-indent))
689 Each of the different Lisp modes has a slightly different keymap. For
690 example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other
691 Lisp modes do not. However, all Lisp modes have some commands in
692 common. The following code sets up the common commands:
696 (defvar shared-lisp-mode-map ()
697 "Keymap for commands shared by all sorts of Lisp modes.")
699 ;; @r{Putting this @code{if} after the @code{defvar} is an older style.}
700 (if shared-lisp-mode-map
702 (setq shared-lisp-mode-map (make-sparse-keymap))
703 (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp)
704 (define-key shared-lisp-mode-map "\177"
705 'backward-delete-char-untabify))
710 And here is the code to set up the keymap for Lisp mode:
714 (defvar lisp-mode-map ()
715 "Keymap for ordinary Lisp mode...")
719 (setq lisp-mode-map (make-sparse-keymap))
720 (set-keymap-parent lisp-mode-map shared-lisp-mode-map)
721 (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun)
722 (define-key lisp-mode-map "\C-c\C-z" 'run-lisp))
726 Finally, here is the complete major mode function definition for
732 "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
734 Delete converts tabs to spaces as it moves back.
735 Blank lines separate paragraphs. Semicolons start comments.
737 Note that `run-lisp' may be used either to start an inferior Lisp job
738 or to switch back to an existing one.
742 Entry to this mode calls the value of `lisp-mode-hook'
743 if that value is non-nil."
745 (kill-all-local-variables)
748 (use-local-map lisp-mode-map) ; @r{Select the mode's keymap.}
749 (setq major-mode 'lisp-mode) ; @r{This is how @code{describe-mode}}
750 ; @r{finds out what to describe.}
751 (setq mode-name "Lisp") ; @r{This goes into the mode line.}
752 (lisp-mode-variables t) ; @r{This defines various variables.}
753 (make-local-variable 'comment-start-skip)
754 (setq comment-start-skip
755 "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *")
756 (make-local-variable 'font-lock-keywords-case-fold-search)
757 (setq font-lock-keywords-case-fold-search t)
760 (setq imenu-case-fold-search t)
761 (set-syntax-table lisp-mode-syntax-table)
762 (run-mode-hooks 'lisp-mode-hook)) ; @r{This permits the user to use a}
763 ; @r{hook to customize the mode.}
767 @node Auto Major Mode
768 @subsection How Emacs Chooses a Major Mode
770 Based on information in the file name or in the file itself, Emacs
771 automatically selects a major mode for the new buffer when a file is
772 visited. It also processes local variables specified in the file text.
774 @deffn Command fundamental-mode
775 Fundamental mode is a major mode that is not specialized for anything
776 in particular. Other major modes are defined in effect by comparison
777 with this one---their definitions say what to change, starting from
778 Fundamental mode. The @code{fundamental-mode} function does @emph{not}
779 run any mode hooks; you're not supposed to customize it. (If you want Emacs
780 to behave differently in Fundamental mode, change the @emph{global}
784 @deffn Command normal-mode &optional find-file
785 This function establishes the proper major mode and buffer-local variable
786 bindings for the current buffer. First it calls @code{set-auto-mode}
787 (see below), then it runs @code{hack-local-variables} to parse, and
788 bind or evaluate as appropriate, the file's local variables
789 (@pxref{File Local Variables}).
791 If the @var{find-file} argument to @code{normal-mode} is non-@code{nil},
792 @code{normal-mode} assumes that the @code{find-file} function is calling
793 it. In this case, it may process local variables in the @samp{-*-}
794 line or at the end of the file. The variable
795 @code{enable-local-variables} controls whether to do so. @xref{File
796 Variables, , Local Variables in Files, emacs, The GNU Emacs Manual},
797 for the syntax of the local variables section of a file.
799 If you run @code{normal-mode} interactively, the argument
800 @var{find-file} is normally @code{nil}. In this case,
801 @code{normal-mode} unconditionally processes any file local variables.
803 If @code{normal-mode} processes the local variables list and this list
804 specifies a major mode, that mode overrides any mode chosen by
805 @code{set-auto-mode}. If neither @code{set-auto-mode} nor
806 @code{hack-local-variables} specify a major mode, the buffer stays in
807 the major mode determined by @code{default-major-mode} (see below).
809 @cindex file mode specification error
810 @code{normal-mode} uses @code{condition-case} around the call to the
811 major mode function, so errors are caught and reported as a @samp{File
812 mode specification error}, followed by the original error message.
815 @defun set-auto-mode &optional keep-mode-if-same
816 @cindex visited file mode
817 This function selects the major mode that is appropriate for the
818 current buffer. It bases its decision (in order of precedence) on
819 the @w{@samp{-*-}} line, on the @w{@samp{#!}} line (using
820 @code{interpreter-mode-alist}), on the text at the beginning of the
821 buffer (using @code{magic-mode-alist}), and finally on the visited
822 file name (using @code{auto-mode-alist}). @xref{Choosing Modes, , How
823 Major Modes are Chosen, emacs, The GNU Emacs Manual}. However, this
824 function does not look for the @samp{mode:} local variable near the
825 end of a file; the @code{hack-local-variables} function does that.
826 If @code{enable-local-variables} is @code{nil}, @code{set-auto-mode}
827 does not check the @w{@samp{-*-}} line for a mode tag either.
829 If @var{keep-mode-if-same} is non-@code{nil}, this function does not
830 call the mode command if the buffer is already in the proper major
831 mode. For instance, @code{set-visited-file-name} sets this to
832 @code{t} to avoid killing buffer local variables that the user may
836 @defopt default-major-mode
837 This variable holds the default major mode for new buffers. The
838 standard value is @code{fundamental-mode}.
840 If the value of @code{default-major-mode} is @code{nil}, Emacs uses
841 the (previously) current buffer's major mode as the default major mode
842 of a new buffer. However, if that major mode symbol has a @code{mode-class}
843 property with value @code{special}, then it is not used for new buffers;
844 Fundamental mode is used instead. The modes that have this property are
845 those such as Dired and Rmail that are useful only with text that has
846 been specially prepared.
849 @defun set-buffer-major-mode buffer
850 This function sets the major mode of @var{buffer} to the value of
851 @code{default-major-mode}; if that variable is @code{nil}, it uses the
852 current buffer's major mode (if that is suitable). As an exception,
853 if @var{buffer}'s name is @samp{*scratch*}, it sets the mode to
854 @code{initial-major-mode}.
856 The low-level primitives for creating buffers do not use this function,
857 but medium-level commands such as @code{switch-to-buffer} and
858 @code{find-file-noselect} use it whenever they create buffers.
861 @defopt initial-major-mode
862 @cindex @samp{*scratch*}
863 The value of this variable determines the major mode of the initial
864 @samp{*scratch*} buffer. The value should be a symbol that is a major
865 mode command. The default value is @code{lisp-interaction-mode}.
868 @defvar interpreter-mode-alist
869 This variable specifies major modes to use for scripts that specify a
870 command interpreter in a @samp{#!} line. Its value is an alist with
871 elements of the form @code{(@var{interpreter} . @var{mode})}; for
872 example, @code{("perl" . perl-mode)} is one element present by
873 default. The element says to use mode @var{mode} if the file
874 specifies an interpreter which matches @var{interpreter}. The value
875 of @var{interpreter} is actually a regular expression. @xref{Regular
879 @defvar magic-mode-alist
880 This variable's value is an alist with elements of the form
881 @code{(@var{regexp} . @var{function})}, where @var{regexp} is a
882 regular expression and @var{function} is a function or @code{nil}.
883 After visiting a file, @code{set-auto-mode} calls @var{function} if
884 the text at the beginning of the buffer matches @var{regexp} and
885 @var{function} is non-@code{nil}; if @var{function} is @code{nil},
886 @code{auto-mode-alist} gets to decide the mode.
889 @defvar auto-mode-alist
890 This variable contains an association list of file name patterns
891 (regular expressions) and corresponding major mode commands. Usually,
892 the file name patterns test for suffixes, such as @samp{.el} and
893 @samp{.c}, but this need not be the case. An ordinary element of the
894 alist looks like @code{(@var{regexp} . @var{mode-function})}.
900 (("\\`/tmp/fol/" . text-mode)
901 ("\\.texinfo\\'" . texinfo-mode)
902 ("\\.texi\\'" . texinfo-mode)
905 ("\\.el\\'" . emacs-lisp-mode)
912 When you visit a file whose expanded file name (@pxref{File Name
913 Expansion}), with version numbers and backup suffixes removed using
914 @code{file-name-sans-versions} (@pxref{File Name Components}), matches
915 a @var{regexp}, @code{set-auto-mode} calls the corresponding
916 @var{mode-function}. This feature enables Emacs to select the proper
917 major mode for most files.
919 If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
920 @var{function} t)}, then after calling @var{function}, Emacs searches
921 @code{auto-mode-alist} again for a match against the portion of the file
922 name that did not match before. This feature is useful for
923 uncompression packages: an entry of the form @code{("\\.gz\\'"
924 @var{function} t)} can uncompress the file and then put the uncompressed
925 file in the proper mode according to the name sans @samp{.gz}.
927 Here is an example of how to prepend several pattern pairs to
928 @code{auto-mode-alist}. (You might use this sort of expression in your
933 (setq auto-mode-alist
935 ;; @r{File name (within directory) starts with a dot.}
936 '(("/\\.[^/]*\\'" . fundamental-mode)
937 ;; @r{File name has no dot.}
938 ("[^\\./]*\\'" . fundamental-mode)
939 ;; @r{File name ends in @samp{.C}.}
940 ("\\.C\\'" . c++-mode))
947 @subsection Getting Help about a Major Mode
949 @cindex help for major mode
950 @cindex documentation for major mode
952 The @code{describe-mode} function is used to provide information
953 about major modes. It is normally called with @kbd{C-h m}. The
954 @code{describe-mode} function uses the value of @code{major-mode},
955 which is why every major mode function needs to set the
956 @code{major-mode} variable.
958 @deffn Command describe-mode
959 This function displays the documentation of the current major mode.
961 The @code{describe-mode} function calls the @code{documentation}
962 function using the value of @code{major-mode} as an argument. Thus, it
963 displays the documentation string of the major mode function.
964 (@xref{Accessing Documentation}.)
968 This variable holds the symbol for the current buffer's major mode.
969 This symbol should have a function definition that is the command to
970 switch to that major mode. The @code{describe-mode} function uses the
971 documentation string of the function as the documentation of the major
976 @subsection Defining Derived Modes
979 It's often useful to define a new major mode in terms of an existing
980 one. An easy way to do this is to use @code{define-derived-mode}.
982 @defmac define-derived-mode variant parent name docstring keyword-args@dots{} body@dots{}
983 This construct defines @var{variant} as a major mode command, using
984 @var{name} as the string form of the mode name. @var{variant} and
985 @var{parent} should be unquoted symbols.
987 The new command @var{variant} is defined to call the function
988 @var{parent}, then override certain aspects of that parent mode:
992 The new mode has its own sparse keymap, named
993 @code{@var{variant}-map}. @code{define-derived-mode}
994 makes the parent mode's keymap the parent of the new map, unless
995 @code{@var{variant}-map} is already set and already has a parent.
998 The new mode has its own syntax table, kept in the variable
999 @code{@var{variant}-syntax-table}, unless you override this using the
1000 @code{:syntax-table} keyword (see below). @code{define-derived-mode}
1001 makes the parent mode's syntax-table the parent of
1002 @code{@var{variant}-syntax-table}, unless the latter is already set
1003 and already has a parent different from the standard syntax table.
1006 The new mode has its own abbrev table, kept in the variable
1007 @code{@var{variant}-abbrev-table}, unless you override this using the
1008 @code{:abbrev-table} keyword (see below).
1011 The new mode has its own mode hook, @code{@var{variant}-hook}. It
1012 runs this hook, after running the hooks of its ancestor modes, with
1013 @code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}.
1016 In addition, you can specify how to override other aspects of
1017 @var{parent} with @var{body}. The command @var{variant}
1018 evaluates the forms in @var{body} after setting up all its usual
1019 overrides, just before running the mode hooks.
1021 You can also specify @code{nil} for @var{parent}. This gives the new
1022 mode no parent. Then @code{define-derived-mode} behaves as described
1023 above, but, of course, omits all actions connected with @var{parent}.
1025 The argument @var{docstring} specifies the documentation string for
1026 the new mode. @code{define-derived-mode} adds some general
1027 information about the mode's hook, followed by the mode's keymap, at
1028 the end of this docstring. If you omit @var{docstring},
1029 @code{define-derived-mode} generates a documentation string.
1031 The @var{keyword-args} are pairs of keywords and values. The values
1032 are evaluated. The following keywords are currently supported:
1036 If this is specified, it is the customization group for this mode.
1039 You can use this to explicitly specify a syntax table for the new
1040 mode. If you specify a @code{nil} value, the new mode uses the same
1041 syntax table as @var{parent}, or the standard syntax table if
1042 @var{parent} is @code{nil}. (Note that this does @emph{not} follow
1043 the convention used for non-keyword arguments that a @code{nil} value
1044 is equivalent with not specifying the argument.)
1047 You can use this to explicitly specify an abbrev table for the new
1048 mode. If you specify a @code{nil} value, the new mode uses the same
1049 abbrev table as @var{parent}, or @code{fundamental-mode-abbrev-table}
1050 if @var{parent} is @code{nil}. (Again, a @code{nil} value is
1051 @emph{not} equivalent to not specifying this keyword.)
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 does is to 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 called
1125 directly or indirectly by the major mode function are all run in
1126 sequence at the end, just before @code{after-change-major-mode-hook}.
1128 If you are customizing a major mode, rather than defining one, the
1129 above is all you need to know about the hooks run at the end of a
1130 major mode. This also applies if you use @code{define-derived-mode}
1131 to define a major mode, because that macro will automatically
1132 implement the above for you.
1134 Programmers wishing to define a major mode without using
1135 @code{define-derived-mode}, should make sure that their major mode
1136 follows the above conventions. @xref{Major Mode Conventions}, for how
1137 this should be accomplished. Below, we give some implementation
1140 @defun run-mode-hooks &rest hookvars
1141 Major modes should run their mode hook using this function. It is
1142 similar to @code{run-hooks} (@pxref{Hooks}), but if run inside a
1143 @code{delay-mode-hooks} form, this function does not run any hooks.
1144 Instead, it arranges for @var{hookvars} to be run at a later call to
1145 the function. Otherwise, @code{run-mode-hooks} runs any delayed hooks
1146 in order, then @var{hookvars} and finally
1147 @code{after-change-major-mode-hook}.
1150 @defmac delay-mode-hooks body...
1151 This macro executes @var{body} like @code{progn}, but all calls to
1152 @code{run-mode-hooks} inside @var{body} delay running their hooks.
1153 They will be run by the first call to @code{run-mode-hooks} after exit
1154 from @code{delay-mode-hooks}.
1157 @defvar after-change-major-mode-hook
1158 Every major mode function should run this normal hook at its very end.
1159 It normally does not need to do so explicitly. Indeed, a major mode
1160 function should normally run its mode hook with @code{run-mode-hooks}
1161 as the very last thing it does and @code{run-mode-hooks} runs
1162 @code{after-change-major-mode-hook} at its very end.
1166 @section Minor Modes
1169 A @dfn{minor mode} provides features that users may enable or disable
1170 independently of the choice of major mode. Minor modes can be enabled
1171 individually or in combination. Minor modes would be better named
1172 ``generally available, optional feature modes,'' except that such a name
1175 A minor mode is not usually meant as a variation of a single major mode.
1176 Usually they are general and can apply to many major modes. For
1177 example, Auto Fill mode works with any major mode that permits text
1178 insertion. To be general, a minor mode must be effectively independent
1179 of the things major modes do.
1181 A minor mode is often much more difficult to implement than a major
1182 mode. One reason is that you should be able to activate and deactivate
1183 minor modes in any order. A minor mode should be able to have its
1184 desired effect regardless of the major mode and regardless of the other
1185 minor modes in effect.
1187 Often the biggest problem in implementing a minor mode is finding a
1188 way to insert the necessary hook into the rest of Emacs. Minor mode
1189 keymaps make this easier than it used to be.
1191 @defvar minor-mode-list
1192 The value of this variable is a list of all minor mode commands.
1196 * Minor Mode Conventions:: Tips for writing a minor mode.
1197 * Keymaps and Minor Modes:: How a minor mode can have its own keymap.
1198 * Defining Minor Modes:: A convenient facility for defining minor modes.
1201 @node Minor Mode Conventions
1202 @subsection Conventions for Writing Minor Modes
1203 @cindex minor mode conventions
1204 @cindex conventions for writing minor modes
1206 There are conventions for writing minor modes just as there are for
1207 major modes. Several of the major mode conventions apply to minor
1208 modes as well: those regarding the name of the mode initialization
1209 function, the names of global symbols, and the use of keymaps and
1212 In addition, there are several conventions that are specific to
1213 minor modes. (The easiest way to follow all the conventions is to use
1214 the macro @code{define-minor-mode}; @ref{Defining Minor Modes}.)
1218 @cindex mode variable
1219 Make a variable whose name ends in @samp{-mode} to control the minor
1220 mode. We call this the @dfn{mode variable}. The minor mode command
1221 should set this variable (@code{nil} to disable; anything else to
1224 If possible, implement the mode so that setting the variable
1225 automatically enables or disables the mode. Then the minor mode command
1226 does not need to do anything except set the variable.
1228 This variable is used in conjunction with the @code{minor-mode-alist} to
1229 display the minor mode name in the mode line. It can also enable
1230 or disable a minor mode keymap. Individual commands or hooks can also
1231 check the variable's value.
1233 If you want the minor mode to be enabled separately in each buffer,
1234 make the variable buffer-local.
1237 Define a command whose name is the same as the mode variable.
1238 Its job is to enable and disable the mode by setting the variable.
1240 The command should accept one optional argument. If the argument is
1241 @code{nil}, it should toggle the mode (turn it on if it is off, and
1242 off if it is on). It should turn the mode on if the argument is a
1243 positive integer, the symbol @code{t}, or a list whose @sc{car} is one
1244 of those. It should turn the mode off if the argument is a negative
1245 integer or zero, the symbol @code{-}, or a list whose @sc{car} is a
1246 negative integer or zero. The meaning of other arguments is not
1249 Here is an example taken from the definition of @code{transient-mark-mode}.
1250 It shows the use of @code{transient-mark-mode} as a variable that enables or
1251 disables the mode's behavior, and also shows the proper way to toggle,
1252 enable or disable the minor mode based on the raw prefix argument value.
1256 (setq transient-mark-mode
1257 (if (null arg) (not transient-mark-mode)
1258 (> (prefix-numeric-value arg) 0)))
1263 Add an element to @code{minor-mode-alist} for each minor mode
1264 (@pxref{Definition of minor-mode-alist}), if you want to indicate the
1265 minor mode in the mode line. This element should be a list of the
1269 (@var{mode-variable} @var{string})
1272 Here @var{mode-variable} is the variable that controls enabling of the
1273 minor mode, and @var{string} is a short string, starting with a space,
1274 to represent the mode in the mode line. These strings must be short so
1275 that there is room for several of them at once.
1277 When you add an element to @code{minor-mode-alist}, use @code{assq} to
1278 check for an existing element, to avoid duplication. For example:
1282 (unless (assq 'leif-mode minor-mode-alist)
1283 (setq minor-mode-alist
1284 (cons '(leif-mode " Leif") minor-mode-alist)))
1289 or like this, using @code{add-to-list} (@pxref{Setting Variables}):
1293 (add-to-list 'minor-mode-alist '(leif-mode " Leif"))
1298 Global minor modes distributed with Emacs should if possible support
1299 enabling and disabling via Custom (@pxref{Customization}). To do this,
1300 the first step is to define the mode variable with @code{defcustom}, and
1301 specify @code{:type boolean}.
1303 If just setting the variable is not sufficient to enable the mode, you
1304 should also specify a @code{:set} method which enables the mode by
1305 invoking the mode command. Note in the variable's documentation string that
1306 setting the variable other than via Custom may not take effect.
1308 Also mark the definition with an autoload cookie (@pxref{autoload cookie}),
1309 and specify a @code{:require} so that customizing the variable will load
1310 the library that defines the mode. This will copy suitable definitions
1311 into @file{loaddefs.el} so that users can use @code{customize-option} to
1312 enable the mode. For example:
1318 (defcustom msb-mode nil
1320 Setting this variable directly does not take effect;
1321 use either \\[customize] or the function `msb-mode'."
1322 :set (lambda (symbol value)
1323 (msb-mode (or value 0)))
1324 :initialize 'custom-initialize-default
1332 @node Keymaps and Minor Modes
1333 @subsection Keymaps and Minor Modes
1335 Each minor mode can have its own keymap, which is active when the mode
1336 is enabled. To set up a keymap for a minor mode, add an element to the
1337 alist @code{minor-mode-map-alist}. @xref{Definition of minor-mode-map-alist}.
1339 @cindex @code{self-insert-command}, minor modes
1340 One use of minor mode keymaps is to modify the behavior of certain
1341 self-inserting characters so that they do something else as well as
1342 self-insert. In general, this is the only way to do that, since the
1343 facilities for customizing @code{self-insert-command} are limited to
1344 special cases (designed for abbrevs and Auto Fill mode). (Do not try
1345 substituting your own definition of @code{self-insert-command} for the
1346 standard one. The editor command loop handles this function specially.)
1348 The key sequences bound in a minor mode should consist of @kbd{C-c}
1349 followed by a punctuation character @emph{other than} @kbd{@{},
1350 @kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:}, and @kbd{;}. (Those few punctuation
1351 characters are reserved for major modes.)
1353 @node Defining Minor Modes
1354 @subsection Defining Minor Modes
1356 The macro @code{define-minor-mode} offers a convenient way of
1357 implementing a mode in one self-contained definition.
1359 @defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args... body...
1360 @tindex define-minor-mode
1361 This macro defines a new minor mode whose name is @var{mode} (a
1362 symbol). It defines a command named @var{mode} to toggle the minor
1363 mode, with @var{doc} as its documentation string. It also defines a
1364 variable named @var{mode}, which is set to @code{t} or @code{nil} by
1365 enabling or disabling the mode. The variable is initialized to
1368 The string @var{lighter} says what to display in the mode line
1369 when the mode is enabled; if it is @code{nil}, the mode is not displayed
1372 The optional argument @var{keymap} specifies the keymap for the minor mode.
1373 It can be a variable name, whose value is the keymap, or it can be an alist
1374 specifying bindings in this form:
1377 (@var{key-sequence} . @var{definition})
1380 The above three arguments @var{init-value}, @var{lighter}, and
1381 @var{keymap} can be (partially) omitted when @var{keyword-args} are
1382 used. The @var{keyword-args} consist of keywords followed by
1383 corresponding values. A few keywords have special meanings:
1386 @item :group @var{group}
1387 Custom group name to use in all generated @code{defcustom} forms.
1388 Defaults to @var{mode} without the possible trailing @samp{-mode}.
1389 @strong{Warning:} don't use this default group name unless you have
1390 written a @code{defgroup} to define that group properly. @xref{Group
1393 @item :global @var{global}
1394 If non-@code{nil} specifies that the minor mode should be global. By
1395 default, minor modes defined with @code{define-minor-mode} are
1398 @item :init-value @var{init-value}
1399 This is equivalent to specifying @var{init-value} positionally.
1401 @item :lighter @var{lighter}
1402 This is equivalent to specifying @var{lighter} positionally.
1404 @item :keymap @var{keymap}
1405 This is equivalent to specifying @var{keymap} positionally.
1408 Any other keyword arguments are passed passed directly to the
1409 @code{defcustom} generated for the variable @var{mode}.
1411 The command named @var{mode} first performs the standard actions such
1412 as setting the variable named @var{mode} and then executes the
1413 @var{body} forms, if any. It finishes by running the mode hook
1414 variable @code{@var{mode}-hook}.
1417 @findex easy-mmode-define-minor-mode
1418 The name @code{easy-mmode-define-minor-mode} is an alias
1421 Here is an example of using @code{define-minor-mode}:
1424 (define-minor-mode hungry-mode
1425 "Toggle Hungry mode.
1426 With no argument, this command toggles the mode.
1427 Non-null prefix argument turns on the mode.
1428 Null prefix argument turns off the mode.
1430 When Hungry mode is enabled, the control delete key
1431 gobbles all preceding whitespace except the last.
1432 See the command \\[hungry-electric-delete]."
1433 ;; The initial value.
1435 ;; The indicator for the mode line.
1437 ;; The minor mode bindings.
1438 '(("\C-\^?" . hungry-electric-delete))
1443 This defines a minor mode named ``Hungry mode'', a command named
1444 @code{hungry-mode} to toggle it, a variable named @code{hungry-mode}
1445 which indicates whether the mode is enabled, and a variable named
1446 @code{hungry-mode-map} which holds the keymap that is active when the
1447 mode is enabled. It initializes the keymap with a key binding for
1448 @kbd{C-@key{DEL}}. It puts the variable @code{hungry-mode} into
1449 custom group @code{hunger}. There are no @var{body} forms---many
1450 minor modes don't need any.
1452 Here's an equivalent way to write it:
1455 (define-minor-mode hungry-mode
1456 "Toggle Hungry mode.
1457 With no argument, this command toggles the mode.
1458 Non-null prefix argument turns on the mode.
1459 Null prefix argument turns off the mode.
1461 When Hungry mode is enabled, the control delete key
1462 gobbles all preceding whitespace except the last.
1463 See the command \\[hungry-electric-delete]."
1464 ;; The initial value.
1466 ;; The indicator for the mode line.
1468 ;; The minor mode bindings.
1470 '(("\C-\^?" . hungry-electric-delete)
1474 (hungry-electric-delete t))))
1478 @defmac define-global-minor-mode global-mode mode turn-on keyword-args...
1479 This defines a global minor mode named @var{global-mode} whose meaning
1480 is to enable the buffer-local minor mode @var{mode} in every buffer.
1481 To turn on the minor mode in a buffer, it uses the function
1482 @var{turn-on}; to turn off the minor mode, it calls @code{mode} with
1483 @minus{}1 as argument.
1485 Use @code{:group @var{group}} in @var{keyword-args} to specify the
1486 custom group for the mode variable of the global minor mode.
1489 @node Mode Line Format
1490 @section Mode-Line Format
1493 Each Emacs window (aside from minibuffer windows) typically has a mode
1494 line at the bottom, which displays status information about the buffer
1495 displayed in the window. The mode line contains information about the
1496 buffer, such as its name, associated file, depth of recursive editing,
1497 and major and minor modes. A window can also have a @dfn{header
1498 line}, which is much like the mode line but appears at the top of the
1501 This section describes how to control the contents of the mode line
1502 and header line. We include it in this chapter because much of the
1503 information displayed in the mode line relates to the enabled major and
1507 * Mode Line Basics::
1508 * Mode Line Data:: The data structure that controls the mode line.
1509 * Mode Line Variables:: Variables used in that data structure.
1510 * %-Constructs:: Putting information into a mode line.
1511 * Properties in Mode:: Using text properties in the mode line.
1512 * Header Lines:: Like a mode line, but at the top.
1513 * Emulating Mode Line:: Formatting text as the mode line would.
1516 @node Mode Line Basics
1517 @subsection Mode Line Basics
1519 @code{mode-line-format} is a buffer-local variable that holds a
1520 template used to display the mode line of the current buffer. All
1521 windows for the same buffer use the same @code{mode-line-format}, so
1522 their mode lines appear the same---except for scrolling percentages, and
1523 line and column numbers, since those depend on point and on how the
1524 window is scrolled. @code{header-line-format} is used likewise for
1527 For efficiency, Emacs does not recompute the mode line and header
1528 line of a window in every redisplay. It does so when circumstances
1529 appear to call for it---for instance, if you change the window
1530 configuration, switch buffers, narrow or widen the buffer, scroll, or
1531 change the buffer's modification status. If you modify any of the
1532 variables referenced by @code{mode-line-format} (@pxref{Mode Line
1533 Variables}), or any other variables and data structures that affect
1534 how text is displayed (@pxref{Display}), you may want to force an
1535 update of the mode line so as to display the new information or
1536 display it in the new way.
1539 @defun force-mode-line-update &optional all
1540 Force redisplay of the current buffer's mode line and header line.
1541 The next redisplay will update the mode line and header line based on
1542 the latest values of all relevant variables. With optional
1543 non-@code{nil} @var{all}, force redisplay of all mode lines and header
1546 This function also forces recomputation of the menu bar menus
1547 and the frame title.
1550 The selected window's mode line is usually displayed in a different
1551 color using the face @code{mode-line}. Other windows' mode lines
1552 appear in the face @code{mode-line-inactive} instead. @xref{Faces}.
1554 A window that is just one line tall does not display either a mode
1555 line or a header line, even if the variables call for one. A window
1556 that is two lines tall cannot display both a mode line and a header
1557 line at once; if the variables call for both, only the mode line
1560 @node Mode Line Data
1561 @subsection The Data Structure of the Mode Line
1562 @cindex mode-line construct
1564 The mode-line contents are controlled by a data structure of lists,
1565 strings, symbols, and numbers kept in buffer-local variables. The data
1566 structure is called a @dfn{mode-line construct}, and it is built in
1567 recursive fashion out of simpler mode-line constructs. The same data
1568 structure is used for constructing frame titles (@pxref{Frame Titles})
1569 and header lines (@pxref{Header Lines}).
1571 @defvar mode-line-format
1572 The value of this variable is a mode-line construct with overall
1573 responsibility for the mode-line format. The value of this variable
1574 controls which other variables are used to form the mode-line text, and
1577 If you set this variable to @code{nil} in a buffer, that buffer does not
1581 A mode-line construct may be as simple as a fixed string of text, but
1582 it usually specifies how to use other variables to construct the text.
1583 Many of these variables are themselves defined to have mode-line
1584 constructs as their values.
1586 The default value of @code{mode-line-format} incorporates the values
1587 of variables such as @code{mode-line-position} and
1588 @code{mode-line-modes} (which in turn incorporates the values of the
1589 variables @code{mode-name} and @code{minor-mode-alist}). Because of
1590 this, very few modes need to alter @code{mode-line-format} itself. For
1591 most purposes, it is sufficient to alter some of the variables that
1592 @code{mode-line-format} either directly or indirectly refers to.
1594 A mode-line construct may be a list, a symbol, or a string. If the
1595 value is a list, each element may be a list, a symbol, or a string.
1597 The mode line can display various faces, if the strings that control
1598 it have the @code{face} property. @xref{Properties in Mode}. In
1599 addition, the face @code{mode-line} is used as a default for the whole
1600 mode line (@pxref{Standard Faces}).
1603 @cindex percent symbol in mode line
1605 A string as a mode-line construct is displayed verbatim in the mode line
1606 except for @dfn{@code{%}-constructs}. Decimal digits after the @samp{%}
1607 specify the field width for space filling on the right (i.e., the data
1608 is left justified). @xref{%-Constructs}.
1611 A symbol as a mode-line construct stands for its value. The value of
1612 @var{symbol} is used as a mode-line construct, in place of @var{symbol}.
1613 However, the symbols @code{t} and @code{nil} are ignored, as is any
1614 symbol whose value is void.
1616 There is one exception: if the value of @var{symbol} is a string, it is
1617 displayed verbatim: the @code{%}-constructs are not recognized.
1619 Unless @var{symbol} is marked as ``risky'' (i.e., it has a
1620 non-@code{nil} @code{risky-local-variable} property), all properties in
1621 any strings, as well as all @code{:eval} and @code{:propertize} forms in
1622 the value of that symbol will be ignored.
1624 @item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{})
1625 A list whose first element is a string or list means to process all the
1626 elements recursively and concatenate the results. This is the most
1627 common form of mode-line construct.
1629 @item (:eval @var{form})
1630 A list whose first element is the symbol @code{:eval} says to evaluate
1631 @var{form}, and use the result as a string to display. Make sure this
1632 evaluation cannot load any files, as doing so could cause infinite
1635 @item (:propertize @var{elt} @var{props}@dots{})
1636 A list whose first element is the symbol @code{:propertize} says to
1637 process the mode-line construct @var{elt} recursively and add the text
1638 properties specified by @var{props} to the result. The argument
1639 @var{props} should consist of zero or more pairs @var{text-property}
1640 @var{value}. (This feature is new as of Emacs 22.1.)
1642 @item (@var{symbol} @var{then} @var{else})
1643 A list whose first element is a symbol that is not a keyword specifies a
1644 conditional. Its meaning depends on the value of @var{symbol}. If the
1645 value is non-@code{nil}, the second element, @var{then}, is processed
1646 recursively as a mode-line element. But if the value of @var{symbol} is
1647 @code{nil}, the third element, @var{else}, is processed recursively.
1648 You may omit @var{else}; then the mode-line element displays nothing if
1649 the value of @var{symbol} is @code{nil}.
1651 @item (@var{width} @var{rest}@dots{})
1652 A list whose first element is an integer specifies truncation or
1653 padding of the results of @var{rest}. The remaining elements
1654 @var{rest} are processed recursively as mode-line constructs and
1655 concatenated together. When @var{width} is positive, the result is
1656 space filled on the right if its width is less than @var{width}. When
1657 @var{width} is negative, the result is truncated on the right to
1658 @minus{}@var{width} columns if its width exceeds @minus{}@var{width}.
1660 For example, the usual way to show what percentage of a buffer is above
1661 the top of the window is to use a list like this: @code{(-3 "%p")}.
1664 If you do alter @code{mode-line-format} itself, the new value should
1665 use the same variables that appear in the default value (@pxref{Mode
1666 Line Variables}), rather than duplicating their contents or displaying
1667 the information in another fashion. This way, customizations made by
1668 the user or by Lisp programs (such as @code{display-time} and major
1669 modes) via changes to those variables remain effective.
1671 @cindex Shell mode @code{mode-line-format}
1672 Here is an example of a @code{mode-line-format} that might be
1673 useful for @code{shell-mode}, since it contains the host name and default
1678 (setq mode-line-format
1680 'mode-line-mule-info
1682 'mode-line-frame-identification
1686 ;; @r{Note that this is evaluated while making the list.}
1687 ;; @r{It makes a mode-line construct which is just a string.}
1695 '(:eval (mode-line-mode-name))
1701 '(which-func-mode ("" which-func-format "--"))
1702 '(line-number-mode "L%l--")
1703 '(column-number-mode "C%c--")
1710 (The variables @code{line-number-mode}, @code{column-number-mode}
1711 and @code{which-func-mode} enable particular minor modes; as usual,
1712 these variable names are also the minor mode command names.)
1714 @node Mode Line Variables
1715 @subsection Variables Used in the Mode Line
1717 This section describes variables incorporated by the
1718 standard value of @code{mode-line-format} into the text of the mode
1719 line. There is nothing inherently special about these variables; any
1720 other variables could have the same effects on the mode line if
1721 @code{mode-line-format} were changed to use them.
1723 @defvar mode-line-mule-info
1724 This variable holds the value of the mode-line construct that displays
1725 information about the language environment, buffer coding system, and
1726 current input method. @xref{Non-ASCII Characters}.
1729 @defvar mode-line-modified
1730 This variable holds the value of the mode-line construct that displays
1731 whether the current buffer is modified.
1733 The default value of @code{mode-line-modified} is @code{("%1*%1+")}.
1734 This means that the mode line displays @samp{**} if the buffer is
1735 modified, @samp{--} if the buffer is not modified, @samp{%%} if the
1736 buffer is read only, and @samp{%*} if the buffer is read only and
1739 Changing this variable does not force an update of the mode line.
1742 @defvar mode-line-frame-identification
1743 This variable identifies the current frame. The default value is
1744 @code{" "} if you are using a window system which can show multiple
1745 frames, or @code{"-%F "} on an ordinary terminal which shows only one
1749 @defvar mode-line-buffer-identification
1750 This variable identifies the buffer being displayed in the window. Its
1751 default value is @code{("%12b")}, which displays the buffer name, padded
1752 with spaces to at least 12 columns.
1755 @defvar mode-line-position
1756 This variable indicates the position in the buffer. Here is a
1757 simplified version of its default value. The actual default value
1758 also specifies addition of the @code{help-echo} text property.
1763 (size-indication-mode (8 " of %I"))
1767 ((column-number-mode
1770 ((column-number-mode
1775 This means that @code{mode-line-position} displays at least the buffer
1776 percentage and possibly the buffer size, the line number and the column
1781 The variable @code{vc-mode}, buffer-local in each buffer, records
1782 whether the buffer's visited file is maintained with version control,
1783 and, if so, which kind. Its value is a string that appears in the mode
1784 line, or @code{nil} for no version control.
1787 @defvar mode-line-modes
1788 This variable displays the buffer's major and minor modes. Here is a
1789 simplified version of its default value. The real default value also
1790 specifies addition of text properties.
1795 mode-line-process minor-mode-alist
1800 So @code{mode-line-modes} normally also displays the recursive editing
1801 level, information on the process status and whether narrowing is in
1805 The following three variables are used in @code{mode-line-modes}:
1808 This buffer-local variable holds the ``pretty'' name of the current
1809 buffer's major mode. Each major mode should set this variable so that the
1810 mode name will appear in the mode line.
1813 @defvar mode-line-process
1814 This buffer-local variable contains the mode-line information on process
1815 status in modes used for communicating with subprocesses. It is
1816 displayed immediately following the major mode name, with no intervening
1817 space. For example, its value in the @samp{*shell*} buffer is
1818 @code{(":%s")}, which allows the shell to display its status along
1819 with the major mode as: @samp{(Shell:run)}. Normally this variable
1823 @defvar minor-mode-alist
1824 @anchor{Definition of minor-mode-alist}
1825 This variable holds an association list whose elements specify how the
1826 mode line should indicate that a minor mode is active. Each element of
1827 the @code{minor-mode-alist} should be a two-element list:
1830 (@var{minor-mode-variable} @var{mode-line-string})
1833 More generally, @var{mode-line-string} can be any mode-line spec. It
1834 appears in the mode line when the value of @var{minor-mode-variable}
1835 is non-@code{nil}, and not otherwise. These strings should begin with
1836 spaces so that they don't run together. Conventionally, the
1837 @var{minor-mode-variable} for a specific mode is set to a
1838 non-@code{nil} value when that minor mode is activated.
1840 @code{minor-mode-alist} itself is not buffer-local. Each variable
1841 mentioned in the alist should be buffer-local if its minor mode can be
1842 enabled separately in each buffer.
1845 @defvar global-mode-string
1846 This variable holds a mode-line spec that, by default, appears in the
1847 mode line just after the @code{which-func-mode} minor mode if set,
1848 else after @code{mode-line-modes}. The command @code{display-time}
1849 sets @code{global-mode-string} to refer to the variable
1850 @code{display-time-string}, which holds a string containing the time
1851 and load information.
1853 The @samp{%M} construct substitutes the value of
1854 @code{global-mode-string}, but that is obsolete, since the variable is
1855 included in the mode line from @code{mode-line-format}.
1858 The variable @code{default-mode-line-format} is where
1859 @code{mode-line-format} usually gets its value:
1861 @defvar default-mode-line-format
1862 This variable holds the default @code{mode-line-format} for buffers
1863 that do not override it. This is the same as @code{(default-value
1864 'mode-line-format)}.
1866 Here is a simplified version of the default value of
1867 @code{default-mode-line-format}. The real default value also
1868 specifies addition of text properties.
1875 mode-line-frame-identification
1876 mode-line-buffer-identification
1884 (which-func-mode ("" which-func-format "--"))
1885 (global-mode-string ("--" global-mode-string))
1892 @subsection @code{%}-Constructs in the Mode Line
1894 The following table lists the recognized @code{%}-constructs and what
1895 they mean. In any construct except @samp{%%}, you can add a decimal
1896 integer after the @samp{%} to specify a minimum field width. If the
1897 width is less, the field is padded with spaces to the right.
1901 The current buffer name, obtained with the @code{buffer-name} function.
1902 @xref{Buffer Names}.
1905 The current column number of point.
1908 The visited file name, obtained with the @code{buffer-file-name}
1909 function. @xref{Buffer File Name}.
1912 The title (only on a window system) or the name of the selected frame.
1913 @xref{Window Frame Parameters}.
1916 The size of the accessible part of the current buffer; basically
1917 @code{(- (point-max) (point-min))}.
1920 Like @samp{%i}, but the size is printed in a more readable way by using
1921 @samp{k} for 10^3, @samp{M} for 10^6, @samp{G} for 10^9, etc., to
1925 The current line number of point, counting within the accessible portion
1929 @samp{Narrow} when narrowing is in effect; nothing otherwise (see
1930 @code{narrow-to-region} in @ref{Narrowing}).
1933 The percentage of the buffer text above the @strong{top} of window, or
1934 @samp{Top}, @samp{Bottom} or @samp{All}. Note that the default
1935 mode-line specification truncates this to three characters.
1938 The percentage of the buffer text that is above the @strong{bottom} of
1939 the window (which includes the text visible in the window, as well as
1940 the text above the top), plus @samp{Top} if the top of the buffer is
1941 visible on screen; or @samp{Bottom} or @samp{All}.
1944 The status of the subprocess belonging to the current buffer, obtained with
1945 @code{process-status}. @xref{Process Information}.
1948 Whether the visited file is a text file or a binary file. This is a
1949 meaningful distinction only on certain operating systems (@pxref{MS-DOS
1953 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
1954 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
1955 @samp{-} otherwise. @xref{Buffer Modification}.
1958 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
1959 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
1960 @samp{-} otherwise. This differs from @samp{%*} only for a modified
1961 read-only buffer. @xref{Buffer Modification}.
1964 @samp{*} if the buffer is modified, and @samp{-} otherwise.
1967 An indication of the depth of recursive editing levels (not counting
1968 minibuffer levels): one @samp{[} for each editing level.
1969 @xref{Recursive Editing}.
1972 One @samp{]} for each recursive editing level (not counting minibuffer
1976 Dashes sufficient to fill the remainder of the mode line.
1979 The character @samp{%}---this is how to include a literal @samp{%} in a
1980 string in which @code{%}-constructs are allowed.
1983 The following two @code{%}-constructs are still supported, but they are
1984 obsolete, since you can get the same results with the variables
1985 @code{mode-name} and @code{global-mode-string}.
1989 The value of @code{mode-name}.
1992 The value of @code{global-mode-string}. Currently, only
1993 @code{display-time} modifies the value of @code{global-mode-string}.
1996 @node Properties in Mode
1997 @subsection Properties in the Mode Line
1998 @cindex text properties in the mode line
2000 Certain text properties are meaningful in the
2001 mode line. The @code{face} property affects the appearance of text; the
2002 @code{help-echo} property associates help strings with the text, and
2003 @code{local-map} can make the text mouse-sensitive.
2005 There are four ways to specify text properties for text in the mode
2010 Put a string with a text property directly into the mode-line data
2014 Put a text property on a mode-line %-construct such as @samp{%12b}; then
2015 the expansion of the %-construct will have that same text property.
2018 Use a @code{(:propertize @var{elt} @var{props}@dots{})} construct to
2019 give @var{elt} a text property specified by @var{props}.
2022 Use a list containing @code{:eval @var{form}} in the mode-line data
2023 structure, and make @var{form} evaluate to a string that has a text
2027 You use the @code{local-map} property to specify a keymap. Like any
2028 keymap, it can bind character keys and function keys; but that has no
2029 effect, since it is impossible to move point into the mode line. This
2030 keymap can only take real effect for mouse clicks.
2032 When the mode line refers to a variable which does not have a
2033 non-@code{nil} @code{risky-local-variable} property, any text
2034 properties given or specified within that variable's values are
2035 ignored. This is because such properties could otherwise specify
2036 functions to be called, and those functions could come from file
2040 @subsection Window Header Lines
2041 @cindex header line (of a window)
2042 @cindex window header line
2044 A window can have a @dfn{header line} at the
2045 top, just as it can have a mode line at the bottom. The header line
2046 feature works just like the mode-line feature, except that it's
2047 controlled by different variables.
2049 @tindex header-line-format
2050 @defvar header-line-format
2051 This variable, local in every buffer, specifies how to display the
2052 header line, for windows displaying the buffer. The format of the value
2053 is the same as for @code{mode-line-format} (@pxref{Mode Line Data}).
2056 @tindex default-header-line-format
2057 @defvar default-header-line-format
2058 This variable holds the default @code{header-line-format} for buffers
2059 that do not override it. This is the same as @code{(default-value
2060 'header-line-format)}.
2062 It is normally @code{nil}, so that ordinary buffers have no header line.
2065 @node Emulating Mode Line
2066 @subsection Emulating Mode-Line Formatting
2068 You can use the function @code{format-mode-line} to compute
2069 the text that would appear in a mode line or header line
2070 based on a certain mode-line specification.
2072 @defun format-mode-line format &optional face window buffer
2073 This function formats a line of text according to @var{format} as if
2074 it were generating the mode line for @var{window}, but instead of
2075 displaying the text in the mode line or the header line, it returns
2076 the text as a string. The argument @var{window} defaults to the
2077 selected window. If @var{buffer} is non-@code{nil}, all the
2078 information used is taken from @var{buffer}; by default, it comes from
2079 @var{window}'s buffer.
2081 The value string normally has text properties that correspond to the
2082 faces, keymaps, etc., that the mode line would have. And any character
2083 for which no @code{face} property is specified gets a default
2084 value which is usually @var{face}. (If @var{face} is @code{t},
2085 that stands for either @code{mode-line} if @var{window} is selected,
2086 otherwise @code{mode-line-inactive}. If @var{face} is @code{nil} or
2087 omitted, that stands for no face property.)
2089 However, if @var{face} is an integer, the value has no text properties.
2091 For example, @code{(format-mode-line header-line-format)} returns the
2092 text that would appear in the selected window's header line (@code{""}
2093 if it has no header line). @code{(format-mode-line header-line-format
2094 'header-line)} returns the same text, with each character
2095 carrying the face that it will have in the header line itself.
2102 @dfn{Imenu} is a feature that lets users select a definition or
2103 section in the buffer, from a menu which lists all of them, to go
2104 directly to that location in the buffer. Imenu works by constructing
2105 a buffer index which lists the names and buffer positions of the
2106 definitions, or other named portions of the buffer; then the user can
2107 choose one of them and move point to it. Major modes can add a menu
2108 bar item to use Imenu using @code{imenu-add-to-menubar}.
2110 @defun imenu-add-to-menubar name
2111 This function defines a local menu bar item named @var{name}
2115 The user-level commands for using Imenu are described in the Emacs
2116 Manual (@pxref{Imenu,, Imenu, emacs, the Emacs Manual}). This section
2117 explains how to customize Imenu's method of finding definitions or
2118 buffer portions for a particular major mode.
2120 The usual and simplest way is to set the variable
2121 @code{imenu-generic-expression}:
2123 @defvar imenu-generic-expression
2124 This variable, if non-@code{nil}, is a list that specifies regular
2125 expressions for finding definitions for Imenu. Simple elements of
2126 @code{imenu-generic-expression} look like this:
2129 (@var{menu-title} @var{regexp} @var{index})
2132 Here, if @var{menu-title} is non-@code{nil}, it says that the matches
2133 for this element should go in a submenu of the buffer index;
2134 @var{menu-title} itself specifies the name for the submenu. If
2135 @var{menu-title} is @code{nil}, the matches for this element go directly
2136 in the top level of the buffer index.
2138 The second item in the list, @var{regexp}, is a regular expression
2139 (@pxref{Regular Expressions}); anything in the buffer that it matches
2140 is considered a definition, something to mention in the buffer index.
2141 The third item, @var{index}, is a non-negative integer that indicates
2142 which subexpression in @var{regexp} matches the definition's name.
2144 An element can also look like this:
2147 (@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{})
2150 Like in the previous case, each match for this element creates an
2151 index item. However, if this index item is selected by the user, it
2152 calls @var{function} with arguments consisting of the item name, the
2153 buffer position, and @var{arguments}.
2155 For Emacs Lisp mode, @code{imenu-generic-expression} could look like
2158 @c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]
2161 ((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
2162 \\s-+\\([-A-Za-z0-9+]+\\)" 2)
2165 ("*Vars*" "^\\s-*(def\\(var\\|const\\)\
2166 \\s-+\\([-A-Za-z0-9+]+\\)" 2)
2171 (def\\(type\\|struct\\|class\\|ine-condition\\)\
2172 \\s-+\\([-A-Za-z0-9+]+\\)" 2))
2176 Setting this variable makes it buffer-local in the current buffer.
2179 @defvar imenu-case-fold-search
2180 This variable controls whether matching against the regular
2181 expressions in the value of @code{imenu-generic-expression} is
2182 case-sensitive: @code{t}, the default, means matching should ignore
2185 Setting this variable makes it buffer-local in the current buffer.
2188 @defvar imenu-syntax-alist
2189 This variable is an alist of syntax table modifiers to use while
2190 processing @code{imenu-generic-expression}, to override the syntax table
2191 of the current buffer. Each element should have this form:
2194 (@var{characters} . @var{syntax-description})
2197 The @sc{car}, @var{characters}, can be either a character or a string.
2198 The element says to give that character or characters the syntax
2199 specified by @var{syntax-description}, which is passed to
2200 @code{modify-syntax-entry} (@pxref{Syntax Table Functions}).
2202 This feature is typically used to give word syntax to characters which
2203 normally have symbol syntax, and thus to simplify
2204 @code{imenu-generic-expression} and speed up matching.
2205 For example, Fortran mode uses it this way:
2208 (setq imenu-syntax-alist '(("_$" . "w")))
2211 The @code{imenu-generic-expression} regular expressions can then use
2212 @samp{\\sw+} instead of @samp{\\(\\sw\\|\\s_\\)+}. Note that this
2213 technique may be inconvenient when the mode needs to limit the initial
2214 character of a name to a smaller set of characters than are allowed in
2217 Setting this variable makes it buffer-local in the current buffer.
2220 Another way to customize Imenu for a major mode is to set the
2221 variables @code{imenu-prev-index-position-function} and
2222 @code{imenu-extract-index-name-function}:
2224 @defvar imenu-prev-index-position-function
2225 If this variable is non-@code{nil}, its value should be a function that
2226 finds the next ``definition'' to put in the buffer index, scanning
2227 backward in the buffer from point. It should return @code{nil} if it
2228 doesn't find another ``definition'' before point. Otherwise it should
2229 leave point at the place it finds a ``definition,'' and return any
2230 non-@code{nil} value.
2232 Setting this variable makes it buffer-local in the current buffer.
2235 @defvar imenu-extract-index-name-function
2236 If this variable is non-@code{nil}, its value should be a function to
2237 return the name for a definition, assuming point is in that definition
2238 as the @code{imenu-prev-index-position-function} function would leave
2241 Setting this variable makes it buffer-local in the current buffer.
2244 The last way to customize Imenu for a major mode is to set the
2245 variable @code{imenu-create-index-function}:
2247 @defvar imenu-create-index-function
2248 This variable specifies the function to use for creating a buffer
2249 index. The function should take no arguments, and return an index
2250 alist for the current buffer. It is called within
2251 @code{save-excursion}, so where it leaves point makes no difference.
2253 The index alist can have three types of elements. Simple elements
2257 (@var{index-name} . @var{index-position})
2260 Selecting a simple element has the effect of moving to position
2261 @var{index-position} in the buffer. Special elements look like this:
2264 (@var{index-name} @var{index-position} @var{function} @var{arguments}@dots{})
2267 Selecting a special element performs:
2270 (funcall @var{function}
2271 @var{index-name} @var{index-position} @var{arguments}@dots{})
2274 A nested sub-alist element looks like this:
2277 (@var{menu-title} @var{sub-alist})
2280 It creates the submenu @var{menu-title} specified by @var{sub-alist}.
2282 The default value of @code{imenu-create-index-function} is
2283 @code{imenu-default-create-index-function}. This function uses
2284 @code{imenu-prev-index-position-function} and
2285 @code{imenu-extract-index-name-function} to produce the index alist.
2286 However, if either of these two variables is @code{nil}, the default
2287 function uses @code{imenu-generic-expression} instead.
2289 Setting this variable makes it buffer-local in the current buffer.
2292 @node Font Lock Mode
2293 @section Font Lock Mode
2294 @cindex Font Lock Mode
2296 @dfn{Font Lock mode} is a feature that automatically attaches
2297 @code{face} properties to certain parts of the buffer based on their
2298 syntactic role. How it parses the buffer depends on the major mode;
2299 most major modes define syntactic criteria for which faces to use in
2300 which contexts. This section explains how to customize Font Lock for a
2301 particular major mode.
2303 Font Lock mode finds text to highlight in two ways: through
2304 syntactic parsing based on the syntax table, and through searching
2305 (usually for regular expressions). Syntactic fontification happens
2306 first; it finds comments and string constants and highlights them.
2307 Search-based fontification happens second.
2310 * Font Lock Basics:: Overview of customizing Font Lock.
2311 * Search-based Fontification:: Fontification based on regexps.
2312 * Other Font Lock Variables:: Additional customization facilities.
2313 * Levels of Font Lock:: Each mode can define alternative levels
2314 so that the user can select more or less.
2315 * Precalculated Fontification:: How Lisp programs that produce the buffer
2316 contents can also specify how to fontify it.
2317 * Faces for Font Lock:: Special faces specifically for Font Lock.
2318 * Syntactic Font Lock:: Fontification based on syntax tables.
2319 * Setting Syntax Properties:: Defining character syntax based on context
2320 using the Font Lock mechanism.
2323 @node Font Lock Basics
2324 @subsection Font Lock Basics
2326 There are several variables that control how Font Lock mode highlights
2327 text. But major modes should not set any of these variables directly.
2328 Instead, they should set @code{font-lock-defaults} as a buffer-local
2329 variable. The value assigned to this variable is used, if and when Font
2330 Lock mode is enabled, to set all the other variables.
2332 @defvar font-lock-defaults
2333 This variable is set by major modes, as a buffer-local variable, to
2334 specify how to fontify text in that mode. It automatically becomes
2335 buffer-local when you set it. The value should look like this:
2338 (@var{keywords} [@var{keywords-only} [@var{case-fold}
2339 [@var{syntax-alist} [@var{syntax-begin} @var{other-vars}@dots{}]]]])
2342 The first element, @var{keywords}, indirectly specifies the value of
2343 @code{font-lock-keywords} which directs search-based fontification.
2344 It can be a symbol, a variable or a function whose value is the list
2345 to use for @code{font-lock-keywords}. It can also be a list of
2346 several such symbols, one for each possible level of fontification.
2347 The first symbol specifies how to do level 1 fontification, the second
2348 symbol how to do level 2, and so on. @xref{Levels of Font Lock}.
2350 The second element, @var{keywords-only}, specifies the value of the
2351 variable @code{font-lock-keywords-only}. If this is non-@code{nil},
2352 syntactic fontification (of strings and comments) is not performed.
2353 @xref{Syntactic Font Lock}.
2355 The third element, @var{case-fold}, specifies the value of
2356 @code{font-lock-keywords-case-fold-search}. If it is non-@code{nil},
2357 Font Lock mode ignores case when searching as directed by
2358 @code{font-lock-keywords}.
2360 If the fourth element, @var{syntax-alist}, is non-@code{nil}, it
2361 should be a list of cons cells of the form @code{(@var{char-or-string}
2362 . @var{string})}. These are used to set up a syntax table for
2363 syntactic fontification (@pxref{Syntax Table Functions}). The
2364 resulting syntax table is stored in @code{font-lock-syntax-table}.
2366 The fifth element, @var{syntax-begin}, specifies the value of
2367 @code{font-lock-beginning-of-syntax-function}.
2369 All the remaining elements (if any) are collectively called
2370 @var{other-vars}. Each of these elements should have the form
2371 @code{(@var{variable} . @var{value})}---which means, make
2372 @var{variable} buffer-local and then set it to @var{value}. You can
2373 use these @var{other-vars} to set other variables that affect
2374 fontification, aside from those you can control with the first five
2375 elements. @xref{Other Font Lock Variables}.
2378 @node Search-based Fontification
2379 @subsection Search-based Fontification
2381 The most important variable for customizing Font Lock mode is
2382 @code{font-lock-keywords}. It specifies the search criteria for
2383 search-based fontification. You should specify the value of this
2384 variable with @var{keywords} in @code{font-lock-defaults}.
2386 @defvar font-lock-keywords
2387 This variable's value is a list of the keywords to highlight. Be
2388 careful when composing regular expressions for this list; a poorly
2389 written pattern can dramatically slow things down!
2392 Each element of @code{font-lock-keywords} specifies how to find
2393 certain cases of text, and how to highlight those cases. Font Lock mode
2394 processes the elements of @code{font-lock-keywords} one by one, and for
2395 each element, it finds and handles all matches. Ordinarily, once
2396 part of the text has been fontified already, this cannot be overridden
2397 by a subsequent match in the same text; but you can specify different
2398 behavior using the @var{override} element of a @var{subexp-highlighter}.
2400 Each element of @code{font-lock-keywords} should have one of these
2405 Highlight all matches for @var{regexp} using
2406 @code{font-lock-keyword-face}. For example,
2409 ;; @r{Highlight occurrences of the word @samp{foo}}
2410 ;; @r{using @code{font-lock-keyword-face}.}
2414 The function @code{regexp-opt} (@pxref{Regexp Functions}) is useful
2415 for calculating optimal regular expressions to match a number of
2418 @item @var{function}
2419 Find text by calling @var{function}, and highlight the matches
2420 it finds using @code{font-lock-keyword-face}.
2422 When @var{function} is called, it receives one argument, the limit of
2423 the search; it should begin searching at point, and not search beyond the
2424 limit. It should return non-@code{nil} if it succeeds, and set the
2425 match data to describe the match that was found. Returning @code{nil}
2426 indicates failure of the search.
2428 Fontification will call @var{function} repeatedly with the same limit,
2429 and with point where the previous invocation left it, until
2430 @var{function} fails. On failure, @var{function} need not reset point
2431 in any particular way.
2433 @item (@var{matcher} . @var{subexp})
2434 In this kind of element, @var{matcher} is either a regular
2435 expression or a function, as described above. The @sc{cdr},
2436 @var{subexp}, specifies which subexpression of @var{matcher} should be
2437 highlighted (instead of the entire text that @var{matcher} matched).
2440 ;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},}
2441 ;; @r{using @code{font-lock-keyword-face}.}
2445 If you use @code{regexp-opt} to produce the regular expression
2446 @var{matcher}, then you can use @code{regexp-opt-depth} (@pxref{Regexp
2447 Functions}) to calculate the value for @var{subexp}.
2449 @item (@var{matcher} . @var{facespec})
2450 In this kind of element, @var{facespec} is an expression whose value
2451 specifies the face to use for highlighting. In the simplest case,
2452 @var{facespec} is a Lisp variable (a symbol) whose value is a face
2456 ;; @r{Highlight occurrences of @samp{fubar},}
2457 ;; @r{using the face which is the value of @code{fubar-face}.}
2458 ("fubar" . fubar-face)
2461 However, @var{facespec} can also evaluate to a list of this form:
2464 (face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{})
2468 to specify the face @var{face} and various additional text properties
2469 to put on the text that matches. If you do this, be sure to add the
2470 other text property names that you set in this way to the value of
2471 @code{font-lock-extra-managed-props} so that the properties will also
2472 be cleared out when they are no longer appropriate. Alternatively,
2473 you can set the variable @code{font-lock-unfontify-region-function} to
2474 a function that clears these properties. @xref{Other Font Lock
2477 @item (@var{matcher} . @var{subexp-highlighter})
2478 In this kind of element, @var{subexp-highlighter} is a list
2479 which specifies how to highlight matches found by @var{matcher}.
2483 (@var{subexp} @var{facespec} [[@var{override} [@var{laxmatch}]])
2486 The @sc{car}, @var{subexp}, is an integer specifying which subexpression
2487 of the match to fontify (0 means the entire matching text). The second
2488 subelement, @var{facespec}, is an expression whose value specifies the
2489 face, as described above.
2491 The last two values in @var{subexp-highlighter}, @var{override} and
2492 @var{laxmatch}, are optional flags. If @var{override} is @code{t},
2493 this element can override existing fontification made by previous
2494 elements of @code{font-lock-keywords}. If it is @code{keep}, then
2495 each character is fontified if it has not been fontified already by
2496 some other element. If it is @code{prepend}, the face specified by
2497 @var{facespec} is added to the beginning of the @code{font-lock-face}
2498 property. If it is @code{append}, the face is added to the end of the
2499 @code{font-lock-face} property.
2501 If @var{laxmatch} is non-@code{nil}, it means there should be no error
2502 if there is no subexpression numbered @var{subexp} in @var{matcher}.
2503 Obviously, fontification of the subexpression numbered @var{subexp} will
2504 not occur. However, fontification of other subexpressions (and other
2505 regexps) will continue. If @var{laxmatch} is @code{nil}, and the
2506 specified subexpression is missing, then an error is signaled which
2507 terminates search-based fontification.
2509 Here are some examples of elements of this kind, and what they do:
2512 ;; @r{Highlight occurrences of either @samp{foo} or @samp{bar}, using}
2513 ;; @r{@code{foo-bar-face}, even if they have already been highlighted.}
2514 ;; @r{@code{foo-bar-face} should be a variable whose value is a face.}
2515 ("foo\\|bar" 0 foo-bar-face t)
2517 ;; @r{Highlight the first subexpression within each occurrence}
2518 ;; @r{that the function @code{fubar-match} finds,}
2519 ;; @r{using the face which is the value of @code{fubar-face}.}
2520 (fubar-match 1 fubar-face)
2523 @item (@var{matcher} . @var{anchored-highlighter})
2524 In this kind of element, @var{anchored-highlighter} specifies how to
2525 highlight text that follows a match found by @var{matcher}. So a
2526 match found by @var{matcher} acts as the anchor for further searches
2527 specified by @var{anchored-highlighter}. @var{anchored-highlighter}
2528 is a list of the following form:
2531 (@var{anchored-matcher} @var{pre-form} @var{post-form}
2532 @var{subexp-highlighters}@dots{})
2535 Here, @var{anchored-matcher}, like @var{matcher}, is either a regular
2536 expression or a function. After a match of @var{matcher} is found,
2537 point is at the end of the match. Now, Font Lock evaluates the form
2538 @var{pre-form}. Then it searches for matches of
2539 @var{anchored-matcher} and uses @var{subexp-highlighters} to highlight
2540 these. A @var{subexp-highlighter} is as described above. Finally,
2541 Font Lock evaluates @var{post-form}.
2543 The forms @var{pre-form} and @var{post-form} can be used to initialize
2544 before, and cleanup after, @var{anchored-matcher} is used. Typically,
2545 @var{pre-form} is used to move point to some position relative to the
2546 match of @var{matcher}, before starting with @var{anchored-matcher}.
2547 @var{post-form} might be used to move back, before resuming with
2550 After Font Lock evaluates @var{pre-form}, it does not search for
2551 @var{anchored-matcher} beyond the end of the line. However, if
2552 @var{pre-form} returns a buffer position that is greater than the
2553 position of point after @var{pre-form} is evaluated, then the position
2554 returned by @var{pre-form} is used as the limit of the search instead.
2555 It is generally a bad idea to return a position greater than the end
2556 of the line; in other words, the @var{anchored-matcher} search should
2562 ;; @r{Highlight occurrences of the word @samp{item} following}
2563 ;; @r{an occurrence of the word @samp{anchor} (on the same line)}
2564 ;; @r{in the value of @code{item-face}.}
2565 ("\\<anchor\\>" "\\<item\\>" nil nil (0 item-face))
2568 Here, @var{pre-form} and @var{post-form} are @code{nil}. Therefore
2569 searching for @samp{item} starts at the end of the match of
2570 @samp{anchor}, and searching for subsequent instances of @samp{anchor}
2571 resumes from where searching for @samp{item} concluded.
2573 @item (@var{matcher} @var{highlighters}@dots{})
2574 This sort of element specifies several @var{highlighter} lists for a
2575 single @var{matcher}. A @var{highlighter} list can be of the type
2576 @var{subexp-highlighter} or @var{anchored-highlighter} as described
2582 ;; @r{Highlight occurrences of the word @samp{anchor} in the value}
2583 ;; @r{of @code{anchor-face}, and subsequent occurrences of the word}
2584 ;; @r{@samp{item} (on the same line) in the value of @code{item-face}.}
2585 ("\\<anchor\\>" (0 anchor-face)
2586 ("\\<item\\>" nil nil (0 item-face)))
2589 @item (eval . @var{form})
2590 Here @var{form} is an expression to be evaluated the first time
2591 this value of @code{font-lock-keywords} is used in a buffer.
2592 Its value should have one of the forms described in this table.
2595 @vindex font-lock-multiline
2596 @strong{Warning:} Do not design an element of @code{font-lock-keywords}
2597 to match text which spans lines; this does not work reliably. While
2598 @code{font-lock-fontify-buffer} handles multi-line patterns correctly,
2599 updating when you edit the buffer does not, since it considers text one
2600 line at a time. If you have patterns that typically only span one
2601 line but can occasionally span two or three, such as
2602 @samp{<title>...</title>}, you can ask Font Lock to be more careful by
2603 setting @code{font-lock-multiline} to @code{t}. But it still will not
2606 You can use @var{case-fold} in @code{font-lock-defaults} to specify
2607 the value of @code{font-lock-keywords-case-fold-search} which says
2608 whether search-based fontification should be case-insensitive.
2610 @defvar font-lock-keywords-case-fold-search
2611 Non-@code{nil} means that regular expression matching for the sake of
2612 @code{font-lock-keywords} should be case-insensitive.
2615 You can use @code{font-lock-add-keywords} to add additional
2616 search-based fontification rules to a major mode, and
2617 @code{font-lock-remove-keywords} to removes rules.
2619 @defun font-lock-add-keywords mode keywords &optional append
2620 This function adds highlighting @var{keywords} for @var{mode}. The
2621 argument @var{keywords} should be a list with the same format as the
2622 variable @code{font-lock-keywords}. @var{mode} should be a symbol,
2623 the major mode command name, such as @code{c-mode}. When Font Lock
2624 mode is turned on in @var{mode}, it adds @var{keywords} to
2625 @code{font-lock-keywords}. @var{mode} can also be @code{nil}; the
2626 highlighting @var{keywords} are immediately added to
2627 @code{font-lock-keywords} in the current buffer in that case.
2629 By default, @var{keywords} are added at the beginning of
2630 @code{font-lock-keywords}. If the optional argument @var{append} is
2631 @code{set}, they are used to replace the value of
2632 @code{font-lock-keywords}. If @var{append} is any other
2633 non-@code{nil} value, they are added at the end of
2634 @code{font-lock-keywords}.
2639 (font-lock-add-keywords 'c-mode
2640 '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
2641 ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face)))
2644 adds two fontification patterns for C mode: one to fontify the word
2645 @samp{FIXME}, even in comments, and another to fontify the words
2646 @samp{and}, @samp{or} and @samp{not} as keywords.
2648 Some modes have specialized support for additional patterns. See the
2649 variables @code{c-font-lock-extra-types},
2650 @code{c++-font-lock-extra-types}, @code{objc-font-lock-extra-types}
2651 and @code{java-font-lock-extra-types}, for example.
2654 @defun font-lock-remove-keywords mode keywords
2655 This function removes highlighting @var{keywords} for @var{mode}. As
2656 in @code{font-lock-add-keywords}, @var{mode} should be a major mode
2657 command name or @code{nil}. If @code{nil}, the highlighting
2658 @var{keywords} are immediately removed in the current buffer.
2661 @strong{Warning:} Only use a non-@code{nil} @var{mode} argument when
2662 you use @code{font-lock-add-keywords} or
2663 @code{font-lock-remove-keywords} in your @file{.emacs} file. When you
2664 use these functions from a Lisp program (such as a minor mode), we
2665 recommend that you use @code{nil} for @var{mode} (and place the call
2666 on a hook) to avoid subtle problems due to the details of the
2669 @node Other Font Lock Variables
2670 @subsection Other Font Lock Variables
2672 This section describes additional variables that a major mode can
2673 set by means of @var{other-vars} in @code{font-lock-defaults}
2674 (@pxref{Font Lock Basics}).
2676 @defvar font-lock-mark-block-function
2677 If this variable is non-@code{nil}, it should be a function that is
2678 called with no arguments, to choose an enclosing range of text for
2679 refontification for the command @kbd{M-o M-o}
2680 (@code{font-lock-fontify-block}).
2682 The function should report its choice by placing the region around it.
2683 A good choice is a range of text large enough to give proper results,
2684 but not too large so that refontification becomes slow. Typical values
2685 are @code{mark-defun} for programming modes or @code{mark-paragraph} for
2689 @defvar font-lock-extra-managed-props
2690 This variable specifies additional properties (other than
2691 @code{font-lock-face}) that are being managed by Font Lock mode. It
2692 is used by @code{font-lock-default-unfontify-region}, which normally
2693 only manages the @code{font-lock-face} property. If you want Font
2694 Lock to manage other properties as well, you must specify them in a
2695 @var{facespec} in @code{font-lock-keywords} as well as add them to
2696 this list. @xref{Search-based Fontification}.
2699 @defvar font-lock-fontify-buffer-function
2700 Function to use for fontifying the buffer. The default value is
2701 @code{font-lock-default-fontify-buffer}.
2704 @defvar font-lock-unfontify-buffer-function
2705 Function to use for unfontifying the buffer. This is used when
2706 turning off Font Lock mode. The default value is
2707 @code{font-lock-default-unfontify-buffer}.
2710 @defvar font-lock-fontify-region-function
2711 Function to use for fontifying a region. It should take two
2712 arguments, the beginning and end of the region, and an optional third
2713 argument @var{verbose}. If @var{verbose} is non-@code{nil}, the
2714 function should print status messages. The default value is
2715 @code{font-lock-default-fontify-region}.
2718 @defvar font-lock-unfontify-region-function
2719 Function to use for unfontifying a region. It should take two
2720 arguments, the beginning and end of the region. The default value is
2721 @code{font-lock-default-unfontify-region}.
2724 @defvar font-lock-lines-before
2725 This variable specifies the number of extra lines to consider when
2726 refontifying the buffer after each text change. Font lock begins
2727 refontifying from that number of lines before the changed region. The
2728 default is 1, but using a larger value can be useful for coping with
2729 multi-line patterns.
2733 @defvar font-lock-inhibit-thing-lock
2734 List of Font Lock mode related modes that should not be turned on.
2735 Currently, valid mode names are @code{fast-lock-mode},
2736 @code{jit-lock-mode} and @code{lazy-lock-mode}.
2740 @node Levels of Font Lock
2741 @subsection Levels of Font Lock
2743 Many major modes offer three different levels of fontification. You
2744 can define multiple levels by using a list of symbols for @var{keywords}
2745 in @code{font-lock-defaults}. Each symbol specifies one level of
2746 fontification; it is up to the user to choose one of these levels. The
2747 chosen level's symbol value is used to initialize
2748 @code{font-lock-keywords}.
2750 Here are the conventions for how to define the levels of
2755 Level 1: highlight function declarations, file directives (such as include or
2756 import directives), strings and comments. The idea is speed, so only
2757 the most important and top-level components are fontified.
2760 Level 2: in addition to level 1, highlight all language keywords,
2761 including type names that act like keywords, as well as named constant
2762 values. The idea is that all keywords (either syntactic or semantic)
2763 should be fontified appropriately.
2766 Level 3: in addition to level 2, highlight the symbols being defined in
2767 function and variable declarations, and all builtin function names,
2768 wherever they appear.
2771 @node Precalculated Fontification
2772 @subsection Precalculated Fontification
2774 In addition to using @code{font-lock-defaults} for search-based
2775 fontification, you may use the special character property
2776 @code{font-lock-face} (@pxref{Special Properties}). This property
2777 acts just like the explicit @code{face} property, but its activation
2778 is toggled when the user calls @kbd{M-x font-lock-mode}. Using
2779 @code{font-lock-face} is especially convenient for special modes
2780 which construct their text programmatically, such as
2781 @code{list-buffers} and @code{occur}.
2783 If your mode does not use any of the other machinery of Font Lock
2784 (i.e. it only uses the @code{font-lock-face} property), it should not
2785 set the variable @code{font-lock-defaults}. That way, it will not
2786 cause loading of the @file{font-lock} library.
2788 @node Faces for Font Lock
2789 @subsection Faces for Font Lock
2791 You can make Font Lock mode use any face, but several faces are
2792 defined specifically for Font Lock mode. Each of these symbols is both
2793 a face name, and a variable whose default value is the symbol itself.
2794 Thus, the default value of @code{font-lock-comment-face} is
2795 @code{font-lock-comment-face}. This means you can write
2796 @code{font-lock-comment-face} in a context such as
2797 @code{font-lock-keywords} where a face-name-valued expression is used.
2800 @item font-lock-comment-face
2801 @vindex font-lock-comment-face
2802 Used (typically) for comments.
2804 @item font-lock-comment-delimiter-face
2805 @vindex font-lock-comment-delimiter-face
2806 Used (typically) for comments delimiters.
2808 @item font-lock-doc-face
2809 @vindex font-lock-doc-face
2810 Used (typically) for documentation strings in the code.
2812 @item font-lock-string-face
2813 @vindex font-lock-string-face
2814 Used (typically) for string constants.
2816 @item font-lock-keyword-face
2817 @vindex font-lock-keyword-face
2818 Used (typically) for keywords---names that have special syntactic
2819 significance, like @code{for} and @code{if} in C.
2821 @item font-lock-builtin-face
2822 @vindex font-lock-builtin-face
2823 Used (typically) for built-in function names.
2825 @item font-lock-function-name-face
2826 @vindex font-lock-function-name-face
2827 Used (typically) for the name of a function being defined or declared,
2828 in a function definition or declaration.
2830 @item font-lock-variable-name-face
2831 @vindex font-lock-variable-name-face
2832 Used (typically) for the name of a variable being defined or declared,
2833 in a variable definition or declaration.
2835 @item font-lock-type-face
2836 @vindex font-lock-type-face
2837 Used (typically) for names of user-defined data types,
2838 where they are defined and where they are used.
2840 @item font-lock-constant-face
2841 @vindex font-lock-constant-face
2842 Used (typically) for constant names.
2844 @item font-lock-preprocessor-face
2845 @vindex font-lock-preprocessor-face
2846 Used (typically) for preprocessor commands.
2848 @item font-lock-warning-face
2849 @vindex font-lock-warning-face
2850 Used (typically) for constructs that are peculiar, or that greatly
2851 change the meaning of other text. For example, this is used for
2852 @samp{;;;###autoload} cookies in Emacs Lisp, and for @code{#error}
2856 @node Syntactic Font Lock
2857 @subsection Syntactic Font Lock
2859 Syntactic fontification uses the syntax table to find comments and
2860 string constants (@pxref{Syntax Tables}). It highlights them using
2861 @code{font-lock-comment-face} and @code{font-lock-string-face}
2862 (@pxref{Faces for Font Lock}). There are several variables that
2863 affect syntactic fontification; you should set them by means of
2864 @code{font-lock-defaults} (@pxref{Font Lock Basics}).
2866 @defvar font-lock-keywords-only
2867 Non-@code{nil} means Font Lock should not do syntactic fontification;
2868 it should only fontify based on @code{font-lock-keywords}. The normal
2869 way for a mode to set this variable to @code{t} is with
2870 @var{keywords-only} in @code{font-lock-defaults}.
2873 @defvar font-lock-syntax-table
2874 This variable holds the syntax table to use for fontification of
2875 comments and strings. Specify it using @var{syntax-alist} in
2876 @code{font-lock-defaults}.
2880 @c The docstring says that font-lock-syntax-table is semi-obsolete.
2881 @c How the alternative should be used is not clear. --lute
2883 @defvar font-lock-beginning-of-syntax-function
2884 If this variable is non-@code{nil}, it should be a function to move
2885 point back to a position that is syntactically at ``top level'' and
2886 outside of strings or comments. Font Lock uses this when necessary
2887 to get the right results for syntactic fontification.
2889 This function is called with no arguments. It should leave point at
2890 the beginning of any enclosing syntactic block. Typical values are
2891 @code{beginning-of-line} (used when the start of the line is known to
2892 be outside a syntactic block), or @code{beginning-of-defun} for
2893 programming modes, or @code{backward-paragraph} for textual modes.
2895 If the value is @code{nil}, the beginning of the buffer is used as a
2896 position outside of a syntactic block. This cannot be wrong, but it
2899 Specify this variable using @var{syntax-begin} in
2900 @code{font-lock-defaults}.
2903 @defvar font-lock-syntactic-face-function
2904 A function to determine which face to use for a given syntactic
2905 element (a string or a comment). The function is called with one
2906 argument, the parse state at point returned by
2907 @code{parse-partial-sexp}, and should return a face. The default
2908 value returns @code{font-lock-comment-face} for comments and
2909 @code{font-lock-string-face} for strings.
2911 This can be used to highlighting different kinds of strings or
2912 comments differently. It is also sometimes abused together with
2913 @code{font-lock-syntactic-keywords} to highlight elements that span
2914 multiple lines, but this is too obscure to document in this manual.
2916 Specify this variable using @var{other-vars} in
2917 @code{font-lock-defaults}.
2920 @node Setting Syntax Properties
2921 @subsection Setting Syntax Properties
2923 Font Lock mode can be used to update @code{syntax-table} properties
2924 automatically (@pxref{Syntax Properties}). This is useful in
2925 languages for which a single syntax table by itself is not sufficient.
2927 @defvar font-lock-syntactic-keywords
2928 This variable enables and controls updating @code{syntax-table}
2929 properties by Font Lock. Its value should be a list of elements of
2933 (@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch})
2936 The parts of this element have the same meanings as in the corresponding
2937 sort of element of @code{font-lock-keywords},
2940 (@var{matcher} @var{subexp} @var{facespec} @var{override} @var{laxmatch})
2943 However, instead of specifying the value @var{facespec} to use for the
2944 @code{face} property, it specifies the value @var{syntax} to use for
2945 the @code{syntax-table} property. Here, @var{syntax} can be a string
2946 (as taken by @code{modify-syntax-entry}), a syntax table, a cons cell
2947 (as returned by @code{string-to-syntax}), or an expression whose value
2948 is one of those two types. @var{override} cannot be @code{prepend} or
2951 For example, an element of the form:
2954 ("\\$\\(#\\)" 1 ".")
2957 highlights syntactically a hash character when following a dollar
2958 character, with a SYNTAX of @code{"."} (meaning punctuation syntax).
2959 Assuming that the buffer syntax table specifies hash characters to
2960 have comment start syntax, the element will only highlight hash
2961 characters that do not follow dollar characters as comments
2964 An element of the form:
2972 highlights syntactically both single quotes which surround a single
2973 character, with a SYNTAX of @code{"\""} (meaning string quote syntax).
2974 Assuming that the buffer syntax table does not specify single quotes
2975 to have quote syntax, the element will only highlight single quotes of
2976 the form @samp{'@var{c}'} as strings syntactically. Other forms, such
2977 as @samp{foo'bar} or @samp{'fubar'}, will not be highlighted as
2980 Major modes normally set this variable with @var{other-vars} in
2981 @code{font-lock-defaults}.
2984 @node Desktop Save Mode
2985 @section Desktop Save Mode
2986 @cindex desktop save mode
2988 @dfn{Desktop Save Mode} is a feature to save the state of Emacs from
2989 one session to another. The user-level commands for using Desktop
2990 Save Mode are described in the GNU Emacs Manual (@pxref{Saving Emacs
2991 Sessions,,, emacs, the GNU Emacs Manual}). Modes whose buffers visit
2992 a file, don't have to do anything to use this feature.
2994 For buffers not visiting a file to have their state saved, the major
2995 mode must bind the buffer local variable @code{desktop-save-buffer} to
2996 a non-@code{nil} value.
2998 @defvar desktop-save-buffer
2999 If this buffer-local variable is non-@code{nil}, the buffer will have
3000 its state saved in the desktop file at desktop save. If the value is
3001 a function, it is called at desktop save with argument
3002 @var{desktop-dirname}, and its value is saved in the desktop file along
3003 with the state of the buffer for which it was called. When file names
3004 are returned as part of the auxiliary information, they should be
3005 formatted using the call
3008 (desktop-file-name @var{file-name} @var{desktop-dirname})
3013 For buffers not visiting a file to be restored, the major mode must
3014 define a function to do the job, and that function must be listed in
3015 the alist @code{desktop-buffer-mode-handlers}.
3017 @defvar desktop-buffer-mode-handlers
3021 (@var{major-mode} . @var{restore-buffer-function})
3024 The function @var{restore-buffer-function} will be called with
3028 (@var{buffer-file-name} @var{buffer-name} @var{desktop-buffer-misc})
3031 and it should return the restored buffer.
3032 Here @var{desktop-buffer-misc} is the value returned by the function
3033 optionally bound to @code{desktop-save-buffer}.
3037 arch-tag: 4c7bff41-36e6-4da6-9e7f-9b9289e27c8e