*** empty log message ***
[emacs.git] / lispref / modes.texi
blob07725ab98707ee08bab60180c6163f8ed491d1a7
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003
4 @c   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
9 @cindex mode
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}.
22 @menu
23 * Major Modes::        Defining major modes.
24 * Minor Modes::        Defining minor modes.
25 * Mode Line Format::   Customizing the text that appears in the mode line.
26 * Imenu::              How a mode can provide a menu
27                          of definitions in the buffer.
28 * Font Lock Mode::     How modes can highlight text according to syntax.
29 * Hooks::              How to use hooks; how to write code that provides hooks.
30 @end menu
32 @node Major Modes
33 @section Major Modes
34 @cindex major mode
35 @cindex Fundamental mode
37   Major modes specialize Emacs for editing particular kinds of text.
38 Each buffer has only one major mode at a time.  For each major mode
39 there is a function to switch to that mode in the current buffer; its
40 name should end in @samp{-mode}.  These functions work by setting
41 buffer-local variable bindings and other data associated with the
42 buffer, such as a local keymap.  The effect lasts until you switch
43 to another major mode in the same buffer.
45   The least specialized major mode is called @dfn{Fundamental mode}.
46 This mode has no mode-specific definitions or variable settings, so each
47 Emacs command behaves in its default manner, and each option is in its
48 default state.  All other major modes redefine various keys and options.
49 For example, Lisp Interaction mode provides special key bindings for
50 @kbd{C-j} (@code{eval-print-last-sexp}), @key{TAB}
51 (@code{lisp-indent-line}), and other keys.
53   When you need to write several editing commands to help you perform a
54 specialized editing task, creating a new major mode is usually a good
55 idea.  In practice, writing a major mode is easy (in contrast to
56 writing a minor mode, which is often difficult).
58   If the new mode is similar to an old one, it is often unwise to modify
59 the old one to serve two purposes, since it may become harder to use and
60 maintain.  Instead, copy and rename an existing major mode definition
61 and alter the copy---or define a @dfn{derived mode} (@pxref{Derived
62 Modes}).  For example, Rmail Edit mode, which is in
63 @file{emacs/lisp/mail/rmailedit.el}, is a major mode that is very similar to
64 Text mode except that it provides two additional commands.  Its
65 definition is distinct from that of Text mode, but uses that of Text mode.
67   Even if the new mode is not an obvious derivative of any other mode,
68 it is convenient to use @code{define-derived-mode} with a @code{nil}
69 parent argument, since it automatically enforces the most important
70 coding conventions for you.
72 @findex define-generic-mode
73   For a very simple programming language major mode that handles
74 comments and fontification, you can use @code{define-generic-mode}
75 in @file{generic.el}.
77   Rmail Edit mode offers an example of changing the major mode
78 temporarily for a buffer, so it can be edited in a different way (with
79 ordinary Emacs commands rather than Rmail commands).  In such cases, the
80 temporary major mode usually provides a command to switch back to the
81 buffer's usual mode (Rmail mode, in this case).  You might be tempted to
82 present the temporary redefinitions inside a recursive edit and restore
83 the usual ones when the user exits; but this is a bad idea because it
84 constrains the user's options when it is done in more than one buffer:
85 recursive edits must be exited most-recently-entered first.  Using an
86 alternative major mode avoids this limitation.  @xref{Recursive
87 Editing}.
89   The standard GNU Emacs Lisp library directory tree contains the code
90 for several major modes, in files such as @file{text-mode.el},
91 @file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
92 @file{rmail.el}.  They are found in various subdirectories of the
93 @file{lisp} directory.  You can study these libraries to see how modes
94 are written.  Text mode is perhaps the simplest major mode aside from
95 Fundamental mode.  Rmail mode is a complicated and specialized mode.
97 @menu
98 * Major Mode Conventions::  Coding conventions for keymaps, etc.
99 * Example Major Modes::     Text mode and Lisp modes.
100 * Auto Major Mode::         How Emacs chooses the major mode automatically.
101 * Mode Help::               Finding out how to use a mode.
102 * Derived Modes::           Defining a new major mode based on another major
103                               mode.
104 @end menu
106 @node Major Mode Conventions
107 @subsection Major Mode Conventions
109   The code for existing major modes follows various coding conventions,
110 including conventions for local keymap and syntax table initialization,
111 global names, and hooks.  Please follow these conventions when you
112 define a new major mode.
114   This list of conventions is only partial, because each major mode
115 should aim for consistency in general with other Emacs major modes.
116 This makes Emacs as a whole more coherent.  It is impossible to list
117 here all the possible points where this issue might come up; if the
118 Emacs developers point out an area where your major mode deviates from
119 the usual conventions, please make it compatible.
121 @itemize @bullet
122 @item
123 Define a command whose name ends in @samp{-mode}, with no arguments,
124 that switches to the new mode in the current buffer.  This command
125 should set up the keymap, syntax table, and buffer-local variables in an
126 existing buffer, without changing the buffer's contents.
128 @item
129 Write a documentation string for this command that describes the
130 special commands available in this mode.  @kbd{C-h m}
131 (@code{describe-mode}) in your mode will display this string.
133 The documentation string may include the special documentation
134 substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
135 @samp{\<@var{keymap}>}, which enable the documentation to adapt
136 automatically to the user's own key bindings.  @xref{Keys in
137 Documentation}.
139 @item
140 The major mode command should start by calling
141 @code{kill-all-local-variables}.  This is what gets rid of the
142 buffer-local variables of the major mode previously in effect.
144 @item
145 The major mode command should set the variable @code{major-mode} to the
146 major mode command symbol.  This is how @code{describe-mode} discovers
147 which documentation to print.
149 @item
150 The major mode command should set the variable @code{mode-name} to the
151 ``pretty'' name of the mode, as a string.  This string appears in the
152 mode line.
154 @item
155 @cindex functions in modes
156 Since all global names are in the same name space, all the global
157 variables, constants, and functions that are part of the mode should
158 have names that start with the major mode name (or with an abbreviation
159 of it if the name is long).  @xref{Coding Conventions}.
161 @item
162 In a major mode for editing some kind of structured text, such as a
163 programming language, indentation of text according to structure is
164 probably useful.  So the mode should set @code{indent-line-function}
165 to a suitable function, and probably customize other variables
166 for indentation.
168 @item
169 @cindex keymaps in modes
170 The major mode should usually have its own keymap, which is used as the
171 local keymap in all buffers in that mode.  The major mode command should
172 call @code{use-local-map} to install this local map.  @xref{Active
173 Keymaps}, for more information.
175 This keymap should be stored permanently in a global variable named
176 @code{@var{modename}-mode-map}.  Normally the library that defines the
177 mode sets this variable.
179 @xref{Tips for Defining}, for advice about how to write the code to set
180 up the mode's keymap variable.
182 @item
183 The key sequences bound in a major mode keymap should usually start with
184 @kbd{C-c}, followed by a control character, a digit, or @kbd{@{},
185 @kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}.  The other punctuation
186 characters are reserved for minor modes, and ordinary letters are
187 reserved for users.
189 It is reasonable for a major mode to rebind a key sequence with a
190 standard meaning, if it implements a command that does ``the same job''
191 in a way that fits the major mode better.  For example, a major mode for
192 editing a programming language might redefine @kbd{C-M-a} to ``move to
193 the beginning of a function'' in a way that works better for that
194 language.
196 Major modes such as Dired or Rmail that do not allow self-insertion of
197 text can reasonably redefine letters and other printing characters as
198 editing commands.  Dired and Rmail both do this.
200 @item
201 Major modes must not define @key{RET} to do anything other than insert
202 a newline.  The command to insert a newline and then indent is
203 @kbd{C-j}.  Please keep this distinction uniform for all major modes.
205 @item
206 Major modes should not alter options that are primary a matter of user
207 preference, such as whether Auto-Fill mode is enabled.  Leave this to
208 each user to decide.  However, a major mode should customize other
209 variables so that Auto-Fill mode will work usefully @emph{if} the user
210 decides to use it.
212 @item
213 @cindex syntax tables in modes
214 The mode may have its own syntax table or may share one with other
215 related modes.  If it has its own syntax table, it should store this in
216 a variable named @code{@var{modename}-mode-syntax-table}.  @xref{Syntax
217 Tables}.
219 @item
220 If the mode handles a language that has a syntax for comments, it should
221 set the variables that define the comment syntax.  @xref{Options for
222 Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}.
224 @item
225 @cindex abbrev tables in modes
226 The mode may have its own abbrev table or may share one with other
227 related modes.  If it has its own abbrev table, it should store this in
228 a variable named @code{@var{modename}-mode-abbrev-table}.  @xref{Abbrev
229 Tables}.
231 @item
232 The mode should specify how to do highlighting for Font Lock mode, by
233 setting up a buffer-local value for the variable
234 @code{font-lock-defaults} (@pxref{Font Lock Mode}).
236 @item
237 The mode should specify how Imenu should find the definitions or
238 sections of a buffer, by setting up a buffer-local value for the
239 variable @code{imenu-generic-expression} or
240 @code{imenu-create-index-function} (@pxref{Imenu}).
242 @item
243 Use @code{defvar} or @code{defcustom} to set mode-related variables, so
244 that they are not reinitialized if they already have a value.  (Such
245 reinitialization could discard customizations made by the user.)
247 @item
248 @cindex buffer-local variables in modes
249 To make a buffer-local binding for an Emacs customization variable, use
250 @code{make-local-variable} in the major mode command, not
251 @code{make-variable-buffer-local}.  The latter function would make the
252 variable local to every buffer in which it is subsequently set, which
253 would affect buffers that do not use this mode.  It is undesirable for a
254 mode to have such global effects.  @xref{Buffer-Local Variables}.
256 With rare exceptions, the only reasonable way to use
257 @code{make-variable-buffer-local} in a Lisp package is for a variable
258 which is used only within that package.  Using it on a variable used by
259 other packages would interfere with them.
261 @item
262 @cindex mode hook
263 @cindex major mode hook
264 Each major mode should have a @dfn{mode hook} named
265 @code{@var{modename}-mode-hook}.  The major mode command should run that
266 hook, with @code{run-mode-hooks}, as the very last thing it
267 does.  @xref{Hooks}.
269 @item
270 The major mode command may start by calling some other major mode
271 command (called the @dfn{parent mode}) and then alter some of its
272 settings.  A mode that does this is called a @dfn{derived mode}.  The
273 recommended way to define one is to use @code{define-derived-mode},
274 but this is not required.  Such a mode should use
275 @code{delay-mode-hooks} around its entire body, including the call to
276 the parent mode command and the final call to @code{run-mode-hooks}.
277 (Using @code{define-derived-mode} does this automatically.) 
279 @item
280 If something special should be done if the user switches a buffer from
281 this mode to any other major mode, this mode can set up a buffer-local
282 value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}).
284 @item
285 If this mode is appropriate only for specially-prepared text, then the
286 major mode command symbol should have a property named @code{mode-class}
287 with value @code{special}, put on as follows:
289 @kindex mode-class @r{(property)}
290 @cindex @code{special}
291 @example
292 (put 'funny-mode 'mode-class 'special)
293 @end example
295 @noindent
296 This tells Emacs that new buffers created while the current buffer is in
297 Funny mode should not inherit Funny mode.  Modes such as Dired, Rmail,
298 and Buffer List use this feature.
300 @item
301 If you want to make the new mode the default for files with certain
302 recognizable names, add an element to @code{auto-mode-alist} to select
303 the mode for those file names.  If you define the mode command to
304 autoload, you should add this element in the same file that calls
305 @code{autoload}.  Otherwise, it is sufficient to add the element in the
306 file that contains the mode definition.  @xref{Auto Major Mode}.
308 @item
309 In the documentation, you should provide a sample @code{autoload} form
310 and an example of how to add to @code{auto-mode-alist}, that users can
311 include in their init files (@pxref{Init File}).
313 @item
314 @cindex mode loading
315 The top-level forms in the file defining the mode should be written so
316 that they may be evaluated more than once without adverse consequences.
317 Even if you never load the file more than once, someone else will.
318 @end itemize
320 @node Example Major Modes
321 @subsection Major Mode Examples
323   Text mode is perhaps the simplest mode besides Fundamental mode.
324 Here are excerpts from  @file{text-mode.el} that illustrate many of
325 the conventions listed above:
327 @smallexample
328 @group
329 ;; @r{Create mode-specific tables.}
330 (defvar text-mode-syntax-table nil
331   "Syntax table used while in text mode.")
332 @end group
334 @group
335 (if text-mode-syntax-table
336     ()              ; @r{Do not change the table if it is already set up.}
337   (setq text-mode-syntax-table (make-syntax-table))
338   (modify-syntax-entry ?\" ".   " text-mode-syntax-table)
339   (modify-syntax-entry ?\\ ".   " text-mode-syntax-table)
340   (modify-syntax-entry ?' "w   " text-mode-syntax-table))
341 @end group
343 @group
344 (defvar text-mode-abbrev-table nil
345   "Abbrev table used while in text mode.")
346 (define-abbrev-table 'text-mode-abbrev-table ())
347 @end group
349 @group
350 (defvar text-mode-map nil    ; @r{Create a mode-specific keymap.}
351   "Keymap for Text mode.
352 Many other modes, such as Mail mode, Outline mode and Indented Text mode,
353 inherit all the commands defined in this map.")
355 (if text-mode-map
356     ()              ; @r{Do not change the keymap if it is already set up.}
357   (setq text-mode-map (make-sparse-keymap))
358   (define-key text-mode-map "\e\t" 'ispell-complete-word)
359   (define-key text-mode-map "\t" 'indent-relative)
360   (define-key text-mode-map "\es" 'center-line)
361   (define-key text-mode-map "\eS" 'center-paragraph))
362 @end group
363 @end smallexample
365   This was formerly the complete major mode function definition for Text mode:
367 @smallexample
368 @group
369 (defun text-mode ()
370   "Major mode for editing text intended for humans to read...
371  Special commands: \\@{text-mode-map@}
372 @end group
373 @group
374 Turning on text-mode runs the hook `text-mode-hook'."
375   (interactive)
376   (kill-all-local-variables)
377   (use-local-map text-mode-map)
378 @end group
379 @group
380   (setq local-abbrev-table text-mode-abbrev-table)
381   (set-syntax-table text-mode-syntax-table)
382 @end group
383 @group
384   (make-local-variable 'paragraph-start)
385   (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter))
386   (make-local-variable 'paragraph-separate)
387   (setq paragraph-separate paragraph-start)
388   (make-local-variable 'indent-line-function)
389   (setq indent-line-function 'indent-relative-maybe)
390 @end group
391 @group
392   (setq mode-name "Text")
393   (setq major-mode 'text-mode)
394   (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
395                                     ;   @r{customize the mode with a hook.}
396 @end group
397 @end smallexample
399 @cindex @file{lisp-mode.el}
400   The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
401 Interaction mode) have more features than Text mode and the code is
402 correspondingly more complicated.  Here are excerpts from
403 @file{lisp-mode.el} that illustrate how these modes are written.
405 @cindex syntax table example
406 @smallexample
407 @group
408 ;; @r{Create mode-specific table variables.}
409 (defvar lisp-mode-syntax-table nil "")
410 (defvar emacs-lisp-mode-syntax-table nil "")
411 (defvar lisp-mode-abbrev-table nil "")
412 @end group
414 @group
415 (if (not emacs-lisp-mode-syntax-table) ; @r{Do not change the table}
416                                        ;   @r{if it is already set.}
417     (let ((i 0))
418       (setq emacs-lisp-mode-syntax-table (make-syntax-table))
419 @end group
421 @group
422       ;; @r{Set syntax of chars up to 0 to class of chars that are}
423       ;;   @r{part of symbol names but not words.}
424       ;;   @r{(The number 0 is @code{48} in the @sc{ascii} character set.)}
425       (while (< i ?0)
426         (modify-syntax-entry i "_   " emacs-lisp-mode-syntax-table)
427         (setq i (1+ i)))
428       @dots{}
429 @end group
430 @group
431       ;; @r{Set the syntax for other characters.}
432       (modify-syntax-entry ?  "    " emacs-lisp-mode-syntax-table)
433       (modify-syntax-entry ?\t "    " emacs-lisp-mode-syntax-table)
434       @dots{}
435 @end group
436 @group
437       (modify-syntax-entry ?\( "()  " emacs-lisp-mode-syntax-table)
438       (modify-syntax-entry ?\) ")(  " emacs-lisp-mode-syntax-table)
439       @dots{}))
440 ;; @r{Create an abbrev table for lisp-mode.}
441 (define-abbrev-table 'lisp-mode-abbrev-table ())
442 @end group
443 @end smallexample
445   Much code is shared among the three Lisp modes.  The following
446 function sets various variables; it is called by each of the major Lisp
447 mode functions:
449 @smallexample
450 @group
451 (defun lisp-mode-variables (lisp-syntax)
452   (cond (lisp-syntax
453           (set-syntax-table lisp-mode-syntax-table)))
454   (setq local-abbrev-table lisp-mode-abbrev-table)
455   @dots{}
456 @end group
457 @end smallexample
459   Functions such as @code{forward-paragraph} use the value of the
460 @code{paragraph-start} variable.  Since Lisp code is different from
461 ordinary text, the @code{paragraph-start} variable needs to be set
462 specially to handle Lisp.  Also, comments are indented in a special
463 fashion in Lisp and the Lisp modes need their own mode-specific
464 @code{comment-indent-function}.  The code to set these variables is the
465 rest of @code{lisp-mode-variables}.
467 @smallexample
468 @group
469   (make-local-variable 'paragraph-start)
470   (setq paragraph-start (concat page-delimiter "\\|$" ))
471   (make-local-variable 'paragraph-separate)
472   (setq paragraph-separate paragraph-start)
473   @dots{}
474 @end group
475 @group
476   (make-local-variable 'comment-indent-function)
477   (setq comment-indent-function 'lisp-comment-indent))
478   @dots{}
479 @end group
480 @end smallexample
482   Each of the different Lisp modes has a slightly different keymap.  For
483 example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other
484 Lisp modes do not.  However, all Lisp modes have some commands in
485 common.  The following code sets up the common commands:
487 @smallexample
488 @group
489 (defvar shared-lisp-mode-map ()
490   "Keymap for commands shared by all sorts of Lisp modes.")
492 (if shared-lisp-mode-map
493     ()
494    (setq shared-lisp-mode-map (make-sparse-keymap))
495    (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp)
496    (define-key shared-lisp-mode-map "\177"
497                'backward-delete-char-untabify))
498 @end group
499 @end smallexample
501 @noindent
502 And here is the code to set up the keymap for Lisp mode:
504 @smallexample
505 @group
506 (defvar lisp-mode-map ()
507   "Keymap for ordinary Lisp mode...")
509 (if lisp-mode-map
510     ()
511   (setq lisp-mode-map (make-sparse-keymap))
512   (set-keymap-parent lisp-mode-map shared-lisp-mode-map)
513   (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun)
514   (define-key lisp-mode-map "\C-c\C-z" 'run-lisp))
515 @end group
516 @end smallexample
518   Finally, here is the complete major mode function definition for
519 Lisp mode.
521 @smallexample
522 @group
523 (defun lisp-mode ()
524   "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
525 Commands:
526 Delete converts tabs to spaces as it moves back.
527 Blank lines separate paragraphs.  Semicolons start comments.
528 \\@{lisp-mode-map@}
529 Note that `run-lisp' may be used either to start an inferior Lisp job
530 or to switch back to an existing one.
531 @end group
533 @group
534 Entry to this mode calls the value of `lisp-mode-hook'
535 if that value is non-nil."
536   (interactive)
537   (kill-all-local-variables)
538 @end group
539 @group
540   (use-local-map lisp-mode-map)          ; @r{Select the mode's keymap.}
541   (setq major-mode 'lisp-mode)           ; @r{This is how @code{describe-mode}}
542                                          ;   @r{finds out what to describe.}
543   (setq mode-name "Lisp")                ; @r{This goes into the mode line.}
544   (lisp-mode-variables t)                ; @r{This defines various variables.}
545 @end group
546 @group
547   (setq imenu-case-fold-search t)
548   (set-syntax-table lisp-mode-syntax-table)
549   (run-mode-hooks 'lisp-mode-hook))           ; @r{This permits the user to use a}
550                                          ;   @r{hook to customize the mode.}
551 @end group
552 @end smallexample
554 @node Auto Major Mode
555 @subsection How Emacs Chooses a Major Mode
557   Based on information in the file name or in the file itself, Emacs
558 automatically selects a major mode for the new buffer when a file is
559 visited.  It also processes local variables specified in the file text.
561 @deffn Command fundamental-mode
562   Fundamental mode is a major mode that is not specialized for anything
563 in particular.  Other major modes are defined in effect by comparison
564 with this one---their definitions say what to change, starting from
565 Fundamental mode.  The @code{fundamental-mode} function does @emph{not}
566 run any hooks; you're not supposed to customize it.  (If you want Emacs
567 to behave differently in Fundamental mode, change the @emph{global}
568 state of Emacs.)
569 @end deffn
571 @deffn Command normal-mode &optional find-file
572 This function establishes the proper major mode and buffer-local variable
573 bindings for the current buffer.  First it calls @code{set-auto-mode},
574 then it runs @code{hack-local-variables} to parse, and bind or
575 evaluate as appropriate, the file's local variables.
577 If the @var{find-file} argument to @code{normal-mode} is non-@code{nil},
578 @code{normal-mode} assumes that the @code{find-file} function is calling
579 it.  In this case, it may process a local variables list at the end of
580 the file and in the @samp{-*-} line.  The variable
581 @code{enable-local-variables} controls whether to do so.  @xref{File
582 variables, , Local Variables in Files, emacs, The GNU Emacs Manual}, for
583 the syntax of the local variables section of a file.
585 If you run @code{normal-mode} interactively, the argument
586 @var{find-file} is normally @code{nil}.  In this case,
587 @code{normal-mode} unconditionally processes any local variables list.
589 @cindex file mode specification error
590 @code{normal-mode} uses @code{condition-case} around the call to the
591 major mode function, so errors are caught and reported as a @samp{File
592 mode specification error},  followed by the original error message.
593 @end deffn
595 @defun set-auto-mode
596 @cindex visited file mode
597   This function selects the major mode that is appropriate for the
598 current buffer.  It may base its decision on the value of the @w{@samp{-*-}}
599 line, on the visited file name (using @code{auto-mode-alist}), on the
600 @w{@samp{#!}} line (using @code{interpreter-mode-alist}), or on the
601 file's local variables list.  However, this function does not look for
602 the @samp{mode:} local variable near the end of a file; the
603 @code{hack-local-variables} function does that.  @xref{Choosing Modes, ,
604 How Major Modes are Chosen, emacs, The GNU Emacs Manual}.
605 @end defun
607 @defopt default-major-mode
608 This variable holds the default major mode for new buffers.  The
609 standard value is @code{fundamental-mode}.
611 If the value of @code{default-major-mode} is @code{nil}, Emacs uses
612 the (previously) current buffer's major mode for the major mode of a new
613 buffer.  However, if that major mode symbol has a @code{mode-class}
614 property with value @code{special}, then it is not used for new buffers;
615 Fundamental mode is used instead.  The modes that have this property are
616 those such as Dired and Rmail that are useful only with text that has
617 been specially prepared.
618 @end defopt
620 @defun set-buffer-major-mode buffer
621 This function sets the major mode of @var{buffer} to the value of
622 @code{default-major-mode}.  If that variable is @code{nil}, it uses
623 the current buffer's major mode (if that is suitable).
625 The low-level primitives for creating buffers do not use this function,
626 but medium-level commands such as @code{switch-to-buffer} and
627 @code{find-file-noselect} use it whenever they create buffers.
628 @end defun
630 @defvar initial-major-mode
631 @cindex @samp{*scratch*}
632 The value of this variable determines the major mode of the initial
633 @samp{*scratch*} buffer.  The value should be a symbol that is a major
634 mode command.  The default value is @code{lisp-interaction-mode}.
635 @end defvar
637 @defvar auto-mode-alist
638 This variable contains an association list of file name patterns
639 (regular expressions; @pxref{Regular Expressions}) and corresponding
640 major mode commands.  Usually, the file name patterns test for suffixes,
641 such as @samp{.el} and @samp{.c}, but this need not be the case.  An
642 ordinary element of the alist looks like @code{(@var{regexp} .
643 @var{mode-function})}.
645 For example,
647 @smallexample
648 @group
649 (("\\`/tmp/fol/" . text-mode)
650  ("\\.texinfo\\'" . texinfo-mode)
651  ("\\.texi\\'" . texinfo-mode)
652 @end group
653 @group
654  ("\\.el\\'" . emacs-lisp-mode)
655  ("\\.c\\'" . c-mode)
656  ("\\.h\\'" . c-mode)
657  @dots{})
658 @end group
659 @end smallexample
661 When you visit a file whose expanded file name (@pxref{File Name
662 Expansion}) matches a @var{regexp}, @code{set-auto-mode} calls the
663 corresponding @var{mode-function}.  This feature enables Emacs to select
664 the proper major mode for most files.
666 If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
667 @var{function} t)}, then after calling @var{function}, Emacs searches
668 @code{auto-mode-alist} again for a match against the portion of the file
669 name that did not match before.  This feature is useful for
670 uncompression packages: an entry of the form @code{("\\.gz\\'"
671 @var{function} t)} can uncompress the file and then put the uncompressed
672 file in the proper mode according to the name sans @samp{.gz}.
674 Here is an example of how to prepend several pattern pairs to
675 @code{auto-mode-alist}.  (You might use this sort of expression in your
676 init file.)
678 @smallexample
679 @group
680 (setq auto-mode-alist
681   (append
682    ;; @r{File name (within directory) starts with a dot.}
683    '(("/\\.[^/]*\\'" . fundamental-mode)
684      ;; @r{File name has no dot.}
685      ("[^\\./]*\\'" . fundamental-mode)
686      ;; @r{File name ends in @samp{.C}.}
687      ("\\.C\\'" . c++-mode))
688    auto-mode-alist))
689 @end group
690 @end smallexample
691 @end defvar
693 @defvar interpreter-mode-alist
694 This variable specifies major modes to use for scripts that specify a
695 command interpreter in a @samp{#!} line.  Its value is a list of
696 elements of the form @code{(@var{interpreter} . @var{mode})}; for
697 example, @code{("perl" . perl-mode)} is one element present by default.
698 The element says to use mode @var{mode} if the file specifies
699 an interpreter which matches @var{interpreter}.  The value of
700 @var{interpreter} is actually a regular expression.
702 This variable is applicable only when the @code{auto-mode-alist} does
703 not indicate which major mode to use.
704 @end defvar
706 @node Mode Help
707 @subsection Getting Help about a Major Mode
708 @cindex mode help
709 @cindex help for major mode
710 @cindex documentation for major mode
712   The @code{describe-mode} function is used to provide information
713 about major modes.  It is normally called with @kbd{C-h m}.  The
714 @code{describe-mode} function uses the value of @code{major-mode},
715 which is why every major mode function needs to set the
716 @code{major-mode} variable.
718 @deffn Command describe-mode
719 This function displays the documentation of the current major mode.
721 The @code{describe-mode} function calls the @code{documentation}
722 function using the value of @code{major-mode} as an argument.  Thus, it
723 displays the documentation string of the major mode function.
724 (@xref{Accessing Documentation}.)
725 @end deffn
727 @defvar major-mode
728 This variable holds the symbol for the current buffer's major mode.
729 This symbol should have a function definition that is the command to
730 switch to that major mode.  The @code{describe-mode} function uses the
731 documentation string of the function as the documentation of the major
732 mode.
733 @end defvar
735 @node Derived Modes
736 @subsection Defining Derived Modes
738   It's often useful to define a new major mode in terms of an existing
739 one.  An easy way to do this is to use @code{define-derived-mode}.
741 @defmac define-derived-mode variant parent name docstring body@dots{}
742 This construct defines @var{variant} as a major mode command, using
743 @var{name} as the string form of the mode name.
745 The new command @var{variant} is defined to call the function
746 @var{parent}, then override certain aspects of that parent mode:
748 @itemize @bullet
749 @item
750 The new mode has its own keymap, named @code{@var{variant}-map}.
751 @code{define-derived-mode} initializes this map to inherit from
752 @code{@var{parent}-map}, if it is not already set.
754 @item
755 The new mode has its own syntax table, kept in the variable
756 @code{@var{variant}-syntax-table}.
757 @code{define-derived-mode} initializes this variable by copying
758 @code{@var{parent}-syntax-table}, if it is not already set.
760 @item
761 The new mode has its own abbrev table, kept in the variable
762 @code{@var{variant}-abbrev-table}.
763 @code{define-derived-mode} initializes this variable by copying
764 @code{@var{parent}-abbrev-table}, if it is not already set.
766 @item
767 The new mode has its own mode hook, @code{@var{variant}-hook},
768 which it runs in standard fashion as the very last thing that it does.
769 (The new mode also runs the mode hook of @var{parent} as part
770 of calling @var{parent}.)
771 @end itemize
773 In addition, you can specify how to override other aspects of
774 @var{parent} with @var{body}.  The command @var{variant}
775 evaluates the forms in @var{body} after setting up all its usual
776 overrides, just before running @code{@var{variant}-hook}.
778 The argument @var{docstring} specifies the documentation string for the
779 new mode.  If you omit @var{docstring}, @code{define-derived-mode}
780 generates a documentation string.
782 Here is a hypothetical example:
784 @example
785 (define-derived-mode hypertext-mode
786   text-mode "Hypertext"
787   "Major mode for hypertext.
788 \\@{hypertext-mode-map@}"
789   (setq case-fold-search nil))
791 (define-key hypertext-mode-map
792   [down-mouse-3] 'do-hyper-link)
793 @end example
795 Do not write an @code{interactive} spec in the definition;
796 @code{define-derived-mode} does that automatically.
797 @end defmac
799 @node Minor Modes
800 @section Minor Modes
801 @cindex minor mode
803   A @dfn{minor mode} provides features that users may enable or disable
804 independently of the choice of major mode.  Minor modes can be enabled
805 individually or in combination.  Minor modes would be better named
806 ``generally available, optional feature modes,'' except that such a name
807 would be unwieldy.
809   A minor mode is not usually meant as a variation of a single major mode.
810 Usually they are general and can apply to many major modes.  For
811 example, Auto Fill mode works with any major mode that permits text
812 insertion.  To be general, a minor mode must be effectively independent
813 of the things major modes do.
815   A minor mode is often much more difficult to implement than a major
816 mode.  One reason is that you should be able to activate and deactivate
817 minor modes in any order.  A minor mode should be able to have its
818 desired effect regardless of the major mode and regardless of the other
819 minor modes in effect.
821   Often the biggest problem in implementing a minor mode is finding a
822 way to insert the necessary hook into the rest of Emacs.  Minor mode
823 keymaps make this easier than it used to be.
825 @defvar minor-mode-list
826 The value of this variable is a list of all minor mode commands.
827 @end defvar
829 @menu
830 * Minor Mode Conventions::      Tips for writing a minor mode.
831 * Keymaps and Minor Modes::     How a minor mode can have its own keymap.
832 * Defining Minor Modes::        A convenient facility for defining minor modes.
833 @end menu
835 @node Minor Mode Conventions
836 @subsection Conventions for Writing Minor Modes
837 @cindex minor mode conventions
838 @cindex conventions for writing minor modes
840   There are conventions for writing minor modes just as there are for
841 major modes.  Several of the major mode conventions apply to minor
842 modes as well: those regarding the name of the mode initialization
843 function, the names of global symbols, and the use of keymaps and
844 other tables.
846   In addition, there are several conventions that are specific to
847 minor modes.
849 @itemize @bullet
850 @item
851 @cindex mode variable
852 Make a variable whose name ends in @samp{-mode} to control the minor
853 mode.  We call this the @dfn{mode variable}.  The minor mode command
854 should set this variable (@code{nil} to disable; anything else to
855 enable).
857 If possible, implement the mode so that setting the variable
858 automatically enables or disables the mode.  Then the minor mode command
859 does not need to do anything except set the variable.
861 This variable is used in conjunction with the @code{minor-mode-alist} to
862 display the minor mode name in the mode line.  It can also enable
863 or disable a minor mode keymap.  Individual commands or hooks can also
864 check the variable's value.
866 If you want the minor mode to be enabled separately in each buffer,
867 make the variable buffer-local.
869 @item
870 Define a command whose name is the same as the mode variable.
871 Its job is to enable and disable the mode by setting the variable.
873 The command should accept one optional argument.  If the argument is
874 @code{nil}, it should toggle the mode (turn it on if it is off, and
875 off if it is on).  It should turn the mode on if the argument is a
876 positive integer, the symbol @code{t}, or a list whose @sc{car} is one
877 of those.  It should turn the mode off if the argument is a negative
878 integer or zero, the symbol @code{-}, or a list whose @sc{car} is one
879 of those.  The meaning of other arguments is not specified.
881 Here is an example taken from the definition of @code{transient-mark-mode}.
882 It shows the use of @code{transient-mark-mode} as a variable that enables or
883 disables the mode's behavior, and also shows the proper way to toggle,
884 enable or disable the minor mode based on the raw prefix argument value.
886 @smallexample
887 @group
888 (setq transient-mark-mode
889       (if (null arg) (not transient-mark-mode)
890         (> (prefix-numeric-value arg) 0)))
891 @end group
892 @end smallexample
894 @item
895 Add an element to @code{minor-mode-alist} for each minor mode
896 (@pxref{Mode Line Variables}), if you want to indicate the minor mode in
897 the mode line.  This element should be a list of the following form:
899 @smallexample
900 (@var{mode-variable} @var{string})
901 @end smallexample
903 Here @var{mode-variable} is the variable that controls enabling of the
904 minor mode, and @var{string} is a short string, starting with a space,
905 to represent the mode in the mode line.  These strings must be short so
906 that there is room for several of them at once.
908 When you add an element to @code{minor-mode-alist}, use @code{assq} to
909 check for an existing element, to avoid duplication.  For example:
911 @smallexample
912 @group
913 (unless (assq 'leif-mode minor-mode-alist)
914   (setq minor-mode-alist
915         (cons '(leif-mode " Leif") minor-mode-alist)))
916 @end group
917 @end smallexample
919 @noindent
920 or like this, using @code{add-to-list} (@pxref{Setting Variables}):
922 @smallexample
923 @group
924 (add-to-list 'minor-mode-alist '(leif-mode " Leif"))
925 @end group
926 @end smallexample
927 @end itemize
929   Global minor modes distributed with Emacs should if possible support
930 enabling and disabling via Custom (@pxref{Customization}).  To do this,
931 the first step is to define the mode variable with @code{defcustom}, and
932 specify @code{:type boolean}.
934   If just setting the variable is not sufficient to enable the mode, you
935 should also specify a @code{:set} method which enables the mode by
936 invoke the mode command.  Note in the variable's documentation string that
937 setting the variable other than via Custom may not take effect.
939   Also mark the definition with an autoload cookie (@pxref{Autoload}),
940 and specify a @code{:require} so that customizing the variable will load
941 the library that defines the mode.  This will copy suitable definitions
942 into @file{loaddefs.el} so that users can use @code{customize-option} to
943 enable the mode.  For example:
945 @smallexample
946 @group
948 ;;;###autoload
949 (defcustom msb-mode nil
950   "Toggle msb-mode.
951 Setting this variable directly does not take effect;
952 use either \\[customize] or the function `msb-mode'."
953   :set (lambda (symbol value)
954          (msb-mode (or value 0)))
955   :initialize 'custom-initialize-default
956   :version "20.4"
957   :type    'boolean
958   :group   'msb
959   :require 'msb)
960 @end group
961 @end smallexample
963 @node Keymaps and Minor Modes
964 @subsection Keymaps and Minor Modes
966   Each minor mode can have its own keymap, which is active when the mode
967 is enabled.  To set up a keymap for a minor mode, add an element to the
968 alist @code{minor-mode-map-alist}.  @xref{Active Keymaps}.
970 @cindex @code{self-insert-command}, minor modes
971   One use of minor mode keymaps is to modify the behavior of certain
972 self-inserting characters so that they do something else as well as
973 self-insert.  In general, this is the only way to do that, since the
974 facilities for customizing @code{self-insert-command} are limited to
975 special cases (designed for abbrevs and Auto Fill mode).  (Do not try
976 substituting your own definition of @code{self-insert-command} for the
977 standard one.  The editor command loop handles this function specially.)
979 The key sequences bound in a minor mode should consist of @kbd{C-c}
980 followed by a punctuation character @emph{other than} @kbd{@{},
981 @kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:}, and @kbd{;}.  (Those few punctuation
982 characters are reserved for major modes.)
984 @node Defining Minor Modes
985 @subsection Defining Minor Modes
987   The macro @code{define-minor-mode} offers a convenient way of
988 implementing a mode in one self-contained definition.  It supports only
989 buffer-local minor modes, not global ones.
991 @defmac define-minor-mode mode doc [init-value [lighter [keymap keyword-args... body...]]]
992 @tindex define-minor-mode
993 This macro defines a new minor mode whose name is @var{mode} (a
994 symbol).  It defines a command named @var{mode} to toggle the minor
995 mode, with @var{doc} as its documentation string.  It also defines a
996 variable named @var{mode}, which is set to @code{t} or @code{nil} by
997 enabling or disabling the mode.  The variable is initialized to
998 @var{init-value}.
1000 The string @var{lighter} says what to display in the mode line
1001 when the mode is enabled; if it is @code{nil}, the mode is not displayed
1002 in the mode line.
1004 The optional argument @var{keymap} specifies the keymap for the minor mode.
1005 It can be a variable name, whose value is the keymap, or it can be an alist
1006 specifying bindings in this form:
1008 @example
1009 (@var{key-sequence} . @var{definition})
1010 @end example
1012 The @var{keyword-args} consist of keywords followed by corresponding
1013 values.  A few keywords have special meanings:
1015 @table @code
1016 @item :global @var{global}
1017 If non-@code{nil} specifies that the minor mode should be global.
1018 By default, minor modes are buffer-local.
1020 @item :init-value @var{init-value}
1021 This is equivalent to specifying @var{init-value} positionally.
1023 @item :lighter @var{lighter}
1024 This is equivalent to specifying @var{lighter} positionally.
1026 @item :keymap @var{keymap}
1027 This is equivalent to specifying @var{keymap} positionally.
1028 @end table
1030 Any other keyword arguments are passed passed directly to the
1031 @code{defcustom} generated for the variable @var{mode}.
1033 The command named @var{mode} finishes by executing the @var{body} forms,
1034 if any, after it has performed the standard actions such as setting
1035 the variable named @var{mode}.
1036 @end defmac
1038 @findex easy-mmode-define-minor-mode
1039   The name @code{easy-mmode-define-minor-mode} is an alias
1040 for this macro.
1042   Here is an example of using @code{define-minor-mode}:
1044 @smallexample
1045 (define-minor-mode hungry-mode
1046   "Toggle Hungry mode.
1047 With no argument, this command toggles the mode.
1048 Non-null prefix argument turns on the mode.
1049 Null prefix argument turns off the mode.
1051 When Hungry mode is enabled, the control delete key
1052 gobbles all preceding whitespace except the last.
1053 See the command \\[hungry-electric-delete]."
1054  ;; The initial value.
1055  nil
1056  ;; The indicator for the mode line.
1057  " Hungry"
1058  ;; The minor mode bindings.
1059  '(("\C-\^?" . hungry-electric-delete)
1060    ("\C-\M-\^?"
1061     . (lambda ()
1062         (interactive)
1063         (hungry-electric-delete t))))
1064  :group 'hunger)
1065 @end smallexample
1067 @noindent
1068 This defines a minor mode named ``Hungry mode'', a command named
1069 @code{hungry-mode} to toggle it, a variable named @code{hungry-mode}
1070 which indicates whether the mode is enabled, and a variable named
1071 @code{hungry-mode-map} which holds the keymap that is active when the
1072 mode is enabled.  It initializes the keymap with key bindings for
1073 @kbd{C-@key{DEL}} and @kbd{C-M-@key{DEL}}.  It puts the variable
1074 @code{hungry-mode} into custom group @code{hunger}.  There are no
1075 @var{body} forms---many minor modes don't need any.
1077   Here's an equivalent way to write it:
1079 @smallexample
1080 (define-minor-mode hungry-mode
1081   "Toggle Hungry mode.
1082 With no argument, this command toggles the mode.
1083 Non-null prefix argument turns on the mode.
1084 Null prefix argument turns off the mode.
1086 When Hungry mode is enabled, the control delete key
1087 gobbles all preceding whitespace except the last.
1088 See the command \\[hungry-electric-delete]."
1089  ;; The initial value.
1090  :initial-value nil
1091  ;; The indicator for the mode line.
1092  :lighter " Hungry"
1093  ;; The minor mode bindings.
1094  :keymap
1095  '(("\C-\^?" . hungry-electric-delete)
1096    ("\C-\M-\^?"
1097     . (lambda ()
1098         (interactive)
1099         (hungry-electric-delete t))))
1100  :group 'hunger)
1101 @end smallexample
1103 @node Mode Line Format
1104 @section Mode Line Format
1105 @cindex mode line
1107   Each Emacs window (aside from minibuffer windows) typically has a mode
1108 line at the bottom, which displays status information about the buffer
1109 displayed in the window.  The mode line contains information about the
1110 buffer, such as its name, associated file, depth of recursive editing,
1111 and major and minor modes.  A window can also have a @dfn{header
1112 line}, which is much like the mode line but appears at the top of the
1113 window (starting in Emacs 21).
1115   This section describes how to control the contents of the mode line
1116 and header line.  We include it in this chapter because much of the
1117 information displayed in the mode line relates to the enabled major and
1118 minor modes.
1120   @code{mode-line-format} is a buffer-local variable that holds a
1121 template used to display the mode line of the current buffer.  All
1122 windows for the same buffer use the same @code{mode-line-format}, so
1123 their mode lines appear the same---except for scrolling percentages, and
1124 line and column numbers, since those depend on point and on how the
1125 window is scrolled.  @code{header-line-format} is used likewise for
1126 header lines.
1128   For efficiency, Emacs does not recompute the mode line and header
1129 line of a window in every redisplay.  It does so when circumstances
1130 appear to call for it---for instance, if you change the window
1131 configuration, switch buffers, narrow or widen the buffer, scroll, or
1132 change the buffer's modification status.  If you modify any of the
1133 variables referenced by @code{mode-line-format} (@pxref{Mode Line
1134 Variables}), or any other variables and data structures that affect
1135 how text is displayed (@pxref{Display}), you may want to force an
1136 update of the mode line so as to display the new information or
1137 display it in the new way.
1139 @c Emacs 19 feature
1140 @defun force-mode-line-update
1141 Force redisplay of the current buffer's mode line and header line.
1142 The next redisplay will update the mode line and header line based on
1143 the latest values of all relevant variables.
1145 This function also forces recomputation of the menu bar menus
1146 and the frame title.
1147 @end defun
1149   The mode line is usually displayed in inverse video; see
1150 @code{mode-line-inverse-video} in @ref{Inverse Video}.
1152   A window that is just one line tall does not display either a mode
1153 line or a header line, even if the variables call for one.  A window
1154 that is two lines tall cannot display both a mode line and a header
1155 line at once; if the variables call for both, only the mode line
1156 actually appears.
1158 @menu
1159 * Mode Line Data::        The data structure that controls the mode line.
1160 * Mode Line Variables::   Variables used in that data structure.
1161 * %-Constructs::          Putting information into a mode line.
1162 * Properties in Mode::    Using text properties in the mode line.
1163 * Header Lines::          Like a mode line, but at the top.
1164 * Emulating Mode Line::   Formatting text as the mode line would.
1165 @end menu
1167 @node Mode Line Data
1168 @subsection The Data Structure of the Mode Line
1169 @cindex mode line construct
1171   The mode line contents are controlled by a data structure of lists,
1172 strings, symbols, and numbers kept in buffer-local variables.  The data
1173 structure is called a @dfn{mode line construct}, and it is built in
1174 recursive fashion out of simpler mode line constructs.  The same data
1175 structure is used for constructing frame titles (@pxref{Frame Titles})
1176 and header lines (@pxref{Header Lines}).
1178 @defvar mode-line-format
1179 The value of this variable is a mode line construct with overall
1180 responsibility for the mode line format.  The value of this variable
1181 controls which other variables are used to form the mode line text, and
1182 where they appear.
1184 If you set this variable to @code{nil} in a buffer, that buffer does not
1185 have a mode line.  (This feature was added in Emacs 21.)
1186 @end defvar
1188   A mode line construct may be as simple as a fixed string of text, but
1189 it usually specifies how to use other variables to construct the text.
1190 Many of these variables are themselves defined to have mode line
1191 constructs as their values.
1193   The default value of @code{mode-line-format} incorporates the values
1194 of variables such as @code{mode-name} and @code{minor-mode-alist}.
1195 Because of this, very few modes need to alter @code{mode-line-format}
1196 itself.  For most purposes, it is sufficient to alter some of the
1197 variables that @code{mode-line-format} refers to.
1199   A mode line construct may be a list, a symbol, or a string.  If the
1200 value is a list, each element may be a list, a symbol, or a string.
1202   The mode line can display various faces, if the strings that control
1203 it have the @code{face} property.  @xref{Properties in Mode}.  In
1204 addition, the face @code{mode-line} is used as a default for the whole
1205 mode line (@pxref{Standard Faces}).
1207 @table @code
1208 @cindex percent symbol in mode line
1209 @item @var{string}
1210 A string as a mode line construct is displayed verbatim in the mode line
1211 except for @dfn{@code{%}-constructs}.  Decimal digits after the @samp{%}
1212 specify the field width for space filling on the right (i.e., the data
1213 is left justified).  @xref{%-Constructs}.
1215 @item @var{symbol}
1216 A symbol as a mode line construct stands for its value.  The value of
1217 @var{symbol} is used as a mode line construct, in place of @var{symbol}.
1218 However, the symbols @code{t} and @code{nil} are ignored, as is any
1219 symbol whose value is void.
1221 There is one exception: if the value of @var{symbol} is a string, it is
1222 displayed verbatim: the @code{%}-constructs are not recognized.
1224 @item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{})
1225 A list whose first element is a string or list means to process all the
1226 elements recursively and concatenate the results.  This is the most
1227 common form of mode line construct.
1229 @item (:eval @var{form})
1230 A list whose first element is the symbol @code{:eval} says to evaluate
1231 @var{form}, and use the result as a string to display.
1232 (This feature is new as of Emacs 21.)
1234 @item (@var{symbol} @var{then} @var{else})
1235 A list whose first element is a symbol that is not a keyword specifies a
1236 conditional.  Its meaning depends on the value of @var{symbol}.  If the
1237 value is non-@code{nil}, the second element, @var{then}, is processed
1238 recursively as a mode line element.  But if the value of @var{symbol} is
1239 @code{nil}, the third element, @var{else}, is processed recursively.
1240 You may omit @var{else}; then the mode line element displays nothing if
1241 the value of @var{symbol} is @code{nil}.
1243 @item (@var{width} @var{rest}@dots{})
1244 A list whose first element is an integer specifies truncation or
1245 padding of the results of @var{rest}.  The remaining elements
1246 @var{rest} are processed recursively as mode line constructs and
1247 concatenated together.  Then the result is space filled (if
1248 @var{width} is positive) or truncated (to @minus{}@var{width} columns,
1249 if @var{width} is negative) on the right.
1251 For example, the usual way to show what percentage of a buffer is above
1252 the top of the window is to use a list like this: @code{(-3 "%p")}.
1253 @end table
1255   If you do alter @code{mode-line-format} itself, the new value should
1256 use the same variables that appear in the default value (@pxref{Mode
1257 Line Variables}), rather than duplicating their contents or displaying
1258 the information in another fashion.  This way, customizations made by
1259 the user or by Lisp programs (such as @code{display-time} and major
1260 modes) via changes to those variables remain effective.
1262 @cindex Shell mode @code{mode-line-format}
1263   Here is an example of a @code{mode-line-format} that might be
1264 useful for @code{shell-mode}, since it contains the host name and default
1265 directory.
1267 @example
1268 @group
1269 (setq mode-line-format
1270   (list "-"
1271    'mode-line-mule-info
1272    'mode-line-modified
1273    'mode-line-frame-identification
1274    "%b--"
1275 @end group
1276 @group
1277    ;; @r{Note that this is evaluated while making the list.}
1278    ;; @r{It makes a mode line construct which is just a string.}
1279    (getenv "HOST")
1280 @end group
1281    ":"
1282    'default-directory
1283    "   "
1284    'global-mode-string
1285    "   %[("
1286    '(:eval (mode-line-mode-name))
1287    'mode-line-process
1288    'minor-mode-alist
1289    "%n"
1290    ")%]--"
1291 @group
1292    '(which-func-mode ("" which-func-format "--"))
1293    '(line-number-mode "L%l--")
1294    '(column-number-mode "C%c--")
1295    '(-3 . "%p")
1296    "-%-"))
1297 @end group
1298 @end example
1300 @noindent
1301 (The variables @code{line-number-mode}, @code{column-number-mode}
1302 and @code{which-func-mode} enable particular minor modes; as usual,
1303 these variable names are also the minor mode command names.)
1305 @node Mode Line Variables
1306 @subsection Variables Used in the Mode Line
1308   This section describes variables incorporated by the
1309 standard value of @code{mode-line-format} into the text of the mode
1310 line.  There is nothing inherently special about these variables; any
1311 other variables could have the same effects on the mode line if
1312 @code{mode-line-format} were changed to use them.
1314 @defvar mode-line-mule-info
1315 This variable holds the value of the mode-line construct that displays
1316 information about the language environment, buffer coding system, and
1317 current input method.  @xref{Non-ASCII Characters}.
1318 @end defvar
1320 @defvar mode-line-modified
1321 This variable holds the value of the mode-line construct that displays
1322 whether the current buffer is modified.
1324 The default value of @code{mode-line-modified} is @code{("%1*%1+")}.
1325 This means that the mode line displays @samp{**} if the buffer is
1326 modified, @samp{--} if the buffer is not modified, @samp{%%} if the
1327 buffer is read only, and @samp{%*} if the buffer is read only and
1328 modified.
1330 Changing this variable does not force an update of the mode line.
1331 @end defvar
1333 @defvar mode-line-frame-identification
1334 This variable identifies the current frame.  The default value is
1335 @code{" "} if you are using a window system which can show multiple
1336 frames, or @code{"-%F "} on an ordinary terminal which shows only one
1337 frame at a time.
1338 @end defvar
1340 @defvar mode-line-buffer-identification
1341 This variable identifies the buffer being displayed in the window.  Its
1342 default value is @code{("%12b")}, which displays the buffer name, padded
1343 with spaces to at least 12 columns.
1344 @end defvar
1346 @defvar global-mode-string
1347 This variable holds a mode line spec that appears in the mode line by
1348 default, just after the buffer name.  The command @code{display-time}
1349 sets @code{global-mode-string} to refer to the variable
1350 @code{display-time-string}, which holds a string containing the time and
1351 load information.
1353 The @samp{%M} construct substitutes the value of
1354 @code{global-mode-string}, but that is obsolete, since the variable is
1355 included in the mode line from @code{mode-line-format}.
1356 @end defvar
1358 @defvar mode-name
1359 This buffer-local variable holds the ``pretty'' name of the current
1360 buffer's major mode.  Each major mode should set this variable so that the
1361 mode name will appear in the mode line.
1362 @end defvar
1364 @defvar minor-mode-alist
1365 This variable holds an association list whose elements specify how the
1366 mode line should indicate that a minor mode is active.  Each element of
1367 the @code{minor-mode-alist} should be a two-element list:
1369 @example
1370 (@var{minor-mode-variable} @var{mode-line-string})
1371 @end example
1373 More generally, @var{mode-line-string} can be any mode line spec.  It
1374 appears in the mode line when the value of @var{minor-mode-variable} is
1375 non-@code{nil}, and not otherwise.  These strings should begin with
1376 spaces so that they don't run together.  Conventionally, the
1377 @var{minor-mode-variable} for a specific mode is set to a non-@code{nil}
1378 value when that minor mode is activated.
1380 The default value of @code{minor-mode-alist} is:
1382 @example
1383 @group
1384 minor-mode-alist
1385 @result{} ((vc-mode vc-mode)
1386     (abbrev-mode " Abbrev")
1387     (overwrite-mode overwrite-mode)
1388     (auto-fill-function " Fill")
1389     (defining-kbd-macro " Def")
1390     (isearch-mode isearch-mode))
1391 @end group
1392 @end example
1394 @code{minor-mode-alist} itself is not buffer-local.  Each variable
1395 mentioned in the alist should be buffer-local if its minor mode can be
1396 enabled separately in each buffer.
1397 @end defvar
1399 @defvar mode-line-process
1400 This buffer-local variable contains the mode line information on process
1401 status in modes used for communicating with subprocesses.  It is
1402 displayed immediately following the major mode name, with no intervening
1403 space.  For example, its value in the @samp{*shell*} buffer is
1404 @code{(":%s")}, which allows the shell to display its status along
1405 with the major mode as: @samp{(Shell:run)}.  Normally this variable
1406 is @code{nil}.
1407 @end defvar
1409   Some variables are used by @code{minor-mode-alist} to display
1410 a string for various minor modes when enabled.  This is a typical
1411 example:
1413 @defvar vc-mode
1414 The variable @code{vc-mode}, buffer-local in each buffer, records
1415 whether the buffer's visited file is maintained with version control,
1416 and, if so, which kind.  Its value is a string that appears in the mode
1417 line, or @code{nil} for no version control.
1418 @end defvar
1420   The variable @code{default-mode-line-format} is where
1421 @code{mode-line-format} usually gets its value:
1423 @defvar default-mode-line-format
1424 This variable holds the default @code{mode-line-format} for buffers
1425 that do not override it.  This is the same as @code{(default-value
1426 'mode-line-format)}.
1428 The default value of @code{default-mode-line-format} is this list:
1430 @example
1431 @group
1432 ("-"
1433  mode-line-mule-info
1434  mode-line-modified
1435  mode-line-frame-identification
1436  mode-line-buffer-identification
1437 @end group
1438  "   "
1439  global-mode-string
1440 @group
1441  "   %[("
1442  ;; @r{@code{mode-line-mode-name} is a function}
1443  ;; @r{that copies the mode name and adds text}
1444  ;; @r{properties to make it mouse-sensitive.}
1445  (:eval (mode-line-mode-name))
1446  mode-line-process
1447  minor-mode-alist
1448  "%n"
1449  ")%]--"
1450 @end group
1451 @group
1452  (which-func-mode ("" which-func-format "--"))
1453  (line-number-mode "L%l--")
1454  (column-number-mode "C%c--")
1455  (-3 . "%p")
1456  "-%-")
1457 @end group
1458 @end example
1459 @end defvar
1461 @node %-Constructs
1462 @subsection @code{%}-Constructs in the Mode Line
1464   The following table lists the recognized @code{%}-constructs and what
1465 they mean.  In any construct except @samp{%%}, you can add a decimal
1466 integer after the @samp{%} to specify how many characters to display.
1468 @table @code
1469 @item %b
1470 The current buffer name, obtained with the @code{buffer-name} function.
1471 @xref{Buffer Names}.
1473 @item %c
1474 The current column number of point.
1476 @item %f
1477 The visited file name, obtained with the @code{buffer-file-name}
1478 function.  @xref{Buffer File Name}.
1480 @item %F
1481 The title (only on a window system) or the name of the selected frame.
1482 @xref{Window Frame Parameters}.
1484 @item %i
1485 The size of the accessible part of the current buffer; basically
1486 @code{(- (point-max) (point-min))}.
1488 @item %I
1489 Like @samp{%i}, but the size is printed in a more readable way by using
1490 @samp{k} for 10^3, @samp{M} for 10^6, @samp{G} for 10^9, etc., to
1491 abbreviate.
1493 @item %l
1494 The current line number of point, counting within the accessible portion
1495 of the buffer.
1497 @item %n
1498 @samp{Narrow} when narrowing is in effect; nothing otherwise (see
1499 @code{narrow-to-region} in @ref{Narrowing}).
1501 @item %p
1502 The percentage of the buffer text above the @strong{top} of window, or
1503 @samp{Top}, @samp{Bottom} or @samp{All}.  Note that the default
1504 mode-line specification truncates this to three characters.
1506 @item %P
1507 The percentage of the buffer text that is above the @strong{bottom} of
1508 the window (which includes the text visible in the window, as well as
1509 the text above the top), plus @samp{Top} if the top of the buffer is
1510 visible on screen; or @samp{Bottom} or @samp{All}.
1512 @item %s
1513 The status of the subprocess belonging to the current buffer, obtained with
1514 @code{process-status}.  @xref{Process Information}.
1516 @item %t
1517 Whether the visited file is a text file or a binary file.  This is a
1518 meaningful distinction only on certain operating systems (@pxref{MS-DOS
1519 File Types}).
1521 @item %*
1522 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
1523 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
1524 @samp{-} otherwise.  @xref{Buffer Modification}.
1526 @item %+
1527 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
1528 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
1529 @samp{-} otherwise.  This differs from @samp{%*} only for a modified
1530 read-only buffer.  @xref{Buffer Modification}.
1532 @item %&
1533 @samp{*} if the buffer is modified, and @samp{-} otherwise.
1535 @item %[
1536 An indication of the depth of recursive editing levels (not counting
1537 minibuffer levels): one @samp{[} for each editing level.
1538 @xref{Recursive Editing}.
1540 @item %]
1541 One @samp{]} for each recursive editing level (not counting minibuffer
1542 levels).
1544 @item %-
1545 Dashes sufficient to fill the remainder of the mode line.
1547 @item %%
1548 The character @samp{%}---this is how to include a literal @samp{%} in a
1549 string in which @code{%}-constructs are allowed.
1550 @end table
1552 The following two @code{%}-constructs are still supported, but they are
1553 obsolete, since you can get the same results with the variables
1554 @code{mode-name} and @code{global-mode-string}.
1556 @table @code
1557 @item %m
1558 The value of @code{mode-name}.
1560 @item %M
1561 The value of @code{global-mode-string}.  Currently, only
1562 @code{display-time} modifies the value of @code{global-mode-string}.
1563 @end table
1565 @node Properties in Mode
1566 @subsection Properties in the Mode Line
1568   Starting in Emacs 21, certain text properties are meaningful in the
1569 mode line.  The @code{face} property affects the appearance of text; the
1570 @code{help-echo} property associate help strings with the text, and
1571 @code{local-map} can make the text mouse-sensitive.
1573   There are three ways to specify text properties for text in the mode
1574 line:
1576 @enumerate
1577 @item
1578 Put a string with the @code{local-map} property directly into the
1579 mode-line data structure.
1581 @item
1582 Put a @code{local-map} property on a mode-line %-construct
1583 such as @samp{%12b}; then the expansion of the %-construct
1584 will have that same text property.
1586 @item
1587 Use a list containing @code{:eval @var{form}} in the mode-line data
1588 structure, and make @var{form} evaluate to a string that has a
1589 @code{local-map} property.
1590 @end enumerate
1592   You use the @code{local-map} property to specify a keymap.  Like any
1593 keymap, it can bind character keys and function keys; but that has no
1594 effect, since it is impossible to move point into the mode line.  This
1595 keymap can only take real effect for mouse clicks.
1597 @node Header Lines
1598 @subsection Window Header Lines
1599 @cindex header line (of a window)
1600 @cindex window header line
1602   Starting in Emacs 21, a window can have a @dfn{header line} at the
1603 top, just as it can have a mode line at the bottom.  The header line
1604 feature works just like the mode line feature, except that it's
1605 controlled by different variables.
1607 @tindex header-line-format
1608 @defvar header-line-format
1609 This variable, local in every buffer, specifies how to display the
1610 header line, for windows displaying the buffer.  The format of the value
1611 is the same as for @code{mode-line-format} (@pxref{Mode Line Data}).
1612 @end defvar
1614 @tindex default-header-line-format
1615 @defvar default-header-line-format
1616 This variable holds the default @code{header-line-format} for buffers
1617 that do not override it.  This is the same as @code{(default-value
1618 'header-line-format)}.
1620 It is normally @code{nil}, so that ordinary buffers have no header line.
1621 @end defvar
1623 @node Emulating Mode Line
1624 @subsection Emulating Mode Line Formatting
1626   You can use the function @code{format-mode-line} to compute
1627 the text that would appear in a mode line or header line
1628 based on certain mode line specification.
1630 @defun format-mode-line &optional format window no-props
1631 This function formats a line of text according to @var{format} as if
1632 it were generating the mode line for @var{window}, but instead of
1633 displaying the text in the mode line or the header line, it returns
1634 the text as a string.
1636 If @var{format} is @code{nil}, that means to use
1637 @code{mode-line-format} and return the text that would appear in the
1638 mode line.  If @var{format} is @code{t}, that means to use
1639 @code{header-line-format} so as to return the text that would appear
1640 in the header line (@code{""} if the window has no header line).
1641 The argument @var{window} defaults to the selected window.
1643 The value string normally has text properties that correspond to the
1644 faces, keymaps, etc., that the mode line would have.  If
1645 @var{no-props} is non-@code{nil}, the value has no text properties.
1646 @end defun
1648 @node Imenu
1649 @section Imenu
1651 @cindex Imenu
1652   @dfn{Imenu} is a feature that lets users select a definition or
1653 section in the buffer, from a menu which lists all of them, to go
1654 directly to that location in the buffer.  Imenu works by constructing
1655 a buffer index which lists the names and buffer positions of the
1656 definitions, or other named portions of the buffer; then the user can
1657 choose one of them and move point to it.  The user-level commands for
1658 using Imenu are described in the Emacs Manual (@pxref{Imenu,, Imenu,
1659 emacs, the Emacs Manual}).  This section explains how to customize
1660 Imenu's method of finding definitions or buffer portions for a
1661 particular major mode.
1663   The usual and simplest way is to set the variable
1664 @code{imenu-generic-expression}:
1666 @defvar imenu-generic-expression
1667 This variable, if non-@code{nil}, specifies regular expressions for
1668 finding definitions for Imenu.  In the simplest case, elements should
1669 look like this:
1671 @example
1672 (@var{menu-title} @var{regexp} @var{subexp})
1673 @end example
1675 Here, if @var{menu-title} is non-@code{nil}, it says that the matches
1676 for this element should go in a submenu of the buffer index;
1677 @var{menu-title} itself specifies the name for the submenu.  If
1678 @var{menu-title} is @code{nil}, the matches for this element go directly
1679 in the top level of the buffer index.
1681 The second item in the list, @var{regexp}, is a regular expression
1682 (@pxref{Regular Expressions}); anything in the buffer that it matches is
1683 considered a definition, something to mention in the buffer index.  The
1684 third item, @var{subexp}, indicates which subexpression in @var{regexp}
1685 matches the definition's name.
1687 An element can also look like this:
1689 @example
1690 (@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{})
1691 @end example
1693 Each match for this element creates a special index item which, if
1694 selected by the user, calls @var{function} with arguments consisting of
1695 the item name, the buffer position, and @var{arguments}.
1697 For Emacs Lisp mode, @var{pattern} could look like this:
1699 @c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]
1700 @example
1701 @group
1702 ((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
1703 \\s-+\\([-A-Za-z0-9+]+\\)" 2)
1704 @end group
1705 @group
1706  ("*Vars*" "^\\s-*(def\\(var\\|const\\)\
1707 \\s-+\\([-A-Za-z0-9+]+\\)" 2)
1708 @end group
1709 @group
1710  ("*Types*"
1711   "^\\s-*\
1712 (def\\(type\\|struct\\|class\\|ine-condition\\)\
1713 \\s-+\\([-A-Za-z0-9+]+\\)" 2))
1714 @end group
1715 @end example
1717 Setting this variable makes it buffer-local in the current buffer.
1718 @end defvar
1720 @defvar imenu-case-fold-search
1721 This variable controls whether matching against
1722 @var{imenu-generic-expression} is case-sensitive: @code{t}, the default,
1723 means matching should ignore case.
1725 Setting this variable makes it buffer-local in the current buffer.
1726 @end defvar
1728 @defvar imenu-syntax-alist
1729 This variable is an alist of syntax table modifiers to use while
1730 processing @code{imenu-generic-expression}, to override the syntax table
1731 of the current buffer.  Each element should have this form:
1733 @example
1734 (@var{characters} . @var{syntax-description})
1735 @end example
1737 The @sc{car}, @var{characters}, can be either a character or a string.
1738 The element says to give that character or characters the syntax
1739 specified by @var{syntax-description}, which is passed to
1740 @code{modify-syntax-entry} (@pxref{Syntax Table Functions}).
1742 This feature is typically used to give word syntax to characters which
1743 normally have symbol syntax, and thus to simplify
1744 @code{imenu-generic-expression} and speed up matching.
1745 For example, Fortran mode uses it this way:
1747 @example
1748 (setq imenu-syntax-alist '(("_$" . "w")))
1749 @end example
1751 The @code{imenu-generic-expression} patterns can then use @samp{\\sw+}
1752 instead of @samp{\\(\\sw\\|\\s_\\)+}.  Note that this technique may be
1753 inconvenient when the mode needs to limit the initial character
1754 of a name to a smaller set of characters than are allowed in the rest
1755 of a name.
1757 Setting this variable makes it buffer-local in the current buffer.
1758 @end defvar
1760   Another way to customize Imenu for a major mode is to set the
1761 variables @code{imenu-prev-index-position-function} and
1762 @code{imenu-extract-index-name-function}:
1764 @defvar imenu-prev-index-position-function
1765 If this variable is non-@code{nil}, its value should be a function that
1766 finds the next ``definition'' to put in the buffer index, scanning
1767 backward in the buffer from point.  It should return @code{nil} if it
1768 doesn't find another ``definition'' before point.  Otherwise it should
1769 leave point at the place it finds a ``definition,'' and return any
1770 non-@code{nil} value.
1772 Setting this variable makes it buffer-local in the current buffer.
1773 @end defvar
1775 @defvar imenu-extract-index-name-function
1776 If this variable is non-@code{nil}, its value should be a function to
1777 return the name for a definition, assuming point is in that definition
1778 as the @code{imenu-prev-index-position-function} function would leave
1781 Setting this variable makes it buffer-local in the current buffer.
1782 @end defvar
1784   The last way to customize Imenu for a major mode is to set the
1785 variable @code{imenu-create-index-function}:
1787 @defvar imenu-create-index-function
1788 This variable specifies the function to use for creating a buffer index.
1789 The function should take no arguments, and return an index for the
1790 current buffer.  It is called within @code{save-excursion}, so where it
1791 leaves point makes no difference.
1793 The default value is a function that uses
1794 @code{imenu-generic-expression} to produce the index alist.  If you
1795 specify a different function, then @code{imenu-generic-expression} is
1796 not used.
1798 Setting this variable makes it buffer-local in the current buffer.
1799 @end defvar
1801 @defvar imenu-index-alist
1802 This variable holds the index alist for the current buffer.
1803 Setting it makes it buffer-local in the current buffer.
1805 Simple elements in the alist look like @code{(@var{index-name}
1806 . @var{index-position})}.  Selecting a simple element has the effect of
1807 moving to position @var{index-position} in the buffer.
1809 Special elements look like @code{(@var{index-name} @var{position}
1810 @var{function} @var{arguments}@dots{})}.  Selecting a special element
1811 performs
1813 @example
1814 (funcall @var{function} @var{index-name} @var{position} @var{arguments}@dots{})
1815 @end example
1817 A nested sub-alist element looks like @code{(@var{index-name}
1818 @var{sub-alist})}.
1819 @end defvar
1821 @node Font Lock Mode
1822 @section Font Lock Mode
1823 @cindex Font Lock Mode
1825   @dfn{Font Lock mode} is a feature that automatically attaches
1826 @code{face} properties to certain parts of the buffer based on their
1827 syntactic role.  How it parses the buffer depends on the major mode;
1828 most major modes define syntactic criteria for which faces to use in
1829 which contexts.  This section explains how to customize Font Lock for a
1830 particular major mode.
1832   Font Lock mode finds text to highlight in two ways: through syntactic
1833 parsing based on the syntax table, and through searching (usually for
1834 regular expressions).  Syntactic fontification happens first; it finds
1835 comments and string constants, and highlights them using
1836 @code{font-lock-comment-face} and @code{font-lock-string-face}
1837 (@pxref{Faces for Font Lock}).  Search-based fontification follows.
1839 @menu
1840 * Font Lock Basics::
1841 * Search-based Fontification::
1842 * Other Font Lock Variables::
1843 * Levels of Font Lock::
1844 * Precalculated Fontification::
1845 * Faces for Font Lock::
1846 * Syntactic Font Lock::
1847 @end menu
1849 @node Font Lock Basics
1850 @subsection Font Lock Basics
1852   There are several variables that control how Font Lock mode highlights
1853 text.  But major modes should not set any of these variables directly.
1854 Instead, they should set @code{font-lock-defaults} as a buffer-local
1855 variable.  The value assigned to this variable is used, if and when Font
1856 Lock mode is enabled, to set all the other variables.
1858 @defvar font-lock-defaults
1859 This variable is set by major modes, as a buffer-local variable, to
1860 specify how to fontify text in that mode.  The value should look like
1861 this:
1863 @example
1864 (@var{keywords} @var{keywords-only} @var{case-fold}
1865  @var{syntax-alist} @var{syntax-begin} @var{other-vars}@dots{})
1866 @end example
1868 The first element, @var{keywords}, indirectly specifies the value of
1869 @code{font-lock-keywords}.  It can be a symbol, a variable whose value
1870 is the list to use for @code{font-lock-keywords}.  It can also be a list of
1871 several such symbols, one for each possible level of fontification.  The
1872 first symbol specifies how to do level 1 fontification, the second
1873 symbol how to do level 2, and so on.
1875 The second element, @var{keywords-only}, specifies the value of the
1876 variable @code{font-lock-keywords-only}.  If this is non-@code{nil},
1877 syntactic fontification (of strings and comments) is not performed.
1879 The third element, @var{case-fold}, specifies the value of
1880 @code{font-lock-case-fold-search}.  If it is non-@code{nil}, Font Lock
1881 mode ignores case when searching as directed by
1882 @code{font-lock-keywords}.
1884 If the fourth element, @var{syntax-alist}, is non-@code{nil}, it should be
1885 a list of cons cells of the form @code{(@var{char-or-string}
1886 . @var{string})}.  These are used to set up a syntax table for
1887 fontification (@pxref{Syntax Table Functions}).  The resulting syntax
1888 table is stored in @code{font-lock-syntax-table}.
1890 The fifth element, @var{syntax-begin}, specifies the value of
1891 @code{font-lock-beginning-of-syntax-function} (see below).
1893 All the remaining elements (if any) are collectively called
1894 @var{other-vars}.  Each of these elements should have the form
1895 @code{(@var{variable} . @var{value})}---which means, make @var{variable}
1896 buffer-local and then set it to @var{value}.  You can use these
1897 @var{other-vars} to set other variables that affect fontification,
1898 aside from those you can control with the first five elements.
1899 @end defvar
1901 @node Search-based Fontification
1902 @subsection Search-based Fontification
1904   The most important variable for customizing Font Lock mode is
1905 @code{font-lock-keywords}.  It specifies the search criteria for
1906 search-based fontification.
1908 @defvar font-lock-keywords
1909 This variable's value is a list of the keywords to highlight.  Be
1910 careful when composing regular expressions for this list; a poorly
1911 written pattern can dramatically slow things down!
1912 @end defvar
1914   Each element of @code{font-lock-keywords} specifies how to find
1915 certain cases of text, and how to highlight those cases.  Font Lock mode
1916 processes the elements of @code{font-lock-keywords} one by one, and for
1917 each element, it finds and handles all matches.  Ordinarily, once
1918 part of the text has been fontified already, this cannot be overridden
1919 by a subsequent match in the same text; but you can specify different
1920 behavior using the @var{override} element of a @var{highlighter}.
1922   Each element of @code{font-lock-keywords} should have one of these
1923 forms:
1925 @table @code
1926 @item @var{regexp}
1927 Highlight all matches for @var{regexp} using
1928 @code{font-lock-keyword-face}.  For example,
1930 @example
1931 ;; @r{Highlight discrete occurrences of @samp{foo}}
1932 ;; @r{using @code{font-lock-keyword-face}.}
1933 "\\<foo\\>"
1934 @end example
1936 The function @code{regexp-opt} (@pxref{Syntax of Regexps}) is useful for
1937 calculating optimal regular expressions to match a number of different
1938 keywords.
1940 @item @var{function}
1941 Find text by calling @var{function}, and highlight the matches
1942 it finds using @code{font-lock-keyword-face}.
1944 When @var{function} is called, it receives one argument, the limit of
1945 the search; it should searching at point, and not search beyond the
1946 limit.  It should return non-@code{nil} if it succeeds, and set the
1947 match data to describe the match that was found.  Returning @code{nil}
1948 indicates failure of the search.
1950 Fontification will call @var{function} repeatedly with the same limit,
1951 and with point where the previous invocation left it, until
1952 @var{function} fails.  On failure, @var{function} need not reset point
1953 in any particular way.
1955 @item (@var{matcher} . @var{match})
1956 In this kind of element, @var{matcher} is either a regular
1957 expression or a function, as described above.  The @sc{cdr},
1958 @var{match}, specifies which subexpression of @var{matcher} should be
1959 highlighted (instead of the entire text that @var{matcher} matched).
1961 @example
1962 ;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},}
1963 ;; @r{using @code{font-lock-keyword-face}.}
1964 ("fu\\(bar\\)" . 1)
1965 @end example
1967 If you use @code{regexp-opt} to produce the regular expression
1968 @var{matcher}, then you can use @code{regexp-opt-depth} (@pxref{Syntax
1969 of Regexps}) to calculate the value for @var{match}.
1971 @item (@var{matcher} . @var{facename})
1972 In this kind of element, @var{facename} is an expression whose value
1973 specifies the face name to use for highlighting.
1975 @example
1976 ;; @r{Highlight occurrences of @samp{fubar},}
1977 ;; @r{using the face which is the value of @code{fubar-face}.}
1978 ("fubar" . fubar-face)
1979 @end example
1981 The value of @var{facename} is usually a face name (a symbol), but it
1982 can also be a list of the form
1984 @example
1985 (face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{})
1986 @end example
1988 to specify various text properties to put on the text that matches.
1989 If you do this, be sure to add the other text property names that you
1990 set in this way to the value of @code{font-lock-extra-managed-props}
1991 so that the properties will also be cleared out when they are no longer
1992 appropriate.
1994 @item (@var{matcher} . @var{highlighter})
1995 In this kind of element, @var{highlighter} is a list
1996 which specifies how to highlight matches found by @var{matcher}.
1997 It has the form
1999 @example
2000 (@var{subexp} @var{facename} @var{override} @var{laxmatch})
2001 @end example
2003 The @sc{car}, @var{subexp}, is an integer specifying which subexpression
2004 of the match to fontify (0 means the entire matching text).  The second
2005 subelement, @var{facename}, specifies the face, as described above.
2007 The last two values in @var{highlighter}, @var{override} and
2008 @var{laxmatch}, are flags.  If @var{override} is @code{t}, this
2009 element can override existing fontification made by previous elements
2010 of @code{font-lock-keywords}.  If it is @code{keep}, then each
2011 character is fontified if it has not been fontified already by some
2012 other element.  If it is @code{prepend}, the face @var{facename} is
2013 added to the beginning of the @code{font-lock-face} property.  If it
2014 is @code{append}, the face @var{facename} is added to the end of the
2015 @code{font-lock-face} property.
2017 If @var{laxmatch} is non-@code{nil}, it means there should be no error
2018 if there is no subexpression numbered @var{subexp} in @var{matcher}.
2019 Obviously, fontification of the subexpression numbered @var{subexp} will
2020 not occur.  However, fontification of other subexpressions (and other
2021 regexps) will continue.  If @var{laxmatch} is @code{nil}, and the
2022 specified subexpression is missing, then an error is signalled which
2023 terminates search-based fontification.
2025 Here are some examples of elements of this kind, and what they do:
2027 @smallexample
2028 ;; @r{Highlight occurrences of either @samp{foo} or @samp{bar},}
2029 ;; @r{using @code{foo-bar-face}, even if they have already been highlighted.}
2030 ;; @r{@code{foo-bar-face} should be a variable whose value is a face.}
2031 ("foo\\|bar" 0 foo-bar-face t)
2033 ;; @r{Highlight the first subexpression within each occurrence}
2034 ;; @r{that the function @code{fubar-match} finds,}
2035 ;; @r{using the face which is the value of @code{fubar-face}.}
2036 (fubar-match 1 fubar-face)
2037 @end smallexample
2039 @item (@var{matcher} @var{highlighters}@dots{})
2040 This sort of element specifies several @var{highlighter} lists for a
2041 single @var{matcher}.  In order for this to be useful, each
2042 @var{highlighter} should have a different value of @var{subexp}; that is,
2043 each one should apply to a different subexpression of @var{matcher}.
2045 @ignore
2046 @item (@var{matcher} . @var{anchored})
2047 In this kind of element, @var{anchored} acts much like a
2048 @var{highlighter}, but it is more complex and can specify multiple
2049 successive searches.
2051 For highlighting single items, typically only @var{highlighter} is
2052 required.  However, if an item or (typically) items are to be
2053 highlighted following the instance of another item (the anchor) then
2054 @var{anchored} may be required.
2056 It has this format:
2058 @example
2059 (@var{submatcher} @var{pre-match-form} @var{post-match-form} @var{highlighters}@dots{})
2060 @end example
2062 @c I can't parse this text -- rms
2063 where @var{submatcher} is much like @var{matcher}, with one
2064 exception---see below.  @var{pre-match-form} and @var{post-match-form}
2065 are evaluated before the first, and after the last, instance
2066 @var{anchored}'s @var{submatcher} is used.  Therefore they can be used
2067 to initialize before, and cleanup after, @var{submatcher} is used.
2068 Typically, @var{pre-match-form} is used to move to some position
2069 relative to the original @var{submatcher}, before starting with
2070 @var{anchored}'s @var{submatcher}.  @var{post-match-form} might be used
2071 to move, before resuming with @var{anchored}'s parent's @var{matcher}.
2073 For example, an element of the form highlights (if not already highlighted):
2075 @example
2076 ("\\<anchor\\>" (0 anchor-face) ("\\<item\\>" nil nil (0 item-face)))
2077 @end example
2079 Discrete occurrences of @samp{anchor} in the value of
2080 @code{anchor-face}, and subsequent discrete occurrences of @samp{item}
2081 (on the same line) in the value of @code{item-face}.  (Here
2082 @var{pre-match-form} and @var{post-match-form} are @code{nil}.
2083 Therefore @samp{item} is initially searched for starting from the end of
2084 the match of @samp{anchor}, and searching for subsequent instance of
2085 @samp{anchor} resumes from where searching for @samp{item} concluded.)
2087 The above-mentioned exception is as follows.  The limit of the
2088 @var{submatcher} search defaults to the end of the line after
2089 @var{pre-match-form} is evaluated.  However, if @var{pre-match-form}
2090 returns a position greater than the position after @var{pre-match-form}
2091 is evaluated, that position is used as the limit of the search.  It is
2092 generally a bad idea to return a position greater than the end of the
2093 line; in other words, the @var{submatcher} search should not span lines.
2095 @item (@var{matcher} @var{highlighters-or-anchoreds} ...)
2096 @end ignore
2098 @item (eval . @var{form})
2099 Here @var{form} is an expression to be evaluated the first time
2100 this value of @code{font-lock-keywords} is used in a buffer.
2101 Its value should have one of the forms described in this table.
2102 @end table
2104 @strong{Warning:} Do not design an element of @code{font-lock-keywords}
2105 to match text which spans lines; this does not work reliably.  While
2106 @code{font-lock-fontify-buffer} handles multi-line patterns correctly,
2107 updating when you edit the buffer does not, since it considers text one
2108 line at a time.
2110 @node Other Font Lock Variables
2111 @subsection Other Font Lock Variables
2113   This section describes additional variables that a major mode
2114 can set by means of @code{font-lock-defaults}.
2116 @defvar font-lock-keywords-only
2117 Non-@code{nil} means Font Lock should not fontify comments or strings
2118 syntactically; it should only fontify based on
2119 @code{font-lock-keywords}.
2120 @end defvar
2122 @ignore
2123 Other variables include those for buffer-specialized fontification functions,
2124 `font-lock-fontify-buffer-function', `font-lock-unfontify-buffer-function',
2125 `font-lock-fontify-region-function', `font-lock-unfontify-region-function',
2126 `font-lock-inhibit-thing-lock' and `font-lock-maximum-size'.
2127 @end ignore
2129 @defvar font-lock-keywords-case-fold-search
2130 Non-@code{nil} means that regular expression matching for the sake of
2131 @code{font-lock-keywords} should be case-insensitive.
2132 @end defvar
2134 @defvar font-lock-syntax-table
2135 This variable specifies the syntax table to use for fontification of
2136 comments and strings.
2137 @end defvar
2139 @defvar font-lock-beginning-of-syntax-function
2140 If this variable is non-@code{nil}, it should be a function to move
2141 point back to a position that is syntactically at ``top level'' and
2142 outside of strings or comments.  Font Lock uses this when necessary
2143 to get the right results for syntactic fontification.
2145 This function is called with no arguments.  It should leave point at the
2146 beginning of any enclosing syntactic block.  Typical values are
2147 @code{beginning-of-line} (i.e., the start of the line is known to be
2148 outside a syntactic block), or @code{beginning-of-defun} for programming
2149 modes or @code{backward-paragraph} for textual modes (i.e., the
2150 mode-dependent function is known to move outside a syntactic block).
2152 If the value is @code{nil}, the beginning of the buffer is used as a
2153 position outside of a syntactic block.  This cannot be wrong, but it can
2154 be slow.
2155 @end defvar
2157 @defvar font-lock-mark-block-function
2158 If this variable is non-@code{nil}, it should be a function that is
2159 called with no arguments, to choose an enclosing range of text for
2160 refontification for the command @kbd{M-g M-g}
2161 (@code{font-lock-fontify-block}).
2163 The function should report its choice by placing the region around it.
2164 A good choice is a range of text large enough to give proper results,
2165 but not too large so that refontification becomes slow.  Typical values
2166 are @code{mark-defun} for programming modes or @code{mark-paragraph} for
2167 textual modes.
2168 @end defvar
2170 @defvar font-lock-extra-managed-props
2171 Additional properties (other than @code{font-lock-face}) that are
2172 being managed by Font Lock mode.  Font Lock mode normally manages only
2173 the @code{font-lock-face} property; if you want it to manage others as
2174 well, you must specify them in a @var{facename} in
2175 @code{font-lock-keywords} as well as adding them to this list.
2176 @end defvar
2178 @node Levels of Font Lock
2179 @subsection Levels of Font Lock
2181   Many major modes offer three different levels of fontification.  You
2182 can define multiple levels by using a list of symbols for @var{keywords}
2183 in @code{font-lock-defaults}.  Each symbol specifies one level of
2184 fontification; it is up to the user to choose one of these levels.  The
2185 chosen level's symbol value is used to initialize
2186 @code{font-lock-keywords}.
2188   Here are the conventions for how to define the levels of
2189 fontification:
2191 @itemize @bullet
2192 @item
2193 Level 1: highlight function declarations, file directives (such as include or
2194 import directives), strings and comments.  The idea is speed, so only
2195 the most important and top-level components are fontified.
2197 @item
2198 Level 2: in addition to level 1, highlight all language keywords,
2199 including type names that act like keywords, as well as named constant
2200 values.  The idea is that all keywords (either syntactic or semantic)
2201 should be fontified appropriately.
2203 @item
2204 Level 3: in addition to level 2, highlight the symbols being defined in
2205 function and variable declarations, and all builtin function names,
2206 wherever they appear.
2207 @end itemize
2209 @node Precalculated Fontification
2210 @subsection Precalculated Fontification
2212 In addition to using @code{font-lock-defaults} for search-based
2213 fontification, you may use the special character property
2214 @code{font-lock-face} (@pxref{Special Properties}).  This property
2215 acts just like the explicit @code{face} property, but its activation
2216 is toggled when the user calls @kbd{M-x font-lock-mode}.  Using
2217 @code{font-lock-face} is especially conveninent for special modes
2218 which construct their text programmatically, such as
2219 @code{list-buffers} and @code{occur}.
2221 If your mode does not use any of the other machinery of Font Lock
2222 (i.e. it only uses the @code{font-lock-face} property), you can tell
2223 Emacs not to load all of font-lock.el (unless it's already loaded), by
2224 setting the variable @code{font-lock-core-only} to non-@code{nil} as
2225 part of the @code{font-lock-defaults} settings.  Here is the canonical
2226 way to do this:
2228 @example
2229 (set (make-local-variable 'font-lock-defaults)
2230      '(nil t nil nil nil (font-lock-core-only . t)))
2231 @end example
2233 @node Faces for Font Lock
2234 @subsection Faces for Font Lock
2236   You can make Font Lock mode use any face, but several faces are
2237 defined specifically for Font Lock mode.  Each of these symbols is both
2238 a face name, and a variable whose default value is the symbol itself.
2239 Thus, the default value of @code{font-lock-comment-face} is
2240 @code{font-lock-comment-face}.  This means you can write
2241 @code{font-lock-comment-face} in a context such as
2242 @code{font-lock-keywords} where a face-name-valued expression is used.
2244 @table @code
2245 @item font-lock-comment-face
2246 @vindex font-lock-comment-face
2247 Used (typically) for comments.
2249 @item font-lock-string-face
2250 @vindex font-lock-string-face
2251 Used (typically) for string constants.
2253 @item font-lock-keyword-face
2254 @vindex font-lock-keyword-face
2255 Used (typically) for keywords---names that have special syntactic
2256 significance, like @code{for} and @code{if} in C.
2258 @item font-lock-builtin-face
2259 @vindex font-lock-builtin-face
2260 Used (typically) for built-in function names.
2262 @item font-lock-function-name-face
2263 @vindex font-lock-function-name-face
2264 Used (typically) for the name of a function being defined or declared,
2265 in a function definition or declaration.
2267 @item font-lock-variable-name-face
2268 @vindex font-lock-variable-name-face
2269 Used (typically) for the name of a variable being defined or declared,
2270 in a variable definition or declaration.
2272 @item font-lock-type-face
2273 @vindex font-lock-type-face
2274 Used (typically) for names of user-defined data types,
2275 where they are defined and where they are used.
2277 @item font-lock-constant-face
2278 @vindex font-lock-constant-face
2279 Used (typically) for constant names.
2281 @item font-locl-preprocessor-face
2282 @vindex font-locl-preprocessor-face
2283 Used (typically) for preprocessor commands.
2285 @item font-lock-warning-face
2286 @vindex font-lock-warning-face
2287 Used (typically) for constructs that are peculiar, or that greatly
2288 change the meaning of other text.  For example, this is used for
2289 @samp{;;;###autoload} cookies in Emacs Lisp, and for @code{#error}
2290 directives in C.
2291 @end table
2293 @node Syntactic Font Lock
2294 @subsection Syntactic Font Lock
2296   Font Lock mode can be used to update @code{syntax-table} properties
2297 automatically.  This is useful in languages for which a single syntax
2298 table by itself is not sufficient.
2300 @defvar font-lock-syntactic-keywords
2301 This variable enables and controls syntactic Font Lock.  It is
2302 normally set via @code{font-lock-defaults}.  Its value should be a
2303 list of elements of this form:
2305 @example
2306 (@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch})
2307 @end example
2309 The parts of this element have the same meanings as in the corresponding
2310 sort of element of @code{font-lock-keywords},
2312 @example
2313 (@var{matcher} @var{subexp} @var{facename} @var{override} @var{laxmatch})
2314 @end example
2316 However, instead of specifying the value @var{facename} to use for the
2317 @code{face} property, it specifies the value @var{syntax} to use for
2318 the @code{syntax-table} property.  Here, @var{syntax} can be a string
2319 (as taken by @code{modify-syntax-entry}), a syntax table, a cons cell
2320 (as returned by @code{string-to-syntax}), or an expression whose value
2321 is one of those two types.  @var{override} cannot be @code{prepend} or
2322 @code{append}.
2324 For example, an element of the form:
2326 @example
2327 ("\\$\\(#\\)" 1 ".")
2328 @end example
2330 highlights syntactically a hash character when following a dollar
2331 character, with a SYNTAX of @code{"."} (meaning punctuation syntax).
2332 Assuming that the buffer syntax table specifies hash characters to
2333 have comment start syntax, the element will only highlight hash
2334 characters that do not follow dollar characters as comments
2335 syntactically.
2337 An element of the form:
2339 @example
2340  ("\\('\\).\\('\\)"
2341   (1 "\"")
2342   (2 "\""))
2343 @end example
2345 highlights syntactically both single quotes which surround a single
2346 character, with a SYNTAX of @code{"\""} (meaning string quote syntax).
2347 Assuming that the buffer syntax table does not specify single quotes
2348 to have quote syntax, the element will only highlight single quotes of
2349 the form @samp{'@var{c}'} as strings syntactically.  Other forms, such
2350 as @samp{foo'bar} or @samp{'fubar'}, will not be highlighted as
2351 strings.
2353 @end defvar
2355 @node Hooks
2356 @section Hooks
2357 @cindex hooks
2359   A @dfn{hook} is a variable where you can store a function or functions
2360 to be called on a particular occasion by an existing program.  Emacs
2361 provides hooks for the sake of customization.  Most often, hooks are set
2362 up in the init file (@pxref{Init File}), but Lisp programs can set them also.
2363 @xref{Standard Hooks}, for a list of standard hook variables.
2365 @cindex normal hook
2366   Most of the hooks in Emacs are @dfn{normal hooks}.  These variables
2367 contain lists of functions to be called with no arguments.  When the
2368 hook name ends in @samp{-hook}, that tells you it is normal.  We try to
2369 make all hooks normal, as much as possible, so that you can use them in
2370 a uniform way.
2372   Every major mode function is supposed to run a normal hook called the
2373 @dfn{mode hook} as the last step of initialization.  This makes it easy
2374 for a user to customize the behavior of the mode, by overriding the
2375 buffer-local variable assignments already made by the mode.  But hooks
2376 are used in other contexts too.  For example, the hook
2377 @code{suspend-hook} runs just before Emacs suspends itself
2378 (@pxref{Suspending Emacs}).
2380   The recommended way to add a hook function to a normal hook is by
2381 calling @code{add-hook} (see below).  The hook functions may be any of
2382 the valid kinds of functions that @code{funcall} accepts (@pxref{What Is
2383 a Function}).  Most normal hook variables are initially void;
2384 @code{add-hook} knows how to deal with this.
2386 @cindex abnormal hook
2387   If the hook variable's name does not end with @samp{-hook}, that
2388 indicates it is probably an @dfn{abnormal hook}.  Then you should look at its
2389 documentation to see how to use the hook properly.
2391   If the variable's name ends in @samp{-functions} or @samp{-hooks},
2392 then the value is a list of functions, but it is abnormal in that either
2393 these functions are called with arguments or their values are used in
2394 some way.  You can use @code{add-hook} to add a function to the list,
2395 but you must take care in writing the function.  (A few of these
2396 variables, notably those ending in @samp{-hooks}, are actually
2397 normal hooks which were named before we established the convention of
2398 using @samp{-hook} for them.)
2400   If the variable's name ends in @samp{-function}, then its value
2401 is just a single function, not a list of functions.
2403   Here's an example that uses a mode hook to turn on Auto Fill mode when
2404 in Lisp Interaction mode:
2406 @example
2407 (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
2408 @end example
2410   At the appropriate time, Emacs uses the @code{run-hooks} function to
2411 run particular hooks.  This function calls the hook functions that have
2412 been added with @code{add-hook}.
2414 @defun run-hooks &rest hookvars
2415 This function takes one or more hook variable names as arguments, and
2416 runs each hook in turn.  Each argument should be a symbol that is a hook
2417 variable.  These arguments are processed in the order specified.
2419 If a hook variable has a non-@code{nil} value, that value may be a
2420 function or a list of functions.  If the value is a function (either a
2421 lambda expression or a symbol with a function definition), it is called.
2422 If it is a list, the elements are called, in order.  The hook functions
2423 are called with no arguments.  Nowadays, storing a single function in
2424 the hook variable is semi-obsolete; you should always use a list of
2425 functions.
2427 For example, here's how @code{emacs-lisp-mode} runs its mode hook:
2429 @example
2430 (run-hooks 'emacs-lisp-mode-hook)
2431 @end example
2432 @end defun
2434 @defun run-mode-hooks &rest hookvars
2435 Like @code{run-hooks}, but is affected by the @code{delay-mode-hooks}
2436 macro.
2437 @end defun
2439 @defmac delay-mode-hooks body...
2440 This macro executes the @var{body} forms but defers all calls to
2441 @code{run-mode-hooks} within them until the end of @var{body}.
2442 This macro enables a derived mode to arrange not to run
2443 its parent modes' mode hooks until the end.
2444 @end defmac
2446 @defun run-hook-with-args hook &rest args
2447 This function is the way to run an abnormal hook which passes arguments
2448 to the hook functions.  It calls each of the hook functions, passing
2449 each of them the arguments @var{args}.
2450 @end defun
2452 @defun run-hook-with-args-until-failure hook &rest args
2453 This function is the way to run an abnormal hook which passes arguments
2454 to the hook functions, and stops as soon as any hook function fails.  It
2455 calls each of the hook functions, passing each of them the arguments
2456 @var{args}, until some hook function returns @code{nil}.  Then it stops,
2457 and returns @code{nil} if some hook function returned @code{nil}.
2458 Otherwise it returns a non-@code{nil} value.
2459 @end defun
2461 @defun run-hook-with-args-until-success hook &rest args
2462 This function is the way to run an abnormal hook which passes arguments
2463 to the hook functions, and stops as soon as any hook function succeeds.
2464 It calls each of the hook functions, passing each of them the arguments
2465 @var{args}, until some hook function returns non-@code{nil}.  Then it
2466 stops, and returns whatever was returned by the last hook function
2467 that was called.
2468 @end defun
2470 @defun add-hook hook function &optional append local
2471 This function is the handy way to add function @var{function} to hook
2472 variable @var{hook}.  The argument @var{function} may be any valid Lisp
2473 function with the proper number of arguments.  For example,
2475 @example
2476 (add-hook 'text-mode-hook 'my-text-hook-function)
2477 @end example
2479 @noindent
2480 adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
2482 You can use @code{add-hook} for abnormal hooks as well as for normal
2483 hooks.
2485 It is best to design your hook functions so that the order in which they
2486 are executed does not matter.  Any dependence on the order is ``asking
2487 for trouble.''  However, the order is predictable: normally,
2488 @var{function} goes at the front of the hook list, so it will be
2489 executed first (barring another @code{add-hook} call).  If the optional
2490 argument @var{append} is non-@code{nil}, the new hook function goes at
2491 the end of the hook list and will be executed last.
2493 If @var{local} is non-@code{nil}, that says to add @var{function}
2494 to the buffer-local hook list instead of to the global hook list.
2495 @end defun
2497 @defun remove-hook hook function &optional local
2498 This function removes @var{function} from the hook variable @var{hook}.
2500 If @var{local} is non-@code{nil}, that says to remove @var{function}
2501 from the buffer-local hook list instead of from the global hook list.
2502 @end defun
2504 @ignore
2505    arch-tag: 4c7bff41-36e6-4da6-9e7f-9b9289e27c8e
2506 @end ignore