2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2016 Free Software
5 @c See the file elisp.texi for copying conditions.
7 @chapter Major and Minor Modes
10 A @dfn{mode} is a set of definitions that customize Emacs and can be
11 turned on and off while you edit. There are two varieties of modes:
12 @dfn{major modes}, which are mutually exclusive and used for editing
13 particular kinds of text, and @dfn{minor modes}, which provide features
14 that users can enable individually.
16 This chapter describes how to write both major and minor modes, how to
17 indicate them in the mode line, and how they run hooks supplied by the
18 user. For related topics such as keymaps and syntax tables, see
19 @ref{Keymaps}, and @ref{Syntax Tables}.
22 * Hooks:: How to use hooks; how to write code that provides hooks.
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:: Providing a menu of definitions made in a buffer.
27 * Font Lock Mode:: How modes can highlight text according to syntax.
28 * Auto-Indentation:: How to teach Emacs to indent for a major mode.
29 * Desktop Save Mode:: How modes can have buffer state saved between
37 A @dfn{hook} is a variable where you can store a function or functions
38 to be called on a particular occasion by an existing program. Emacs
39 provides hooks for the sake of customization. Most often, hooks are set
40 up in the init file (@pxref{Init File}), but Lisp programs can set them also.
41 @xref{Standard Hooks}, for a list of some standard hook variables.
44 Most of the hooks in Emacs are @dfn{normal hooks}. These variables
45 contain lists of functions to be called with no arguments. By
46 convention, whenever the hook name ends in @samp{-hook}, that tells
47 you it is normal. We try to make all hooks normal, as much as
48 possible, so that you can use them in a uniform way.
50 Every major mode command is supposed to run a normal hook called the
51 @dfn{mode hook} as one of the last steps of initialization. This makes
52 it easy for a user to customize the behavior of the mode, by overriding
53 the buffer-local variable assignments already made by the mode. Most
54 minor mode functions also run a mode hook at the end. But hooks are
55 used in other contexts too. For example, the hook @code{suspend-hook}
56 runs just before Emacs suspends itself (@pxref{Suspending Emacs}).
58 The recommended way to add a hook function to a hook is by calling
59 @code{add-hook} (@pxref{Setting Hooks}). The hook functions may be any
60 of the valid kinds of functions that @code{funcall} accepts (@pxref{What
61 Is a Function}). Most normal hook variables are initially void;
62 @code{add-hook} knows how to deal with this. You can add hooks either
63 globally or buffer-locally with @code{add-hook}.
66 If the hook variable's name does not end with @samp{-hook}, that
67 indicates it is probably an @dfn{abnormal hook}. That means the hook
68 functions are called with arguments, or their return values are used
69 in some way. The hook's documentation says how the functions are
70 called. You can use @code{add-hook} to add a function to an abnormal
71 hook, but you must write the function to follow the hook's calling
72 convention. By convention, abnormal hook names end in @samp{-functions}.
74 @cindex single-function hook
75 If the variable's name ends in @samp{-function}, then its value is
76 just a single function, not a list of functions. @code{add-hook} cannot be
77 used to modify such a @emph{single function hook}, and you have to use
78 @code{add-function} instead (@pxref{Advising Functions}).
81 * Running Hooks:: How to run a hook.
82 * Setting Hooks:: How to put functions on a hook, or remove them.
86 @subsection Running Hooks
88 In this section, we document the @code{run-hooks} function, which is
89 used to run a normal hook. We also document the functions for running
90 various kinds of abnormal hooks.
92 @defun run-hooks &rest hookvars
93 This function takes one or more normal hook variable names as
94 arguments, and runs each hook in turn. Each argument should be a
95 symbol that is a normal hook variable. These arguments are processed
96 in the order specified.
98 If a hook variable has a non-@code{nil} value, that value should be a
99 list of functions. @code{run-hooks} calls all the functions, one by
100 one, with no arguments.
102 The hook variable's value can also be a single function---either a
103 lambda expression or a symbol with a function definition---which
104 @code{run-hooks} calls. But this usage is obsolete.
106 If the hook variable is buffer-local, the buffer-local variable will
107 be used instead of the global variable. However, if the buffer-local
108 variable contains the element @code{t}, the global hook variable will
112 @defun run-hook-with-args hook &rest args
113 This function runs an abnormal hook by calling all the hook functions in
114 @var{hook}, passing each one the arguments @var{args}.
117 @defun run-hook-with-args-until-failure hook &rest args
118 This function runs an abnormal hook by calling each hook function in
119 turn, stopping if one of them fails by returning @code{nil}. Each
120 hook function is passed the arguments @var{args}. If this function
121 stops because one of the hook functions fails, it returns @code{nil};
122 otherwise it returns a non-@code{nil} value.
125 @defun run-hook-with-args-until-success hook &rest args
126 This function runs an abnormal hook by calling each hook function,
127 stopping if one of them succeeds by returning a non-@code{nil}
128 value. Each hook function is passed the arguments @var{args}. If this
129 function stops because one of the hook functions returns a
130 non-@code{nil} value, it returns that value; otherwise it returns
135 @subsection Setting Hooks
137 Here's an example that uses a mode hook to turn on Auto Fill mode when
138 in Lisp Interaction mode:
141 (add-hook 'lisp-interaction-mode-hook 'auto-fill-mode)
144 @defun add-hook hook function &optional append local
145 This function is the handy way to add function @var{function} to hook
146 variable @var{hook}. You can use it for abnormal hooks as well as for
147 normal hooks. @var{function} can be any Lisp function that can accept
148 the proper number of arguments for @var{hook}. For example,
151 (add-hook 'text-mode-hook 'my-text-hook-function)
155 adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
157 If @var{function} is already present in @var{hook} (comparing using
158 @code{equal}), then @code{add-hook} does not add it a second time.
160 If @var{function} has a non-@code{nil} property
161 @code{permanent-local-hook}, then @code{kill-all-local-variables} (or
162 changing major modes) won't delete it from the hook variable's local
165 For a normal hook, hook functions should be designed so that the order
166 in which they are executed does not matter. Any dependence on the order
167 is asking for trouble. However, the order is predictable: normally,
168 @var{function} goes at the front of the hook list, so it is executed
169 first (barring another @code{add-hook} call). If the optional argument
170 @var{append} is non-@code{nil}, the new hook function goes at the end of
171 the hook list and is executed last.
173 @code{add-hook} can handle the cases where @var{hook} is void or its
174 value is a single function; it sets or changes the value to a list of
177 If @var{local} is non-@code{nil}, that says to add @var{function} to the
178 buffer-local hook list instead of to the global hook list. This makes
179 the hook buffer-local and adds @code{t} to the buffer-local value. The
180 latter acts as a flag to run the hook functions in the default value as
181 well as in the local value.
184 @defun remove-hook hook function &optional local
185 This function removes @var{function} from the hook variable
186 @var{hook}. It compares @var{function} with elements of @var{hook}
187 using @code{equal}, so it works for both symbols and lambda
190 If @var{local} is non-@code{nil}, that says to remove @var{function}
191 from the buffer-local hook list instead of from the global hook list.
198 @cindex major mode command
199 Major modes specialize Emacs for editing particular kinds of text.
200 Each buffer has one major mode at a time. Every major mode is
201 associated with a @dfn{major mode command}, whose name should end in
202 @samp{-mode}. This command takes care of switching to that mode in the
203 current buffer, by setting various buffer-local variables such as a
204 local keymap. @xref{Major Mode Conventions}.
206 The least specialized major mode is called @dfn{Fundamental mode},
207 which has no mode-specific definitions or variable settings.
209 @deffn Command fundamental-mode
210 This is the major mode command for Fundamental mode. Unlike other mode
211 commands, it does @emph{not} run any mode hooks (@pxref{Major Mode
212 Conventions}), since you are not supposed to customize this mode.
215 The easiest way to write a major mode is to use the macro
216 @code{define-derived-mode}, which sets up the new mode as a variant of
217 an existing major mode. @xref{Derived Modes}. We recommend using
218 @code{define-derived-mode} even if the new mode is not an obvious
219 derivative of another mode, as it automatically enforces many coding
220 conventions for you. @xref{Basic Major Modes}, for common modes to
223 The standard GNU Emacs Lisp directory tree contains the code for
224 several major modes, in files such as @file{text-mode.el},
225 @file{texinfo.el}, @file{lisp-mode.el}, and @file{rmail.el}. You can
226 study these libraries to see how modes are written.
229 The buffer-local value of this variable holds the symbol for the current
230 major mode. Its default value holds the default major mode for new
231 buffers. The standard default value is @code{fundamental-mode}.
233 If the default value is @code{nil}, then whenever Emacs creates a new
234 buffer via a command such as @kbd{C-x b} (@code{switch-to-buffer}), the
235 new buffer is put in the major mode of the previously current buffer.
236 As an exception, if the major mode of the previous buffer has a
237 @code{mode-class} symbol property with value @code{special}, the new
238 buffer is put in Fundamental mode (@pxref{Major Mode Conventions}).
242 * Major Mode Conventions:: Coding conventions for keymaps, etc.
243 * Auto Major Mode:: How Emacs chooses the major mode automatically.
244 * Mode Help:: Finding out how to use a mode.
245 * Derived Modes:: Defining a new major mode based on another major
247 * Basic Major Modes:: Modes that other modes are often derived from.
248 * Mode Hooks:: Hooks run at the end of major mode functions.
249 * Tabulated List Mode:: Parent mode for buffers containing tabulated data.
250 * Generic Modes:: Defining a simple major mode that supports
251 comment syntax and Font Lock mode.
252 * Example Major Modes:: Text mode and Lisp modes.
255 @node Major Mode Conventions
256 @subsection Major Mode Conventions
257 @cindex major mode conventions
258 @cindex conventions for writing major modes
260 The code for every major mode should follow various coding
261 conventions, including conventions for local keymap and syntax table
262 initialization, function and variable names, and hooks.
264 If you use the @code{define-derived-mode} macro, it will take care of
265 many of these conventions automatically. @xref{Derived Modes}. Note
266 also that Fundamental mode is an exception to many of these conventions,
267 because it represents the default state of Emacs.
269 The following list of conventions is only partial. Each major mode
270 should aim for consistency in general with other Emacs major modes, as
271 this makes Emacs as a whole more coherent. It is impossible to list
272 here all the possible points where this issue might come up; if the
273 Emacs developers point out an area where your major mode deviates from
274 the usual conventions, please make it compatible.
278 Define a major mode command whose name ends in @samp{-mode}. When
279 called with no arguments, this command should switch to the new mode in
280 the current buffer by setting up the keymap, syntax table, and
281 buffer-local variables in an existing buffer. It should not change the
285 Write a documentation string for this command that describes the special
286 commands available in this mode. @xref{Mode Help}.
288 The documentation string may include the special documentation
289 substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
290 @samp{\<@var{keymap}>}, which allow the help display to adapt
291 automatically to the user's own key bindings. @xref{Keys in
295 The major mode command should start by calling
296 @code{kill-all-local-variables}. This runs the normal hook
297 @code{change-major-mode-hook}, then gets rid of the buffer-local
298 variables of the major mode previously in effect. @xref{Creating
302 The major mode command should set the variable @code{major-mode} to the
303 major mode command symbol. This is how @code{describe-mode} discovers
304 which documentation to print.
307 The major mode command should set the variable @code{mode-name} to the
308 ``pretty'' name of the mode, usually a string (but see @ref{Mode Line
309 Data}, for other possible forms). The name of the mode appears
313 @cindex functions in modes
314 Since all global names are in the same name space, all the global
315 variables, constants, and functions that are part of the mode should
316 have names that start with the major mode name (or with an abbreviation
317 of it if the name is long). @xref{Coding Conventions}.
320 In a major mode for editing some kind of structured text, such as a
321 programming language, indentation of text according to structure is
322 probably useful. So the mode should set @code{indent-line-function}
323 to a suitable function, and probably customize other variables
324 for indentation. @xref{Auto-Indentation}.
327 @cindex keymaps in modes
328 The major mode should usually have its own keymap, which is used as the
329 local keymap in all buffers in that mode. The major mode command should
330 call @code{use-local-map} to install this local map. @xref{Active
331 Keymaps}, for more information.
333 This keymap should be stored permanently in a global variable named
334 @code{@var{modename}-mode-map}. Normally the library that defines the
335 mode sets this variable.
337 @xref{Tips for Defining}, for advice about how to write the code to set
338 up the mode's keymap variable.
341 The key sequences bound in a major mode keymap should usually start with
342 @kbd{C-c}, followed by a control character, a digit, or @kbd{@{},
343 @kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}. The other punctuation
344 characters are reserved for minor modes, and ordinary letters are
347 A major mode can also rebind the keys @kbd{M-n}, @kbd{M-p} and
348 @kbd{M-s}. The bindings for @kbd{M-n} and @kbd{M-p} should normally
349 be some kind of moving forward and backward, but this does not
350 necessarily mean cursor motion.
352 It is legitimate for a major mode to rebind a standard key sequence if
353 it provides a command that does the same job in a way better
354 suited to the text this mode is used for. For example, a major mode
355 for editing a programming language might redefine @kbd{C-M-a} to
356 move to the beginning of a function in a way that works better for
359 It is also legitimate for a major mode to rebind a standard key
360 sequence whose standard meaning is rarely useful in that mode. For
361 instance, minibuffer modes rebind @kbd{M-r}, whose standard meaning is
362 rarely of any use in the minibuffer. Major modes such as Dired or
363 Rmail that do not allow self-insertion of text can reasonably redefine
364 letters and other printing characters as special commands.
367 Major modes for editing text should not define @key{RET} to do
368 anything other than insert a newline. However, it is ok for
369 specialized modes for text that users don't directly edit, such as
370 Dired and Info modes, to redefine @key{RET} to do something entirely
374 Major modes should not alter options that are primarily a matter of user
375 preference, such as whether Auto-Fill mode is enabled. Leave this to
376 each user to decide. However, a major mode should customize other
377 variables so that Auto-Fill mode will work usefully @emph{if} the user
381 @cindex syntax tables in modes
382 The mode may have its own syntax table or may share one with other
383 related modes. If it has its own syntax table, it should store this in
384 a variable named @code{@var{modename}-mode-syntax-table}. @xref{Syntax
388 If the mode handles a language that has a syntax for comments, it should
389 set the variables that define the comment syntax. @xref{Options for
390 Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}.
393 @cindex abbrev tables in modes
394 The mode may have its own abbrev table or may share one with other
395 related modes. If it has its own abbrev table, it should store this
396 in a variable named @code{@var{modename}-mode-abbrev-table}. If the
397 major mode command defines any abbrevs itself, it should pass @code{t}
398 for the @var{system-flag} argument to @code{define-abbrev}.
399 @xref{Defining Abbrevs}.
402 The mode should specify how to do highlighting for Font Lock mode, by
403 setting up a buffer-local value for the variable
404 @code{font-lock-defaults} (@pxref{Font Lock Mode}).
407 Each face that the mode defines should, if possible, inherit from an
408 existing Emacs face. @xref{Basic Faces}, and @ref{Faces for Font Lock}.
411 The mode should specify how Imenu should find the definitions or
412 sections of a buffer, by setting up a buffer-local value for the
413 variable @code{imenu-generic-expression}, for the two variables
414 @code{imenu-prev-index-position-function} and
415 @code{imenu-extract-index-name-function}, or for the variable
416 @code{imenu-create-index-function} (@pxref{Imenu}).
419 The mode can specify a local value for
420 @code{eldoc-documentation-function} to tell ElDoc mode how to handle
424 The mode can specify how to complete various keywords by adding one or
425 more buffer-local entries to the special hook
426 @code{completion-at-point-functions}. @xref{Completion in Buffers}.
429 @cindex buffer-local variables in modes
430 To make a buffer-local binding for an Emacs customization variable, use
431 @code{make-local-variable} in the major mode command, not
432 @code{make-variable-buffer-local}. The latter function would make the
433 variable local to every buffer in which it is subsequently set, which
434 would affect buffers that do not use this mode. It is undesirable for a
435 mode to have such global effects. @xref{Buffer-Local Variables}.
437 With rare exceptions, the only reasonable way to use
438 @code{make-variable-buffer-local} in a Lisp package is for a variable
439 which is used only within that package. Using it on a variable used by
440 other packages would interfere with them.
444 @cindex major mode hook
445 Each major mode should have a normal @dfn{mode hook} named
446 @code{@var{modename}-mode-hook}. The very last thing the major mode command
447 should do is to call @code{run-mode-hooks}. This runs the normal
448 hook @code{change-major-mode-after-body-hook}, the mode hook,
449 and then the normal hook @code{after-change-major-mode-hook}.
453 The major mode command may start by calling some other major mode
454 command (called the @dfn{parent mode}) and then alter some of its
455 settings. A mode that does this is called a @dfn{derived mode}. The
456 recommended way to define one is to use the @code{define-derived-mode}
457 macro, but this is not required. Such a mode should call the parent
458 mode command inside a @code{delay-mode-hooks} form. (Using
459 @code{define-derived-mode} does this automatically.) @xref{Derived
460 Modes}, and @ref{Mode Hooks}.
463 If something special should be done if the user switches a buffer from
464 this mode to any other major mode, this mode can set up a buffer-local
465 value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}).
468 If this mode is appropriate only for specially-prepared text produced by
469 the mode itself (rather than by the user typing at the keyboard or by an
470 external file), then the major mode command symbol should have a
471 property named @code{mode-class} with value @code{special}, put on as
474 @kindex mode-class @r{(property)}
475 @cindex @code{special} modes
477 (put 'funny-mode 'mode-class 'special)
481 This tells Emacs that new buffers created while the current buffer is in
482 Funny mode should not be put in Funny mode, even though the default
483 value of @code{major-mode} is @code{nil}. By default, the value of
484 @code{nil} for @code{major-mode} means to use the current buffer's major
485 mode when creating new buffers (@pxref{Auto Major Mode}), but with such
486 @code{special} modes, Fundamental mode is used instead. Modes such as
487 Dired, Rmail, and Buffer List use this feature.
489 The function @code{view-buffer} does not enable View mode in buffers
490 whose mode-class is special, because such modes usually provide their
491 own View-like bindings.
493 The @code{define-derived-mode} macro automatically marks the derived
494 mode as special if the parent mode is special. Special mode is a
495 convenient parent for such modes to inherit from; @xref{Basic Major
499 If you want to make the new mode the default for files with certain
500 recognizable names, add an element to @code{auto-mode-alist} to select
501 the mode for those file names (@pxref{Auto Major Mode}). If you
502 define the mode command to autoload, you should add this element in
503 the same file that calls @code{autoload}. If you use an autoload
504 cookie for the mode command, you can also use an autoload cookie for
505 the form that adds the element (@pxref{autoload cookie}). If you do
506 not autoload the mode command, it is sufficient to add the element in
507 the file that contains the mode definition.
511 The top-level forms in the file defining the mode should be written so
512 that they may be evaluated more than once without adverse consequences.
513 For instance, use @code{defvar} or @code{defcustom} to set mode-related
514 variables, so that they are not reinitialized if they already have a
515 value (@pxref{Defining Variables}).
519 @node Auto Major Mode
520 @subsection How Emacs Chooses a Major Mode
521 @cindex major mode, automatic selection
523 When Emacs visits a file, it automatically selects a major mode for
524 the buffer based on information in the file name or in the file itself.
525 It also processes local variables specified in the file text.
527 @deffn Command normal-mode &optional find-file
528 This function establishes the proper major mode and buffer-local variable
529 bindings for the current buffer. First it calls @code{set-auto-mode}
530 (see below), then it runs @code{hack-local-variables} to parse, and
531 bind or evaluate as appropriate, the file's local variables
532 (@pxref{File Local Variables}).
534 If the @var{find-file} argument to @code{normal-mode} is non-@code{nil},
535 @code{normal-mode} assumes that the @code{find-file} function is calling
536 it. In this case, it may process local variables in the @samp{-*-}
537 line or at the end of the file. The variable
538 @code{enable-local-variables} controls whether to do so. @xref{File
539 Variables, , Local Variables in Files, emacs, The GNU Emacs Manual},
540 for the syntax of the local variables section of a file.
542 If you run @code{normal-mode} interactively, the argument
543 @var{find-file} is normally @code{nil}. In this case,
544 @code{normal-mode} unconditionally processes any file local variables.
546 The function calls @code{set-auto-mode} to choose a major mode. If this
547 does not specify a mode, the buffer stays in the major mode determined
548 by the default value of @code{major-mode} (see below).
550 @cindex file mode specification error
551 @code{normal-mode} uses @code{condition-case} around the call to the
552 major mode command, so errors are caught and reported as a @samp{File
553 mode specification error}, followed by the original error message.
556 @defun set-auto-mode &optional keep-mode-if-same
557 @cindex visited file mode
558 This function selects the major mode that is appropriate for the
559 current buffer. It bases its decision (in order of precedence) on the
560 @w{@samp{-*-}} line, on any @samp{mode:} local variable near the end of
561 a file, on the @w{@samp{#!}} line (using @code{interpreter-mode-alist}),
562 on the text at the beginning of the buffer (using
563 @code{magic-mode-alist}), and finally on the visited file name (using
564 @code{auto-mode-alist}). @xref{Choosing Modes, , How Major Modes are
565 Chosen, emacs, The GNU Emacs Manual}. If @code{enable-local-variables}
566 is @code{nil}, @code{set-auto-mode} does not check the @w{@samp{-*-}}
567 line, or near the end of the file, for any mode tag.
569 @vindex inhibit-local-variables-regexps
570 There are some file types where it is not appropriate to scan the file
571 contents for a mode specifier. For example, a tar archive may happen to
572 contain, near the end of the file, a member file that has a local
573 variables section specifying a mode for that particular file. This
574 should not be applied to the containing tar file. Similarly, a tiff
575 image file might just happen to contain a first line that seems to
576 match the @w{@samp{-*-}} pattern. For these reasons, both these file
577 extensions are members of the list @code{inhibit-local-variables-regexps}.
578 Add patterns to this list to prevent Emacs searching them for local
579 variables of any kind (not just mode specifiers).
581 If @var{keep-mode-if-same} is non-@code{nil}, this function does not
582 call the mode command if the buffer is already in the proper major
583 mode. For instance, @code{set-visited-file-name} sets this to
584 @code{t} to avoid killing buffer local variables that the user may
588 @defun set-buffer-major-mode buffer
589 This function sets the major mode of @var{buffer} to the default value of
590 @code{major-mode}; if that is @code{nil}, it uses the
591 current buffer's major mode (if that is suitable). As an exception,
592 if @var{buffer}'s name is @file{*scratch*}, it sets the mode to
593 @code{initial-major-mode}.
595 The low-level primitives for creating buffers do not use this function,
596 but medium-level commands such as @code{switch-to-buffer} and
597 @code{find-file-noselect} use it whenever they create buffers.
600 @defopt initial-major-mode
601 @cindex @file{*scratch*}
602 The value of this variable determines the major mode of the initial
603 @file{*scratch*} buffer. The value should be a symbol that is a major
604 mode command. The default value is @code{lisp-interaction-mode}.
607 @defvar interpreter-mode-alist
608 This variable specifies major modes to use for scripts that specify a
609 command interpreter in a @samp{#!} line. Its value is an alist with
610 elements of the form @code{(@var{regexp} . @var{mode})}; this says to
611 use mode @var{mode} if the file specifies an interpreter which matches
612 @code{\\`@var{regexp}\\'}. For example, one of the default elements
613 is @code{("python[0-9.]*" . python-mode)}.
616 @defvar magic-mode-alist
617 This variable's value is an alist with elements of the form
618 @code{(@var{regexp} . @var{function})}, where @var{regexp} is a
619 regular expression and @var{function} is a function or @code{nil}.
620 After visiting a file, @code{set-auto-mode} calls @var{function} if
621 the text at the beginning of the buffer matches @var{regexp} and
622 @var{function} is non-@code{nil}; if @var{function} is @code{nil},
623 @code{auto-mode-alist} gets to decide the mode.
626 @defvar magic-fallback-mode-alist
627 This works like @code{magic-mode-alist}, except that it is handled
628 only if @code{auto-mode-alist} does not specify a mode for this file.
631 @defvar auto-mode-alist
632 This variable contains an association list of file name patterns
633 (regular expressions) and corresponding major mode commands. Usually,
634 the file name patterns test for suffixes, such as @samp{.el} and
635 @samp{.c}, but this need not be the case. An ordinary element of the
636 alist looks like @code{(@var{regexp} . @var{mode-function})}.
642 (("\\`/tmp/fol/" . text-mode)
643 ("\\.texinfo\\'" . texinfo-mode)
644 ("\\.texi\\'" . texinfo-mode)
647 ("\\.el\\'" . emacs-lisp-mode)
654 When you visit a file whose expanded file name (@pxref{File Name
655 Expansion}), with version numbers and backup suffixes removed using
656 @code{file-name-sans-versions} (@pxref{File Name Components}), matches
657 a @var{regexp}, @code{set-auto-mode} calls the corresponding
658 @var{mode-function}. This feature enables Emacs to select the proper
659 major mode for most files.
661 If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
662 @var{function} t)}, then after calling @var{function}, Emacs searches
663 @code{auto-mode-alist} again for a match against the portion of the file
664 name that did not match before. This feature is useful for
665 uncompression packages: an entry of the form @code{("\\.gz\\'"
666 @var{function} t)} can uncompress the file and then put the uncompressed
667 file in the proper mode according to the name sans @samp{.gz}.
669 Here is an example of how to prepend several pattern pairs to
670 @code{auto-mode-alist}. (You might use this sort of expression in your
675 (setq auto-mode-alist
677 ;; @r{File name (within directory) starts with a dot.}
678 '(("/\\.[^/]*\\'" . fundamental-mode)
679 ;; @r{File name has no dot.}
680 ("/[^\\./]*\\'" . fundamental-mode)
681 ;; @r{File name ends in @samp{.C}.}
682 ("\\.C\\'" . c++-mode))
689 @subsection Getting Help about a Major Mode
691 @cindex help for major mode
692 @cindex documentation for major mode
694 The @code{describe-mode} function provides information about major
695 modes. It is normally bound to @kbd{C-h m}. It uses the value of the
696 variable @code{major-mode} (@pxref{Major Modes}), which is why every
697 major mode command needs to set that variable.
699 @deffn Command describe-mode &optional buffer
700 This command displays the documentation of the current buffer's major
701 mode and minor modes. It uses the @code{documentation} function to
702 retrieve the documentation strings of the major and minor mode
703 commands (@pxref{Accessing Documentation}).
705 If called from Lisp with a non-@code{nil} @var{buffer} argument, this
706 function displays the documentation for that buffer's major and minor
707 modes, rather than those of the current buffer.
711 @subsection Defining Derived Modes
714 The recommended way to define a new major mode is to derive it from an
715 existing one using @code{define-derived-mode}. If there is no closely
716 related mode, you should inherit from either @code{text-mode},
717 @code{special-mode}, or @code{prog-mode}. @xref{Basic Major Modes}. If
718 none of these are suitable, you can inherit from @code{fundamental-mode}
719 (@pxref{Major Modes}).
721 @defmac define-derived-mode variant parent name docstring keyword-args@dots{} body@dots{}
722 This macro defines @var{variant} as a major mode command, using
723 @var{name} as the string form of the mode name. @var{variant} and
724 @var{parent} should be unquoted symbols.
726 The new command @var{variant} is defined to call the function
727 @var{parent}, then override certain aspects of that parent mode:
731 The new mode has its own sparse keymap, named
732 @code{@var{variant}-map}. @code{define-derived-mode}
733 makes the parent mode's keymap the parent of the new map, unless
734 @code{@var{variant}-map} is already set and already has a parent.
737 The new mode has its own syntax table, kept in the variable
738 @code{@var{variant}-syntax-table}, unless you override this using the
739 @code{:syntax-table} keyword (see below). @code{define-derived-mode}
740 makes the parent mode's syntax-table the parent of
741 @code{@var{variant}-syntax-table}, unless the latter is already set
742 and already has a parent different from the standard syntax table.
745 The new mode has its own abbrev table, kept in the variable
746 @code{@var{variant}-abbrev-table}, unless you override this using the
747 @code{:abbrev-table} keyword (see below).
750 The new mode has its own mode hook, @code{@var{variant}-hook}. It
751 runs this hook, after running the hooks of its ancestor modes, with
752 @code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}.
755 In addition, you can specify how to override other aspects of
756 @var{parent} with @var{body}. The command @var{variant}
757 evaluates the forms in @var{body} after setting up all its usual
758 overrides, just before running the mode hooks.
760 If @var{parent} has a non-@code{nil} @code{mode-class} symbol
761 property, then @code{define-derived-mode} sets the @code{mode-class}
762 property of @var{variant} to the same value. This ensures, for
763 example, that if @var{parent} is a special mode, then @var{variant} is
764 also a special mode (@pxref{Major Mode Conventions}).
766 You can also specify @code{nil} for @var{parent}. This gives the new
767 mode no parent. Then @code{define-derived-mode} behaves as described
768 above, but, of course, omits all actions connected with @var{parent}.
770 The argument @var{docstring} specifies the documentation string for the
771 new mode. @code{define-derived-mode} adds some general information
772 about the mode's hook, followed by the mode's keymap, at the end of this
773 documentation string. If you omit @var{docstring},
774 @code{define-derived-mode} generates a documentation string.
776 The @var{keyword-args} are pairs of keywords and values. The values
777 are evaluated. The following keywords are currently supported:
781 You can use this to explicitly specify a syntax table for the new
782 mode. If you specify a @code{nil} value, the new mode uses the same
783 syntax table as @var{parent}, or the standard syntax table if
784 @var{parent} is @code{nil}. (Note that this does @emph{not} follow
785 the convention used for non-keyword arguments that a @code{nil} value
786 is equivalent with not specifying the argument.)
789 You can use this to explicitly specify an abbrev table for the new
790 mode. If you specify a @code{nil} value, the new mode uses the same
791 abbrev table as @var{parent}, or @code{fundamental-mode-abbrev-table}
792 if @var{parent} is @code{nil}. (Again, a @code{nil} value is
793 @emph{not} equivalent to not specifying this keyword.)
796 If this is specified, the value should be the customization group for
797 this mode. (Not all major modes have one.) The command
798 @code{customize-mode} uses this. @code{define-derived-mode} does
799 @emph{not} automatically define the specified customization group.
802 Here is a hypothetical example:
805 (define-derived-mode hypertext-mode
806 text-mode "Hypertext"
807 "Major mode for hypertext.
808 \\@{hypertext-mode-map@}"
809 (setq case-fold-search nil))
811 (define-key hypertext-mode-map
812 [down-mouse-3] 'do-hyper-link)
815 Do not write an @code{interactive} spec in the definition;
816 @code{define-derived-mode} does that automatically.
819 @defun derived-mode-p &rest modes
820 This function returns non-@code{nil} if the current major mode is
821 derived from any of the major modes given by the symbols @var{modes}.
824 @node Basic Major Modes
825 @subsection Basic Major Modes
827 Apart from Fundamental mode, there are three major modes that other
828 major modes commonly derive from: Text mode, Prog mode, and Special
829 mode. While Text mode is useful in its own right (e.g., for editing
830 files ending in @file{.txt}), Prog mode and Special mode exist mainly to
831 let other modes derive from them.
833 @vindex prog-mode-hook
834 As far as possible, new major modes should be derived, either directly
835 or indirectly, from one of these three modes. One reason is that this
836 allows users to customize a single mode hook
837 (e.g., @code{prog-mode-hook}) for an entire family of relevant modes
838 (e.g., all programming language modes).
840 @deffn Command text-mode
841 Text mode is a major mode for editing human languages. It defines the
842 @samp{"} and @samp{\} characters as having punctuation syntax
843 (@pxref{Syntax Class Table}), and binds @kbd{M-@key{TAB}} to
844 @code{ispell-complete-word} (@pxref{Spelling,,, emacs, The GNU Emacs
847 An example of a major mode derived from Text mode is HTML mode.
848 @xref{HTML Mode,,SGML and HTML Modes, emacs, The GNU Emacs Manual}.
851 @deffn Command prog-mode
852 Prog mode is a basic major mode for buffers containing programming
853 language source code. Most of the programming language major modes
854 built into Emacs are derived from it.
856 Prog mode binds @code{parse-sexp-ignore-comments} to @code{t}
857 (@pxref{Motion via Parsing}) and @code{bidi-paragraph-direction} to
858 @code{left-to-right} (@pxref{Bidirectional Display}).
861 @deffn Command special-mode
862 Special mode is a basic major mode for buffers containing text that is
863 produced specially by Emacs, rather than directly from a file. Major
864 modes derived from Special mode are given a @code{mode-class} property
865 of @code{special} (@pxref{Major Mode Conventions}).
867 Special mode sets the buffer to read-only. Its keymap defines several
868 common bindings, including @kbd{q} for @code{quit-window} and @kbd{g}
869 for @code{revert-buffer} (@pxref{Reverting}).
871 An example of a major mode derived from Special mode is Buffer Menu
872 mode, which is used by the @file{*Buffer List*} buffer. @xref{List
873 Buffers,,Listing Existing Buffers, emacs, The GNU Emacs Manual}.
876 In addition, modes for buffers of tabulated data can inherit from
877 Tabulated List mode, which is in turn derived from Special mode.
878 @xref{Tabulated List Mode}.
881 @subsection Mode Hooks
883 Every major mode command should finish by running the mode-independent
884 normal hook @code{change-major-mode-after-body-hook}, its mode hook,
885 and the normal hook @code{after-change-major-mode-hook}.
886 It does this by calling @code{run-mode-hooks}. If the major mode is a
887 derived mode, that is if it calls another major mode (the parent mode)
888 in its body, it should do this inside @code{delay-mode-hooks} so that
889 the parent won't run these hooks itself. Instead, the derived mode's
890 call to @code{run-mode-hooks} runs the parent's mode hook too.
891 @xref{Major Mode Conventions}.
893 Emacs versions before Emacs 22 did not have @code{delay-mode-hooks}.
894 Versions before 24 did not have @code{change-major-mode-after-body-hook}.
895 When user-implemented major modes do not use @code{run-mode-hooks} and
896 have not been updated to use these newer features, they won't entirely
897 follow these conventions: they may run the parent's mode hook too early,
898 or fail to run @code{after-change-major-mode-hook}. If you encounter
899 such a major mode, please correct it to follow these conventions.
901 When you define a major mode using @code{define-derived-mode}, it
902 automatically makes sure these conventions are followed. If you
903 define a major mode ``by hand'', not using @code{define-derived-mode},
904 use the following functions to handle these conventions automatically.
906 @defun run-mode-hooks &rest hookvars
907 Major modes should run their mode hook using this function. It is
908 similar to @code{run-hooks} (@pxref{Hooks}), but it also runs
909 @code{change-major-mode-after-body-hook} and
910 @code{after-change-major-mode-hook}.
912 When this function is called during the execution of a
913 @code{delay-mode-hooks} form, it does not run the hooks immediately.
914 Instead, it arranges for the next call to @code{run-mode-hooks} to run
918 @defmac delay-mode-hooks body@dots{}
919 When one major mode command calls another, it should do so inside of
920 @code{delay-mode-hooks}.
922 This macro executes @var{body}, but tells all @code{run-mode-hooks}
923 calls during the execution of @var{body} to delay running their hooks.
924 The hooks will actually run during the next call to
925 @code{run-mode-hooks} after the end of the @code{delay-mode-hooks}
929 @defvar change-major-mode-after-body-hook
930 This is a normal hook run by @code{run-mode-hooks}. It is run before
934 @defvar after-change-major-mode-hook
935 This is a normal hook run by @code{run-mode-hooks}. It is run at the
936 very end of every properly-written major mode command.
939 @node Tabulated List Mode
940 @subsection Tabulated List mode
941 @cindex Tabulated List mode
943 Tabulated List mode is a major mode for displaying tabulated data,
944 i.e., data consisting of @dfn{entries}, each entry occupying one row of
945 text with its contents divided into columns. Tabulated List mode
946 provides facilities for pretty-printing rows and columns, and sorting
947 the rows according to the values in each column. It is derived from
948 Special mode (@pxref{Basic Major Modes}).
950 Tabulated List mode is intended to be used as a parent mode by a more
951 specialized major mode. Examples include Process Menu mode
952 (@pxref{Process Information}) and Package Menu mode (@pxref{Package
953 Menu,,, emacs, The GNU Emacs Manual}).
955 @findex tabulated-list-mode
956 Such a derived mode should use @code{define-derived-mode} in the usual
957 way, specifying @code{tabulated-list-mode} as the second argument
958 (@pxref{Derived Modes}). The body of the @code{define-derived-mode}
959 form should specify the format of the tabulated data, by assigning
960 values to the variables documented below; optionally, it can then call
961 the function @code{tabulated-list-init-header}, which will populate a
962 header with the names of the columns.
964 The derived mode should also define a @dfn{listing command}. This,
965 not the mode command, is what the user calls (e.g., @kbd{M-x
966 list-processes}). The listing command should create or switch to a
967 buffer, turn on the derived mode, specify the tabulated data, and
968 finally call @code{tabulated-list-print} to populate the buffer.
970 @defvar tabulated-list-format
971 This buffer-local variable specifies the format of the Tabulated List
972 data. Its value should be a vector. Each element of the vector
973 represents a data column, and should be a list @code{(@var{name}
974 @var{width} @var{sort})}, where
978 @var{name} is the column's name (a string).
981 @var{width} is the width to reserve for the column (an integer). This
982 is meaningless for the last column, which runs to the end of each line.
985 @var{sort} specifies how to sort entries by the column. If @code{nil},
986 the column cannot be used for sorting. If @code{t}, the column is
987 sorted by comparing string values. Otherwise, this should be a
988 predicate function for @code{sort} (@pxref{Rearrangement}), which
989 accepts two arguments with the same form as the elements of
990 @code{tabulated-list-entries} (see below).
994 @defvar tabulated-list-entries
995 This buffer-local variable specifies the entries displayed in the
996 Tabulated List buffer. Its value should be either a list, or a
999 If the value is a list, each list element corresponds to one entry, and
1000 should have the form @w{@code{(@var{id} @var{contents})}}, where
1004 @var{id} is either @code{nil}, or a Lisp object that identifies the
1005 entry. If the latter, the cursor stays on the same entry when
1006 re-sorting entries. Comparison is done with @code{equal}.
1009 @var{contents} is a vector with the same number of elements as
1010 @code{tabulated-list-format}. Each vector element is either a string,
1011 which is inserted into the buffer as-is, or a list @code{(@var{label}
1012 . @var{properties})}, which means to insert a text button by calling
1013 @code{insert-text-button} with @var{label} and @var{properties} as
1014 arguments (@pxref{Making Buttons}).
1016 There should be no newlines in any of these strings.
1019 Otherwise, the value should be a function which returns a list of the
1020 above form when called with no arguments.
1023 @defvar tabulated-list-revert-hook
1024 This normal hook is run prior to reverting a Tabulated List buffer. A
1025 derived mode can add a function to this hook to recompute
1026 @code{tabulated-list-entries}.
1029 @defvar tabulated-list-printer
1030 The value of this variable is the function called to insert an entry at
1031 point, including its terminating newline. The function should accept
1032 two arguments, @var{id} and @var{contents}, having the same meanings as
1033 in @code{tabulated-list-entries}. The default value is a function which
1034 inserts an entry in a straightforward way; a mode which uses Tabulated
1035 List mode in a more complex way can specify another function.
1038 @defvar tabulated-list-sort-key
1039 The value of this variable specifies the current sort key for the
1040 Tabulated List buffer. If it is @code{nil}, no sorting is done.
1041 Otherwise, it should have the form @code{(@var{name} . @var{flip})},
1042 where @var{name} is a string matching one of the column names in
1043 @code{tabulated-list-format}, and @var{flip}, if non-@code{nil}, means
1044 to invert the sort order.
1047 @defun tabulated-list-init-header
1048 This function computes and sets @code{header-line-format} for the
1049 Tabulated List buffer (@pxref{Header Lines}), and assigns a keymap to
1050 the header line to allow sorting entries by clicking on column headers.
1052 Modes derived from Tabulated List mode should call this after setting
1053 the above variables (in particular, only after setting
1054 @code{tabulated-list-format}).
1057 @defun tabulated-list-print &optional remember-pos update
1058 This function populates the current buffer with entries. It should be
1059 called by the listing command. It erases the buffer, sorts the entries
1060 specified by @code{tabulated-list-entries} according to
1061 @code{tabulated-list-sort-key}, then calls the function specified by
1062 @code{tabulated-list-printer} to insert each entry.
1064 If the optional argument @var{remember-pos} is non-@code{nil}, this
1065 function looks for the @var{id} element on the current line, if any, and
1066 tries to move to that entry after all the entries are (re)inserted.
1068 If the optional argument @var{update} is non-@code{nil}, this function
1069 will only erase or add entries that have changed since the last print.
1070 This is several times faster if most entries haven't changed since the
1071 last time this function was called. The only difference in outcome is
1072 that tags placed via @code{tabulated-list-put-tag} will not be removed
1073 from entries that haven't changed (normally all tags are removed).
1077 @subsection Generic Modes
1078 @cindex generic mode
1080 @dfn{Generic modes} are simple major modes with basic support for
1081 comment syntax and Font Lock mode. To define a generic mode, use the
1082 macro @code{define-generic-mode}. See the file @file{generic-x.el}
1083 for some examples of the use of @code{define-generic-mode}.
1085 @defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring
1086 This macro defines a generic mode command named @var{mode} (a symbol,
1087 not quoted). The optional argument @var{docstring} is the
1088 documentation for the mode command. If you do not supply it,
1089 @code{define-generic-mode} generates one by default.
1091 The argument @var{comment-list} is a list in which each element is
1092 either a character, a string of one or two characters, or a cons cell.
1093 A character or a string is set up in the mode's syntax table as a
1094 comment starter. If the entry is a cons cell, the @sc{car} is set
1095 up as a comment starter and the @sc{cdr} as a comment ender.
1096 (Use @code{nil} for the latter if you want comments to end at the end
1097 of the line.) Note that the syntax table mechanism has limitations
1098 about what comment starters and enders are actually possible.
1099 @xref{Syntax Tables}.
1101 The argument @var{keyword-list} is a list of keywords to highlight
1102 with @code{font-lock-keyword-face}. Each keyword should be a string.
1103 Meanwhile, @var{font-lock-list} is a list of additional expressions to
1104 highlight. Each element of this list should have the same form as an
1105 element of @code{font-lock-keywords}. @xref{Search-based
1108 The argument @var{auto-mode-list} is a list of regular expressions to
1109 add to the variable @code{auto-mode-alist}. They are added by the execution
1110 of the @code{define-generic-mode} form, not by expanding the macro call.
1112 Finally, @var{function-list} is a list of functions for the mode
1113 command to call for additional setup. It calls these functions just
1114 before it runs the mode hook variable @code{@var{mode}-hook}.
1117 @node Example Major Modes
1118 @subsection Major Mode Examples
1120 Text mode is perhaps the simplest mode besides Fundamental mode.
1121 Here are excerpts from @file{text-mode.el} that illustrate many of
1122 the conventions listed above:
1126 ;; @r{Create the syntax table for this mode.}
1127 (defvar text-mode-syntax-table
1128 (let ((st (make-syntax-table)))
1129 (modify-syntax-entry ?\" ". " st)
1130 (modify-syntax-entry ?\\ ". " st)
1131 ;; Add 'p' so M-c on 'hello' leads to 'Hello', not 'hello'.
1132 (modify-syntax-entry ?' "w p" st)
1134 "Syntax table used while in `text-mode'.")
1137 ;; @r{Create the keymap for this mode.}
1139 (defvar text-mode-map
1140 (let ((map (make-sparse-keymap)))
1141 (define-key map "\e\t" 'ispell-complete-word)
1143 "Keymap for `text-mode'.
1144 Many other modes, such as `mail-mode', `outline-mode' and
1145 `indented-text-mode', inherit all the commands defined in this map.")
1149 Here is how the actual mode command is defined now:
1153 (define-derived-mode text-mode nil "Text"
1154 "Major mode for editing text written for humans to read.
1155 In this mode, paragraphs are delimited only by blank or white lines.
1156 You can thus get the full benefit of adaptive filling
1157 (see the variable `adaptive-fill-mode').
1159 Turning on Text mode runs the normal hook `text-mode-hook'."
1162 (set (make-local-variable 'text-mode-variant) t)
1163 (set (make-local-variable 'require-final-newline)
1164 mode-require-final-newline)
1165 (set (make-local-variable 'indent-line-function) 'indent-relative))
1170 (The last line is redundant nowadays, since @code{indent-relative} is
1171 the default value, and we'll delete it in a future version.)
1173 @cindex @file{lisp-mode.el}
1174 The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp Interaction
1175 mode) have more features than Text mode and the code is correspondingly
1176 more complicated. Here are excerpts from @file{lisp-mode.el} that
1177 illustrate how these modes are written.
1179 Here is how the Lisp mode syntax and abbrev tables are defined:
1181 @cindex syntax table example
1184 ;; @r{Create mode-specific table variables.}
1185 (defvar lisp-mode-abbrev-table nil)
1186 (define-abbrev-table 'lisp-mode-abbrev-table ())
1188 (defvar lisp-mode-syntax-table
1189 (let ((table (copy-syntax-table emacs-lisp-mode-syntax-table)))
1190 (modify-syntax-entry ?\[ "_ " table)
1191 (modify-syntax-entry ?\] "_ " table)
1192 (modify-syntax-entry ?# "' 14" table)
1193 (modify-syntax-entry ?| "\" 23bn" table)
1195 "Syntax table used in `lisp-mode'.")
1199 The three modes for Lisp share much of their code. For instance,
1200 each calls the following function to set various variables:
1204 (defun lisp-mode-variables (&optional syntax keywords-case-insensitive)
1206 (set-syntax-table lisp-mode-syntax-table))
1207 (setq local-abbrev-table lisp-mode-abbrev-table)
1213 Amongst other things, this function sets up the @code{comment-start}
1214 variable to handle Lisp comments:
1218 (make-local-variable 'comment-start)
1219 (setq comment-start ";")
1224 Each of the different Lisp modes has a slightly different keymap. For
1225 example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other
1226 Lisp modes do not. However, all Lisp modes have some commands in
1227 common. The following code sets up the common commands:
1231 (defvar lisp-mode-shared-map
1232 (let ((map (make-sparse-keymap)))
1233 (define-key map "\e\C-q" 'indent-sexp)
1234 (define-key map "\177" 'backward-delete-char-untabify)
1236 "Keymap for commands shared by all sorts of Lisp modes.")
1241 And here is the code to set up the keymap for Lisp mode:
1245 (defvar lisp-mode-map
1246 (let ((map (make-sparse-keymap))
1247 (menu-map (make-sparse-keymap "Lisp")))
1248 (set-keymap-parent map lisp-mode-shared-map)
1249 (define-key map "\e\C-x" 'lisp-eval-defun)
1250 (define-key map "\C-c\C-z" 'run-lisp)
1253 "Keymap for ordinary Lisp mode.
1254 All commands in `lisp-mode-shared-map' are inherited by this map.")
1259 Finally, here is the major mode command for Lisp mode:
1263 (define-derived-mode lisp-mode prog-mode "Lisp"
1264 "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
1266 Delete converts tabs to spaces as it moves back.
1267 Blank lines separate paragraphs. Semicolons start comments.
1270 Note that `run-lisp' may be used either to start an inferior Lisp job
1271 or to switch back to an existing one.
1275 Entry to this mode calls the value of `lisp-mode-hook'
1276 if that value is non-nil."
1277 (lisp-mode-variables nil t)
1278 (set (make-local-variable 'find-tag-default-function)
1279 'lisp-find-tag-default)
1280 (set (make-local-variable 'comment-start-skip)
1281 "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *")
1282 (setq imenu-case-fold-search t))
1287 @section Minor Modes
1290 A @dfn{minor mode} provides optional features that users may enable or
1291 disable independently of the choice of major mode. Minor modes can be
1292 enabled individually or in combination.
1294 Most minor modes implement features that are independent of the major
1295 mode, and can thus be used with most major modes. For example, Auto
1296 Fill mode works with any major mode that permits text insertion. A few
1297 minor modes, however, are specific to a particular major mode. For
1298 example, Diff Auto Refine mode is a minor mode that is intended to be
1299 used only with Diff mode.
1301 Ideally, a minor mode should have its desired effect regardless of the
1302 other minor modes in effect. It should be possible to activate and
1303 deactivate minor modes in any order.
1305 @defvar minor-mode-list
1306 The value of this variable is a list of all minor mode commands.
1310 * Minor Mode Conventions:: Tips for writing a minor mode.
1311 * Keymaps and Minor Modes:: How a minor mode can have its own keymap.
1312 * Defining Minor Modes:: A convenient facility for defining minor modes.
1315 @node Minor Mode Conventions
1316 @subsection Conventions for Writing Minor Modes
1317 @cindex minor mode conventions
1318 @cindex conventions for writing minor modes
1320 There are conventions for writing minor modes just as there are for
1321 major modes. These conventions are described below. The easiest way to
1322 follow them is to use the macro @code{define-minor-mode}.
1323 @xref{Defining Minor Modes}.
1327 @cindex mode variable
1328 Define a variable whose name ends in @samp{-mode}. We call this the
1329 @dfn{mode variable}. The minor mode command should set this variable.
1330 The value will be @code{nil} if the mode is disabled, and non-@code{nil}
1331 if the mode is enabled. The variable should be buffer-local if the
1332 minor mode is buffer-local.
1334 This variable is used in conjunction with the @code{minor-mode-alist} to
1335 display the minor mode name in the mode line. It also determines
1336 whether the minor mode keymap is active, via @code{minor-mode-map-alist}
1337 (@pxref{Controlling Active Maps}). Individual commands or hooks can
1338 also check its value.
1341 Define a command, called the @dfn{mode command}, whose name is the same
1342 as the mode variable. Its job is to set the value of the mode variable,
1343 plus anything else that needs to be done to actually enable or disable
1344 the mode's features.
1346 The mode command should accept one optional argument. If called
1347 interactively with no prefix argument, it should toggle the mode
1348 (i.e., enable if it is disabled, and disable if it is enabled). If
1349 called interactively with a prefix argument, it should enable the mode
1350 if the argument is positive and disable it otherwise.
1352 If the mode command is called from Lisp (i.e., non-interactively), it
1353 should enable the mode if the argument is omitted or @code{nil}; it
1354 should toggle the mode if the argument is the symbol @code{toggle};
1355 otherwise it should treat the argument in the same way as for an
1356 interactive call with a numeric prefix argument, as described above.
1358 The following example shows how to implement this behavior (it is
1359 similar to the code generated by the @code{define-minor-mode} macro):
1362 (interactive (list (or current-prefix-arg 'toggle)))
1363 (let ((enable (if (eq arg 'toggle)
1364 (not foo-mode) ; @r{this mode's mode variable}
1365 (> (prefix-numeric-value arg) 0))))
1371 The reason for this somewhat complex behavior is that it lets users
1372 easily toggle the minor mode interactively, and also lets the minor mode
1373 be easily enabled in a mode hook, like this:
1376 (add-hook 'text-mode-hook 'foo-mode)
1380 This behaves correctly whether or not @code{foo-mode} was already
1381 enabled, since the @code{foo-mode} mode command unconditionally enables
1382 the minor mode when it is called from Lisp with no argument. Disabling
1383 a minor mode in a mode hook is a little uglier:
1386 (add-hook 'text-mode-hook (lambda () (foo-mode -1)))
1390 However, this is not very commonly done.
1393 Add an element to @code{minor-mode-alist} for each minor mode
1394 (@pxref{Definition of minor-mode-alist}), if you want to indicate the
1395 minor mode in the mode line. This element should be a list of the
1399 (@var{mode-variable} @var{string})
1402 Here @var{mode-variable} is the variable that controls enabling of the
1403 minor mode, and @var{string} is a short string, starting with a space,
1404 to represent the mode in the mode line. These strings must be short so
1405 that there is room for several of them at once.
1407 When you add an element to @code{minor-mode-alist}, use @code{assq} to
1408 check for an existing element, to avoid duplication. For example:
1412 (unless (assq 'leif-mode minor-mode-alist)
1413 (push '(leif-mode " Leif") minor-mode-alist))
1418 or like this, using @code{add-to-list} (@pxref{List Variables}):
1422 (add-to-list 'minor-mode-alist '(leif-mode " Leif"))
1427 In addition, several major mode conventions apply to minor modes as
1428 well: those regarding the names of global symbols, the use of a hook at
1429 the end of the initialization function, and the use of keymaps and other
1432 The minor mode should, if possible, support enabling and disabling via
1433 Custom (@pxref{Customization}). To do this, the mode variable should be
1434 defined with @code{defcustom}, usually with @code{:type 'boolean}. If
1435 just setting the variable is not sufficient to enable the mode, you
1436 should also specify a @code{:set} method which enables the mode by
1437 invoking the mode command. Note in the variable's documentation string
1438 that setting the variable other than via Custom may not take effect.
1439 Also, mark the definition with an autoload cookie (@pxref{autoload
1440 cookie}), and specify a @code{:require} so that customizing the variable
1441 will load the library that defines the mode. For example:
1446 (defcustom msb-mode nil
1448 Setting this variable directly does not take effect;
1449 use either \\[customize] or the function `msb-mode'."
1450 :set 'custom-set-minor-mode
1451 :initialize 'custom-initialize-default
1459 @node Keymaps and Minor Modes
1460 @subsection Keymaps and Minor Modes
1462 Each minor mode can have its own keymap, which is active when the mode
1463 is enabled. To set up a keymap for a minor mode, add an element to the
1464 alist @code{minor-mode-map-alist}. @xref{Definition of minor-mode-map-alist}.
1466 @cindex @code{self-insert-command}, minor modes
1467 One use of minor mode keymaps is to modify the behavior of certain
1468 self-inserting characters so that they do something else as well as
1469 self-insert. (Another way to customize @code{self-insert-command} is
1470 through @code{post-self-insert-hook}. Apart from this, the facilities
1471 for customizing @code{self-insert-command} are limited to special cases,
1472 designed for abbrevs and Auto Fill mode. Do not try substituting your
1473 own definition of @code{self-insert-command} for the standard one. The
1474 editor command loop handles this function specially.)
1476 Minor modes may bind commands to key sequences consisting of @kbd{C-c}
1477 followed by a punctuation character. However, sequences consisting of
1478 @kbd{C-c} followed by one of @kbd{@{@}<>:;}, or a control character or
1479 digit, are reserved for major modes. Also, @kbd{C-c @var{letter}} is
1480 reserved for users. @xref{Key Binding Conventions}.
1482 @node Defining Minor Modes
1483 @subsection Defining Minor Modes
1485 The macro @code{define-minor-mode} offers a convenient way of
1486 implementing a mode in one self-contained definition.
1488 @defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args@dots{} body@dots{}
1489 This macro defines a new minor mode whose name is @var{mode} (a
1490 symbol). It defines a command named @var{mode} to toggle the minor
1491 mode, with @var{doc} as its documentation string.
1493 The toggle command takes one optional (prefix) argument.
1494 If called interactively with no argument it toggles the mode on or off.
1495 A positive prefix argument enables the mode, any other prefix argument
1496 disables it. From Lisp, an argument of @code{toggle} toggles the mode,
1497 whereas an omitted or @code{nil} argument enables the mode.
1498 This makes it easy to enable the minor mode in a major mode hook, for example.
1499 If @var{doc} is @code{nil}, the macro supplies a default documentation string
1500 explaining the above.
1502 By default, it also defines a variable named @var{mode}, which is set to
1503 @code{t} or @code{nil} by enabling or disabling the mode. The variable
1504 is initialized to @var{init-value}. Except in unusual circumstances
1505 (see below), this value must be @code{nil}.
1507 The string @var{lighter} says what to display in the mode line
1508 when the mode is enabled; if it is @code{nil}, the mode is not displayed
1511 The optional argument @var{keymap} specifies the keymap for the minor
1512 mode. If non-@code{nil}, it should be a variable name (whose value is
1513 a keymap), a keymap, or an alist of the form
1516 (@var{key-sequence} . @var{definition})
1520 where each @var{key-sequence} and @var{definition} are arguments
1521 suitable for passing to @code{define-key} (@pxref{Changing Key
1522 Bindings}). If @var{keymap} is a keymap or an alist, this also
1523 defines the variable @code{@var{mode}-map}.
1525 The above three arguments @var{init-value}, @var{lighter}, and
1526 @var{keymap} can be (partially) omitted when @var{keyword-args} are
1527 used. The @var{keyword-args} consist of keywords followed by
1528 corresponding values. A few keywords have special meanings:
1531 @item :group @var{group}
1532 Custom group name to use in all generated @code{defcustom} forms.
1533 Defaults to @var{mode} without the possible trailing @samp{-mode}.
1534 @strong{Warning:} don't use this default group name unless you have
1535 written a @code{defgroup} to define that group properly. @xref{Group
1538 @item :global @var{global}
1539 If non-@code{nil}, this specifies that the minor mode should be global
1540 rather than buffer-local. It defaults to @code{nil}.
1542 One of the effects of making a minor mode global is that the
1543 @var{mode} variable becomes a customization variable. Toggling it
1544 through the Customize interface turns the mode on and off, and its
1545 value can be saved for future Emacs sessions (@pxref{Saving
1546 Customizations,,, emacs, The GNU Emacs Manual}. For the saved
1547 variable to work, you should ensure that the @code{define-minor-mode}
1548 form is evaluated each time Emacs starts; for packages that are not
1549 part of Emacs, the easiest way to do this is to specify a
1550 @code{:require} keyword.
1552 @item :init-value @var{init-value}
1553 This is equivalent to specifying @var{init-value} positionally.
1555 @item :lighter @var{lighter}
1556 This is equivalent to specifying @var{lighter} positionally.
1558 @item :keymap @var{keymap}
1559 This is equivalent to specifying @var{keymap} positionally.
1561 @item :variable @var{place}
1562 This replaces the default variable @var{mode}, used to store the state
1563 of the mode. If you specify this, the @var{mode} variable is not
1564 defined, and any @var{init-value} argument is unused. @var{place}
1565 can be a different named variable (which you must define yourself), or
1566 anything that can be used with the @code{setf} function
1567 (@pxref{Generalized Variables}).
1568 @var{place} can also be a cons @code{(@var{get} . @var{set})},
1569 where @var{get} is an expression that returns the current state,
1570 and @var{set} is a function of one argument (a state) that sets it.
1572 @item :after-hook @var{after-hook}
1573 This defines a single Lisp form which is evaluated after the mode hooks
1574 have run. It should not be quoted.
1577 Any other keyword arguments are passed directly to the
1578 @code{defcustom} generated for the variable @var{mode}.
1580 The command named @var{mode} first performs the standard actions such as
1581 setting the variable named @var{mode} and then executes the @var{body}
1582 forms, if any. It then runs the mode hook variable
1583 @code{@var{mode}-hook} and finishes by evaluating any form in
1587 The initial value must be @code{nil} except in cases where (1) the
1588 mode is preloaded in Emacs, or (2) it is painless for loading to
1589 enable the mode even though the user did not request it. For
1590 instance, if the mode has no effect unless something else is enabled,
1591 and will always be loaded by that time, enabling it by default is
1592 harmless. But these are unusual circumstances. Normally, the
1593 initial value must be @code{nil}.
1595 @findex easy-mmode-define-minor-mode
1596 The name @code{easy-mmode-define-minor-mode} is an alias
1599 Here is an example of using @code{define-minor-mode}:
1602 (define-minor-mode hungry-mode
1603 "Toggle Hungry mode.
1604 Interactively with no argument, this command toggles the mode.
1605 A positive prefix argument enables the mode, any other prefix
1606 argument disables it. From Lisp, argument omitted or nil enables
1607 the mode, `toggle' toggles the state.
1609 When Hungry mode is enabled, the control delete key
1610 gobbles all preceding whitespace except the last.
1611 See the command \\[hungry-electric-delete]."
1612 ;; The initial value.
1614 ;; The indicator for the mode line.
1616 ;; The minor mode bindings.
1617 '(([C-backspace] . hungry-electric-delete))
1622 This defines a minor mode named ``Hungry mode'', a command named
1623 @code{hungry-mode} to toggle it, a variable named @code{hungry-mode}
1624 which indicates whether the mode is enabled, and a variable named
1625 @code{hungry-mode-map} which holds the keymap that is active when the
1626 mode is enabled. It initializes the keymap with a key binding for
1627 @kbd{C-@key{DEL}}. It puts the variable @code{hungry-mode} into
1628 custom group @code{hunger}. There are no @var{body} forms---many
1629 minor modes don't need any.
1631 Here's an equivalent way to write it:
1634 (define-minor-mode hungry-mode
1635 "Toggle Hungry mode.
1636 ...rest of documentation as before..."
1637 ;; The initial value.
1639 ;; The indicator for the mode line.
1641 ;; The minor mode bindings.
1643 '(([C-backspace] . hungry-electric-delete)
1647 (hungry-electric-delete t))))
1651 @defmac define-globalized-minor-mode global-mode mode turn-on keyword-args@dots{}
1652 This defines a global toggle named @var{global-mode} whose meaning is
1653 to enable or disable the buffer-local minor mode @var{mode} in all
1654 buffers. To turn on the minor mode in a buffer, it uses the function
1655 @var{turn-on}; to turn off the minor mode, it calls @var{mode} with
1656 @minus{}1 as argument.
1658 Globally enabling the mode also affects buffers subsequently created
1659 by visiting files, and buffers that use a major mode other than
1660 Fundamental mode; but it does not detect the creation of a new buffer
1661 in Fundamental mode.
1663 This defines the customization option @var{global-mode} (@pxref{Customization}),
1664 which can be toggled in the Customize interface to turn the minor mode on
1665 and off. As with @code{define-minor-mode}, you should ensure that the
1666 @code{define-globalized-minor-mode} form is evaluated each time Emacs
1667 starts, for example by providing a @code{:require} keyword.
1669 Use @code{:group @var{group}} in @var{keyword-args} to specify the
1670 custom group for the mode variable of the global minor mode.
1672 Generally speaking, when you define a globalized minor mode, you should
1673 also define a non-globalized version, so that people can use (or
1674 disable) it in individual buffers. This also allows them to disable a
1675 globally enabled minor mode in a specific major mode, by using that
1680 @node Mode Line Format
1681 @section Mode Line Format
1684 Each Emacs window (aside from minibuffer windows) typically has a mode
1685 line at the bottom, which displays status information about the buffer
1686 displayed in the window. The mode line contains information about the
1687 buffer, such as its name, associated file, depth of recursive editing,
1688 and major and minor modes. A window can also have a @dfn{header
1689 line}, which is much like the mode line but appears at the top of the
1692 This section describes how to control the contents of the mode line
1693 and header line. We include it in this chapter because much of the
1694 information displayed in the mode line relates to the enabled major and
1698 * Base: Mode Line Basics. Basic ideas of mode line control.
1699 * Data: Mode Line Data. The data structure that controls the mode line.
1700 * Top: Mode Line Top. The top level variable, mode-line-format.
1701 * Mode Line Variables:: Variables used in that data structure.
1702 * %-Constructs:: Putting information into a mode line.
1703 * Properties in Mode:: Using text properties in the mode line.
1704 * Header Lines:: Like a mode line, but at the top.
1705 * Emulating Mode Line:: Formatting text as the mode line would.
1708 @node Mode Line Basics
1709 @subsection Mode Line Basics
1711 The contents of each mode line are specified by the buffer-local
1712 variable @code{mode-line-format} (@pxref{Mode Line Top}). This variable
1713 holds a @dfn{mode line construct}: a template that controls what is
1714 displayed on the buffer's mode line. The value of
1715 @code{header-line-format} specifies the buffer's header line in the same
1716 way. All windows for the same buffer use the same
1717 @code{mode-line-format} and @code{header-line-format}.
1719 For efficiency, Emacs does not continuously recompute each window's
1720 mode line and header line. It does so when circumstances appear to call
1721 for it---for instance, if you change the window configuration, switch
1722 buffers, narrow or widen the buffer, scroll, or modify the buffer. If
1723 you alter any of the variables referenced by @code{mode-line-format} or
1724 @code{header-line-format} (@pxref{Mode Line Variables}), or any other
1725 data structures that affect how text is displayed (@pxref{Display}), you
1726 should use the function @code{force-mode-line-update} to update the
1729 @defun force-mode-line-update &optional all
1730 This function forces Emacs to update the current buffer's mode line and
1731 header line, based on the latest values of all relevant variables,
1732 during its next redisplay cycle. If the optional argument @var{all} is
1733 non-@code{nil}, it forces an update for all mode lines and header lines.
1735 This function also forces an update of the menu bar and frame title.
1738 The selected window's mode line is usually displayed in a different
1739 color using the face @code{mode-line}. Other windows' mode lines appear
1740 in the face @code{mode-line-inactive} instead. @xref{Faces}.
1742 @node Mode Line Data
1743 @subsection The Data Structure of the Mode Line
1744 @cindex mode line construct
1746 The mode line contents are controlled by a data structure called a
1747 @dfn{mode line construct}, made up of lists, strings, symbols, and
1748 numbers kept in buffer-local variables. Each data type has a specific
1749 meaning for the mode line appearance, as described below. The same data
1750 structure is used for constructing frame titles (@pxref{Frame Titles})
1751 and header lines (@pxref{Header Lines}).
1753 A mode line construct may be as simple as a fixed string of text,
1754 but it usually specifies how to combine fixed strings with variables'
1755 values to construct the text. Many of these variables are themselves
1756 defined to have mode line constructs as their values.
1758 Here are the meanings of various data types as mode line constructs:
1761 @cindex percent symbol in mode line
1763 A string as a mode line construct appears verbatim except for
1764 @dfn{@code{%}-constructs} in it. These stand for substitution of
1765 other data; see @ref{%-Constructs}.
1767 If parts of the string have @code{face} properties, they control
1768 display of the text just as they would text in the buffer. Any
1769 characters which have no @code{face} properties are displayed, by
1770 default, in the face @code{mode-line} or @code{mode-line-inactive}
1771 (@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}). The
1772 @code{help-echo} and @code{keymap} properties in @var{string} have
1773 special meanings. @xref{Properties in Mode}.
1776 A symbol as a mode line construct stands for its value. The value of
1777 @var{symbol} is used as a mode line construct, in place of @var{symbol}.
1778 However, the symbols @code{t} and @code{nil} are ignored, as is any
1779 symbol whose value is void.
1781 There is one exception: if the value of @var{symbol} is a string, it is
1782 displayed verbatim: the @code{%}-constructs are not recognized.
1784 Unless @var{symbol} is marked as risky (i.e., it has a
1785 non-@code{nil} @code{risky-local-variable} property), all text
1786 properties specified in @var{symbol}'s value are ignored. This includes
1787 the text properties of strings in @var{symbol}'s value, as well as all
1788 @code{:eval} and @code{:propertize} forms in it. (The reason for this
1789 is security: non-risky variables could be set automatically from file
1790 variables without prompting the user.)
1792 @item (@var{string} @var{rest}@dots{})
1793 @itemx (@var{list} @var{rest}@dots{})
1794 A list whose first element is a string or list means to process all the
1795 elements recursively and concatenate the results. This is the most
1796 common form of mode line construct.
1798 @item (:eval @var{form})
1799 A list whose first element is the symbol @code{:eval} says to evaluate
1800 @var{form}, and use the result as a string to display. Make sure this
1801 evaluation cannot load any files, as doing so could cause infinite
1804 @item (:propertize @var{elt} @var{props}@dots{})
1805 A list whose first element is the symbol @code{:propertize} says to
1806 process the mode line construct @var{elt} recursively, then add the text
1807 properties specified by @var{props} to the result. The argument
1808 @var{props} should consist of zero or more pairs @var{text-property}
1811 @item (@var{symbol} @var{then} @var{else})
1812 A list whose first element is a symbol that is not a keyword specifies
1813 a conditional. Its meaning depends on the value of @var{symbol}. If
1814 @var{symbol} has a non-@code{nil} value, the second element,
1815 @var{then}, is processed recursively as a mode line construct.
1816 Otherwise, the third element, @var{else}, is processed recursively.
1817 You may omit @var{else}; then the mode line construct displays nothing
1818 if the value of @var{symbol} is @code{nil} or void.
1820 @item (@var{width} @var{rest}@dots{})
1821 A list whose first element is an integer specifies truncation or
1822 padding of the results of @var{rest}. The remaining elements
1823 @var{rest} are processed recursively as mode line constructs and
1824 concatenated together. When @var{width} is positive, the result is
1825 space filled on the right if its width is less than @var{width}. When
1826 @var{width} is negative, the result is truncated on the right to
1827 @minus{}@var{width} columns if its width exceeds @minus{}@var{width}.
1829 For example, the usual way to show what percentage of a buffer is above
1830 the top of the window is to use a list like this: @code{(-3 "%p")}.
1834 @subsection The Top Level of Mode Line Control
1836 The variable in overall control of the mode line is
1837 @code{mode-line-format}.
1839 @defopt mode-line-format
1840 The value of this variable is a mode line construct that controls the
1841 contents of the mode-line. It is always buffer-local in all buffers.
1843 If you set this variable to @code{nil} in a buffer, that buffer does not
1844 have a mode line. (A window that is just one line tall also does not
1845 display a mode line.)
1848 The default value of @code{mode-line-format} is designed to use the
1849 values of other variables such as @code{mode-line-position} and
1850 @code{mode-line-modes} (which in turn incorporates the values of the
1851 variables @code{mode-name} and @code{minor-mode-alist}). Very few
1852 modes need to alter @code{mode-line-format} itself. For most
1853 purposes, it is sufficient to alter some of the variables that
1854 @code{mode-line-format} either directly or indirectly refers to.
1856 If you do alter @code{mode-line-format} itself, the new value should
1857 use the same variables that appear in the default value (@pxref{Mode
1858 Line Variables}), rather than duplicating their contents or displaying
1859 the information in another fashion. This way, customizations made by
1860 the user or by Lisp programs (such as @code{display-time} and major
1861 modes) via changes to those variables remain effective.
1863 Here is a hypothetical example of a @code{mode-line-format} that might
1864 be useful for Shell mode (in reality, Shell mode does not set
1865 @code{mode-line-format}):
1869 (setq mode-line-format
1871 'mode-line-mule-info
1873 'mode-line-frame-identification
1877 ;; @r{Note that this is evaluated while making the list.}
1878 ;; @r{It makes a mode line construct which is just a string.}
1886 '(:eval (mode-line-mode-name))
1892 '(which-func-mode ("" which-func-format "--"))
1893 '(line-number-mode "L%l--")
1894 '(column-number-mode "C%c--")
1900 (The variables @code{line-number-mode}, @code{column-number-mode}
1901 and @code{which-func-mode} enable particular minor modes; as usual,
1902 these variable names are also the minor mode command names.)
1904 @node Mode Line Variables
1905 @subsection Variables Used in the Mode Line
1907 This section describes variables incorporated by the standard value of
1908 @code{mode-line-format} into the text of the mode line. There is
1909 nothing inherently special about these variables; any other variables
1910 could have the same effects on the mode line if the value of
1911 @code{mode-line-format} is changed to use them. However, various parts
1912 of Emacs set these variables on the understanding that they will control
1913 parts of the mode line; therefore, practically speaking, it is essential
1914 for the mode line to use them. Also see
1915 @ref{Optional Mode Line,,, emacs, The GNU Emacs Manual}.
1917 @defvar mode-line-mule-info
1918 This variable holds the value of the mode line construct that displays
1919 information about the language environment, buffer coding system, and
1920 current input method. @xref{Non-ASCII Characters}.
1923 @defvar mode-line-modified
1924 This variable holds the value of the mode line construct that displays
1925 whether the current buffer is modified. Its default value displays
1926 @samp{**} if the buffer is modified, @samp{--} if the buffer is not
1927 modified, @samp{%%} if the buffer is read only, and @samp{%*} if the
1928 buffer is read only and modified.
1930 Changing this variable does not force an update of the mode line.
1933 @defvar mode-line-frame-identification
1934 This variable identifies the current frame. Its default value
1935 displays @code{" "} if you are using a window system which can show
1936 multiple frames, or @code{"-%F "} on an ordinary terminal which shows
1937 only one frame at a time.
1940 @defvar mode-line-buffer-identification
1941 This variable identifies the buffer being displayed in the window.
1942 Its default value displays the buffer name, padded with spaces to at
1946 @defvar mode-line-position
1947 This variable indicates the position in the buffer. Its default value
1948 displays the buffer percentage and, optionally, the buffer size, the
1949 line number and the column number.
1953 The variable @code{vc-mode}, buffer-local in each buffer, records
1954 whether the buffer's visited file is maintained with version control,
1955 and, if so, which kind. Its value is a string that appears in the mode
1956 line, or @code{nil} for no version control.
1959 @defvar mode-line-modes
1960 This variable displays the buffer's major and minor modes. Its
1961 default value also displays the recursive editing level, information
1962 on the process status, and whether narrowing is in effect.
1965 @defvar mode-line-remote
1966 This variable is used to show whether @code{default-directory} for the
1967 current buffer is remote.
1970 @defvar mode-line-client
1971 This variable is used to identify @code{emacsclient} frames.
1974 The following three variables are used in @code{mode-line-modes}:
1977 This buffer-local variable holds the ``pretty'' name of the current
1978 buffer's major mode. Each major mode should set this variable so that
1979 the mode name will appear in the mode line. The value does not have
1980 to be a string, but can use any of the data types valid in a mode-line
1981 construct (@pxref{Mode Line Data}). To compute the string that will
1982 identify the mode name in the mode line, use @code{format-mode-line}
1983 (@pxref{Emulating Mode Line}).
1986 @defvar mode-line-process
1987 This buffer-local variable contains the mode line information on process
1988 status in modes used for communicating with subprocesses. It is
1989 displayed immediately following the major mode name, with no intervening
1990 space. For example, its value in the @file{*shell*} buffer is
1991 @code{(":%s")}, which allows the shell to display its status along
1992 with the major mode as: @samp{(Shell:run)}. Normally this variable
1996 @defvar mode-line-front-space
1997 This variable is displayed at the front of the mode line. By default,
1998 this construct is displayed right at the beginning of the mode line,
1999 except that if there is a memory-full message, it is displayed first.
2002 @defvar mode-line-end-spaces
2003 This variable is displayed at the end of the mode line.
2006 @defvar mode-line-misc-info
2007 Mode line construct for miscellaneous information. By default, this
2008 shows the information specified by @code{global-mode-string}.
2011 @defvar minor-mode-alist
2012 @anchor{Definition of minor-mode-alist}
2013 This variable holds an association list whose elements specify how the
2014 mode line should indicate that a minor mode is active. Each element of
2015 the @code{minor-mode-alist} should be a two-element list:
2018 (@var{minor-mode-variable} @var{mode-line-string})
2021 More generally, @var{mode-line-string} can be any mode line construct.
2022 It appears in the mode line when the value of @var{minor-mode-variable}
2023 is non-@code{nil}, and not otherwise. These strings should begin with
2024 spaces so that they don't run together. Conventionally, the
2025 @var{minor-mode-variable} for a specific mode is set to a non-@code{nil}
2026 value when that minor mode is activated.
2028 @code{minor-mode-alist} itself is not buffer-local. Each variable
2029 mentioned in the alist should be buffer-local if its minor mode can be
2030 enabled separately in each buffer.
2033 @defvar global-mode-string
2034 This variable holds a mode line construct that, by default, appears in
2035 the mode line just after the @code{which-func-mode} minor mode if set,
2036 else after @code{mode-line-modes}. The command @code{display-time} sets
2037 @code{global-mode-string} to refer to the variable
2038 @code{display-time-string}, which holds a string containing the time and
2041 The @samp{%M} construct substitutes the value of
2042 @code{global-mode-string}, but that is obsolete, since the variable is
2043 included in the mode line from @code{mode-line-format}.
2046 Here is a simplified version of the default value of
2047 @code{mode-line-format}. The real default value also
2048 specifies addition of text properties.
2055 mode-line-frame-identification
2056 mode-line-buffer-identification
2064 (which-func-mode ("" which-func-format "--"))
2065 (global-mode-string ("--" global-mode-string))
2071 @subsection @code{%}-Constructs in the Mode Line
2073 Strings used as mode line constructs can use certain
2074 @code{%}-constructs to substitute various kinds of data. The
2075 following is a list of the defined @code{%}-constructs, and what they
2078 In any construct except @samp{%%}, you can add a decimal integer
2079 after the @samp{%} to specify a minimum field width. If the width is
2080 less, the field is padded to that width. Purely numeric constructs
2081 (@samp{c}, @samp{i}, @samp{I}, and @samp{l}) are padded by inserting
2082 spaces to the left, and others are padded by inserting spaces to the
2087 The current buffer name, obtained with the @code{buffer-name} function.
2088 @xref{Buffer Names}.
2091 The current column number of point.
2094 When Emacs is nearly out of memory for Lisp objects, a brief message
2095 saying so. Otherwise, this is empty.
2098 The visited file name, obtained with the @code{buffer-file-name}
2099 function. @xref{Buffer File Name}.
2102 The title (only on a window system) or the name of the selected frame.
2103 @xref{Basic Parameters}.
2106 The size of the accessible part of the current buffer; basically
2107 @code{(- (point-max) (point-min))}.
2110 Like @samp{%i}, but the size is printed in a more readable way by using
2111 @samp{k} for 10^3, @samp{M} for 10^6, @samp{G} for 10^9, etc., to
2115 The current line number of point, counting within the accessible portion
2119 @samp{Narrow} when narrowing is in effect; nothing otherwise (see
2120 @code{narrow-to-region} in @ref{Narrowing}).
2123 The percentage of the buffer text above the @strong{top} of window, or
2124 @samp{Top}, @samp{Bottom} or @samp{All}. Note that the default mode
2125 line construct truncates this to three characters.
2128 The percentage of the buffer text that is above the @strong{bottom} of
2129 the window (which includes the text visible in the window, as well as
2130 the text above the top), plus @samp{Top} if the top of the buffer is
2131 visible on screen; or @samp{Bottom} or @samp{All}.
2134 The status of the subprocess belonging to the current buffer, obtained with
2135 @code{process-status}. @xref{Process Information}.
2138 The mnemonics of keyboard, terminal, and buffer coding systems.
2141 Like @samp{%z}, but including the end-of-line format.
2144 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
2145 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
2146 @samp{-} otherwise. @xref{Buffer Modification}.
2149 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
2150 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
2151 @samp{-} otherwise. This differs from @samp{%*} only for a modified
2152 read-only buffer. @xref{Buffer Modification}.
2155 @samp{*} if the buffer is modified, and @samp{-} otherwise.
2158 An indication of the depth of recursive editing levels (not counting
2159 minibuffer levels): one @samp{[} for each editing level.
2160 @xref{Recursive Editing}.
2163 One @samp{]} for each recursive editing level (not counting minibuffer
2167 Dashes sufficient to fill the remainder of the mode line.
2170 The character @samp{%}---this is how to include a literal @samp{%} in a
2171 string in which @code{%}-constructs are allowed.
2174 The following two @code{%}-constructs are still supported, but they are
2175 obsolete, since you can get the same results with the variables
2176 @code{mode-name} and @code{global-mode-string}.
2180 The value of @code{mode-name}.
2183 The value of @code{global-mode-string}.
2186 @node Properties in Mode
2187 @subsection Properties in the Mode Line
2188 @cindex text properties in the mode line
2190 Certain text properties are meaningful in the
2191 mode line. The @code{face} property affects the appearance of text; the
2192 @code{help-echo} property associates help strings with the text, and
2193 @code{keymap} can make the text mouse-sensitive.
2195 There are four ways to specify text properties for text in the mode
2200 Put a string with a text property directly into the mode line data
2204 Put a text property on a mode line %-construct such as @samp{%12b}; then
2205 the expansion of the %-construct will have that same text property.
2208 Use a @code{(:propertize @var{elt} @var{props}@dots{})} construct to
2209 give @var{elt} a text property specified by @var{props}.
2212 Use a list containing @code{:eval @var{form}} in the mode line data
2213 structure, and make @var{form} evaluate to a string that has a text
2217 You can use the @code{keymap} property to specify a keymap. This
2218 keymap only takes real effect for mouse clicks; binding character keys
2219 and function keys to it has no effect, since it is impossible to move
2220 point into the mode line.
2222 When the mode line refers to a variable which does not have a
2223 non-@code{nil} @code{risky-local-variable} property, any text
2224 properties given or specified within that variable's values are
2225 ignored. This is because such properties could otherwise specify
2226 functions to be called, and those functions could come from file
2230 @subsection Window Header Lines
2231 @cindex header line (of a window)
2232 @cindex window header line
2234 A window can have a @dfn{header line} at the top, just as it can have
2235 a mode line at the bottom. The header line feature works just like the
2236 mode line feature, except that it's controlled by
2237 @code{header-line-format}:
2239 @defvar header-line-format
2240 This variable, local in every buffer, specifies how to display the
2241 header line, for windows displaying the buffer. The format of the value
2242 is the same as for @code{mode-line-format} (@pxref{Mode Line Data}).
2243 It is normally @code{nil}, so that ordinary buffers have no header line.
2246 @defun window-header-line-height &optional window
2247 This function returns the height in pixels of @var{window}'s header
2248 line. @var{window} must be a live window, and defaults to the
2252 A window that is just one line tall never displays a header line. A
2253 window that is two lines tall cannot display both a mode line and a
2254 header line at once; if it has a mode line, then it does not display a
2257 @node Emulating Mode Line
2258 @subsection Emulating Mode Line Formatting
2260 You can use the function @code{format-mode-line} to compute the text
2261 that would appear in a mode line or header line based on a certain
2262 mode line construct.
2264 @defun format-mode-line format &optional face window buffer
2265 This function formats a line of text according to @var{format} as if it
2266 were generating the mode line for @var{window}, but it also returns the
2267 text as a string. The argument @var{window} defaults to the selected
2268 window. If @var{buffer} is non-@code{nil}, all the information used is
2269 taken from @var{buffer}; by default, it comes from @var{window}'s
2272 The value string normally has text properties that correspond to the
2273 faces, keymaps, etc., that the mode line would have. Any character for
2274 which no @code{face} property is specified by @var{format} gets a
2275 default value determined by @var{face}. If @var{face} is @code{t}, that
2276 stands for either @code{mode-line} if @var{window} is selected,
2277 otherwise @code{mode-line-inactive}. If @var{face} is @code{nil} or
2278 omitted, that stands for the default face. If @var{face} is an integer,
2279 the value returned by this function will have no text properties.
2281 You can also specify other valid faces as the value of @var{face}.
2282 If specified, that face provides the @code{face} property for characters
2283 whose face is not specified by @var{format}.
2285 Note that using @code{mode-line}, @code{mode-line-inactive}, or
2286 @code{header-line} as @var{face} will actually redisplay the mode line
2287 or the header line, respectively, using the current definitions of the
2288 corresponding face, in addition to returning the formatted string.
2289 (Other faces do not cause redisplay.)
2291 For example, @code{(format-mode-line header-line-format)} returns the
2292 text that would appear in the selected window's header line (@code{""}
2293 if it has no header line). @code{(format-mode-line header-line-format
2294 'header-line)} returns the same text, with each character
2295 carrying the face that it will have in the header line itself, and also
2296 redraws the header line.
2303 @dfn{Imenu} is a feature that lets users select a definition or
2304 section in the buffer, from a menu which lists all of them, to go
2305 directly to that location in the buffer. Imenu works by constructing
2306 a buffer index which lists the names and buffer positions of the
2307 definitions, or other named portions of the buffer; then the user can
2308 choose one of them and move point to it. Major modes can add a menu
2309 bar item to use Imenu using @code{imenu-add-to-menubar}.
2311 @deffn Command imenu-add-to-menubar name
2312 This function defines a local menu bar item named @var{name}
2316 The user-level commands for using Imenu are described in the Emacs
2317 Manual (@pxref{Imenu,, Imenu, emacs, the Emacs Manual}). This section
2318 explains how to customize Imenu's method of finding definitions or
2319 buffer portions for a particular major mode.
2321 The usual and simplest way is to set the variable
2322 @code{imenu-generic-expression}:
2324 @defvar imenu-generic-expression
2325 This variable, if non-@code{nil}, is a list that specifies regular
2326 expressions for finding definitions for Imenu. Simple elements of
2327 @code{imenu-generic-expression} look like this:
2330 (@var{menu-title} @var{regexp} @var{index})
2333 Here, if @var{menu-title} is non-@code{nil}, it says that the matches
2334 for this element should go in a submenu of the buffer index;
2335 @var{menu-title} itself specifies the name for the submenu. If
2336 @var{menu-title} is @code{nil}, the matches for this element go directly
2337 in the top level of the buffer index.
2339 The second item in the list, @var{regexp}, is a regular expression
2340 (@pxref{Regular Expressions}); anything in the buffer that it matches
2341 is considered a definition, something to mention in the buffer index.
2342 The third item, @var{index}, is a non-negative integer that indicates
2343 which subexpression in @var{regexp} matches the definition's name.
2345 An element can also look like this:
2348 (@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{})
2351 Each match for this element creates an index item, and when the index
2352 item is selected by the user, it calls @var{function} with arguments
2353 consisting of the item name, the buffer position, and @var{arguments}.
2355 For Emacs Lisp mode, @code{imenu-generic-expression} could look like
2358 @c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]
2361 ((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
2362 \\s-+\\([-A-Za-z0-9+]+\\)" 2)
2365 ("*Vars*" "^\\s-*(def\\(var\\|const\\)\
2366 \\s-+\\([-A-Za-z0-9+]+\\)" 2)
2371 (def\\(type\\|struct\\|class\\|ine-condition\\)\
2372 \\s-+\\([-A-Za-z0-9+]+\\)" 2))
2376 Setting this variable makes it buffer-local in the current buffer.
2379 @defvar imenu-case-fold-search
2380 This variable controls whether matching against the regular
2381 expressions in the value of @code{imenu-generic-expression} is
2382 case-sensitive: @code{t}, the default, means matching should ignore
2385 Setting this variable makes it buffer-local in the current buffer.
2388 @defvar imenu-syntax-alist
2389 This variable is an alist of syntax table modifiers to use while
2390 processing @code{imenu-generic-expression}, to override the syntax table
2391 of the current buffer. Each element should have this form:
2394 (@var{characters} . @var{syntax-description})
2397 The @sc{car}, @var{characters}, can be either a character or a string.
2398 The element says to give that character or characters the syntax
2399 specified by @var{syntax-description}, which is passed to
2400 @code{modify-syntax-entry} (@pxref{Syntax Table Functions}).
2402 This feature is typically used to give word syntax to characters which
2403 normally have symbol syntax, and thus to simplify
2404 @code{imenu-generic-expression} and speed up matching.
2405 For example, Fortran mode uses it this way:
2408 (setq imenu-syntax-alist '(("_$" . "w")))
2411 The @code{imenu-generic-expression} regular expressions can then use
2412 @samp{\\sw+} instead of @samp{\\(\\sw\\|\\s_\\)+}. Note that this
2413 technique may be inconvenient when the mode needs to limit the initial
2414 character of a name to a smaller set of characters than are allowed in
2417 Setting this variable makes it buffer-local in the current buffer.
2420 Another way to customize Imenu for a major mode is to set the
2421 variables @code{imenu-prev-index-position-function} and
2422 @code{imenu-extract-index-name-function}:
2424 @defvar imenu-prev-index-position-function
2425 If this variable is non-@code{nil}, its value should be a function that
2426 finds the next definition to put in the buffer index, scanning
2427 backward in the buffer from point. It should return @code{nil} if it
2428 doesn't find another definition before point. Otherwise it should
2429 leave point at the place it finds a definition and return any
2430 non-@code{nil} value.
2432 Setting this variable makes it buffer-local in the current buffer.
2435 @defvar imenu-extract-index-name-function
2436 If this variable is non-@code{nil}, its value should be a function to
2437 return the name for a definition, assuming point is in that definition
2438 as the @code{imenu-prev-index-position-function} function would leave
2441 Setting this variable makes it buffer-local in the current buffer.
2444 The last way to customize Imenu for a major mode is to set the
2445 variable @code{imenu-create-index-function}:
2447 @defvar imenu-create-index-function
2448 This variable specifies the function to use for creating a buffer
2449 index. The function should take no arguments, and return an index
2450 alist for the current buffer. It is called within
2451 @code{save-excursion}, so where it leaves point makes no difference.
2453 The index alist can have three types of elements. Simple elements
2457 (@var{index-name} . @var{index-position})
2460 Selecting a simple element has the effect of moving to position
2461 @var{index-position} in the buffer. Special elements look like this:
2464 (@var{index-name} @var{index-position} @var{function} @var{arguments}@dots{})
2467 Selecting a special element performs:
2470 (funcall @var{function}
2471 @var{index-name} @var{index-position} @var{arguments}@dots{})
2474 A nested sub-alist element looks like this:
2477 (@var{menu-title} . @var{sub-alist})
2480 It creates the submenu @var{menu-title} specified by @var{sub-alist}.
2482 The default value of @code{imenu-create-index-function} is
2483 @code{imenu-default-create-index-function}. This function calls the
2484 value of @code{imenu-prev-index-position-function} and the value of
2485 @code{imenu-extract-index-name-function} to produce the index alist.
2486 However, if either of these two variables is @code{nil}, the default
2487 function uses @code{imenu-generic-expression} instead.
2489 Setting this variable makes it buffer-local in the current buffer.
2492 @node Font Lock Mode
2493 @section Font Lock Mode
2494 @cindex Font Lock mode
2496 @dfn{Font Lock mode} is a buffer-local minor mode that automatically
2497 attaches @code{face} properties to certain parts of the buffer based on
2498 their syntactic role. How it parses the buffer depends on the major
2499 mode; most major modes define syntactic criteria for which faces to use
2500 in which contexts. This section explains how to customize Font Lock for
2501 a particular major mode.
2503 Font Lock mode finds text to highlight in two ways: through
2504 syntactic parsing based on the syntax table, and through searching
2505 (usually for regular expressions). Syntactic fontification happens
2506 first; it finds comments and string constants and highlights them.
2507 Search-based fontification happens second.
2510 * Font Lock Basics:: Overview of customizing Font Lock.
2511 * Search-based Fontification:: Fontification based on regexps.
2512 * Customizing Keywords:: Customizing search-based fontification.
2513 * Other Font Lock Variables:: Additional customization facilities.
2514 * Levels of Font Lock:: Each mode can define alternative levels
2515 so that the user can select more or less.
2516 * Precalculated Fontification:: How Lisp programs that produce the buffer
2517 contents can also specify how to fontify it.
2518 * Faces for Font Lock:: Special faces specifically for Font Lock.
2519 * Syntactic Font Lock:: Fontification based on syntax tables.
2520 * Multiline Font Lock:: How to coerce Font Lock into properly
2521 highlighting multiline constructs.
2524 @node Font Lock Basics
2525 @subsection Font Lock Basics
2527 The Font Lock functionality is based on several basic functions.
2528 Each of these calls the function specified by the corresponding
2529 variable. This indirection allows major and minor modes to modify the
2530 way fontification works in the buffers of that mode, and even use the
2531 Font Lock mechanisms for features that have nothing to do with
2532 fontification. (This is why the description below says ``should''
2533 when it describes what the functions do: the mode can customize the
2534 values of the corresponding variables to do something entirely
2535 different.) The variables mentioned below are described in @ref{Other
2536 Font Lock Variables}.
2539 @item font-lock-fontify-buffer
2540 This function should fontify the current buffer's accessible portion,
2541 by calling the function specified by
2542 @code{font-lock-fontify-buffer-function}.
2544 @item font-lock-unfontify-buffer
2545 Used when turning Font Lock off to remove the fontification. Calls
2546 the function specified by @code{font-lock-unfontify-buffer-function}.
2548 @item font-lock-fontify-region beg end &optional loudly
2549 Should fontify the region between @var{beg} and @var{end}. If
2550 @var{loudly} is non-@code{nil}, should display status messages while
2551 fontifying. Calls the function specified by
2552 @code{font-lock-fontify-region-function}.
2554 @item font-lock-unfontify-region beg end
2555 Should remove fontification from the region between @var{beg} and
2556 @var{end}. Calls the function specified by
2557 @code{font-lock-unfontify-region-function}.
2559 @item font-lock-flush &optional beg end
2560 This function should mark the fontification of the region between
2561 @var{beg} and @var{end} as outdated. If not specified or @code{nil},
2562 @var{beg} and @var{end} default to the beginning and end of the
2563 buffer's accessible portion. Calls the function specified by
2564 @code{font-lock-flush-function}.
2566 @item font-lock-ensure &optional beg end
2567 This function should make sure the region between @var{beg} and
2568 @var{end} has been fontified. The optional arguments @var{beg} and
2569 @var{end} default to the beginning and the end of the buffer's
2570 accessible portion. Calls the function specified by
2571 @code{font-lock-ensure-function}.
2574 There are several variables that control how Font Lock mode highlights
2575 text. But major modes should not set any of these variables directly.
2576 Instead, they should set @code{font-lock-defaults} as a buffer-local
2577 variable. The value assigned to this variable is used, if and when Font
2578 Lock mode is enabled, to set all the other variables.
2580 @defvar font-lock-defaults
2581 This variable is set by modes to specify how to fontify text in that
2582 mode. It automatically becomes buffer-local when set. If its value
2583 is @code{nil}, Font Lock mode does no highlighting, and you can use
2584 the @samp{Faces} menu (under @samp{Edit} and then @samp{Text
2585 Properties} in the menu bar) to assign faces explicitly to text in the
2588 If non-@code{nil}, the value should look like this:
2591 (@var{keywords} [@var{keywords-only} [@var{case-fold}
2592 [@var{syntax-alist} @var{other-vars}@dots{}]]])
2595 The first element, @var{keywords}, indirectly specifies the value of
2596 @code{font-lock-keywords} which directs search-based fontification.
2597 It can be a symbol, a variable or a function whose value is the list
2598 to use for @code{font-lock-keywords}. It can also be a list of
2599 several such symbols, one for each possible level of fontification.
2600 The first symbol specifies the @samp{mode default} level of
2601 fontification, the next symbol level 1 fontification, the next level 2,
2602 and so on. The @samp{mode default} level is normally the same as level
2603 1. It is used when @code{font-lock-maximum-decoration} has a @code{nil}
2604 value. @xref{Levels of Font Lock}.
2606 The second element, @var{keywords-only}, specifies the value of the
2607 variable @code{font-lock-keywords-only}. If this is omitted or
2608 @code{nil}, syntactic fontification (of strings and comments) is also
2609 performed. If this is non-@code{nil}, syntactic fontification is not
2610 performed. @xref{Syntactic Font Lock}.
2612 The third element, @var{case-fold}, specifies the value of
2613 @code{font-lock-keywords-case-fold-search}. If it is non-@code{nil},
2614 Font Lock mode ignores case during search-based fontification.
2616 If the fourth element, @var{syntax-alist}, is non-@code{nil}, it should
2617 be a list of cons cells of the form @code{(@var{char-or-string}
2618 . @var{string})}. These are used to set up a syntax table for syntactic
2619 fontification; the resulting syntax table is stored in
2620 @code{font-lock-syntax-table}. If @var{syntax-alist} is omitted or
2621 @code{nil}, syntactic fontification uses the syntax table returned by
2622 the @code{syntax-table} function. @xref{Syntax Table Functions}.
2624 All the remaining elements (if any) are collectively called
2625 @var{other-vars}. Each of these elements should have the form
2626 @code{(@var{variable} . @var{value})}---which means, make
2627 @var{variable} buffer-local and then set it to @var{value}. You can
2628 use these @var{other-vars} to set other variables that affect
2629 fontification, aside from those you can control with the first five
2630 elements. @xref{Other Font Lock Variables}.
2633 If your mode fontifies text explicitly by adding
2634 @code{font-lock-face} properties, it can specify @code{(nil t)} for
2635 @code{font-lock-defaults} to turn off all automatic fontification.
2636 However, this is not required; it is possible to fontify some things
2637 using @code{font-lock-face} properties and set up automatic
2638 fontification for other parts of the text.
2640 @node Search-based Fontification
2641 @subsection Search-based Fontification
2643 The variable which directly controls search-based fontification is
2644 @code{font-lock-keywords}, which is typically specified via the
2645 @var{keywords} element in @code{font-lock-defaults}.
2647 @defvar font-lock-keywords
2648 The value of this variable is a list of the keywords to highlight. Lisp
2649 programs should not set this variable directly. Normally, the value is
2650 automatically set by Font Lock mode, using the @var{keywords} element in
2651 @code{font-lock-defaults}. The value can also be altered using the
2652 functions @code{font-lock-add-keywords} and
2653 @code{font-lock-remove-keywords} (@pxref{Customizing Keywords}).
2656 Each element of @code{font-lock-keywords} specifies how to find
2657 certain cases of text, and how to highlight those cases. Font Lock mode
2658 processes the elements of @code{font-lock-keywords} one by one, and for
2659 each element, it finds and handles all matches. Ordinarily, once
2660 part of the text has been fontified already, this cannot be overridden
2661 by a subsequent match in the same text; but you can specify different
2662 behavior using the @var{override} element of a @var{subexp-highlighter}.
2664 Each element of @code{font-lock-keywords} should have one of these
2669 Highlight all matches for @var{regexp} using
2670 @code{font-lock-keyword-face}. For example,
2673 ;; @r{Highlight occurrences of the word @samp{foo}}
2674 ;; @r{using @code{font-lock-keyword-face}.}
2678 Be careful when composing these regular expressions; a poorly written
2679 pattern can dramatically slow things down! The function
2680 @code{regexp-opt} (@pxref{Regexp Functions}) is useful for calculating
2681 optimal regular expressions to match several keywords.
2683 @item @var{function}
2684 Find text by calling @var{function}, and highlight the matches
2685 it finds using @code{font-lock-keyword-face}.
2687 When @var{function} is called, it receives one argument, the limit of
2688 the search; it should begin searching at point, and not search beyond the
2689 limit. It should return non-@code{nil} if it succeeds, and set the
2690 match data to describe the match that was found. Returning @code{nil}
2691 indicates failure of the search.
2693 Fontification will call @var{function} repeatedly with the same limit,
2694 and with point where the previous invocation left it, until
2695 @var{function} fails. On failure, @var{function} need not reset point
2696 in any particular way.
2698 @item (@var{matcher} . @var{subexp})
2699 In this kind of element, @var{matcher} is either a regular
2700 expression or a function, as described above. The @sc{cdr},
2701 @var{subexp}, specifies which subexpression of @var{matcher} should be
2702 highlighted (instead of the entire text that @var{matcher} matched).
2705 ;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},}
2706 ;; @r{using @code{font-lock-keyword-face}.}
2710 If you use @code{regexp-opt} to produce the regular expression
2711 @var{matcher}, you can use @code{regexp-opt-depth} (@pxref{Regexp
2712 Functions}) to calculate the value for @var{subexp}.
2714 @item (@var{matcher} . @var{facespec})
2715 In this kind of element, @var{facespec} is an expression whose value
2716 specifies the face to use for highlighting. In the simplest case,
2717 @var{facespec} is a Lisp variable (a symbol) whose value is a face
2721 ;; @r{Highlight occurrences of @samp{fubar},}
2722 ;; @r{using the face which is the value of @code{fubar-face}.}
2723 ("fubar" . fubar-face)
2726 However, @var{facespec} can also evaluate to a list of this form:
2729 (face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{})
2733 to specify the face @var{face} and various additional text properties
2734 to put on the text that matches. If you do this, be sure to add the
2735 other text property names that you set in this way to the value of
2736 @code{font-lock-extra-managed-props} so that the properties will also
2737 be cleared out when they are no longer appropriate. Alternatively,
2738 you can set the variable @code{font-lock-unfontify-region-function} to
2739 a function that clears these properties. @xref{Other Font Lock
2742 @item (@var{matcher} . @var{subexp-highlighter})
2743 In this kind of element, @var{subexp-highlighter} is a list
2744 which specifies how to highlight matches found by @var{matcher}.
2748 (@var{subexp} @var{facespec} [@var{override} [@var{laxmatch}]])
2751 The @sc{car}, @var{subexp}, is an integer specifying which subexpression
2752 of the match to fontify (0 means the entire matching text). The second
2753 subelement, @var{facespec}, is an expression whose value specifies the
2754 face, as described above.
2756 The last two values in @var{subexp-highlighter}, @var{override} and
2757 @var{laxmatch}, are optional flags. If @var{override} is @code{t},
2758 this element can override existing fontification made by previous
2759 elements of @code{font-lock-keywords}. If it is @code{keep}, then
2760 each character is fontified if it has not been fontified already by
2761 some other element. If it is @code{prepend}, the face specified by
2762 @var{facespec} is added to the beginning of the @code{font-lock-face}
2763 property. If it is @code{append}, the face is added to the end of the
2764 @code{font-lock-face} property.
2766 If @var{laxmatch} is non-@code{nil}, it means there should be no error
2767 if there is no subexpression numbered @var{subexp} in @var{matcher}.
2768 Obviously, fontification of the subexpression numbered @var{subexp} will
2769 not occur. However, fontification of other subexpressions (and other
2770 regexps) will continue. If @var{laxmatch} is @code{nil}, and the
2771 specified subexpression is missing, then an error is signaled which
2772 terminates search-based fontification.
2774 Here are some examples of elements of this kind, and what they do:
2777 ;; @r{Highlight occurrences of either @samp{foo} or @samp{bar}, using}
2778 ;; @r{@code{foo-bar-face}, even if they have already been highlighted.}
2779 ;; @r{@code{foo-bar-face} should be a variable whose value is a face.}
2780 ("foo\\|bar" 0 foo-bar-face t)
2782 ;; @r{Highlight the first subexpression within each occurrence}
2783 ;; @r{that the function @code{fubar-match} finds,}
2784 ;; @r{using the face which is the value of @code{fubar-face}.}
2785 (fubar-match 1 fubar-face)
2788 @item (@var{matcher} . @var{anchored-highlighter})
2789 In this kind of element, @var{anchored-highlighter} specifies how to
2790 highlight text that follows a match found by @var{matcher}. So a
2791 match found by @var{matcher} acts as the anchor for further searches
2792 specified by @var{anchored-highlighter}. @var{anchored-highlighter}
2793 is a list of the following form:
2796 (@var{anchored-matcher} @var{pre-form} @var{post-form}
2797 @var{subexp-highlighters}@dots{})
2800 Here, @var{anchored-matcher}, like @var{matcher}, is either a regular
2801 expression or a function. After a match of @var{matcher} is found,
2802 point is at the end of the match. Now, Font Lock evaluates the form
2803 @var{pre-form}. Then it searches for matches of
2804 @var{anchored-matcher} and uses @var{subexp-highlighters} to highlight
2805 these. A @var{subexp-highlighter} is as described above. Finally,
2806 Font Lock evaluates @var{post-form}.
2808 The forms @var{pre-form} and @var{post-form} can be used to initialize
2809 before, and cleanup after, @var{anchored-matcher} is used. Typically,
2810 @var{pre-form} is used to move point to some position relative to the
2811 match of @var{matcher}, before starting with @var{anchored-matcher}.
2812 @var{post-form} might be used to move back, before resuming with
2815 After Font Lock evaluates @var{pre-form}, it does not search for
2816 @var{anchored-matcher} beyond the end of the line. However, if
2817 @var{pre-form} returns a buffer position that is greater than the
2818 position of point after @var{pre-form} is evaluated, then the position
2819 returned by @var{pre-form} is used as the limit of the search instead.
2820 It is generally a bad idea to return a position greater than the end
2821 of the line; in other words, the @var{anchored-matcher} search should
2827 ;; @r{Highlight occurrences of the word @samp{item} following}
2828 ;; @r{an occurrence of the word @samp{anchor} (on the same line)}
2829 ;; @r{in the value of @code{item-face}.}
2830 ("\\<anchor\\>" "\\<item\\>" nil nil (0 item-face))
2833 Here, @var{pre-form} and @var{post-form} are @code{nil}. Therefore
2834 searching for @samp{item} starts at the end of the match of
2835 @samp{anchor}, and searching for subsequent instances of @samp{anchor}
2836 resumes from where searching for @samp{item} concluded.
2838 @item (@var{matcher} @var{highlighters}@dots{})
2839 This sort of element specifies several @var{highlighter} lists for a
2840 single @var{matcher}. A @var{highlighter} list can be of the type
2841 @var{subexp-highlighter} or @var{anchored-highlighter} as described
2847 ;; @r{Highlight occurrences of the word @samp{anchor} in the value}
2848 ;; @r{of @code{anchor-face}, and subsequent occurrences of the word}
2849 ;; @r{@samp{item} (on the same line) in the value of @code{item-face}.}
2850 ("\\<anchor\\>" (0 anchor-face)
2851 ("\\<item\\>" nil nil (0 item-face)))
2854 @item (eval . @var{form})
2855 Here @var{form} is an expression to be evaluated the first time
2856 this value of @code{font-lock-keywords} is used in a buffer.
2857 Its value should have one of the forms described in this table.
2860 @strong{Warning:} Do not design an element of @code{font-lock-keywords}
2861 to match text which spans lines; this does not work reliably.
2862 For details, see @xref{Multiline Font Lock}.
2864 You can use @var{case-fold} in @code{font-lock-defaults} to specify
2865 the value of @code{font-lock-keywords-case-fold-search} which says
2866 whether search-based fontification should be case-insensitive.
2868 @defvar font-lock-keywords-case-fold-search
2869 Non-@code{nil} means that regular expression matching for the sake of
2870 @code{font-lock-keywords} should be case-insensitive.
2873 @node Customizing Keywords
2874 @subsection Customizing Search-Based Fontification
2876 You can use @code{font-lock-add-keywords} to add additional
2877 search-based fontification rules to a major mode, and
2878 @code{font-lock-remove-keywords} to remove rules.
2880 @defun font-lock-add-keywords mode keywords &optional how
2881 This function adds highlighting @var{keywords}, for the current buffer
2882 or for major mode @var{mode}. The argument @var{keywords} should be a
2883 list with the same format as the variable @code{font-lock-keywords}.
2885 If @var{mode} is a symbol which is a major mode command name, such as
2886 @code{c-mode}, the effect is that enabling Font Lock mode in
2887 @var{mode} will add @var{keywords} to @code{font-lock-keywords}.
2888 Calling with a non-@code{nil} value of @var{mode} is correct only in
2889 your @file{~/.emacs} file.
2891 If @var{mode} is @code{nil}, this function adds @var{keywords} to
2892 @code{font-lock-keywords} in the current buffer. This way of calling
2893 @code{font-lock-add-keywords} is usually used in mode hook functions.
2895 By default, @var{keywords} are added at the beginning of
2896 @code{font-lock-keywords}. If the optional argument @var{how} is
2897 @code{set}, they are used to replace the value of
2898 @code{font-lock-keywords}. If @var{how} is any other non-@code{nil}
2899 value, they are added at the end of @code{font-lock-keywords}.
2901 Some modes provide specialized support you can use in additional
2902 highlighting patterns. See the variables
2903 @code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types},
2904 and @code{java-font-lock-extra-types}, for example.
2906 @strong{Warning:} Major mode commands must not call
2907 @code{font-lock-add-keywords} under any circumstances, either directly
2908 or indirectly, except through their mode hooks. (Doing so would lead to
2909 incorrect behavior for some minor modes.) They should set up their
2910 rules for search-based fontification by setting
2911 @code{font-lock-keywords}.
2914 @defun font-lock-remove-keywords mode keywords
2915 This function removes @var{keywords} from @code{font-lock-keywords}
2916 for the current buffer or for major mode @var{mode}. As in
2917 @code{font-lock-add-keywords}, @var{mode} should be a major mode
2918 command name or @code{nil}. All the caveats and requirements for
2919 @code{font-lock-add-keywords} apply here too.
2922 For example, the following code adds two fontification patterns for C
2923 mode: one to fontify the word @samp{FIXME}, even in comments, and
2924 another to fontify the words @samp{and}, @samp{or} and @samp{not} as
2928 (font-lock-add-keywords 'c-mode
2929 '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
2930 ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face)))
2934 This example affects only C mode proper. To add the same patterns to C
2935 mode @emph{and} all modes derived from it, do this instead:
2938 (add-hook 'c-mode-hook
2940 (font-lock-add-keywords nil
2941 '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
2942 ("\\<\\(and\\|or\\|not\\)\\>" .
2943 font-lock-keyword-face)))))
2946 @node Other Font Lock Variables
2947 @subsection Other Font Lock Variables
2949 This section describes additional variables that a major mode can
2950 set by means of @var{other-vars} in @code{font-lock-defaults}
2951 (@pxref{Font Lock Basics}).
2953 @defvar font-lock-mark-block-function
2954 If this variable is non-@code{nil}, it should be a function that is
2955 called with no arguments, to choose an enclosing range of text for
2956 refontification for the command @kbd{M-o M-o}
2957 (@code{font-lock-fontify-block}).
2959 The function should report its choice by placing the region around it.
2960 A good choice is a range of text large enough to give proper results,
2961 but not too large so that refontification becomes slow. Typical values
2962 are @code{mark-defun} for programming modes or @code{mark-paragraph} for
2966 @defvar font-lock-extra-managed-props
2967 This variable specifies additional properties (other than
2968 @code{font-lock-face}) that are being managed by Font Lock mode. It
2969 is used by @code{font-lock-default-unfontify-region}, which normally
2970 only manages the @code{font-lock-face} property. If you want Font
2971 Lock to manage other properties as well, you must specify them in a
2972 @var{facespec} in @code{font-lock-keywords} as well as add them to
2973 this list. @xref{Search-based Fontification}.
2976 @defvar font-lock-fontify-buffer-function
2977 Function to use for fontifying the buffer. The default value is
2978 @code{font-lock-default-fontify-buffer}.
2981 @defvar font-lock-unfontify-buffer-function
2982 Function to use for unfontifying the buffer. This is used when
2983 turning off Font Lock mode. The default value is
2984 @code{font-lock-default-unfontify-buffer}.
2987 @defvar font-lock-fontify-region-function
2988 Function to use for fontifying a region. It should take two
2989 arguments, the beginning and end of the region, and an optional third
2990 argument @var{verbose}. If @var{verbose} is non-@code{nil}, the
2991 function should print status messages. The default value is
2992 @code{font-lock-default-fontify-region}.
2995 @defvar font-lock-unfontify-region-function
2996 Function to use for unfontifying a region. It should take two
2997 arguments, the beginning and end of the region. The default value is
2998 @code{font-lock-default-unfontify-region}.
3001 @defvar font-lock-flush-function
3002 Function to use for declaring that a region's fontification is out of
3003 date. It takes two arguments, the beginning and end of the region.
3004 The default value of this variable is
3005 @code{font-lock-after-change-function}.
3008 @defvar font-lock-ensure-function
3009 Function to use for making sure a region of the current buffer has
3010 been fontified. It is called with two arguments, the beginning and
3011 end of the region. The default value of this variable is a function
3012 that calls @code{font-lock-default-fontify-buffer} if the buffer is
3013 not fontified; the effect is to make sure the entire accessible
3014 portion of the buffer is fontified.
3017 @defun jit-lock-register function &optional contextual
3018 This function tells Font Lock mode to run the Lisp function
3019 @var{function} any time it has to fontify or refontify part of the
3020 current buffer. It calls @var{function} before calling the default
3021 fontification functions, and gives it two arguments, @var{start} and
3022 @var{end}, which specify the region to be fontified or refontified.
3024 The optional argument @var{contextual}, if non-@code{nil}, forces Font
3025 Lock mode to always refontify a syntactically relevant part of the
3026 buffer, and not just the modified lines. This argument can usually be
3030 @defun jit-lock-unregister function
3031 If @var{function} was previously registered as a fontification
3032 function using @code{jit-lock-register}, this function unregisters it.
3035 @node Levels of Font Lock
3036 @subsection Levels of Font Lock
3038 Some major modes offer three different levels of fontification. You
3039 can define multiple levels by using a list of symbols for @var{keywords}
3040 in @code{font-lock-defaults}. Each symbol specifies one level of
3041 fontification; it is up to the user to choose one of these levels,
3042 normally by setting @code{font-lock-maximum-decoration} (@pxref{Font
3043 Lock,,, emacs, the GNU Emacs Manual}). The chosen level's symbol value
3044 is used to initialize @code{font-lock-keywords}.
3046 Here are the conventions for how to define the levels of
3051 Level 1: highlight function declarations, file directives (such as include or
3052 import directives), strings and comments. The idea is speed, so only
3053 the most important and top-level components are fontified.
3056 Level 2: in addition to level 1, highlight all language keywords,
3057 including type names that act like keywords, as well as named constant
3058 values. The idea is that all keywords (either syntactic or semantic)
3059 should be fontified appropriately.
3062 Level 3: in addition to level 2, highlight the symbols being defined in
3063 function and variable declarations, and all builtin function names,
3064 wherever they appear.
3067 @node Precalculated Fontification
3068 @subsection Precalculated Fontification
3070 Some major modes such as @code{list-buffers} and @code{occur}
3071 construct the buffer text programmatically. The easiest way for them
3072 to support Font Lock mode is to specify the faces of text when they
3073 insert the text in the buffer.
3075 The way to do this is to specify the faces in the text with the
3076 special text property @code{font-lock-face} (@pxref{Special
3077 Properties}). When Font Lock mode is enabled, this property controls
3078 the display, just like the @code{face} property. When Font Lock mode
3079 is disabled, @code{font-lock-face} has no effect on the display.
3081 It is ok for a mode to use @code{font-lock-face} for some text and
3082 also use the normal Font Lock machinery. But if the mode does not use
3083 the normal Font Lock machinery, it should not set the variable
3084 @code{font-lock-defaults}.
3086 @node Faces for Font Lock
3087 @subsection Faces for Font Lock
3088 @cindex faces for font lock
3089 @cindex font lock faces
3091 Font Lock mode can highlight using any face, but Emacs defines several
3092 faces specifically for Font Lock to use to highlight text. These
3093 @dfn{Font Lock faces} are listed below. They can also be used by major
3094 modes for syntactic highlighting outside of Font Lock mode (@pxref{Major
3097 Each of these symbols is both a face name, and a variable whose
3098 default value is the symbol itself. Thus, the default value of
3099 @code{font-lock-comment-face} is @code{font-lock-comment-face}.
3101 The faces are listed with descriptions of their typical usage, and in
3102 order of greater to lesser prominence. If a mode's syntactic
3103 categories do not fit well with the usage descriptions, the faces can be
3104 assigned using the ordering as a guide.
3107 @item font-lock-warning-face
3108 @vindex font-lock-warning-face
3109 for a construct that is peculiar, or that greatly changes the meaning of
3110 other text, like @samp{;;;###autoload} in Emacs Lisp and @samp{#error}
3113 @item font-lock-function-name-face
3114 @vindex font-lock-function-name-face
3115 for the name of a function being defined or declared.
3117 @item font-lock-variable-name-face
3118 @vindex font-lock-variable-name-face
3119 for the name of a variable being defined or declared.
3121 @item font-lock-keyword-face
3122 @vindex font-lock-keyword-face
3123 for a keyword with special syntactic significance, like @samp{for} and
3126 @item font-lock-comment-face
3127 @vindex font-lock-comment-face
3130 @item font-lock-comment-delimiter-face
3131 @vindex font-lock-comment-delimiter-face
3132 for comments delimiters, like @samp{/*} and @samp{*/} in C@. On most
3133 terminals, this inherits from @code{font-lock-comment-face}.
3135 @item font-lock-type-face
3136 @vindex font-lock-type-face
3137 for the names of user-defined data types.
3139 @item font-lock-constant-face
3140 @vindex font-lock-constant-face
3141 for the names of constants, like @samp{NULL} in C.
3143 @item font-lock-builtin-face
3144 @vindex font-lock-builtin-face
3145 for the names of built-in functions.
3147 @item font-lock-preprocessor-face
3148 @vindex font-lock-preprocessor-face
3149 for preprocessor commands. This inherits, by default, from
3150 @code{font-lock-builtin-face}.
3152 @item font-lock-string-face
3153 @vindex font-lock-string-face
3154 for string constants.
3156 @item font-lock-doc-face
3157 @vindex font-lock-doc-face
3158 for documentation strings in the code. This inherits, by default, from
3159 @code{font-lock-string-face}.
3161 @item font-lock-negation-char-face
3162 @vindex font-lock-negation-char-face
3163 for easily-overlooked negation characters.
3166 @node Syntactic Font Lock
3167 @subsection Syntactic Font Lock
3168 @cindex syntactic font lock
3170 Syntactic fontification uses a syntax table (@pxref{Syntax Tables}) to
3171 find and highlight syntactically relevant text. If enabled, it runs
3172 prior to search-based fontification. The variable
3173 @code{font-lock-syntactic-face-function}, documented below, determines
3174 which syntactic constructs to highlight. There are several variables
3175 that affect syntactic fontification; you should set them by means of
3176 @code{font-lock-defaults} (@pxref{Font Lock Basics}).
3178 Whenever Font Lock mode performs syntactic fontification on a stretch
3179 of text, it first calls the function specified by
3180 @code{syntax-propertize-function}. Major modes can use this to apply
3181 @code{syntax-table} text properties to override the buffer's syntax
3182 table in special cases. @xref{Syntax Properties}.
3184 @defvar font-lock-keywords-only
3185 If the value of this variable is non-@code{nil}, Font Lock does not do
3186 syntactic fontification, only search-based fontification based on
3187 @code{font-lock-keywords}. It is normally set by Font Lock mode based
3188 on the @var{keywords-only} element in @code{font-lock-defaults}.
3191 @defvar font-lock-syntax-table
3192 This variable holds the syntax table to use for fontification of
3193 comments and strings. It is normally set by Font Lock mode based on the
3194 @var{syntax-alist} element in @code{font-lock-defaults}. If this value
3195 is @code{nil}, syntactic fontification uses the buffer's syntax table
3196 (the value returned by the function @code{syntax-table}; @pxref{Syntax
3200 @defvar font-lock-syntactic-face-function
3201 If this variable is non-@code{nil}, it should be a function to determine
3202 which face to use for a given syntactic element (a string or a comment).
3203 The value is normally set through an @var{other-vars} element in
3204 @code{font-lock-defaults}.
3206 The function is called with one argument, the parse state at point
3207 returned by @code{parse-partial-sexp}, and should return a face. The
3208 default value returns @code{font-lock-comment-face} for comments and
3209 @code{font-lock-string-face} for strings (@pxref{Faces for Font Lock}).
3212 @node Multiline Font Lock
3213 @subsection Multiline Font Lock Constructs
3214 @cindex multiline font lock
3216 Normally, elements of @code{font-lock-keywords} should not match
3217 across multiple lines; that doesn't work reliably, because Font Lock
3218 usually scans just part of the buffer, and it can miss a multi-line
3219 construct that crosses the line boundary where the scan starts. (The
3220 scan normally starts at the beginning of a line.)
3222 Making elements that match multiline constructs work properly has
3223 two aspects: correct @emph{identification} and correct
3224 @emph{rehighlighting}. The first means that Font Lock finds all
3225 multiline constructs. The second means that Font Lock will correctly
3226 rehighlight all the relevant text when a multiline construct is
3227 changed---for example, if some of the text that was previously part of
3228 a multiline construct ceases to be part of it. The two aspects are
3229 closely related, and often getting one of them to work will appear to
3230 make the other also work. However, for reliable results you must
3231 attend explicitly to both aspects.
3233 There are three ways to ensure correct identification of multiline
3238 Add a function to @code{font-lock-extend-region-functions} that does
3239 the @emph{identification} and extends the scan so that the scanned
3240 text never starts or ends in the middle of a multiline construct.
3242 Use the @code{font-lock-fontify-region-function} hook similarly to
3243 extend the scan so that the scanned text never starts or ends in the
3244 middle of a multiline construct.
3246 Somehow identify the multiline construct right when it gets inserted
3247 into the buffer (or at any point after that but before font-lock
3248 tries to highlight it), and mark it with a @code{font-lock-multiline}
3249 which will instruct font-lock not to start or end the scan in the
3250 middle of the construct.
3253 There are three ways to do rehighlighting of multiline constructs:
3257 Place a @code{font-lock-multiline} property on the construct. This
3258 will rehighlight the whole construct if any part of it is changed. In
3259 some cases you can do this automatically by setting the
3260 @code{font-lock-multiline} variable, which see.
3262 Make sure @code{jit-lock-contextually} is set and rely on it doing its
3263 job. This will only rehighlight the part of the construct that
3264 follows the actual change, and will do it after a short delay.
3265 This only works if the highlighting of the various parts of your
3266 multiline construct never depends on text in subsequent lines.
3267 Since @code{jit-lock-contextually} is activated by default, this can
3268 be an attractive solution.
3270 Place a @code{jit-lock-defer-multiline} property on the construct.
3271 This works only if @code{jit-lock-contextually} is used, and with the
3272 same delay before rehighlighting, but like @code{font-lock-multiline},
3273 it also handles the case where highlighting depends on
3278 * Font Lock Multiline:: Marking multiline chunks with a text property.
3279 * Region to Refontify:: Controlling which region gets refontified
3280 after a buffer change.
3283 @node Font Lock Multiline
3284 @subsubsection Font Lock Multiline
3286 One way to ensure reliable rehighlighting of multiline Font Lock
3287 constructs is to put on them the text property @code{font-lock-multiline}.
3288 It should be present and non-@code{nil} for text that is part of a
3289 multiline construct.
3291 When Font Lock is about to highlight a range of text, it first
3292 extends the boundaries of the range as necessary so that they do not
3293 fall within text marked with the @code{font-lock-multiline} property.
3294 Then it removes any @code{font-lock-multiline} properties from the
3295 range, and highlights it. The highlighting specification (mostly
3296 @code{font-lock-keywords}) must reinstall this property each time,
3297 whenever it is appropriate.
3299 @strong{Warning:} don't use the @code{font-lock-multiline} property
3300 on large ranges of text, because that will make rehighlighting slow.
3302 @defvar font-lock-multiline
3303 If the @code{font-lock-multiline} variable is set to @code{t}, Font
3304 Lock will try to add the @code{font-lock-multiline} property
3305 automatically on multiline constructs. This is not a universal
3306 solution, however, since it slows down Font Lock somewhat. It can
3307 miss some multiline constructs, or make the property larger or smaller
3310 For elements whose @var{matcher} is a function, the function should
3311 ensure that submatch 0 covers the whole relevant multiline construct,
3312 even if only a small subpart will be highlighted. It is often just as
3313 easy to add the @code{font-lock-multiline} property by hand.
3316 The @code{font-lock-multiline} property is meant to ensure proper
3317 refontification; it does not automatically identify new multiline
3318 constructs. Identifying the requires that Font Lock mode operate on
3319 large enough chunks at a time. This will happen by accident on many
3320 cases, which may give the impression that multiline constructs magically
3321 work. If you set the @code{font-lock-multiline} variable
3322 non-@code{nil}, this impression will be even stronger, since the
3323 highlighting of those constructs which are found will be properly
3324 updated from then on. But that does not work reliably.
3326 To find multiline constructs reliably, you must either manually place
3327 the @code{font-lock-multiline} property on the text before Font Lock
3328 mode looks at it, or use @code{font-lock-fontify-region-function}.
3330 @node Region to Refontify
3331 @subsubsection Region to Fontify after a Buffer Change
3333 When a buffer is changed, the region that Font Lock refontifies is
3334 by default the smallest sequence of whole lines that spans the change.
3335 While this works well most of the time, sometimes it doesn't---for
3336 example, when a change alters the syntactic meaning of text on an
3339 You can enlarge (or even reduce) the region to refontify by setting
3340 the following variable:
3342 @defvar font-lock-extend-after-change-region-function
3343 This buffer-local variable is either @code{nil} or a function for Font
3344 Lock mode to call to determine the region to scan and fontify.
3346 The function is given three parameters, the standard @var{beg},
3347 @var{end}, and @var{old-len} from @code{after-change-functions}
3348 (@pxref{Change Hooks}). It should return either a cons of the
3349 beginning and end buffer positions (in that order) of the region to
3350 fontify, or @code{nil} (which means choose the region in the standard
3351 way). This function needs to preserve point, the match-data, and the
3352 current restriction. The region it returns may start or end in the
3355 Since this function is called after every buffer change, it should be
3359 @node Auto-Indentation
3360 @section Automatic Indentation of code
3362 For programming languages, an important feature of a major mode is to
3363 provide automatic indentation. There are two parts: one is to decide what
3364 is the right indentation of a line, and the other is to decide when to
3365 reindent a line. By default, Emacs reindents a line whenever you
3366 type a character in @code{electric-indent-chars}, which by default only
3367 includes Newline. Major modes can add chars to @code{electric-indent-chars}
3368 according to the syntax of the language.
3370 Deciding what is the right indentation is controlled in Emacs by
3371 @code{indent-line-function} (@pxref{Mode-Specific Indent}). For some modes,
3372 the @emph{right} indentation cannot be known reliably, typically because
3373 indentation is significant so several indentations are valid but with different
3374 meanings. In that case, the mode should set @code{electric-indent-inhibit} to
3375 make sure the line is not constantly re-indented against the user's wishes.
3377 Writing a good indentation function can be difficult and to a large extent it
3378 is still a black art. Many major mode authors will start by writing a simple
3379 indentation function that works for simple cases, for example by comparing with
3380 the indentation of the previous text line. For most programming languages that
3381 are not really line-based, this tends to scale very poorly: improving
3382 such a function to let it handle more diverse situations tends to become more
3383 and more difficult, resulting in the end with a large, complex, unmaintainable
3384 indentation function which nobody dares to touch.
3386 A good indentation function will usually need to actually parse the
3387 text, according to the syntax of the language. Luckily, it is not
3388 necessary to parse the text in as much detail as would be needed
3389 for a compiler, but on the other hand, the parser embedded in the
3390 indentation code will want to be somewhat friendly to syntactically
3393 Good maintainable indentation functions usually fall into two categories:
3394 either parsing forward from some safe starting point until the
3395 position of interest, or parsing backward from the position of interest.
3396 Neither of the two is a clearly better choice than the other: parsing
3397 backward is often more difficult than parsing forward because
3398 programming languages are designed to be parsed forward, but for the
3399 purpose of indentation it has the advantage of not needing to
3400 guess a safe starting point, and it generally enjoys the property
3401 that only a minimum of text will be analyzed to decide the indentation
3402 of a line, so indentation will tend to be less affected by syntax errors in
3403 some earlier unrelated piece of code. Parsing forward on the other hand
3404 is usually easier and has the advantage of making it possible to
3405 reindent efficiently a whole region at a time, with a single parse.
3407 Rather than write your own indentation function from scratch, it is
3408 often preferable to try and reuse some existing ones or to rely
3409 on a generic indentation engine. There are sadly few such
3410 engines. The CC-mode indentation code (used with C, C++, Java, Awk
3411 and a few other such modes) has been made more generic over the years,
3412 so if your language seems somewhat similar to one of those languages,
3413 you might try to use that engine. @c FIXME: documentation?
3414 Another one is SMIE which takes an approach in the spirit
3415 of Lisp sexps and adapts it to non-Lisp languages.
3418 * SMIE:: A simple minded indentation engine.
3422 @subsection Simple Minded Indentation Engine
3425 SMIE is a package that provides a generic navigation and indentation
3426 engine. Based on a very simple parser using an operator precedence
3427 grammar, it lets major modes extend the sexp-based navigation of Lisp
3428 to non-Lisp languages as well as provide a simple to use but reliable
3431 Operator precedence grammar is a very primitive technology for parsing
3432 compared to some of the more common techniques used in compilers.
3433 It has the following characteristics: its parsing power is very limited,
3434 and it is largely unable to detect syntax errors, but it has the
3435 advantage of being algorithmically efficient and able to parse forward
3436 just as well as backward. In practice that means that SMIE can use it
3437 for indentation based on backward parsing, that it can provide both
3438 @code{forward-sexp} and @code{backward-sexp} functionality, and that it
3439 will naturally work on syntactically incorrect code without any extra
3440 effort. The downside is that it also means that most programming
3441 languages cannot be parsed correctly using SMIE, at least not without
3442 resorting to some special tricks (@pxref{SMIE Tricks}).
3445 * SMIE setup:: SMIE setup and features.
3446 * Operator Precedence Grammars:: A very simple parsing technique.
3447 * SMIE Grammar:: Defining the grammar of a language.
3448 * SMIE Lexer:: Defining tokens.
3449 * SMIE Tricks:: Working around the parser's limitations.
3450 * SMIE Indentation:: Specifying indentation rules.
3451 * SMIE Indentation Helpers:: Helper functions for indentation rules.
3452 * SMIE Indentation Example:: Sample indentation rules.
3453 * SMIE Customization:: Customizing indentation.
3457 @subsubsection SMIE Setup and Features
3459 SMIE is meant to be a one-stop shop for structural navigation and
3460 various other features which rely on the syntactic structure of code, in
3461 particular automatic indentation. The main entry point is
3462 @code{smie-setup} which is a function typically called while setting
3465 @defun smie-setup grammar rules-function &rest keywords
3466 Setup SMIE navigation and indentation.
3467 @var{grammar} is a grammar table generated by @code{smie-prec2->grammar}.
3468 @var{rules-function} is a set of indentation rules for use on
3469 @code{smie-rules-function}.
3470 @var{keywords} are additional arguments, which can include the following
3474 @code{:forward-token} @var{fun}: Specify the forward lexer to use.
3476 @code{:backward-token} @var{fun}: Specify the backward lexer to use.
3480 Calling this function is sufficient to make commands such as
3481 @code{forward-sexp}, @code{backward-sexp}, and @code{transpose-sexps} be
3482 able to properly handle structural elements other than just the paired
3483 parentheses already handled by syntax tables. For example, if the
3484 provided grammar is precise enough, @code{transpose-sexps} can correctly
3485 transpose the two arguments of a @code{+} operator, taking into account
3486 the precedence rules of the language.
3488 Calling @code{smie-setup} is also sufficient to make TAB indentation work in
3489 the expected way, extends @code{blink-matching-paren} to apply to
3490 elements like @code{begin...end}, and provides some commands that you
3491 can bind in the major mode keymap.
3493 @deffn Command smie-close-block
3494 This command closes the most recently opened (and not yet closed) block.
3497 @deffn Command smie-down-list &optional arg
3498 This command is like @code{down-list} but it also pays attention to
3499 nesting of tokens other than parentheses, such as @code{begin...end}.
3502 @node Operator Precedence Grammars
3503 @subsubsection Operator Precedence Grammars
3505 SMIE's precedence grammars simply give to each token a pair of
3506 precedences: the left-precedence and the right-precedence. We say
3507 @code{T1 < T2} if the right-precedence of token @code{T1} is less than
3508 the left-precedence of token @code{T2}. A good way to read this
3509 @code{<} is as a kind of parenthesis: if we find @code{... T1 something
3510 T2 ...} then that should be parsed as @code{... T1 (something T2 ...}
3511 rather than as @code{... T1 something) T2 ...}. The latter
3512 interpretation would be the case if we had @code{T1 > T2}. If we have
3513 @code{T1 = T2}, it means that token T2 follows token T1 in the same
3514 syntactic construction, so typically we have @code{"begin" = "end"}.
3515 Such pairs of precedences are sufficient to express left-associativity
3516 or right-associativity of infix operators, nesting of tokens like
3517 parentheses and many other cases.
3519 @c Let's leave this undocumented to leave it more open for change!
3520 @c @defvar smie-grammar
3521 @c The value of this variable is an alist specifying the left and right
3522 @c precedence of each token. It is meant to be initialized by using one of
3523 @c the functions below.
3526 @defun smie-prec2->grammar table
3527 This function takes a @emph{prec2} grammar @var{table} and returns an
3528 alist suitable for use in @code{smie-setup}. The @emph{prec2}
3529 @var{table} is itself meant to be built by one of the functions below.
3532 @defun smie-merge-prec2s &rest tables
3533 This function takes several @emph{prec2} @var{tables} and merges them
3534 into a new @emph{prec2} table.
3537 @defun smie-precs->prec2 precs
3538 This function builds a @emph{prec2} table from a table of precedences
3539 @var{precs}. @var{precs} should be a list, sorted by precedence (for
3540 example @code{"+"} will come before @code{"*"}), of elements of the form
3541 @code{(@var{assoc} @var{op} ...)}, where each @var{op} is a token that
3542 acts as an operator; @var{assoc} is their associativity, which can be
3543 either @code{left}, @code{right}, @code{assoc}, or @code{nonassoc}.
3544 All operators in a given element share the same precedence level
3548 @defun smie-bnf->prec2 bnf &rest resolvers
3549 This function lets you specify the grammar using a BNF notation.
3550 It accepts a @var{bnf} description of the grammar along with a set of
3551 conflict resolution rules @var{resolvers}, and
3552 returns a @emph{prec2} table.
3554 @var{bnf} is a list of nonterminal definitions of the form
3555 @code{(@var{nonterm} @var{rhs1} @var{rhs2} ...)} where each @var{rhs}
3556 is a (non-empty) list of terminals (aka tokens) or non-terminals.
3558 Not all grammars are accepted:
3561 An @var{rhs} cannot be an empty list (an empty list is never needed,
3562 since SMIE allows all non-terminals to match the empty string anyway).
3564 An @var{rhs} cannot have 2 consecutive non-terminals: each pair of
3565 non-terminals needs to be separated by a terminal (aka token).
3566 This is a fundamental limitation of operator precedence grammars.
3569 Additionally, conflicts can occur:
3572 The returned @emph{prec2} table holds constraints between pairs of tokens, and
3573 for any given pair only one constraint can be present: T1 < T2,
3574 T1 = T2, or T1 > T2.
3576 A token can be an @code{opener} (something similar to an open-paren),
3577 a @code{closer} (like a close-paren), or @code{neither} of the two
3578 (e.g., an infix operator, or an inner token like @code{"else"}).
3581 Precedence conflicts can be resolved via @var{resolvers}, which
3582 is a list of @emph{precs} tables (see @code{smie-precs->prec2}): for
3583 each precedence conflict, if those @code{precs} tables
3584 specify a particular constraint, then the conflict is resolved by using
3585 this constraint instead, else a conflict is reported and one of the
3586 conflicting constraints is picked arbitrarily and the others are
3591 @subsubsection Defining the Grammar of a Language
3592 @cindex SMIE grammar
3593 @cindex grammar, SMIE
3595 The usual way to define the SMIE grammar of a language is by
3596 defining a new global variable that holds the precedence table by
3597 giving a set of BNF rules.
3598 For example, the grammar definition for a small Pascal-like language
3603 (defvar sample-smie-grammar
3604 (smie-prec2->grammar
3609 (inst ("begin" insts "end")
3610 ("if" exp "then" inst "else" inst)
3613 (insts (insts ";" insts) (inst))
3617 (exps (exps "," exps) (exp)))
3622 '((assoc "+") (assoc "*")))))
3627 A few things to note:
3631 The above grammar does not explicitly mention the syntax of function
3632 calls: SMIE will automatically allow any sequence of sexps, such as
3633 identifiers, balanced parentheses, or @code{begin ... end} blocks
3634 to appear anywhere anyway.
3636 The grammar category @code{id} has no right hand side: this does not
3637 mean that it can match only the empty string, since as mentioned any
3638 sequence of sexps can appear anywhere anyway.
3640 Because non terminals cannot appear consecutively in the BNF grammar, it
3641 is difficult to correctly handle tokens that act as terminators, so the
3642 above grammar treats @code{";"} as a statement @emph{separator} instead,
3643 which SMIE can handle very well.
3645 Separators used in sequences (such as @code{","} and @code{";"} above)
3646 are best defined with BNF rules such as @code{(foo (foo "separator" foo) ...)}
3647 which generate precedence conflicts which are then resolved by giving
3648 them an explicit @code{(assoc "separator")}.
3650 The @code{("(" exps ")")} rule was not needed to pair up parens, since
3651 SMIE will pair up any characters that are marked as having paren syntax
3652 in the syntax table. What this rule does instead (together with the
3653 definition of @code{exps}) is to make it clear that @code{","} should
3654 not appear outside of parentheses.
3656 Rather than have a single @emph{precs} table to resolve conflicts, it is
3657 preferable to have several tables, so as to let the BNF part of the
3658 grammar specify relative precedences where possible.
3660 Unless there is a very good reason to prefer @code{left} or
3661 @code{right}, it is usually preferable to mark operators as associative,
3662 using @code{assoc}. For that reason @code{"+"} and @code{"*"} are
3663 defined above as @code{assoc}, although the language defines them
3664 formally as left associative.
3668 @subsubsection Defining Tokens
3670 @cindex defining tokens, SMIE
3672 SMIE comes with a predefined lexical analyzer which uses syntax tables
3673 in the following way: any sequence of characters that have word or
3674 symbol syntax is considered a token, and so is any sequence of
3675 characters that have punctuation syntax. This default lexer is
3676 often a good starting point but is rarely actually correct for any given
3677 language. For example, it will consider @code{"2,+3"} to be composed
3678 of 3 tokens: @code{"2"}, @code{",+"}, and @code{"3"}.
3680 To describe the lexing rules of your language to SMIE, you need
3681 2 functions, one to fetch the next token, and another to fetch the
3682 previous token. Those functions will usually first skip whitespace and
3683 comments and then look at the next chunk of text to see if it
3684 is a special token. If so it should skip the token and
3685 return a description of this token. Usually this is simply the string
3686 extracted from the buffer, but it can be anything you want.
3690 (defvar sample-keywords-regexp
3691 (regexp-opt '("+" "*" "," ";" ">" ">=" "<" "<=" ":=" "=")))
3694 (defun sample-smie-forward-token ()
3695 (forward-comment (point-max))
3697 ((looking-at sample-keywords-regexp)
3698 (goto-char (match-end 0))
3699 (match-string-no-properties 0))
3700 (t (buffer-substring-no-properties
3702 (progn (skip-syntax-forward "w_")
3706 (defun sample-smie-backward-token ()
3707 (forward-comment (- (point)))
3709 ((looking-back sample-keywords-regexp (- (point) 2) t)
3710 (goto-char (match-beginning 0))
3711 (match-string-no-properties 0))
3712 (t (buffer-substring-no-properties
3714 (progn (skip-syntax-backward "w_")
3719 Notice how those lexers return the empty string when in front of
3720 parentheses. This is because SMIE automatically takes care of the
3721 parentheses defined in the syntax table. More specifically if the lexer
3722 returns @code{nil} or an empty string, SMIE tries to handle the corresponding
3723 text as a sexp according to syntax tables.
3726 @subsubsection Living With a Weak Parser
3728 The parsing technique used by SMIE does not allow tokens to behave
3729 differently in different contexts. For most programming languages, this
3730 manifests itself by precedence conflicts when converting the
3733 Sometimes, those conflicts can be worked around by expressing the
3734 grammar slightly differently. For example, for Modula-2 it might seem
3735 natural to have a BNF grammar that looks like this:
3739 (inst ("IF" exp "THEN" insts "ELSE" insts "END")
3740 ("CASE" exp "OF" cases "END")
3742 (cases (cases "|" cases)
3743 (caselabel ":" insts)
3748 But this will create conflicts for @code{"ELSE"}: on the one hand, the
3749 IF rule implies (among many other things) that @code{"ELSE" = "END"};
3750 but on the other hand, since @code{"ELSE"} appears within @code{cases},
3751 which appears left of @code{"END"}, we also have @code{"ELSE" > "END"}.
3752 We can solve the conflict either by using:
3755 (inst ("IF" exp "THEN" insts "ELSE" insts "END")
3756 ("CASE" exp "OF" cases "END")
3757 ("CASE" exp "OF" cases "ELSE" insts "END")
3759 (cases (cases "|" cases) (caselabel ":" insts))
3765 (inst ("IF" exp "THEN" else "END")
3766 ("CASE" exp "OF" cases "END")
3768 (else (insts "ELSE" insts))
3769 (cases (cases "|" cases) (caselabel ":" insts) (else))
3773 Reworking the grammar to try and solve conflicts has its downsides, tho,
3774 because SMIE assumes that the grammar reflects the logical structure of
3775 the code, so it is preferable to keep the BNF closer to the intended
3776 abstract syntax tree.
3778 Other times, after careful consideration you may conclude that those
3779 conflicts are not serious and simply resolve them via the
3780 @var{resolvers} argument of @code{smie-bnf->prec2}. Usually this is
3781 because the grammar is simply ambiguous: the conflict does not affect
3782 the set of programs described by the grammar, but only the way those
3783 programs are parsed. This is typically the case for separators and
3784 associative infix operators, where you want to add a resolver like
3785 @code{'((assoc "|"))}. Another case where this can happen is for the
3786 classic @emph{dangling else} problem, where you will use @code{'((assoc
3787 "else" "then"))}. It can also happen for cases where the conflict is
3788 real and cannot really be resolved, but it is unlikely to pose a problem
3791 Finally, in many cases some conflicts will remain despite all efforts to
3792 restructure the grammar. Do not despair: while the parser cannot be
3793 made more clever, you can make the lexer as smart as you want. So, the
3794 solution is then to look at the tokens involved in the conflict and to
3795 split one of those tokens into 2 (or more) different tokens. E.g., if
3796 the grammar needs to distinguish between two incompatible uses of the
3797 token @code{"begin"}, make the lexer return different tokens (say
3798 @code{"begin-fun"} and @code{"begin-plain"}) depending on which kind of
3799 @code{"begin"} it finds. This pushes the work of distinguishing the
3800 different cases to the lexer, which will thus have to look at the
3801 surrounding text to find ad-hoc clues.
3803 @node SMIE Indentation
3804 @subsubsection Specifying Indentation Rules
3805 @cindex indentation rules, SMIE
3807 Based on the provided grammar, SMIE will be able to provide automatic
3808 indentation without any extra effort. But in practice, this default
3809 indentation style will probably not be good enough. You will want to
3810 tweak it in many different cases.
3812 SMIE indentation is based on the idea that indentation rules should be
3813 as local as possible. To this end, it relies on the idea of
3814 @emph{virtual} indentation, which is the indentation that a particular
3815 program point would have if it were at the beginning of a line.
3816 Of course, if that program point is indeed at the beginning of a line,
3817 its virtual indentation is its current indentation. But if not, then
3818 SMIE uses the indentation algorithm to compute the virtual indentation
3819 of that point. Now in practice, the virtual indentation of a program
3820 point does not have to be identical to the indentation it would have if
3821 we inserted a newline before it. To see how this works, the SMIE rule
3822 for indentation after a @code{@{} in C does not care whether the
3823 @code{@{} is standing on a line of its own or is at the end of the
3824 preceding line. Instead, these different cases are handled in the
3825 indentation rule that decides how to indent before a @code{@{}.
3827 Another important concept is the notion of @emph{parent}: The
3828 @emph{parent} of a token, is the head token of the nearest enclosing
3829 syntactic construct. For example, the parent of an @code{else} is the
3830 @code{if} to which it belongs, and the parent of an @code{if}, in turn,
3831 is the lead token of the surrounding construct. The command
3832 @code{backward-sexp} jumps from a token to its parent, but there are
3833 some caveats: for @emph{openers} (tokens which start a construct, like
3834 @code{if}), you need to start with point before the token, while for
3835 others you need to start with point after the token.
3836 @code{backward-sexp} stops with point before the parent token if that is
3837 the @emph{opener} of the token of interest, and otherwise it stops with
3838 point after the parent token.
3840 SMIE indentation rules are specified using a function that takes two
3841 arguments @var{method} and @var{arg} where the meaning of @var{arg} and the
3842 expected return value depend on @var{method}.
3844 @var{method} can be:
3847 @code{:after}, in which case @var{arg} is a token and the function
3848 should return the @var{offset} to use for indentation after @var{arg}.
3850 @code{:before}, in which case @var{arg} is a token and the function
3851 should return the @var{offset} to use to indent @var{arg} itself.
3853 @code{:elem}, in which case the function should return either the offset
3854 to use to indent function arguments (if @var{arg} is the symbol
3855 @code{arg}) or the basic indentation step (if @var{arg} is the symbol
3858 @code{:list-intro}, in which case @var{arg} is a token and the function
3859 should return non-@code{nil} if the token is followed by a list of
3860 expressions (not separated by any token) rather than an expression.
3863 When @var{arg} is a token, the function is called with point just before
3864 that token. A return value of @code{nil} always means to fallback on the
3865 default behavior, so the function should return @code{nil} for arguments it
3868 @var{offset} can be:
3871 @code{nil}: use the default indentation rule.
3873 @code{(column . @var{column})}: indent to column @var{column}.
3875 @var{number}: offset by @var{number}, relative to a base token which is
3876 the current token for @code{:after} and its parent for @code{:before}.
3879 @node SMIE Indentation Helpers
3880 @subsubsection Helper Functions for Indentation Rules
3882 SMIE provides various functions designed specifically for use in the
3883 indentation rules function (several of those functions break if used in
3884 another context). These functions all start with the prefix
3887 @defun smie-rule-bolp
3888 Return non-@code{nil} if the current token is the first on the line.
3891 @defun smie-rule-hanging-p
3892 Return non-@code{nil} if the current token is @emph{hanging}.
3893 A token is @emph{hanging} if it is the last token on the line
3894 and if it is preceded by other tokens: a lone token on a line is not
3898 @defun smie-rule-next-p &rest tokens
3899 Return non-@code{nil} if the next token is among @var{tokens}.
3902 @defun smie-rule-prev-p &rest tokens
3903 Return non-@code{nil} if the previous token is among @var{tokens}.
3906 @defun smie-rule-parent-p &rest parents
3907 Return non-@code{nil} if the current token's parent is among @var{parents}.
3910 @defun smie-rule-sibling-p
3911 Return non-@code{nil} if the current token's parent is actually a
3912 sibling. This is the case for example when the parent of a @code{","}
3913 is just the previous @code{","}.
3916 @defun smie-rule-parent &optional offset
3917 Return the proper offset to align the current token with the parent.
3918 If non-@code{nil}, @var{offset} should be an integer giving an
3919 additional offset to apply.
3922 @defun smie-rule-separator method
3923 Indent current token as a @emph{separator}.
3925 By @emph{separator}, we mean here a token whose sole purpose is to
3926 separate various elements within some enclosing syntactic construct, and
3927 which does not have any semantic significance in itself (i.e., it would
3928 typically not exist as a node in an abstract syntax tree).
3930 Such a token is expected to have an associative syntax and be closely
3931 tied to its syntactic parent. Typical examples are @code{","} in lists
3932 of arguments (enclosed inside parentheses), or @code{";"} in sequences
3933 of instructions (enclosed in a @code{@{...@}} or @code{begin...end}
3936 @var{method} should be the method name that was passed to
3937 @code{smie-rules-function}.
3940 @node SMIE Indentation Example
3941 @subsubsection Sample Indentation Rules
3943 Here is an example of an indentation function:
3946 (defun sample-smie-rules (kind token)
3947 (pcase (cons kind token)
3948 (`(:elem . basic) sample-indent-basic)
3949 (`(,_ . ",") (smie-rule-separator kind))
3950 (`(:after . ":=") sample-indent-basic)
3951 (`(:before . ,(or `"begin" `"(" `"@{")))
3952 (if (smie-rule-hanging-p) (smie-rule-parent)))
3954 (and (not (smie-rule-bolp)) (smie-rule-prev-p "else")
3955 (smie-rule-parent)))))
3959 A few things to note:
3963 The first case indicates the basic indentation increment to use.
3964 If @code{sample-indent-basic} is @code{nil}, then SMIE uses the global
3965 setting @code{smie-indent-basic}. The major mode could have set
3966 @code{smie-indent-basic} buffer-locally instead, but that
3970 The rule for the token @code{","} make SMIE try to be more clever when
3971 the comma separator is placed at the beginning of lines. It tries to
3972 outdent the separator so as to align the code after the comma; for
3976 x = longfunctionname (
3983 The rule for indentation after @code{":="} exists because otherwise
3984 SMIE would treat @code{":="} as an infix operator and would align the
3985 right argument with the left one.
3988 The rule for indentation before @code{"begin"} is an example of the use
3989 of virtual indentation: This rule is used only when @code{"begin"} is
3990 hanging, which can happen only when @code{"begin"} is not at the
3991 beginning of a line. So this is not used when indenting
3992 @code{"begin"} itself but only when indenting something relative to this
3993 @code{"begin"}. Concretely, this rule changes the indentation from:
4008 The rule for indentation before @code{"if"} is similar to the one for
4009 @code{"begin"}, but where the purpose is to treat @code{"else if"}
4010 as a single unit, so as to align a sequence of tests rather than indent
4011 each test further to the right. This function does this only in the
4012 case where the @code{"if"} is not placed on a separate line, hence the
4013 @code{smie-rule-bolp} test.
4015 If we know that the @code{"else"} is always aligned with its @code{"if"}
4016 and is always at the beginning of a line, we can use a more efficient
4020 (and (not (smie-rule-bolp))
4021 (smie-rule-prev-p "else")
4023 (sample-smie-backward-token)
4024 (cons 'column (current-column)))))
4027 The advantage of this formulation is that it reuses the indentation of
4028 the previous @code{"else"}, rather than going all the way back to the
4029 first @code{"if"} of the sequence.
4032 @c In some sense this belongs more in the Emacs manual.
4033 @node SMIE Customization
4034 @subsubsection Customizing Indentation
4036 If you are using a mode whose indentation is provided by SMIE, you can
4037 customize the indentation to suit your preferences. You can do this
4038 on a per-mode basis (using the option @code{smie-config}), or a
4039 per-file basis (using the function @code{smie-config-local} in a
4040 file-local variable specification).
4043 This option lets you customize indentation on a per-mode basis.
4044 It is an alist with elements of the form @code{(@var{mode} . @var{rules})}.
4045 For the precise form of rules, see the variable's documentation; but
4046 you may find it easier to use the command @code{smie-config-guess}.
4049 @deffn Command smie-config-guess
4050 This command tries to work out appropriate settings to produce
4051 your preferred style of indentation. Simply call the command while
4052 visiting a file that is indented with your style.
4055 @deffn Command smie-config-save
4056 Call this command after using @code{smie-config-guess}, to save your
4057 settings for future sessions.
4060 @deffn Command smie-config-show-indent &optional move
4061 This command displays the rules that are used to indent the current
4065 @deffn Command smie-config-set-indent
4066 This command adds a local rule to adjust the indentation of the current line.
4069 @defun smie-config-local rules
4070 This function adds @var{rules} as indentation rules for the current buffer.
4071 These add to any mode-specific rules defined by the @code{smie-config} option.
4072 To specify custom indentation rules for a specific file, add an entry
4073 to the file's local variables of the form:
4074 @code{eval: (smie-config-local '(@var{rules}))}.
4078 @node Desktop Save Mode
4079 @section Desktop Save Mode
4080 @cindex desktop save mode
4082 @dfn{Desktop Save Mode} is a feature to save the state of Emacs from
4083 one session to another. The user-level commands for using Desktop
4084 Save Mode are described in the GNU Emacs Manual (@pxref{Saving Emacs
4085 Sessions,,, emacs, the GNU Emacs Manual}). Modes whose buffers visit
4086 a file, don't have to do anything to use this feature.
4088 For buffers not visiting a file to have their state saved, the major
4089 mode must bind the buffer local variable @code{desktop-save-buffer} to
4090 a non-@code{nil} value.
4092 @defvar desktop-save-buffer
4093 If this buffer-local variable is non-@code{nil}, the buffer will have
4094 its state saved in the desktop file at desktop save. If the value is
4095 a function, it is called at desktop save with argument
4096 @var{desktop-dirname}, and its value is saved in the desktop file along
4097 with the state of the buffer for which it was called. When file names
4098 are returned as part of the auxiliary information, they should be
4099 formatted using the call
4102 (desktop-file-name @var{file-name} @var{desktop-dirname})
4107 For buffers not visiting a file to be restored, the major mode must
4108 define a function to do the job, and that function must be listed in
4109 the alist @code{desktop-buffer-mode-handlers}.
4111 @defvar desktop-buffer-mode-handlers
4115 (@var{major-mode} . @var{restore-buffer-function})
4118 The function @var{restore-buffer-function} will be called with
4122 (@var{buffer-file-name} @var{buffer-name} @var{desktop-buffer-misc})
4125 and it should return the restored buffer.
4126 Here @var{desktop-buffer-misc} is the value returned by the function
4127 optionally bound to @code{desktop-save-buffer}.