* lisp/play/landmark.el (landmark-mode): Fix typos.
[emacs.git] / doc / lispref / modes.texi
blob180fef7241d86eebf2342c1512f9a31c2a8508ff
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software
4 @c Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @node Modes
7 @chapter Major and Minor Modes
8 @cindex mode
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}.
21 @menu
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
30                         Emacs sessions.
31 @end menu
33 @node Hooks
34 @section Hooks
35 @cindex hooks
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.
43 @cindex normal hook
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}.
65 @cindex abnormal 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.
74   By convention, abnormal hook names end in @samp{-functions}.  If the
75 variable's name ends in @samp{-function}, then its value is just a single
76 function, not a list of functions.
78 @menu
79 * Running Hooks::    How to run a hook.
80 * Setting Hooks::    How to put functions on a hook, or remove them.
81 @end menu
83 @node Running Hooks
84 @subsection Running Hooks
86   In this section, we document the @code{run-hooks} function, which is
87 used to run a normal hook.  We also document the functions for running
88 various kinds of abnormal hooks.
90 @defun run-hooks &rest hookvars
91 This function takes one or more normal hook variable names as
92 arguments, and runs each hook in turn.  Each argument should be a
93 symbol that is a normal hook variable.  These arguments are processed
94 in the order specified.
96 If a hook variable has a non-@code{nil} value, that value should be a
97 list of functions.  @code{run-hooks} calls all the functions, one by
98 one, with no arguments.
100 The hook variable's value can also be a single function---either a
101 lambda expression or a symbol with a function definition---which
102 @code{run-hooks} calls.  But this usage is obsolete.
104 If the hook variable is buffer-local, the buffer-local variable will
105 be used instead of the global variable.  However, if the buffer-local
106 variable contains the element @code{t}, the global hook variable will
107 be run as well.
108 @end defun
110 @defun run-hook-with-args hook &rest args
111 This function runs an abnormal hook by calling all the hook functions in
112 @var{hook}, passing each one the arguments @var{args}.
113 @end defun
115 @defun run-hook-with-args-until-failure hook &rest args
116 This function runs an abnormal hook by calling each hook function in
117 turn, stopping if one of them ``fails'' by returning @code{nil}.  Each
118 hook function is passed the arguments @var{args}.  If this function
119 stops because one of the hook functions fails, it returns @code{nil};
120 otherwise it returns a non-@code{nil} value.
121 @end defun
123 @defun run-hook-with-args-until-success hook &rest args
124 This function runs an abnormal hook by calling each hook function,
125 stopping if one of them ``succeeds'' by returning a non-@code{nil}
126 value.  Each hook function is passed the arguments @var{args}.  If this
127 function stops because one of the hook functions returns a
128 non-@code{nil} value, it returns that value; otherwise it returns
129 @code{nil}.
130 @end defun
132 @defmac with-wrapper-hook hook args &rest body
133 This macro runs the abnormal hook @code{hook} as a series of nested
134 ``wrapper functions'' around the @var{body} forms.  The effect is
135 similar to nested @code{around} advices (@pxref{Around-Advice}).
137 Each hook function should accept an argument list consisting of a function
138 @var{fun}, followed by the additional arguments listed in @var{args}.
139 The first hook function is passed a function @var{fun} that, if it is
140 called with arguments @var{args}, performs @var{body} (i.e., the default
141 operation).  The @var{fun} passed to each successive hook function is
142 constructed from all the preceding hook functions (and @var{body}); if
143 this @var{fun} is called with arguments @var{args}, it does what the
144 @code{with-wrapper-hook} call would if the preceding hook functions were
145 the only ones in @var{hook}.
147 Each hook function may call its @var{fun} argument as many times as it
148 wishes, including never.  In that case, such a hook function acts to
149 replace the default definition altogether, and any preceding hook
150 functions.  Of course, a subsequent hook function may do the same thing.
152 Each hook function definition is used to construct the @var{fun} passed
153 to the next hook function in @var{hook}, if any.  The last or
154 ``outermost'' @var{fun} is called once to produce the overall effect.
156 When might you want to use a wrapper hook?  The function
157 @code{filter-buffer-substring} illustrates a common case.  There is a
158 basic functionality, performed by @var{body}---in this case, to extract
159 a buffer-substring.  Then any number of hook functions can act in
160 sequence to modify that string, before returning the final result.
161 A wrapper-hook also allows for a hook function to completely replace the
162 default definition (by not calling @var{fun}).
163 @end defmac
165 @defun run-hook-wrapped hook wrap-function &rest args
166 This function is similar to @code{run-hook-with-args-until-success}.
167 Like that function, it runs the functions on the abnormal hook
168 @code{hook}, stopping at the first one that returns non-@code{nil}.
169 Instead of calling the hook functions directly, though, it actually
170 calls @code{wrap-function} with arguments @code{fun} and @code{args}.
171 @end defun
173 @node Setting Hooks
174 @subsection Setting Hooks
176   Here's an example that uses a mode hook to turn on Auto Fill mode when
177 in Lisp Interaction mode:
179 @example
180 (add-hook 'lisp-interaction-mode-hook 'auto-fill-mode)
181 @end example
183 @defun add-hook hook function &optional append local
184 This function is the handy way to add function @var{function} to hook
185 variable @var{hook}.  You can use it for abnormal hooks as well as for
186 normal hooks.  @var{function} can be any Lisp function that can accept
187 the proper number of arguments for @var{hook}.  For example,
189 @example
190 (add-hook 'text-mode-hook 'my-text-hook-function)
191 @end example
193 @noindent
194 adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
196 If @var{function} is already present in @var{hook} (comparing using
197 @code{equal}), then @code{add-hook} does not add it a second time.
199 If @var{function} has a non-@code{nil} property
200 @code{permanent-local-hook}, then @code{kill-all-local-variables} (or
201 changing major modes) won't delete it from the hook variable's local
202 value.
204 For a normal hook, hook functions should be designed so that the order
205 in which they are executed does not matter.  Any dependence on the order
206 is asking for trouble.  However, the order is predictable: normally,
207 @var{function} goes at the front of the hook list, so it is executed
208 first (barring another @code{add-hook} call).  If the optional argument
209 @var{append} is non-@code{nil}, the new hook function goes at the end of
210 the hook list and is executed last.
212 @code{add-hook} can handle the cases where @var{hook} is void or its
213 value is a single function; it sets or changes the value to a list of
214 functions.
216 If @var{local} is non-@code{nil}, that says to add @var{function} to the
217 buffer-local hook list instead of to the global hook list.  This makes
218 the hook buffer-local and adds @code{t} to the buffer-local value.  The
219 latter acts as a flag to run the hook functions in the default value as
220 well as in the local value.
221 @end defun
223 @defun remove-hook hook function &optional local
224 This function removes @var{function} from the hook variable
225 @var{hook}.  It compares @var{function} with elements of @var{hook}
226 using @code{equal}, so it works for both symbols and lambda
227 expressions.
229 If @var{local} is non-@code{nil}, that says to remove @var{function}
230 from the buffer-local hook list instead of from the global hook list.
231 @end defun
233 @node Major Modes
234 @section Major Modes
235 @cindex major mode
237 @cindex major mode command
238   Major modes specialize Emacs for editing particular kinds of text.
239 Each buffer has one major mode at a time.  Every major mode is
240 associated with a @dfn{major mode command}, whose name should end in
241 @samp{-mode}.  This command takes care of switching to that mode in the
242 current buffer, by setting various buffer-local variables such as a
243 local keymap.  @xref{Major Mode Conventions}.
245   The least specialized major mode is called @dfn{Fundamental mode},
246 which has no mode-specific definitions or variable settings.
248 @deffn Command fundamental-mode
249 This is the major mode command for Fundamental mode.  Unlike other mode
250 commands, it does @emph{not} run any mode hooks (@pxref{Major Mode
251 Conventions}), since you are not supposed to customize this mode.
252 @end deffn
254   The easiest way to write a major mode is to use the macro
255 @code{define-derived-mode}, which sets up the new mode as a variant of
256 an existing major mode.  @xref{Derived Modes}.  We recommend using
257 @code{define-derived-mode} even if the new mode is not an obvious
258 derivative of another mode, as it automatically enforces many coding
259 conventions for you.  @xref{Basic Major Modes}, for common modes to
260 derive from.
262   The standard GNU Emacs Lisp directory tree contains the code for
263 several major modes, in files such as @file{text-mode.el},
264 @file{texinfo.el}, @file{lisp-mode.el}, and @file{rmail.el}.  You can
265 study these libraries to see how modes are written.
267 @defopt major-mode
268 The buffer-local value of this variable holds the symbol for the current
269 major mode.  Its default value holds the default major mode for new
270 buffers.  The standard default value is @code{fundamental-mode}.
272 If the default value is @code{nil}, then whenever Emacs creates a new
273 buffer via a command such as @kbd{C-x b} (@code{switch-to-buffer}), the
274 new buffer is put in the major mode of the previously current buffer.
275 As an exception, if the major mode of the previous buffer has a
276 @code{mode-class} symbol property with value @code{special}, the new
277 buffer is put in Fundamental mode (@pxref{Major Mode Conventions}).
278 @end defopt
280 @menu
281 * Major Mode Conventions::  Coding conventions for keymaps, etc.
282 * Auto Major Mode::         How Emacs chooses the major mode automatically.
283 * Mode Help::               Finding out how to use a mode.
284 * Derived Modes::           Defining a new major mode based on another major
285                               mode.
286 * Basic Major Modes::       Modes that other modes are often derived from.
287 * Mode Hooks::              Hooks run at the end of major mode functions.
288 * Tabulated List Mode::     Parent mode for buffers containing tabulated data.
289 * Generic Modes::           Defining a simple major mode that supports
290                               comment syntax and Font Lock mode.
291 * Example Major Modes::     Text mode and Lisp modes.
292 @end menu
294 @node Major Mode Conventions
295 @subsection Major Mode Conventions
296 @cindex major mode conventions
297 @cindex conventions for writing major modes
299   The code for every major mode should follow various coding
300 conventions, including conventions for local keymap and syntax table
301 initialization, function and variable names, and hooks.
303   If you use the @code{define-derived-mode} macro, it will take care of
304 many of these conventions automatically.  @xref{Derived Modes}.  Note
305 also that Fundamental mode is an exception to many of these conventions,
306 because it represents the default state of Emacs.
308   The following list of conventions is only partial.  Each major mode
309 should aim for consistency in general with other Emacs major modes, as
310 this makes Emacs as a whole more coherent.  It is impossible to list
311 here all the possible points where this issue might come up; if the
312 Emacs developers point out an area where your major mode deviates from
313 the usual conventions, please make it compatible.
315 @itemize @bullet
316 @item
317 Define a major mode command whose name ends in @samp{-mode}.  When
318 called with no arguments, this command should switch to the new mode in
319 the current buffer by setting up the keymap, syntax table, and
320 buffer-local variables in an existing buffer.  It should not change the
321 buffer's contents.
323 @item
324 Write a documentation string for this command that describes the special
325 commands available in this mode.  @xref{Mode Help}.
327 The documentation string may include the special documentation
328 substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
329 @samp{\<@var{keymap}>}, which allow the help display to adapt
330 automatically to the user's own key bindings.  @xref{Keys in
331 Documentation}.
333 @item
334 The major mode command should start by calling
335 @code{kill-all-local-variables}.  This runs the normal hook
336 @code{change-major-mode-hook}, then gets rid of the buffer-local
337 variables of the major mode previously in effect.  @xref{Creating
338 Buffer-Local}.
340 @item
341 The major mode command should set the variable @code{major-mode} to the
342 major mode command symbol.  This is how @code{describe-mode} discovers
343 which documentation to print.
345 @item
346 The major mode command should set the variable @code{mode-name} to the
347 ``pretty'' name of the mode, usually a string (but see @ref{Mode Line
348 Data}, for other possible forms).  The name of the mode appears
349 in the mode line.
351 @item
352 @cindex functions in modes
353 Since all global names are in the same name space, all the global
354 variables, constants, and functions that are part of the mode should
355 have names that start with the major mode name (or with an abbreviation
356 of it if the name is long).  @xref{Coding Conventions}.
358 @item
359 In a major mode for editing some kind of structured text, such as a
360 programming language, indentation of text according to structure is
361 probably useful.  So the mode should set @code{indent-line-function}
362 to a suitable function, and probably customize other variables
363 for indentation.  @xref{Auto-Indentation}.
365 @item
366 @cindex keymaps in modes
367 The major mode should usually have its own keymap, which is used as the
368 local keymap in all buffers in that mode.  The major mode command should
369 call @code{use-local-map} to install this local map.  @xref{Active
370 Keymaps}, for more information.
372 This keymap should be stored permanently in a global variable named
373 @code{@var{modename}-mode-map}.  Normally the library that defines the
374 mode sets this variable.
376 @xref{Tips for Defining}, for advice about how to write the code to set
377 up the mode's keymap variable.
379 @item
380 The key sequences bound in a major mode keymap should usually start with
381 @kbd{C-c}, followed by a control character, a digit, or @kbd{@{},
382 @kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}.  The other punctuation
383 characters are reserved for minor modes, and ordinary letters are
384 reserved for users.
386 A major mode can also rebind the keys @kbd{M-n}, @kbd{M-p} and
387 @kbd{M-s}.  The bindings for @kbd{M-n} and @kbd{M-p} should normally
388 be some kind of ``moving forward and backward'', but this does not
389 necessarily mean cursor motion.
391 It is legitimate for a major mode to rebind a standard key sequence if
392 it provides a command that does ``the same job'' in a way better
393 suited to the text this mode is used for.  For example, a major mode
394 for editing a programming language might redefine @kbd{C-M-a} to
395 ``move to the beginning of a function'' in a way that works better for
396 that language.
398 It is also legitimate for a major mode to rebind a standard key
399 sequence whose standard meaning is rarely useful in that mode.  For
400 instance, minibuffer modes rebind @kbd{M-r}, whose standard meaning is
401 rarely of any use in the minibuffer.  Major modes such as Dired or
402 Rmail that do not allow self-insertion of text can reasonably redefine
403 letters and other printing characters as special commands.
405 @item
406 Major modes for editing text should not define @key{RET} to do
407 anything other than insert a newline.  However, it is ok for
408 specialized modes for text that users don't directly edit, such as
409 Dired and Info modes, to redefine @key{RET} to do something entirely
410 different.
412 @item
413 Major modes should not alter options that are primarily a matter of user
414 preference, such as whether Auto-Fill mode is enabled.  Leave this to
415 each user to decide.  However, a major mode should customize other
416 variables so that Auto-Fill mode will work usefully @emph{if} the user
417 decides to use it.
419 @item
420 @cindex syntax tables in modes
421 The mode may have its own syntax table or may share one with other
422 related modes.  If it has its own syntax table, it should store this in
423 a variable named @code{@var{modename}-mode-syntax-table}.  @xref{Syntax
424 Tables}.
426 @item
427 If the mode handles a language that has a syntax for comments, it should
428 set the variables that define the comment syntax.  @xref{Options for
429 Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}.
431 @item
432 @cindex abbrev tables in modes
433 The mode may have its own abbrev table or may share one with other
434 related modes.  If it has its own abbrev table, it should store this
435 in a variable named @code{@var{modename}-mode-abbrev-table}.  If the
436 major mode command defines any abbrevs itself, it should pass @code{t}
437 for the @var{system-flag} argument to @code{define-abbrev}.
438 @xref{Defining Abbrevs}.
440 @item
441 The mode should specify how to do highlighting for Font Lock mode, by
442 setting up a buffer-local value for the variable
443 @code{font-lock-defaults} (@pxref{Font Lock Mode}).
445 @item
446 Each face that the mode defines should, if possible, inherit from an
447 existing Emacs face.  @xref{Basic Faces}, and @ref{Faces for Font Lock}.
449 @item
450 The mode should specify how Imenu should find the definitions or
451 sections of a buffer, by setting up a buffer-local value for the
452 variable @code{imenu-generic-expression}, for the two variables
453 @code{imenu-prev-index-position-function} and
454 @code{imenu-extract-index-name-function}, or for the variable
455 @code{imenu-create-index-function} (@pxref{Imenu}).
457 @item
458 The mode can specify a local value for
459 @code{eldoc-documentation-function} to tell ElDoc mode how to handle
460 this mode.
462 @item
463 The mode can specify how to complete various keywords by adding one or
464 more buffer-local entries to the special hook
465 @code{completion-at-point-functions}.  @xref{Completion in Buffers}.
467 @item
468 @cindex buffer-local variables in modes
469 To make a buffer-local binding for an Emacs customization variable, use
470 @code{make-local-variable} in the major mode command, not
471 @code{make-variable-buffer-local}.  The latter function would make the
472 variable local to every buffer in which it is subsequently set, which
473 would affect buffers that do not use this mode.  It is undesirable for a
474 mode to have such global effects.  @xref{Buffer-Local Variables}.
476 With rare exceptions, the only reasonable way to use
477 @code{make-variable-buffer-local} in a Lisp package is for a variable
478 which is used only within that package.  Using it on a variable used by
479 other packages would interfere with them.
481 @item
482 @cindex mode hook
483 @cindex major mode hook
484 Each major mode should have a normal @dfn{mode hook} named
485 @code{@var{modename}-mode-hook}.  The very last thing the major mode command
486 should do is to call @code{run-mode-hooks}.  This runs the normal
487 hook @code{change-major-mode-after-body-hook}, the mode hook,
488 and then the normal hook @code{after-change-major-mode-hook}.
489 @xref{Mode Hooks}.
491 @item
492 The major mode command may start by calling some other major mode
493 command (called the @dfn{parent mode}) and then alter some of its
494 settings.  A mode that does this is called a @dfn{derived mode}.  The
495 recommended way to define one is to use the @code{define-derived-mode}
496 macro, but this is not required.  Such a mode should call the parent
497 mode command inside a @code{delay-mode-hooks} form.  (Using
498 @code{define-derived-mode} does this automatically.)  @xref{Derived
499 Modes}, and @ref{Mode Hooks}.
501 @item
502 If something special should be done if the user switches a buffer from
503 this mode to any other major mode, this mode can set up a buffer-local
504 value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}).
506 @item
507 If this mode is appropriate only for specially-prepared text produced by
508 the mode itself (rather than by the user typing at the keyboard or by an
509 external file), then the major mode command symbol should have a
510 property named @code{mode-class} with value @code{special}, put on as
511 follows:
513 @kindex mode-class @r{(property)}
514 @cindex @code{special} modes
515 @example
516 (put 'funny-mode 'mode-class 'special)
517 @end example
519 @noindent
520 This tells Emacs that new buffers created while the current buffer is in
521 Funny mode should not be put in Funny mode, even though the default
522 value of @code{major-mode} is @code{nil}.  By default, the value of
523 @code{nil} for @code{major-mode} means to use the current buffer's major
524 mode when creating new buffers (@pxref{Auto Major Mode}), but with such
525 @code{special} modes, Fundamental mode is used instead.  Modes such as
526 Dired, Rmail, and Buffer List use this feature.
528 The function @code{view-buffer} does not enable View mode in buffers
529 whose mode-class is special, because such modes usually provide their
530 own View-like bindings.
532 The @code{define-derived-mode} macro automatically marks the derived
533 mode as special if the parent mode is special.  Special mode is a
534 convenient parent for such modes to inherit from; @xref{Basic Major
535 Modes}.
537 @item
538 If you want to make the new mode the default for files with certain
539 recognizable names, add an element to @code{auto-mode-alist} to select
540 the mode for those file names (@pxref{Auto Major Mode}).  If you
541 define the mode command to autoload, you should add this element in
542 the same file that calls @code{autoload}.  If you use an autoload
543 cookie for the mode command, you can also use an autoload cookie for
544 the form that adds the element (@pxref{autoload cookie}).  If you do
545 not autoload the mode command, it is sufficient to add the element in
546 the file that contains the mode definition.
548 @item
549 @cindex mode loading
550 The top-level forms in the file defining the mode should be written so
551 that they may be evaluated more than once without adverse consequences.
552 For instance, use @code{defvar} or @code{defcustom} to set mode-related
553 variables, so that they are not reinitialized if they already have a
554 value (@pxref{Defining Variables}).
556 @end itemize
558 @node Auto Major Mode
559 @subsection How Emacs Chooses a Major Mode
560 @cindex major mode, automatic selection
562   When Emacs visits a file, it automatically selects a major mode for
563 the buffer based on information in the file name or in the file itself.
564 It also processes local variables specified in the file text.
566 @deffn Command normal-mode &optional find-file
567 This function establishes the proper major mode and buffer-local variable
568 bindings for the current buffer.  First it calls @code{set-auto-mode}
569 (see below), then it runs @code{hack-local-variables} to parse, and
570 bind or evaluate as appropriate, the file's local variables
571 (@pxref{File Local Variables}).
573 If the @var{find-file} argument to @code{normal-mode} is non-@code{nil},
574 @code{normal-mode} assumes that the @code{find-file} function is calling
575 it.  In this case, it may process local variables in the @samp{-*-}
576 line or at the end of the file.  The variable
577 @code{enable-local-variables} controls whether to do so.  @xref{File
578 Variables, , Local Variables in Files, emacs, The GNU Emacs Manual},
579 for the syntax of the local variables section of a file.
581 If you run @code{normal-mode} interactively, the argument
582 @var{find-file} is normally @code{nil}.  In this case,
583 @code{normal-mode} unconditionally processes any file local variables.
585 The function calls @code{set-auto-mode} to choose a major mode.  If this
586 does not specify a mode, the buffer stays in the major mode determined
587 by the default value of @code{major-mode} (see below).
589 @cindex file mode specification error
590 @code{normal-mode} uses @code{condition-case} around the call to the
591 major mode command, so errors are caught and reported as a @samp{File
592 mode specification error}, followed by the original error message.
593 @end deffn
595 @defun set-auto-mode &optional keep-mode-if-same
596 @cindex visited file mode
597   This function selects the major mode that is appropriate for the
598 current buffer.  It bases its decision (in order of precedence) on the
599 @w{@samp{-*-}} line, on any @samp{mode:} local variable near the end of
600 a file, on the @w{@samp{#!}} line (using @code{interpreter-mode-alist}),
601 on the text at the beginning of the buffer (using
602 @code{magic-mode-alist}), and finally on the visited file name (using
603 @code{auto-mode-alist}).  @xref{Choosing Modes, , How Major Modes are
604 Chosen, emacs, The GNU Emacs Manual}.  If @code{enable-local-variables}
605 is @code{nil}, @code{set-auto-mode} does not check the @w{@samp{-*-}}
606 line, or near the end of the file, for any mode tag.
608 @vindex inhibit-local-variables-regexps
609 There are some file types where it is not appropriate to scan the file
610 contents for a mode specifier.  For example, a tar archive may happen to
611 contain, near the end of the file, a member file that has a local
612 variables section specifying a mode for that particular file.  This
613 should not be applied to the containing tar file.  Similarly, a tiff
614 image file might just happen to contain a first line that seems to
615 match the @w{@samp{-*-}} pattern.  For these reasons, both these file
616 extensions are members of the list @code{inhibit-local-variables-regexps}.
617 Add patterns to this list to prevent Emacs searching them for local
618 variables of any kind (not just mode specifiers).
620 If @var{keep-mode-if-same} is non-@code{nil}, this function does not
621 call the mode command if the buffer is already in the proper major
622 mode.  For instance, @code{set-visited-file-name} sets this to
623 @code{t} to avoid killing buffer local variables that the user may
624 have set.
625 @end defun
627 @defun set-buffer-major-mode buffer
628 This function sets the major mode of @var{buffer} to the default value of
629 @code{major-mode}; if that is @code{nil}, it uses the
630 current buffer's major mode (if that is suitable).  As an exception,
631 if @var{buffer}'s name is @file{*scratch*}, it sets the mode to
632 @code{initial-major-mode}.
634 The low-level primitives for creating buffers do not use this function,
635 but medium-level commands such as @code{switch-to-buffer} and
636 @code{find-file-noselect} use it whenever they create buffers.
637 @end defun
639 @defopt initial-major-mode
640 @cindex @file{*scratch*}
641 The value of this variable determines the major mode of the initial
642 @file{*scratch*} buffer.  The value should be a symbol that is a major
643 mode command.  The default value is @code{lisp-interaction-mode}.
644 @end defopt
646 @defvar interpreter-mode-alist
647 This variable specifies major modes to use for scripts that specify a
648 command interpreter in a @samp{#!} line.  Its value is an alist with
649 elements of the form @code{(@var{interpreter} . @var{mode})}; for
650 example, @code{("perl" . perl-mode)} is one element present by
651 default.  The element says to use mode @var{mode} if the file
652 specifies an interpreter which matches @var{interpreter}.
653 @end defvar
655 @defvar magic-mode-alist
656 This variable's value is an alist with elements of the form
657 @code{(@var{regexp} .  @var{function})}, where @var{regexp} is a
658 regular expression and @var{function} is a function or @code{nil}.
659 After visiting a file, @code{set-auto-mode} calls @var{function} if
660 the text at the beginning of the buffer matches @var{regexp} and
661 @var{function} is non-@code{nil}; if @var{function} is @code{nil},
662 @code{auto-mode-alist} gets to decide the mode.
663 @end defvar
665 @defvar magic-fallback-mode-alist
666 This works like @code{magic-mode-alist}, except that it is handled
667 only if @code{auto-mode-alist} does not specify a mode for this file.
668 @end defvar
670 @defvar auto-mode-alist
671 This variable contains an association list of file name patterns
672 (regular expressions) and corresponding major mode commands.  Usually,
673 the file name patterns test for suffixes, such as @samp{.el} and
674 @samp{.c}, but this need not be the case.  An ordinary element of the
675 alist looks like @code{(@var{regexp} .  @var{mode-function})}.
677 For example,
679 @smallexample
680 @group
681 (("\\`/tmp/fol/" . text-mode)
682  ("\\.texinfo\\'" . texinfo-mode)
683  ("\\.texi\\'" . texinfo-mode)
684 @end group
685 @group
686  ("\\.el\\'" . emacs-lisp-mode)
687  ("\\.c\\'" . c-mode)
688  ("\\.h\\'" . c-mode)
689  @dots{})
690 @end group
691 @end smallexample
693 When you visit a file whose expanded file name (@pxref{File Name
694 Expansion}), with version numbers and backup suffixes removed using
695 @code{file-name-sans-versions} (@pxref{File Name Components}), matches
696 a @var{regexp}, @code{set-auto-mode} calls the corresponding
697 @var{mode-function}.  This feature enables Emacs to select the proper
698 major mode for most files.
700 If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
701 @var{function} t)}, then after calling @var{function}, Emacs searches
702 @code{auto-mode-alist} again for a match against the portion of the file
703 name that did not match before.  This feature is useful for
704 uncompression packages: an entry of the form @code{("\\.gz\\'"
705 @var{function} t)} can uncompress the file and then put the uncompressed
706 file in the proper mode according to the name sans @samp{.gz}.
708 Here is an example of how to prepend several pattern pairs to
709 @code{auto-mode-alist}.  (You might use this sort of expression in your
710 init file.)
712 @smallexample
713 @group
714 (setq auto-mode-alist
715   (append
716    ;; @r{File name (within directory) starts with a dot.}
717    '(("/\\.[^/]*\\'" . fundamental-mode)
718      ;; @r{File name has no dot.}
719      ("/[^\\./]*\\'" . fundamental-mode)
720      ;; @r{File name ends in @samp{.C}.}
721      ("\\.C\\'" . c++-mode))
722    auto-mode-alist))
723 @end group
724 @end smallexample
725 @end defvar
727 @node Mode Help
728 @subsection Getting Help about a Major Mode
729 @cindex mode help
730 @cindex help for major mode
731 @cindex documentation for major mode
733   The @code{describe-mode} function provides information about major
734 modes.  It is normally bound to @kbd{C-h m}.  It uses the value of the
735 variable @code{major-mode} (@pxref{Major Modes}), which is why every
736 major mode command needs to set that variable.
738 @deffn Command describe-mode &optional buffer
739 This command displays the documentation of the current buffer's major
740 mode and minor modes.  It uses the @code{documentation} function to
741 retrieve the documentation strings of the major and minor mode
742 commands (@pxref{Accessing Documentation}).
744 If called from Lisp with a non-nil @var{buffer} argument, this
745 function displays the documentation for that buffer's major and minor
746 modes, rather than those of the current buffer.
747 @end deffn
749 @node Derived Modes
750 @subsection Defining Derived Modes
751 @cindex derived mode
753   The recommended way to define a new major mode is to derive it from an
754 existing one using @code{define-derived-mode}.  If there is no closely
755 related mode, you should inherit from either @code{text-mode},
756 @code{special-mode}, or @code{prog-mode}.  @xref{Basic Major Modes}.  If
757 none of these are suitable, you can inherit from @code{fundamental-mode}
758 (@pxref{Major Modes}).
760 @defmac define-derived-mode variant parent name docstring keyword-args@dots{} body@dots{}
761 This macro defines @var{variant} as a major mode command, using
762 @var{name} as the string form of the mode name.  @var{variant} and
763 @var{parent} should be unquoted symbols.
765 The new command @var{variant} is defined to call the function
766 @var{parent}, then override certain aspects of that parent mode:
768 @itemize @bullet
769 @item
770 The new mode has its own sparse keymap, named
771 @code{@var{variant}-map}.  @code{define-derived-mode}
772 makes the parent mode's keymap the parent of the new map, unless
773 @code{@var{variant}-map} is already set and already has a parent.
775 @item
776 The new mode has its own syntax table, kept in the variable
777 @code{@var{variant}-syntax-table}, unless you override this using the
778 @code{:syntax-table} keyword (see below).  @code{define-derived-mode}
779 makes the parent mode's syntax-table the parent of
780 @code{@var{variant}-syntax-table}, unless the latter is already set
781 and already has a parent different from the standard syntax table.
783 @item
784 The new mode has its own abbrev table, kept in the variable
785 @code{@var{variant}-abbrev-table}, unless you override this using the
786 @code{:abbrev-table} keyword (see below).
788 @item
789 The new mode has its own mode hook, @code{@var{variant}-hook}.  It
790 runs this hook, after running the hooks of its ancestor modes, with
791 @code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}.
792 @end itemize
794 In addition, you can specify how to override other aspects of
795 @var{parent} with @var{body}.  The command @var{variant}
796 evaluates the forms in @var{body} after setting up all its usual
797 overrides, just before running the mode hooks.
799 If @var{parent} has a non-@code{nil} @code{mode-class} symbol
800 property, then @code{define-derived-mode} sets the @code{mode-class}
801 property of @var{variant} to the same value.  This ensures, for
802 example, that if @var{parent} is a special mode, then @var{variant} is
803 also a special mode (@pxref{Major Mode Conventions}).
805 You can also specify @code{nil} for @var{parent}.  This gives the new
806 mode no parent.  Then @code{define-derived-mode} behaves as described
807 above, but, of course, omits all actions connected with @var{parent}.
809 The argument @var{docstring} specifies the documentation string for the
810 new mode.  @code{define-derived-mode} adds some general information
811 about the mode's hook, followed by the mode's keymap, at the end of this
812 documentation string.  If you omit @var{docstring},
813 @code{define-derived-mode} generates a documentation string.
815 The @var{keyword-args} are pairs of keywords and values.  The values
816 are evaluated.  The following keywords are currently supported:
818 @table @code
819 @item :syntax-table
820 You can use this to explicitly specify a syntax table for the new
821 mode.  If you specify a @code{nil} value, the new mode uses the same
822 syntax table as @var{parent}, or the standard syntax table if
823 @var{parent} is @code{nil}.  (Note that this does @emph{not} follow
824 the convention used for non-keyword arguments that a @code{nil} value
825 is equivalent with not specifying the argument.)
827 @item :abbrev-table
828 You can use this to explicitly specify an abbrev table for the new
829 mode.  If you specify a @code{nil} value, the new mode uses the same
830 abbrev table as @var{parent}, or @code{fundamental-mode-abbrev-table}
831 if @var{parent} is @code{nil}.  (Again, a @code{nil} value is
832 @emph{not} equivalent to not specifying this keyword.)
834 @item :group
835 If this is specified, the value should be the customization group for
836 this mode.  (Not all major modes have one.)  Only the (still
837 experimental and unadvertised) command @code{customize-mode} currently
838 uses this.  @code{define-derived-mode} does @emph{not} automatically
839 define the specified customization group.
840 @end table
842 Here is a hypothetical example:
844 @example
845 (define-derived-mode hypertext-mode
846   text-mode "Hypertext"
847   "Major mode for hypertext.
848 \\@{hypertext-mode-map@}"
849   (setq case-fold-search nil))
851 (define-key hypertext-mode-map
852   [down-mouse-3] 'do-hyper-link)
853 @end example
855 Do not write an @code{interactive} spec in the definition;
856 @code{define-derived-mode} does that automatically.
857 @end defmac
859 @defun derived-mode-p &rest modes
860 This function returns non-@code{nil} if the current major mode is
861 derived from any of the major modes given by the symbols @var{modes}.
862 @end defun
864 @node Basic Major Modes
865 @subsection Basic Major Modes
867   Apart from Fundamental mode, there are three major modes that other
868 major modes commonly derive from: Text mode, Prog mode, and Special
869 mode.  While Text mode is useful in its own right (e.g., for editing
870 files ending in @file{.txt}), Prog mode and Special mode exist mainly to
871 let other modes derive from them.
873 @vindex prog-mode-hook
874   As far as possible, new major modes should be derived, either directly
875 or indirectly, from one of these three modes.  One reason is that this
876 allows users to customize a single mode hook
877 (e.g., @code{prog-mode-hook}) for an entire family of relevant modes
878 (e.g., all programming language modes).
880 @deffn Command text-mode
881 Text mode is a major mode for editing human languages.  It defines the
882 @samp{"} and @samp{\} characters as having punctuation syntax
883 (@pxref{Syntax Class Table}), and binds @kbd{M-@key{TAB}} to
884 @code{ispell-complete-word} (@pxref{Spelling,,, emacs, The GNU Emacs
885 Manual}).
887 An example of a major mode derived from Text mode is HTML mode.
888 @xref{HTML Mode,,SGML and HTML Modes, emacs, The GNU Emacs Manual}.
889 @end deffn
891 @deffn Command prog-mode
892 Prog mode is a basic major mode for buffers containing programming
893 language source code.  Most of the programming language major modes
894 built into Emacs are derived from it.
896 Prog mode binds @code{parse-sexp-ignore-comments} to @code{t}
897 (@pxref{Motion via Parsing}) and @code{bidi-paragraph-direction} to
898 @code{left-to-right} (@pxref{Bidirectional Display}).
899 @end deffn
901 @deffn Command special-mode
902 Special mode is a basic major mode for buffers containing text that is
903 produced specially by Emacs, rather than directly from a file.  Major
904 modes derived from Special mode are given a @code{mode-class} property
905 of @code{special} (@pxref{Major Mode Conventions}).
907 Special mode sets the buffer to read-only.  Its keymap defines several
908 common bindings, including @kbd{q} for @code{quit-window} and @kbd{g}
909 for @code{revert-buffer} (@pxref{Reverting}).
911 An example of a major mode derived from Special mode is Buffer Menu
912 mode, which is used by the @file{*Buffer List*} buffer.  @xref{List
913 Buffers,,Listing Existing Buffers, emacs, The GNU Emacs Manual}.
914 @end deffn
916   In addition, modes for buffers of tabulated data can inherit from
917 Tabulated List mode, which is in turn derived from Special mode.
918 @xref{Tabulated List Mode}.
920 @node Mode Hooks
921 @subsection Mode Hooks
923   Every major mode command should finish by running the mode-independent
924 normal hook @code{change-major-mode-after-body-hook}, its mode hook,
925 and the normal hook @code{after-change-major-mode-hook}.
926 It does this by calling @code{run-mode-hooks}.  If the major mode is a
927 derived mode, that is if it calls another major mode (the parent mode)
928 in its body, it should do this inside @code{delay-mode-hooks} so that
929 the parent won't run these hooks itself.  Instead, the derived mode's
930 call to @code{run-mode-hooks} runs the parent's mode hook too.
931 @xref{Major Mode Conventions}.
933   Emacs versions before Emacs 22 did not have @code{delay-mode-hooks}.
934 Versions before 24 did not have @code{change-major-mode-after-body-hook}.
935 When user-implemented major modes do not use @code{run-mode-hooks} and
936 have not been updated to use these newer features, they won't entirely
937 follow these conventions: they may run the parent's mode hook too early,
938 or fail to run @code{after-change-major-mode-hook}.  If you encounter
939 such a major mode, please correct it to follow these conventions.
941   When you defined a major mode using @code{define-derived-mode}, it
942 automatically makes sure these conventions are followed.  If you
943 define a major mode ``by hand'', not using @code{define-derived-mode},
944 use the following functions to handle these conventions automatically.
946 @defun run-mode-hooks &rest hookvars
947 Major modes should run their mode hook using this function.  It is
948 similar to @code{run-hooks} (@pxref{Hooks}), but it also runs
949 @code{change-major-mode-after-body-hook} and
950 @code{after-change-major-mode-hook}.
952 When this function is called during the execution of a
953 @code{delay-mode-hooks} form, it does not run the hooks immediately.
954 Instead, it arranges for the next call to @code{run-mode-hooks} to run
955 them.
956 @end defun
958 @defmac delay-mode-hooks body@dots{}
959 When one major mode command calls another, it should do so inside of
960 @code{delay-mode-hooks}.
962 This macro executes @var{body}, but tells all @code{run-mode-hooks}
963 calls during the execution of @var{body} to delay running their hooks.
964 The hooks will actually run during the next call to
965 @code{run-mode-hooks} after the end of the @code{delay-mode-hooks}
966 construct.
967 @end defmac
969 @defvar change-major-mode-after-body-hook
970 This is a normal hook run by @code{run-mode-hooks}.  It is run before
971 the mode hooks.
972 @end defvar
974 @defvar after-change-major-mode-hook
975 This is a normal hook run by @code{run-mode-hooks}.  It is run at the
976 very end of every properly-written major mode command.
977 @end defvar
979 @node Tabulated List Mode
980 @subsection Tabulated List mode
981 @cindex Tabulated List mode
983   Tabulated List mode is a major mode for displaying tabulated data,
984 i.e., data consisting of @dfn{entries}, each entry occupying one row of
985 text with its contents divided into columns.  Tabulated List mode
986 provides facilities for pretty-printing rows and columns, and sorting
987 the rows according to the values in each column.  It is derived from
988 Special mode (@pxref{Basic Major Modes}).
990   Tabulated List mode is intended to be used as a parent mode by a more
991 specialized major mode.  Examples include Process Menu mode
992 (@pxref{Process Information}) and Package Menu mode (@pxref{Package
993 Menu,,, emacs, The GNU Emacs Manual}).
995 @findex tabulated-list-mode
996   Such a derived mode should use @code{define-derived-mode} in the usual
997 way, specifying @code{tabulated-list-mode} as the second argument
998 (@pxref{Derived Modes}).  The body of the @code{define-derived-mode}
999 form should specify the format of the tabulated data, by assigning
1000 values to the variables documented below; then, it should call the
1001 function @code{tabulated-list-init-header} to initialize the header
1002 line.
1004   The derived mode should also define a @dfn{listing command}.  This,
1005 not the mode command, is what the user calls (e.g., @kbd{M-x
1006 list-processes}).  The listing command should create or switch to a
1007 buffer, turn on the derived mode, specify the tabulated data, and
1008 finally call @code{tabulated-list-print} to populate the buffer.
1010 @defvar tabulated-list-format
1011 This buffer-local variable specifies the format of the Tabulated List
1012 data.  Its value should be a vector.  Each element of the vector
1013 represents a data column, and should be a list @code{(@var{name}
1014 @var{width} @var{sort})}, where
1016 @itemize
1017 @item
1018 @var{name} is the column's name (a string).
1020 @item
1021 @var{width} is the width to reserve for the column (an integer).  This
1022 is meaningless for the last column, which runs to the end of each line.
1024 @item
1025 @var{sort} specifies how to sort entries by the column.  If @code{nil},
1026 the column cannot be used for sorting.  If @code{t}, the column is
1027 sorted by comparing string values.  Otherwise, this should be a
1028 predicate function for @code{sort} (@pxref{Rearrangement}), which
1029 accepts two arguments with the same form as the elements of
1030 @code{tabulated-list-entries} (see below).
1031 @end itemize
1032 @end defvar
1034 @defvar tabulated-list-entries
1035 This buffer-local variable specifies the entries displayed in the
1036 Tabulated List buffer.  Its value should be either a list, or a
1037 function.
1039 If the value is a list, each list element corresponds to one entry, and
1040 should have the form @w{@code{(@var{id} @var{contents})}}, where
1042 @itemize
1043 @item
1044 @var{id} is either @code{nil}, or a Lisp object that identifies the
1045 entry.  If the latter, the cursor stays on the ``same'' entry when
1046 re-sorting entries.  Comparison is done with @code{equal}.
1048 @item
1049 @var{contents} is a vector with the same number of elements as
1050 @code{tabulated-list-format}.  Each vector element is either a string,
1051 which is inserted into the buffer as-is, or a list @code{(@var{label}
1052 . @var{properties})}, which means to insert a text button by calling
1053 @code{insert-text-button} with @var{label} and @var{properties} as
1054 arguments (@pxref{Making Buttons}).
1056 There should be no newlines in any of these strings.
1057 @end itemize
1059 Otherwise, the value should be a function which returns a list of the
1060 above form when called with no arguments.
1061 @end defvar
1063 @defvar tabulated-list-revert-hook
1064 This normal hook is run prior to reverting a Tabulated List buffer.  A
1065 derived mode can add a function to this hook to recompute
1066 @code{tabulated-list-entries}.
1067 @end defvar
1069 @defvar tabulated-list-printer
1070 The value of this variable is the function called to insert an entry at
1071 point, including its terminating newline.  The function should accept
1072 two arguments, @var{id} and @var{contents}, having the same meanings as
1073 in @code{tabulated-list-entries}.  The default value is a function which
1074 inserts an entry in a straightforward way; a mode which uses Tabulated
1075 List mode in a more complex way can specify another function.
1076 @end defvar
1078 @defvar tabulated-list-sort-key
1079 The value of this variable specifies the current sort key for the
1080 Tabulated List buffer.  If it is @code{nil}, no sorting is done.
1081 Otherwise, it should have the form @code{(@var{name} . @var{flip})},
1082 where @var{name} is a string matching one of the column names in
1083 @code{tabulated-list-format}, and @var{flip}, if non-@code{nil}, means
1084 to invert the sort order.
1085 @end defvar
1087 @defun tabulated-list-init-header
1088 This function computes and sets @code{header-line-format} for the
1089 Tabulated List buffer (@pxref{Header Lines}), and assigns a keymap to
1090 the header line to allow sort entries by clicking on column headers.
1092 Modes derived from Tabulated List mode should call this after setting
1093 the above variables (in particular, only after setting
1094 @code{tabulated-list-format}).
1095 @end defun
1097 @defun tabulated-list-print &optional remember-pos
1098 This function populates the current buffer with entries.  It should be
1099 called by the listing command.  It erases the buffer, sorts the entries
1100 specified by @code{tabulated-list-entries} according to
1101 @code{tabulated-list-sort-key}, then calls the function specified by
1102 @code{tabulated-list-printer} to insert each entry.
1104 If the optional argument @var{remember-pos} is non-@code{nil}, this
1105 function looks for the @var{id} element on the current line, if any, and
1106 tries to move to that entry after all the entries are (re)inserted.
1107 @end defun
1109 @node Generic Modes
1110 @subsection Generic Modes
1111 @cindex generic mode
1113   @dfn{Generic modes} are simple major modes with basic support for
1114 comment syntax and Font Lock mode.  To define a generic mode, use the
1115 macro @code{define-generic-mode}.  See the file @file{generic-x.el}
1116 for some examples of the use of @code{define-generic-mode}.
1118 @defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring
1119 This macro defines a generic mode command named @var{mode} (a symbol,
1120 not quoted).  The optional argument @var{docstring} is the
1121 documentation for the mode command.  If you do not supply it,
1122 @code{define-generic-mode} generates one by default.
1124 The argument @var{comment-list} is a list in which each element is
1125 either a character, a string of one or two characters, or a cons cell.
1126 A character or a string is set up in the mode's syntax table as a
1127 ``comment starter''.  If the entry is a cons cell, the @sc{car} is set
1128 up as a ``comment starter'' and the @sc{cdr} as a ``comment ender''.
1129 (Use @code{nil} for the latter if you want comments to end at the end
1130 of the line.)  Note that the syntax table mechanism has limitations
1131 about what comment starters and enders are actually possible.
1132 @xref{Syntax Tables}.
1134 The argument @var{keyword-list} is a list of keywords to highlight
1135 with @code{font-lock-keyword-face}.  Each keyword should be a string.
1136 Meanwhile, @var{font-lock-list} is a list of additional expressions to
1137 highlight.  Each element of this list should have the same form as an
1138 element of @code{font-lock-keywords}.  @xref{Search-based
1139 Fontification}.
1141 The argument @var{auto-mode-list} is a list of regular expressions to
1142 add to the variable @code{auto-mode-alist}.  They are added by the execution
1143 of the @code{define-generic-mode} form, not by expanding the macro call.
1145 Finally, @var{function-list} is a list of functions for the mode
1146 command to call for additional setup.  It calls these functions just
1147 before it runs the mode hook variable @code{@var{mode}-hook}.
1148 @end defmac
1150 @node Example Major Modes
1151 @subsection Major Mode Examples
1153   Text mode is perhaps the simplest mode besides Fundamental mode.
1154 Here are excerpts from  @file{text-mode.el} that illustrate many of
1155 the conventions listed above:
1157 @smallexample
1158 @group
1159 ;; @r{Create the syntax table for this mode.}
1160 (defvar text-mode-syntax-table
1161   (let ((st (make-syntax-table)))
1162     (modify-syntax-entry ?\" ".   " st)
1163     (modify-syntax-entry ?\\ ".   " st)
1164     ;; Add `p' so M-c on `hello' leads to `Hello', not `hello'.
1165     (modify-syntax-entry ?' "w p" st)
1166     st)
1167   "Syntax table used while in `text-mode'.")
1168 @end group
1170 ;; @r{Create the keymap for this mode.}
1171 @group
1172 (defvar text-mode-map
1173   (let ((map (make-sparse-keymap)))
1174     (define-key map "\e\t" 'ispell-complete-word)
1175     map)
1176   "Keymap for `text-mode'.
1177 Many other modes, such as `mail-mode', `outline-mode' and
1178 `indented-text-mode', inherit all the commands defined in this map.")
1179 @end group
1180 @end smallexample
1182   Here is how the actual mode command is defined now:
1184 @smallexample
1185 @group
1186 (define-derived-mode text-mode nil "Text"
1187   "Major mode for editing text written for humans to read.
1188 In this mode, paragraphs are delimited only by blank or white lines.
1189 You can thus get the full benefit of adaptive filling
1190  (see the variable `adaptive-fill-mode').
1191 \\@{text-mode-map@}
1192 Turning on Text mode runs the normal hook `text-mode-hook'."
1193 @end group
1194 @group
1195   (set (make-local-variable 'text-mode-variant) t)
1196   (set (make-local-variable 'require-final-newline)
1197        mode-require-final-newline)
1198   (set (make-local-variable 'indent-line-function) 'indent-relative))
1199 @end group
1200 @end smallexample
1202 @noindent
1203 (The last line is redundant nowadays, since @code{indent-relative} is
1204 the default value, and we'll delete it in a future version.)
1206 @cindex @file{lisp-mode.el}
1207   The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp Interaction
1208 mode) have more features than Text mode and the code is correspondingly
1209 more complicated.  Here are excerpts from @file{lisp-mode.el} that
1210 illustrate how these modes are written.
1212   Here is how the Lisp mode syntax and abbrev tables are defined:
1214 @cindex syntax table example
1215 @smallexample
1216 @group
1217 ;; @r{Create mode-specific table variables.}
1218 (defvar lisp-mode-abbrev-table nil)
1219 (define-abbrev-table 'lisp-mode-abbrev-table ())
1221 (defvar lisp-mode-syntax-table
1222   (let ((table (copy-syntax-table emacs-lisp-mode-syntax-table)))
1223     (modify-syntax-entry ?\[ "_   " table)
1224     (modify-syntax-entry ?\] "_   " table)
1225     (modify-syntax-entry ?# "' 14" table)
1226     (modify-syntax-entry ?| "\" 23bn" table)
1227     table)
1228   "Syntax table used in `lisp-mode'.")
1229 @end group
1230 @end smallexample
1232   The three modes for Lisp share much of their code.  For instance,
1233 each calls the following function to set various variables:
1235 @smallexample
1236 @group
1237 (defun lisp-mode-variables (&optional syntax keywords-case-insensitive)
1238   (when syntax
1239     (set-syntax-table lisp-mode-syntax-table))
1240   (setq local-abbrev-table lisp-mode-abbrev-table)
1241   @dots{}
1242 @end group
1243 @end smallexample
1245 @noindent
1246 Amongst other things, this function sets up the @code{comment-start}
1247 variable to handle Lisp comments:
1249 @smallexample
1250 @group
1251   (make-local-variable 'comment-start)
1252   (setq comment-start ";")
1253   @dots{}
1254 @end group
1255 @end smallexample
1257   Each of the different Lisp modes has a slightly different keymap.  For
1258 example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other
1259 Lisp modes do not.  However, all Lisp modes have some commands in
1260 common.  The following code sets up the common commands:
1262 @smallexample
1263 @group
1264 (defvar lisp-mode-shared-map
1265   (let ((map (make-sparse-keymap)))
1266     (define-key map "\e\C-q" 'indent-sexp)
1267     (define-key map "\177" 'backward-delete-char-untabify)
1268     map)
1269   "Keymap for commands shared by all sorts of Lisp modes.")
1270 @end group
1271 @end smallexample
1273 @noindent
1274 And here is the code to set up the keymap for Lisp mode:
1276 @smallexample
1277 @group
1278 (defvar lisp-mode-map
1279   (let ((map (make-sparse-keymap))
1280         (menu-map (make-sparse-keymap "Lisp")))
1281     (set-keymap-parent map lisp-mode-shared-map)
1282     (define-key map "\e\C-x" 'lisp-eval-defun)
1283     (define-key map "\C-c\C-z" 'run-lisp)
1284     @dots{}
1285     map)
1286   "Keymap for ordinary Lisp mode.
1287 All commands in `lisp-mode-shared-map' are inherited by this map.")
1288 @end group
1289 @end smallexample
1291 @noindent
1292 Finally, here is the major mode command for Lisp mode:
1294 @smallexample
1295 @group
1296 (define-derived-mode lisp-mode prog-mode "Lisp"
1297   "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
1298 Commands:
1299 Delete converts tabs to spaces as it moves back.
1300 Blank lines separate paragraphs.  Semicolons start comments.
1302 \\@{lisp-mode-map@}
1303 Note that `run-lisp' may be used either to start an inferior Lisp job
1304 or to switch back to an existing one.
1305 @end group
1307 @group
1308 Entry to this mode calls the value of `lisp-mode-hook'
1309 if that value is non-nil."
1310   (lisp-mode-variables nil t)
1311   (set (make-local-variable 'find-tag-default-function)
1312        'lisp-find-tag-default)
1313   (set (make-local-variable 'comment-start-skip)
1314        "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *")
1315   (setq imenu-case-fold-search t))
1316 @end group
1317 @end smallexample
1319 @node Minor Modes
1320 @section Minor Modes
1321 @cindex minor mode
1323   A @dfn{minor mode} provides optional features that users may enable or
1324 disable independently of the choice of major mode.  Minor modes can be
1325 enabled individually or in combination.
1327   Most minor modes implement features that are independent of the major
1328 mode, and can thus be used with most major modes.  For example, Auto
1329 Fill mode works with any major mode that permits text insertion.  A few
1330 minor modes, however, are specific to a particular major mode.  For
1331 example, Diff Auto Refine mode is a minor mode that is intended to be
1332 used only with Diff mode.
1334   Ideally, a minor mode should have its desired effect regardless of the
1335 other minor modes in effect.  It should be possible to activate and
1336 deactivate minor modes in any order.
1338 @defvar minor-mode-list
1339 The value of this variable is a list of all minor mode commands.
1340 @end defvar
1342 @menu
1343 * Minor Mode Conventions::      Tips for writing a minor mode.
1344 * Keymaps and Minor Modes::     How a minor mode can have its own keymap.
1345 * Defining Minor Modes::        A convenient facility for defining minor modes.
1346 @end menu
1348 @node Minor Mode Conventions
1349 @subsection Conventions for Writing Minor Modes
1350 @cindex minor mode conventions
1351 @cindex conventions for writing minor modes
1353   There are conventions for writing minor modes just as there are for
1354 major modes.  These conventions are described below.  The easiest way to
1355 follow them is to use the macro @code{define-minor-mode}.
1356 @xref{Defining Minor Modes}.
1358 @itemize @bullet
1359 @item
1360 @cindex mode variable
1361 Define a variable whose name ends in @samp{-mode}.  We call this the
1362 @dfn{mode variable}.  The minor mode command should set this variable.
1363 The value will be @code{nil} if the mode is disabled, and non-@code{nil}
1364 if the mode is enabled.  The variable should be buffer-local if the
1365 minor mode is buffer-local.
1367 This variable is used in conjunction with the @code{minor-mode-alist} to
1368 display the minor mode name in the mode line.  It also determines
1369 whether the minor mode keymap is active, via @code{minor-mode-map-alist}
1370 (@pxref{Controlling Active Maps}).  Individual commands or hooks can
1371 also check its value.
1373 @item
1374 Define a command, called the @dfn{mode command}, whose name is the same
1375 as the mode variable.  Its job is to set the value of the mode variable,
1376 plus anything else that needs to be done to actually enable or disable
1377 the mode's features.
1379 The mode command should accept one optional argument.  If called
1380 interactively with no prefix argument, it should toggle the mode
1381 (i.e., enable if it is disabled, and disable if it is enabled).  If
1382 called interactively with a prefix argument, it should enable the mode
1383 if the argument is positive and disable it otherwise.
1385 If the mode command is called from Lisp (i.e., non-interactively), it
1386 should enable the mode if the argument is omitted or @code{nil}; it
1387 should toggle the mode if the argument is the symbol @code{toggle};
1388 otherwise it should treat the argument in the same way as for an
1389 interactive call with a numeric prefix argument, as described above.
1391 The following example shows how to implement this behavior (it is
1392 similar to the code generated by the @code{define-minor-mode} macro):
1394 @example
1395 (interactive (list (or current-prefix-arg 'toggle)))
1396 (let ((enable (if (eq arg 'toggle)
1397                   (not foo-mode) ; @r{this mode's mode variable}
1398                 (> (prefix-numeric-value arg) 0))))
1399   (if enable
1400       @var{do-enable}
1401     @var{do-disable}))
1402 @end example
1404 The reason for this somewhat complex behavior is that it lets users
1405 easily toggle the minor mode interactively, and also lets the minor mode
1406 be easily enabled in a mode hook, like this:
1408 @example
1409 (add-hook 'text-mode-hook 'foo-mode)
1410 @end example
1412 @noindent
1413 This behaves correctly whether or not @code{foo-mode} was already
1414 enabled, since the @code{foo-mode} mode command unconditionally enables
1415 the minor mode when it is called from Lisp with no argument.  Disabling
1416 a minor mode in a mode hook is a little uglier:
1418 @example
1419 (add-hook 'text-mode-hook (lambda () (foo-mode -1)))
1420 @end example
1422 @noindent
1423 However, this is not very commonly done.
1425 @item
1426 Add an element to @code{minor-mode-alist} for each minor mode
1427 (@pxref{Definition of minor-mode-alist}), if you want to indicate the
1428 minor mode in the mode line.  This element should be a list of the
1429 following form:
1431 @smallexample
1432 (@var{mode-variable} @var{string})
1433 @end smallexample
1435 Here @var{mode-variable} is the variable that controls enabling of the
1436 minor mode, and @var{string} is a short string, starting with a space,
1437 to represent the mode in the mode line.  These strings must be short so
1438 that there is room for several of them at once.
1440 When you add an element to @code{minor-mode-alist}, use @code{assq} to
1441 check for an existing element, to avoid duplication.  For example:
1443 @smallexample
1444 @group
1445 (unless (assq 'leif-mode minor-mode-alist)
1446   (push '(leif-mode " Leif") minor-mode-alist))
1447 @end group
1448 @end smallexample
1450 @noindent
1451 or like this, using @code{add-to-list} (@pxref{List Variables}):
1453 @smallexample
1454 @group
1455 (add-to-list 'minor-mode-alist '(leif-mode " Leif"))
1456 @end group
1457 @end smallexample
1458 @end itemize
1460   In addition, several major mode conventions apply to minor modes as
1461 well: those regarding the names of global symbols, the use of a hook at
1462 the end of the initialization function, and the use of keymaps and other
1463 tables.
1465   The minor mode should, if possible, support enabling and disabling via
1466 Custom (@pxref{Customization}).  To do this, the mode variable should be
1467 defined with @code{defcustom}, usually with @code{:type 'boolean}.  If
1468 just setting the variable is not sufficient to enable the mode, you
1469 should also specify a @code{:set} method which enables the mode by
1470 invoking the mode command.  Note in the variable's documentation string
1471 that setting the variable other than via Custom may not take effect.
1472 Also, mark the definition with an autoload cookie (@pxref{autoload
1473 cookie}), and specify a @code{:require} so that customizing the variable
1474 will load the library that defines the mode.  For example:
1476 @smallexample
1477 @group
1478 ;;;###autoload
1479 (defcustom msb-mode nil
1480   "Toggle msb-mode.
1481 Setting this variable directly does not take effect;
1482 use either \\[customize] or the function `msb-mode'."
1483   :set 'custom-set-minor-mode
1484   :initialize 'custom-initialize-default
1485   :version "20.4"
1486   :type    'boolean
1487   :group   'msb
1488   :require 'msb)
1489 @end group
1490 @end smallexample
1492 @node Keymaps and Minor Modes
1493 @subsection Keymaps and Minor Modes
1495   Each minor mode can have its own keymap, which is active when the mode
1496 is enabled.  To set up a keymap for a minor mode, add an element to the
1497 alist @code{minor-mode-map-alist}.  @xref{Definition of minor-mode-map-alist}.
1499 @cindex @code{self-insert-command}, minor modes
1500   One use of minor mode keymaps is to modify the behavior of certain
1501 self-inserting characters so that they do something else as well as
1502 self-insert.  (Another way to customize @code{self-insert-command} is
1503 through @code{post-self-insert-hook}.  Apart from this, the facilities
1504 for customizing @code{self-insert-command} are limited to special cases,
1505 designed for abbrevs and Auto Fill mode.  Do not try substituting your
1506 own definition of @code{self-insert-command} for the standard one.  The
1507 editor command loop handles this function specially.)
1509 The key sequences bound in a minor mode should consist of @kbd{C-c}
1510 followed by one of @kbd{.,/?`'"[]\|~!#$%^&*()-_+=}.  (The other
1511 punctuation characters are reserved for major modes.)
1513 @node Defining Minor Modes
1514 @subsection Defining Minor Modes
1516   The macro @code{define-minor-mode} offers a convenient way of
1517 implementing a mode in one self-contained definition.
1519 @defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args@dots{} body@dots{}
1520 This macro defines a new minor mode whose name is @var{mode} (a
1521 symbol).  It defines a command named @var{mode} to toggle the minor
1522 mode, with @var{doc} as its documentation string.
1524 The toggle command takes one optional (prefix) argument.
1525 If called interactively with no argument it toggles the mode on or off.
1526 A positive prefix argument enables the mode, any other prefix argument
1527 disables it.  From Lisp, an argument of @code{toggle} toggles the mode,
1528 whereas an omitted or @code{nil} argument enables the mode.
1529 This makes it easy to enable the minor mode in a major mode hook, for example.
1530 If @var{doc} is nil, the macro supplies a default documentation string
1531 explaining the above.
1533 By default, it also defines a variable named @var{mode}, which is set to
1534 @code{t} or @code{nil} by enabling or disabling the mode.  The variable
1535 is initialized to @var{init-value}.  Except in unusual circumstances
1536 (see below), this value must be @code{nil}.
1538 The string @var{lighter} says what to display in the mode line
1539 when the mode is enabled; if it is @code{nil}, the mode is not displayed
1540 in the mode line.
1542 The optional argument @var{keymap} specifies the keymap for the minor
1543 mode.  If non-@code{nil}, it should be a variable name (whose value is
1544 a keymap), a keymap, or an alist of the form
1546 @example
1547 (@var{key-sequence} . @var{definition})
1548 @end example
1550 @noindent
1551 where each @var{key-sequence} and @var{definition} are arguments
1552 suitable for passing to @code{define-key} (@pxref{Changing Key
1553 Bindings}).  If @var{keymap} is a keymap or an alist, this also
1554 defines the variable @code{@var{mode}-map}.
1556 The above three arguments @var{init-value}, @var{lighter}, and
1557 @var{keymap} can be (partially) omitted when @var{keyword-args} are
1558 used.  The @var{keyword-args} consist of keywords followed by
1559 corresponding values.  A few keywords have special meanings:
1561 @table @code
1562 @item :group @var{group}
1563 Custom group name to use in all generated @code{defcustom} forms.
1564 Defaults to @var{mode} without the possible trailing @samp{-mode}.
1565 @strong{Warning:} don't use this default group name unless you have
1566 written a @code{defgroup} to define that group properly.  @xref{Group
1567 Definitions}.
1569 @item :global @var{global}
1570 If non-@code{nil}, this specifies that the minor mode should be global
1571 rather than buffer-local.  It defaults to @code{nil}.
1573 One of the effects of making a minor mode global is that the
1574 @var{mode} variable becomes a customization variable.  Toggling it
1575 through the Customize interface turns the mode on and off, and its
1576 value can be saved for future Emacs sessions (@pxref{Saving
1577 Customizations,,, emacs, The GNU Emacs Manual}.  For the saved
1578 variable to work, you should ensure that the @code{define-minor-mode}
1579 form is evaluated each time Emacs starts; for packages that are not
1580 part of Emacs, the easiest way to do this is to specify a
1581 @code{:require} keyword.
1583 @item :init-value @var{init-value}
1584 This is equivalent to specifying @var{init-value} positionally.
1586 @item :lighter @var{lighter}
1587 This is equivalent to specifying @var{lighter} positionally.
1589 @item :keymap @var{keymap}
1590 This is equivalent to specifying @var{keymap} positionally.
1592 @item :variable @var{place}
1593 This replaces the default variable @var{mode}, used to store the state
1594 of the mode.  If you specify this, the @var{mode} variable is not
1595 defined, and any @var{init-value} argument is unused.  @var{place}
1596 can be a different named variable (which you must define yourself), or
1597 anything that can be used with the @code{setf} function
1598 (@pxref{Generalized Variables}).
1599 @var{place} can also be a cons @code{(@var{get} . @var{set})},
1600 where @var{get} is an expression that returns the current state,
1601 and @var{set} is a function of one argument (a state) that sets it.
1603 @item :after-hook @var{after-hook}
1604 This defines a single Lisp form which is evaluated after the mode hooks
1605 have run.  It should not be quoted.
1606 @end table
1608 Any other keyword arguments are passed directly to the
1609 @code{defcustom} generated for the variable @var{mode}.
1611 The command named @var{mode} first performs the standard actions such as
1612 setting the variable named @var{mode} and then executes the @var{body}
1613 forms, if any.  It then runs the mode hook variable
1614 @code{@var{mode}-hook} and finishes by evaluating any form in
1615 @code{:after-hook}.
1616 @end defmac
1618   The initial value must be @code{nil} except in cases where (1) the
1619 mode is preloaded in Emacs, or (2) it is painless for loading to
1620 enable the mode even though the user did not request it.  For
1621 instance, if the mode has no effect unless something else is enabled,
1622 and will always be loaded by that time, enabling it by default is
1623 harmless.  But these are unusual circumstances.  Normally, the
1624 initial value must be @code{nil}.
1626 @findex easy-mmode-define-minor-mode
1627   The name @code{easy-mmode-define-minor-mode} is an alias
1628 for this macro.
1630   Here is an example of using @code{define-minor-mode}:
1632 @smallexample
1633 (define-minor-mode hungry-mode
1634   "Toggle Hungry mode.
1635 Interactively with no argument, this command toggles the mode.
1636 A positive prefix argument enables the mode, any other prefix
1637 argument disables it.  From Lisp, argument omitted or nil enables
1638 the mode, `toggle' toggles the state.
1640 When Hungry mode is enabled, the control delete key
1641 gobbles all preceding whitespace except the last.
1642 See the command \\[hungry-electric-delete]."
1643  ;; The initial value.
1644  nil
1645  ;; The indicator for the mode line.
1646  " Hungry"
1647  ;; The minor mode bindings.
1648  '(([C-backspace] . hungry-electric-delete))
1649  :group 'hunger)
1650 @end smallexample
1652 @noindent
1653 This defines a minor mode named ``Hungry mode'', a command named
1654 @code{hungry-mode} to toggle it, a variable named @code{hungry-mode}
1655 which indicates whether the mode is enabled, and a variable named
1656 @code{hungry-mode-map} which holds the keymap that is active when the
1657 mode is enabled.  It initializes the keymap with a key binding for
1658 @kbd{C-@key{DEL}}.  It puts the variable @code{hungry-mode} into
1659 custom group @code{hunger}.  There are no @var{body} forms---many
1660 minor modes don't need any.
1662   Here's an equivalent way to write it:
1664 @smallexample
1665 (define-minor-mode hungry-mode
1666   "Toggle Hungry mode.
1667 ...rest of documentation as before..."
1668  ;; The initial value.
1669  :init-value nil
1670  ;; The indicator for the mode line.
1671  :lighter " Hungry"
1672  ;; The minor mode bindings.
1673  :keymap
1674  '(([C-backspace] . hungry-electric-delete)
1675    ([C-M-backspace]
1676     . (lambda ()
1677         (interactive)
1678         (hungry-electric-delete t))))
1679  :group 'hunger)
1680 @end smallexample
1682 @defmac define-globalized-minor-mode global-mode mode turn-on keyword-args@dots{}
1683 This defines a global toggle named @var{global-mode} whose meaning is
1684 to enable or disable the buffer-local minor mode @var{mode} in all
1685 buffers.  To turn on the minor mode in a buffer, it uses the function
1686 @var{turn-on}; to turn off the minor mode, it calls @code{mode} with
1687 @minus{}1 as argument.
1689 Globally enabling the mode also affects buffers subsequently created
1690 by visiting files, and buffers that use a major mode other than
1691 Fundamental mode; but it does not detect the creation of a new buffer
1692 in Fundamental mode.
1694 This defines the customization option @var{global-mode} (@pxref{Customization}),
1695 which can be toggled in the Customize interface to turn the minor mode on
1696 and off.  As with @code{define-minor-mode}, you should ensure that the
1697 @code{define-globalized-minor-mode} form is evaluated each time Emacs
1698 starts, for example by providing a @code{:require} keyword.
1700 Use @code{:group @var{group}} in @var{keyword-args} to specify the
1701 custom group for the mode variable of the global minor mode.
1703 Generally speaking, when you define a globalized minor mode, you should
1704 also define a non-globalized version, so that people can use (or
1705 disable) it in individual buffers.  This also allows them to disable a
1706 globally enabled minor mode in a specific major mode, by using that
1707 mode's hook.
1708 @end defmac
1711 @node Mode Line Format
1712 @section Mode Line Format
1713 @cindex mode line
1715   Each Emacs window (aside from minibuffer windows) typically has a mode
1716 line at the bottom, which displays status information about the buffer
1717 displayed in the window.  The mode line contains information about the
1718 buffer, such as its name, associated file, depth of recursive editing,
1719 and major and minor modes.  A window can also have a @dfn{header
1720 line}, which is much like the mode line but appears at the top of the
1721 window.
1723   This section describes how to control the contents of the mode line
1724 and header line.  We include it in this chapter because much of the
1725 information displayed in the mode line relates to the enabled major and
1726 minor modes.
1728 @menu
1729 * Base: Mode Line Basics.       Basic ideas of mode line control.
1730 * Data: Mode Line Data.         The data structure that controls the mode line.
1731 * Top: Mode Line Top.           The top level variable, mode-line-format.
1732 * Mode Line Variables::         Variables used in that data structure.
1733 * %-Constructs::                Putting information into a mode line.
1734 * Properties in Mode::          Using text properties in the mode line.
1735 * Header Lines::                Like a mode line, but at the top.
1736 * Emulating Mode Line::         Formatting text as the mode line would.
1737 @end menu
1739 @node Mode Line Basics
1740 @subsection Mode Line Basics
1742   The contents of each mode line are specified by the buffer-local
1743 variable @code{mode-line-format} (@pxref{Mode Line Top}).  This variable
1744 holds a @dfn{mode line construct}: a template that controls what is
1745 displayed on the buffer's mode line.  The value of
1746 @code{header-line-format} specifies the buffer's header line in the same
1747 way.  All windows for the same buffer use the same
1748 @code{mode-line-format} and @code{header-line-format}.
1750   For efficiency, Emacs does not continuously recompute each window's
1751 mode line and header line.  It does so when circumstances appear to call
1752 for it---for instance, if you change the window configuration, switch
1753 buffers, narrow or widen the buffer, scroll, or modify the buffer.  If
1754 you alter any of the variables referenced by @code{mode-line-format} or
1755 @code{header-line-format} (@pxref{Mode Line Variables}), or any other
1756 data structures that affect how text is displayed (@pxref{Display}), you
1757 should use the function @code{force-mode-line-update} to update the
1758 display.
1760 @defun force-mode-line-update &optional all
1761 This function forces Emacs to update the current buffer's mode line and
1762 header line, based on the latest values of all relevant variables,
1763 during its next redisplay cycle.  If the optional argument @var{all} is
1764 non-@code{nil}, it forces an update for all mode lines and header lines.
1766 This function also forces an update of the menu bar and frame title.
1767 @end defun
1769   The selected window's mode line is usually displayed in a different
1770 color using the face @code{mode-line}.  Other windows' mode lines appear
1771 in the face @code{mode-line-inactive} instead.  @xref{Faces}.
1773 @node Mode Line Data
1774 @subsection The Data Structure of the Mode Line
1775 @cindex mode line construct
1777   The mode line contents are controlled by a data structure called a
1778 @dfn{mode line construct}, made up of lists, strings, symbols, and
1779 numbers kept in buffer-local variables.  Each data type has a specific
1780 meaning for the mode line appearance, as described below.  The same data
1781 structure is used for constructing frame titles (@pxref{Frame Titles})
1782 and header lines (@pxref{Header Lines}).
1784   A mode line construct may be as simple as a fixed string of text,
1785 but it usually specifies how to combine fixed strings with variables'
1786 values to construct the text.  Many of these variables are themselves
1787 defined to have mode line constructs as their values.
1789   Here are the meanings of various data types as mode line constructs:
1791 @table @code
1792 @cindex percent symbol in mode line
1793 @item @var{string}
1794 A string as a mode line construct appears verbatim except for
1795 @dfn{@code{%}-constructs} in it.  These stand for substitution of
1796 other data; see @ref{%-Constructs}.
1798 If parts of the string have @code{face} properties, they control
1799 display of the text just as they would text in the buffer.  Any
1800 characters which have no @code{face} properties are displayed, by
1801 default, in the face @code{mode-line} or @code{mode-line-inactive}
1802 (@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}).  The
1803 @code{help-echo} and @code{keymap} properties in @var{string} have
1804 special meanings.  @xref{Properties in Mode}.
1806 @item @var{symbol}
1807 A symbol as a mode line construct stands for its value.  The value of
1808 @var{symbol} is used as a mode line construct, in place of @var{symbol}.
1809 However, the symbols @code{t} and @code{nil} are ignored, as is any
1810 symbol whose value is void.
1812 There is one exception: if the value of @var{symbol} is a string, it is
1813 displayed verbatim: the @code{%}-constructs are not recognized.
1815 Unless @var{symbol} is marked as ``risky'' (i.e., it has a
1816 non-@code{nil} @code{risky-local-variable} property), all text
1817 properties specified in @var{symbol}'s value are ignored.  This includes
1818 the text properties of strings in @var{symbol}'s value, as well as all
1819 @code{:eval} and @code{:propertize} forms in it.  (The reason for this
1820 is security: non-risky variables could be set automatically from file
1821 variables without prompting the user.)
1823 @item (@var{string} @var{rest}@dots{})
1824 @itemx (@var{list} @var{rest}@dots{})
1825 A list whose first element is a string or list means to process all the
1826 elements recursively and concatenate the results.  This is the most
1827 common form of mode line construct.
1829 @item (:eval @var{form})
1830 A list whose first element is the symbol @code{:eval} says to evaluate
1831 @var{form}, and use the result as a string to display.  Make sure this
1832 evaluation cannot load any files, as doing so could cause infinite
1833 recursion.
1835 @item (:propertize @var{elt} @var{props}@dots{})
1836 A list whose first element is the symbol @code{:propertize} says to
1837 process the mode line construct @var{elt} recursively, then add the text
1838 properties specified by @var{props} to the result.  The argument
1839 @var{props} should consist of zero or more pairs @var{text-property}
1840 @var{value}.
1842 @item (@var{symbol} @var{then} @var{else})
1843 A list whose first element is a symbol that is not a keyword specifies
1844 a conditional.  Its meaning depends on the value of @var{symbol}.  If
1845 @var{symbol} has a non-@code{nil} value, the second element,
1846 @var{then}, is processed recursively as a mode line construct.
1847 Otherwise, the third element, @var{else}, is processed recursively.
1848 You may omit @var{else}; then the mode line construct displays nothing
1849 if the value of @var{symbol} is @code{nil} or void.
1851 @item (@var{width} @var{rest}@dots{})
1852 A list whose first element is an integer specifies truncation or
1853 padding of the results of @var{rest}.  The remaining elements
1854 @var{rest} are processed recursively as mode line constructs and
1855 concatenated together.  When @var{width} is positive, the result is
1856 space filled on the right if its width is less than @var{width}.  When
1857 @var{width} is negative, the result is truncated on the right to
1858 @minus{}@var{width} columns if its width exceeds @minus{}@var{width}.
1860 For example, the usual way to show what percentage of a buffer is above
1861 the top of the window is to use a list like this: @code{(-3 "%p")}.
1862 @end table
1864 @node Mode Line Top
1865 @subsection The Top Level of Mode Line Control
1867   The variable in overall control of the mode line is
1868 @code{mode-line-format}.
1870 @defopt mode-line-format
1871 The value of this variable is a mode line construct that controls the
1872 contents of the mode-line.  It is always buffer-local in all buffers.
1874 If you set this variable to @code{nil} in a buffer, that buffer does not
1875 have a mode line.  (A window that is just one line tall also does not
1876 display a mode line.)
1877 @end defopt
1879   The default value of @code{mode-line-format} is designed to use the
1880 values of other variables such as @code{mode-line-position} and
1881 @code{mode-line-modes} (which in turn incorporates the values of the
1882 variables @code{mode-name} and @code{minor-mode-alist}).  Very few
1883 modes need to alter @code{mode-line-format} itself.  For most
1884 purposes, it is sufficient to alter some of the variables that
1885 @code{mode-line-format} either directly or indirectly refers to.
1887   If you do alter @code{mode-line-format} itself, the new value should
1888 use the same variables that appear in the default value (@pxref{Mode
1889 Line Variables}), rather than duplicating their contents or displaying
1890 the information in another fashion.  This way, customizations made by
1891 the user or by Lisp programs (such as @code{display-time} and major
1892 modes) via changes to those variables remain effective.
1894   Here is a hypothetical example of a @code{mode-line-format} that might
1895 be useful for Shell mode (in reality, Shell mode does not set
1896 @code{mode-line-format}):
1898 @example
1899 @group
1900 (setq mode-line-format
1901   (list "-"
1902    'mode-line-mule-info
1903    'mode-line-modified
1904    'mode-line-frame-identification
1905    "%b--"
1906 @end group
1907 @group
1908    ;; @r{Note that this is evaluated while making the list.}
1909    ;; @r{It makes a mode line construct which is just a string.}
1910    (getenv "HOST")
1911 @end group
1912    ":"
1913    'default-directory
1914    "   "
1915    'global-mode-string
1916    "   %[("
1917    '(:eval (mode-line-mode-name))
1918    'mode-line-process
1919    'minor-mode-alist
1920    "%n"
1921    ")%]--"
1922 @group
1923    '(which-func-mode ("" which-func-format "--"))
1924    '(line-number-mode "L%l--")
1925    '(column-number-mode "C%c--")
1926    '(-3 "%p")))
1927 @end group
1928 @end example
1930 @noindent
1931 (The variables @code{line-number-mode}, @code{column-number-mode}
1932 and @code{which-func-mode} enable particular minor modes; as usual,
1933 these variable names are also the minor mode command names.)
1935 @node Mode Line Variables
1936 @subsection Variables Used in the Mode Line
1938   This section describes variables incorporated by the standard value of
1939 @code{mode-line-format} into the text of the mode line.  There is
1940 nothing inherently special about these variables; any other variables
1941 could have the same effects on the mode line if the value of
1942 @code{mode-line-format} is changed to use them.  However, various parts
1943 of Emacs set these variables on the understanding that they will control
1944 parts of the mode line; therefore, practically speaking, it is essential
1945 for the mode line to use them.
1947 @defvar mode-line-mule-info
1948 This variable holds the value of the mode line construct that displays
1949 information about the language environment, buffer coding system, and
1950 current input method.  @xref{Non-ASCII Characters}.
1951 @end defvar
1953 @defvar mode-line-modified
1954 This variable holds the value of the mode line construct that displays
1955 whether the current buffer is modified.  Its default value displays
1956 @samp{**} if the buffer is modified, @samp{--} if the buffer is not
1957 modified, @samp{%%} if the buffer is read only, and @samp{%*} if the
1958 buffer is read only and modified.
1960 Changing this variable does not force an update of the mode line.
1961 @end defvar
1963 @defvar mode-line-frame-identification
1964 This variable identifies the current frame.  Its default value
1965 displays @code{" "} if you are using a window system which can show
1966 multiple frames, or @code{"-%F "} on an ordinary terminal which shows
1967 only one frame at a time.
1968 @end defvar
1970 @defvar mode-line-buffer-identification
1971 This variable identifies the buffer being displayed in the window.
1972 Its default value displays the buffer name, padded with spaces to at
1973 least 12 columns.
1974 @end defvar
1976 @defopt mode-line-position
1977 This variable indicates the position in the buffer.  Its default value
1978 displays the buffer percentage and, optionally, the buffer size, the
1979 line number and the column number.
1980 @end defopt
1982 @defvar vc-mode
1983 The variable @code{vc-mode}, buffer-local in each buffer, records
1984 whether the buffer's visited file is maintained with version control,
1985 and, if so, which kind.  Its value is a string that appears in the mode
1986 line, or @code{nil} for no version control.
1987 @end defvar
1989 @defopt mode-line-modes
1990 This variable displays the buffer's major and minor modes.  Its
1991 default value also displays the recursive editing level, information
1992 on the process status, and whether narrowing is in effect.
1993 @end defopt
1995 @defvar mode-line-remote
1996 This variable is used to show whether @code{default-directory} for the
1997 current buffer is remote.
1998 @end defvar
2000 @defvar mode-line-client
2001 This variable is used to identify @code{emacsclient} frames.
2002 @end defvar
2004   The following three variables are used in @code{mode-line-modes}:
2006 @defvar mode-name
2007 This buffer-local variable holds the ``pretty'' name of the current
2008 buffer's major mode.  Each major mode should set this variable so that
2009 the mode name will appear in the mode line.  The value does not have
2010 to be a string, but can use any of the data types valid in a mode-line
2011 construct (@pxref{Mode Line Data}).  To compute the string that will
2012 identify the mode name in the mode line, use @code{format-mode-line}
2013 (@pxref{Emulating Mode Line}).
2014 @end defvar
2016 @defvar mode-line-process
2017 This buffer-local variable contains the mode line information on process
2018 status in modes used for communicating with subprocesses.  It is
2019 displayed immediately following the major mode name, with no intervening
2020 space.  For example, its value in the @file{*shell*} buffer is
2021 @code{(":%s")}, which allows the shell to display its status along
2022 with the major mode as: @samp{(Shell:run)}.  Normally this variable
2023 is @code{nil}.
2024 @end defvar
2026 @defvar minor-mode-alist
2027 @anchor{Definition of minor-mode-alist}
2028 This variable holds an association list whose elements specify how the
2029 mode line should indicate that a minor mode is active.  Each element of
2030 the @code{minor-mode-alist} should be a two-element list:
2032 @example
2033 (@var{minor-mode-variable} @var{mode-line-string})
2034 @end example
2036 More generally, @var{mode-line-string} can be any mode line construct.
2037 It appears in the mode line when the value of @var{minor-mode-variable}
2038 is non-@code{nil}, and not otherwise.  These strings should begin with
2039 spaces so that they don't run together.  Conventionally, the
2040 @var{minor-mode-variable} for a specific mode is set to a non-@code{nil}
2041 value when that minor mode is activated.
2043 @code{minor-mode-alist} itself is not buffer-local.  Each variable
2044 mentioned in the alist should be buffer-local if its minor mode can be
2045 enabled separately in each buffer.
2046 @end defvar
2048 @defvar global-mode-string
2049 This variable holds a mode line construct that, by default, appears in
2050 the mode line just after the @code{which-func-mode} minor mode if set,
2051 else after @code{mode-line-modes}.  The command @code{display-time} sets
2052 @code{global-mode-string} to refer to the variable
2053 @code{display-time-string}, which holds a string containing the time and
2054 load information.
2056 The @samp{%M} construct substitutes the value of
2057 @code{global-mode-string}, but that is obsolete, since the variable is
2058 included in the mode line from @code{mode-line-format}.
2059 @end defvar
2061 Here is a simplified version of the default value of
2062 @code{mode-line-format}.  The real default value also
2063 specifies addition of text properties.
2065 @example
2066 @group
2067 ("-"
2068  mode-line-mule-info
2069  mode-line-modified
2070  mode-line-frame-identification
2071  mode-line-buffer-identification
2072 @end group
2073  "   "
2074  mode-line-position
2075  (vc-mode vc-mode)
2076  "   "
2077 @group
2078  mode-line-modes
2079  (which-func-mode ("" which-func-format "--"))
2080  (global-mode-string ("--" global-mode-string))
2081  "-%-")
2082 @end group
2083 @end example
2085 @node %-Constructs
2086 @subsection @code{%}-Constructs in the Mode Line
2088   Strings used as mode line constructs can use certain
2089 @code{%}-constructs to substitute various kinds of data.  The
2090 following is a list of the defined @code{%}-constructs, and what they
2091 mean.
2093   In any construct except @samp{%%}, you can add a decimal integer
2094 after the @samp{%} to specify a minimum field width.  If the width is
2095 less, the field is padded to that width.  Purely numeric constructs
2096 (@samp{c}, @samp{i}, @samp{I}, and @samp{l}) are padded by inserting
2097 spaces to the left, and others are padded by inserting spaces to the
2098 right.
2100 @table @code
2101 @item %b
2102 The current buffer name, obtained with the @code{buffer-name} function.
2103 @xref{Buffer Names}.
2105 @item %c
2106 The current column number of point.
2108 @item %e
2109 When Emacs is nearly out of memory for Lisp objects, a brief message
2110 saying so.  Otherwise, this is empty.
2112 @item %f
2113 The visited file name, obtained with the @code{buffer-file-name}
2114 function.  @xref{Buffer File Name}.
2116 @item %F
2117 The title (only on a window system) or the name of the selected frame.
2118 @xref{Basic Parameters}.
2120 @item %i
2121 The size of the accessible part of the current buffer; basically
2122 @code{(- (point-max) (point-min))}.
2124 @item %I
2125 Like @samp{%i}, but the size is printed in a more readable way by using
2126 @samp{k} for 10^3, @samp{M} for 10^6, @samp{G} for 10^9, etc., to
2127 abbreviate.
2129 @item %l
2130 The current line number of point, counting within the accessible portion
2131 of the buffer.
2133 @item %n
2134 @samp{Narrow} when narrowing is in effect; nothing otherwise (see
2135 @code{narrow-to-region} in @ref{Narrowing}).
2137 @item %p
2138 The percentage of the buffer text above the @strong{top} of window, or
2139 @samp{Top}, @samp{Bottom} or @samp{All}.  Note that the default mode
2140 line construct truncates this to three characters.
2142 @item %P
2143 The percentage of the buffer text that is above the @strong{bottom} of
2144 the window (which includes the text visible in the window, as well as
2145 the text above the top), plus @samp{Top} if the top of the buffer is
2146 visible on screen; or @samp{Bottom} or @samp{All}.
2148 @item %s
2149 The status of the subprocess belonging to the current buffer, obtained with
2150 @code{process-status}.  @xref{Process Information}.
2152 @item %z
2153 The mnemonics of keyboard, terminal, and buffer coding systems.
2155 @item %Z
2156 Like @samp{%z}, but including the end-of-line format.
2158 @item %*
2159 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
2160 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
2161 @samp{-} otherwise.  @xref{Buffer Modification}.
2163 @item %+
2164 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
2165 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
2166 @samp{-} otherwise.  This differs from @samp{%*} only for a modified
2167 read-only buffer.  @xref{Buffer Modification}.
2169 @item %&
2170 @samp{*} if the buffer is modified, and @samp{-} otherwise.
2172 @item %[
2173 An indication of the depth of recursive editing levels (not counting
2174 minibuffer levels): one @samp{[} for each editing level.
2175 @xref{Recursive Editing}.
2177 @item %]
2178 One @samp{]} for each recursive editing level (not counting minibuffer
2179 levels).
2181 @item %-
2182 Dashes sufficient to fill the remainder of the mode line.
2184 @item %%
2185 The character @samp{%}---this is how to include a literal @samp{%} in a
2186 string in which @code{%}-constructs are allowed.
2187 @end table
2189 The following two @code{%}-constructs are still supported, but they are
2190 obsolete, since you can get the same results with the variables
2191 @code{mode-name} and @code{global-mode-string}.
2193 @table @code
2194 @item %m
2195 The value of @code{mode-name}.
2197 @item %M
2198 The value of @code{global-mode-string}.
2199 @end table
2201 @node Properties in Mode
2202 @subsection Properties in the Mode Line
2203 @cindex text properties in the mode line
2205   Certain text properties are meaningful in the
2206 mode line.  The @code{face} property affects the appearance of text; the
2207 @code{help-echo} property associates help strings with the text, and
2208 @code{keymap} can make the text mouse-sensitive.
2210   There are four ways to specify text properties for text in the mode
2211 line:
2213 @enumerate
2214 @item
2215 Put a string with a text property directly into the mode line data
2216 structure.
2218 @item
2219 Put a text property on a mode line %-construct such as @samp{%12b}; then
2220 the expansion of the %-construct will have that same text property.
2222 @item
2223 Use a @code{(:propertize @var{elt} @var{props}@dots{})} construct to
2224 give @var{elt} a text property specified by @var{props}.
2226 @item
2227 Use a list containing @code{:eval @var{form}} in the mode line data
2228 structure, and make @var{form} evaluate to a string that has a text
2229 property.
2230 @end enumerate
2232   You can use the @code{keymap} property to specify a keymap.  This
2233 keymap only takes real effect for mouse clicks; binding character keys
2234 and function keys to it has no effect, since it is impossible to move
2235 point into the mode line.
2237   When the mode line refers to a variable which does not have a
2238 non-@code{nil} @code{risky-local-variable} property, any text
2239 properties given or specified within that variable's values are
2240 ignored.  This is because such properties could otherwise specify
2241 functions to be called, and those functions could come from file
2242 local variables.
2244 @node Header Lines
2245 @subsection Window Header Lines
2246 @cindex header line (of a window)
2247 @cindex window header line
2249   A window can have a @dfn{header line} at the top, just as it can have
2250 a mode line at the bottom.  The header line feature works just like the
2251 mode line feature, except that it's controlled by
2252 @code{header-line-format}:
2254 @defvar header-line-format
2255 This variable, local in every buffer, specifies how to display the
2256 header line, for windows displaying the buffer.  The format of the value
2257 is the same as for @code{mode-line-format} (@pxref{Mode Line Data}).
2258 It is normally @code{nil}, so that ordinary buffers have no header line.
2259 @end defvar
2261   A window that is just one line tall never displays a header line.  A
2262 window that is two lines tall cannot display both a mode line and a
2263 header line at once; if it has a mode line, then it does not display a
2264 header line.
2266 @node Emulating Mode Line
2267 @subsection Emulating Mode Line Formatting
2269   You can use the function @code{format-mode-line} to compute the text
2270 that would appear in a mode line or header line based on a certain
2271 mode line construct.
2273 @defun format-mode-line format &optional face window buffer
2274 This function formats a line of text according to @var{format} as if it
2275 were generating the mode line for @var{window}, but it also returns the
2276 text as a string.  The argument @var{window} defaults to the selected
2277 window.  If @var{buffer} is non-@code{nil}, all the information used is
2278 taken from @var{buffer}; by default, it comes from @var{window}'s
2279 buffer.
2281 The value string normally has text properties that correspond to the
2282 faces, keymaps, etc., that the mode line would have.  Any character for
2283 which no @code{face} property is specified by @var{format} gets a
2284 default value determined by @var{face}.  If @var{face} is @code{t}, that
2285 stands for either @code{mode-line} if @var{window} is selected,
2286 otherwise @code{mode-line-inactive}.  If @var{face} is @code{nil} or
2287 omitted, that stands for the default face.  If @var{face} is an integer,
2288 the value returned by this function will have no text properties.
2290 You can also specify other valid faces as the value of @var{face}.
2291 If specified, that face provides the @code{face} property for characters
2292 whose face is not specified by @var{format}.
2294 Note that using @code{mode-line}, @code{mode-line-inactive}, or
2295 @code{header-line} as @var{face} will actually redisplay the mode line
2296 or the header line, respectively, using the current definitions of the
2297 corresponding face, in addition to returning the formatted string.
2298 (Other faces do not cause redisplay.)
2300 For example, @code{(format-mode-line header-line-format)} returns the
2301 text that would appear in the selected window's header line (@code{""}
2302 if it has no header line).  @code{(format-mode-line header-line-format
2303 'header-line)} returns the same text, with each character
2304 carrying the face that it will have in the header line itself, and also
2305 redraws the header line.
2306 @end defun
2308 @node Imenu
2309 @section Imenu
2311 @cindex Imenu
2312   @dfn{Imenu} is a feature that lets users select a definition or
2313 section in the buffer, from a menu which lists all of them, to go
2314 directly to that location in the buffer.  Imenu works by constructing
2315 a buffer index which lists the names and buffer positions of the
2316 definitions, or other named portions of the buffer; then the user can
2317 choose one of them and move point to it.  Major modes can add a menu
2318 bar item to use Imenu using @code{imenu-add-to-menubar}.
2320 @deffn Command imenu-add-to-menubar name
2321 This function defines a local menu bar item named @var{name}
2322 to run Imenu.
2323 @end deffn
2325   The user-level commands for using Imenu are described in the Emacs
2326 Manual (@pxref{Imenu,, Imenu, emacs, the Emacs Manual}).  This section
2327 explains how to customize Imenu's method of finding definitions or
2328 buffer portions for a particular major mode.
2330   The usual and simplest way is to set the variable
2331 @code{imenu-generic-expression}:
2333 @defvar imenu-generic-expression
2334 This variable, if non-@code{nil}, is a list that specifies regular
2335 expressions for finding definitions for Imenu.  Simple elements of
2336 @code{imenu-generic-expression} look like this:
2338 @example
2339 (@var{menu-title} @var{regexp} @var{index})
2340 @end example
2342 Here, if @var{menu-title} is non-@code{nil}, it says that the matches
2343 for this element should go in a submenu of the buffer index;
2344 @var{menu-title} itself specifies the name for the submenu.  If
2345 @var{menu-title} is @code{nil}, the matches for this element go directly
2346 in the top level of the buffer index.
2348 The second item in the list, @var{regexp}, is a regular expression
2349 (@pxref{Regular Expressions}); anything in the buffer that it matches
2350 is considered a definition, something to mention in the buffer index.
2351 The third item, @var{index}, is a non-negative integer that indicates
2352 which subexpression in @var{regexp} matches the definition's name.
2354 An element can also look like this:
2356 @example
2357 (@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{})
2358 @end example
2360 Each match for this element creates an index item, and when the index
2361 item is selected by the user, it calls @var{function} with arguments
2362 consisting of the item name, the buffer position, and @var{arguments}.
2364 For Emacs Lisp mode, @code{imenu-generic-expression} could look like
2365 this:
2367 @c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]
2368 @example
2369 @group
2370 ((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
2371 \\s-+\\([-A-Za-z0-9+]+\\)" 2)
2372 @end group
2373 @group
2374  ("*Vars*" "^\\s-*(def\\(var\\|const\\)\
2375 \\s-+\\([-A-Za-z0-9+]+\\)" 2)
2376 @end group
2377 @group
2378  ("*Types*"
2379   "^\\s-*\
2380 (def\\(type\\|struct\\|class\\|ine-condition\\)\
2381 \\s-+\\([-A-Za-z0-9+]+\\)" 2))
2382 @end group
2383 @end example
2385 Setting this variable makes it buffer-local in the current buffer.
2386 @end defvar
2388 @defvar imenu-case-fold-search
2389 This variable controls whether matching against the regular
2390 expressions in the value of @code{imenu-generic-expression} is
2391 case-sensitive: @code{t}, the default, means matching should ignore
2392 case.
2394 Setting this variable makes it buffer-local in the current buffer.
2395 @end defvar
2397 @defvar imenu-syntax-alist
2398 This variable is an alist of syntax table modifiers to use while
2399 processing @code{imenu-generic-expression}, to override the syntax table
2400 of the current buffer.  Each element should have this form:
2402 @example
2403 (@var{characters} . @var{syntax-description})
2404 @end example
2406 The @sc{car}, @var{characters}, can be either a character or a string.
2407 The element says to give that character or characters the syntax
2408 specified by @var{syntax-description}, which is passed to
2409 @code{modify-syntax-entry} (@pxref{Syntax Table Functions}).
2411 This feature is typically used to give word syntax to characters which
2412 normally have symbol syntax, and thus to simplify
2413 @code{imenu-generic-expression} and speed up matching.
2414 For example, Fortran mode uses it this way:
2416 @example
2417 (setq imenu-syntax-alist '(("_$" . "w")))
2418 @end example
2420 The @code{imenu-generic-expression} regular expressions can then use
2421 @samp{\\sw+} instead of @samp{\\(\\sw\\|\\s_\\)+}.  Note that this
2422 technique may be inconvenient when the mode needs to limit the initial
2423 character of a name to a smaller set of characters than are allowed in
2424 the rest of a name.
2426 Setting this variable makes it buffer-local in the current buffer.
2427 @end defvar
2429   Another way to customize Imenu for a major mode is to set the
2430 variables @code{imenu-prev-index-position-function} and
2431 @code{imenu-extract-index-name-function}:
2433 @defvar imenu-prev-index-position-function
2434 If this variable is non-@code{nil}, its value should be a function that
2435 finds the next ``definition'' to put in the buffer index, scanning
2436 backward in the buffer from point.  It should return @code{nil} if it
2437 doesn't find another ``definition'' before point.  Otherwise it should
2438 leave point at the place it finds a ``definition'' and return any
2439 non-@code{nil} value.
2441 Setting this variable makes it buffer-local in the current buffer.
2442 @end defvar
2444 @defvar imenu-extract-index-name-function
2445 If this variable is non-@code{nil}, its value should be a function to
2446 return the name for a definition, assuming point is in that definition
2447 as the @code{imenu-prev-index-position-function} function would leave
2450 Setting this variable makes it buffer-local in the current buffer.
2451 @end defvar
2453   The last way to customize Imenu for a major mode is to set the
2454 variable @code{imenu-create-index-function}:
2456 @defvar imenu-create-index-function
2457 This variable specifies the function to use for creating a buffer
2458 index.  The function should take no arguments, and return an index
2459 alist for the current buffer.  It is called within
2460 @code{save-excursion}, so where it leaves point makes no difference.
2462 The index alist can have three types of elements.  Simple elements
2463 look like this:
2465 @example
2466 (@var{index-name} . @var{index-position})
2467 @end example
2469 Selecting a simple element has the effect of moving to position
2470 @var{index-position} in the buffer.  Special elements look like this:
2472 @example
2473 (@var{index-name} @var{index-position} @var{function} @var{arguments}@dots{})
2474 @end example
2476 Selecting a special element performs:
2478 @example
2479 (funcall @var{function}
2480          @var{index-name} @var{index-position} @var{arguments}@dots{})
2481 @end example
2483 A nested sub-alist element looks like this:
2485 @example
2486 (@var{menu-title} @var{sub-alist})
2487 @end example
2489 It creates the submenu @var{menu-title} specified by @var{sub-alist}.
2491 The default value of @code{imenu-create-index-function} is
2492 @code{imenu-default-create-index-function}.  This function calls the
2493 value of @code{imenu-prev-index-position-function} and the value of
2494 @code{imenu-extract-index-name-function} to produce the index alist.
2495 However, if either of these two variables is @code{nil}, the default
2496 function uses @code{imenu-generic-expression} instead.
2498 Setting this variable makes it buffer-local in the current buffer.
2499 @end defvar
2501 @node Font Lock Mode
2502 @section Font Lock Mode
2503 @cindex Font Lock mode
2505   @dfn{Font Lock mode} is a buffer-local minor mode that automatically
2506 attaches @code{face} properties to certain parts of the buffer based on
2507 their syntactic role.  How it parses the buffer depends on the major
2508 mode; most major modes define syntactic criteria for which faces to use
2509 in which contexts.  This section explains how to customize Font Lock for
2510 a particular major mode.
2512   Font Lock mode finds text to highlight in two ways: through
2513 syntactic parsing based on the syntax table, and through searching
2514 (usually for regular expressions).  Syntactic fontification happens
2515 first; it finds comments and string constants and highlights them.
2516 Search-based fontification happens second.
2518 @menu
2519 * Font Lock Basics::            Overview of customizing Font Lock.
2520 * Search-based Fontification::  Fontification based on regexps.
2521 * Customizing Keywords::        Customizing search-based fontification.
2522 * Other Font Lock Variables::   Additional customization facilities.
2523 * Levels of Font Lock::         Each mode can define alternative levels
2524                                   so that the user can select more or less.
2525 * Precalculated Fontification::  How Lisp programs that produce the buffer
2526                                   contents can also specify how to fontify it.
2527 * Faces for Font Lock::         Special faces specifically for Font Lock.
2528 * Syntactic Font Lock::         Fontification based on syntax tables.
2529 * Multiline Font Lock::         How to coerce Font Lock into properly
2530                                   highlighting multiline constructs.
2531 @end menu
2533 @node Font Lock Basics
2534 @subsection Font Lock Basics
2536   There are several variables that control how Font Lock mode highlights
2537 text.  But major modes should not set any of these variables directly.
2538 Instead, they should set @code{font-lock-defaults} as a buffer-local
2539 variable.  The value assigned to this variable is used, if and when Font
2540 Lock mode is enabled, to set all the other variables.
2542 @defvar font-lock-defaults
2543 This variable is set by major modes to specify how to fontify text in
2544 that mode.  It automatically becomes buffer-local when set.  If its
2545 value is @code{nil}, Font Lock mode does no highlighting, and you can
2546 use the @samp{Faces} menu (under @samp{Edit} and then @samp{Text
2547 Properties} in the menu bar) to assign faces explicitly to text in the
2548 buffer.
2550 If non-@code{nil}, the value should look like this:
2552 @example
2553 (@var{keywords} [@var{keywords-only} [@var{case-fold}
2554  [@var{syntax-alist} [@var{syntax-begin} @var{other-vars}@dots{}]]]])
2555 @end example
2557 The first element, @var{keywords}, indirectly specifies the value of
2558 @code{font-lock-keywords} which directs search-based fontification.
2559 It can be a symbol, a variable or a function whose value is the list
2560 to use for @code{font-lock-keywords}.  It can also be a list of
2561 several such symbols, one for each possible level of fontification.
2562 The first symbol specifies the @samp{mode default} level of
2563 fontification, the next symbol level 1 fontification, the next level 2,
2564 and so on.  The @samp{mode default} level is normally the same as level
2565 1.  It is used when @code{font-lock-maximum-decoration} has a @code{nil}
2566 value.  @xref{Levels of Font Lock}.
2568 The second element, @var{keywords-only}, specifies the value of the
2569 variable @code{font-lock-keywords-only}.  If this is omitted or
2570 @code{nil}, syntactic fontification (of strings and comments) is also
2571 performed.  If this is non-@code{nil}, syntactic fontification is not
2572 performed.  @xref{Syntactic Font Lock}.
2574 The third element, @var{case-fold}, specifies the value of
2575 @code{font-lock-keywords-case-fold-search}.  If it is non-@code{nil},
2576 Font Lock mode ignores case during search-based fontification.
2578 If the fourth element, @var{syntax-alist}, is non-@code{nil}, it should
2579 be a list of cons cells of the form @code{(@var{char-or-string}
2580 . @var{string})}.  These are used to set up a syntax table for syntactic
2581 fontification; the resulting syntax table is stored in
2582 @code{font-lock-syntax-table}.  If @var{syntax-alist} is omitted or
2583 @code{nil}, syntactic fontification uses the syntax table returned by
2584 the @code{syntax-table} function.  @xref{Syntax Table Functions}.
2586 The fifth element, @var{syntax-begin}, specifies the value of
2587 @code{font-lock-beginning-of-syntax-function}.  We recommend setting
2588 this variable to @code{nil} and using @code{syntax-begin-function}
2589 instead.
2591 All the remaining elements (if any) are collectively called
2592 @var{other-vars}.  Each of these elements should have the form
2593 @code{(@var{variable} . @var{value})}---which means, make
2594 @var{variable} buffer-local and then set it to @var{value}.  You can
2595 use these @var{other-vars} to set other variables that affect
2596 fontification, aside from those you can control with the first five
2597 elements.  @xref{Other Font Lock Variables}.
2598 @end defvar
2600   If your mode fontifies text explicitly by adding
2601 @code{font-lock-face} properties, it can specify @code{(nil t)} for
2602 @code{font-lock-defaults} to turn off all automatic fontification.
2603 However, this is not required; it is possible to fontify some things
2604 using @code{font-lock-face} properties and set up automatic
2605 fontification for other parts of the text.
2607 @node Search-based Fontification
2608 @subsection Search-based Fontification
2610   The variable which directly controls search-based fontification is
2611 @code{font-lock-keywords}, which is typically specified via the
2612 @var{keywords} element in @code{font-lock-defaults}.
2614 @defvar font-lock-keywords
2615 The value of this variable is a list of the keywords to highlight.  Lisp
2616 programs should not set this variable directly.  Normally, the value is
2617 automatically set by Font Lock mode, using the @var{keywords} element in
2618 @code{font-lock-defaults}.  The value can also be altered using the
2619 functions @code{font-lock-add-keywords} and
2620 @code{font-lock-remove-keywords} (@pxref{Customizing Keywords}).
2621 @end defvar
2623   Each element of @code{font-lock-keywords} specifies how to find
2624 certain cases of text, and how to highlight those cases.  Font Lock mode
2625 processes the elements of @code{font-lock-keywords} one by one, and for
2626 each element, it finds and handles all matches.  Ordinarily, once
2627 part of the text has been fontified already, this cannot be overridden
2628 by a subsequent match in the same text; but you can specify different
2629 behavior using the @var{override} element of a @var{subexp-highlighter}.
2631   Each element of @code{font-lock-keywords} should have one of these
2632 forms:
2634 @table @code
2635 @item @var{regexp}
2636 Highlight all matches for @var{regexp} using
2637 @code{font-lock-keyword-face}.  For example,
2639 @example
2640 ;; @r{Highlight occurrences of the word @samp{foo}}
2641 ;; @r{using @code{font-lock-keyword-face}.}
2642 "\\<foo\\>"
2643 @end example
2645 Be careful when composing these regular expressions; a poorly written
2646 pattern can dramatically slow things down!  The function
2647 @code{regexp-opt} (@pxref{Regexp Functions}) is useful for calculating
2648 optimal regular expressions to match several keywords.
2650 @item @var{function}
2651 Find text by calling @var{function}, and highlight the matches
2652 it finds using @code{font-lock-keyword-face}.
2654 When @var{function} is called, it receives one argument, the limit of
2655 the search; it should begin searching at point, and not search beyond the
2656 limit.  It should return non-@code{nil} if it succeeds, and set the
2657 match data to describe the match that was found.  Returning @code{nil}
2658 indicates failure of the search.
2660 Fontification will call @var{function} repeatedly with the same limit,
2661 and with point where the previous invocation left it, until
2662 @var{function} fails.  On failure, @var{function} need not reset point
2663 in any particular way.
2665 @item (@var{matcher} . @var{subexp})
2666 In this kind of element, @var{matcher} is either a regular
2667 expression or a function, as described above.  The @sc{cdr},
2668 @var{subexp}, specifies which subexpression of @var{matcher} should be
2669 highlighted (instead of the entire text that @var{matcher} matched).
2671 @example
2672 ;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},}
2673 ;; @r{using @code{font-lock-keyword-face}.}
2674 ("fu\\(bar\\)" . 1)
2675 @end example
2677 If you use @code{regexp-opt} to produce the regular expression
2678 @var{matcher}, you can use @code{regexp-opt-depth} (@pxref{Regexp
2679 Functions}) to calculate the value for @var{subexp}.
2681 @item (@var{matcher} . @var{facespec})
2682 In this kind of element, @var{facespec} is an expression whose value
2683 specifies the face to use for highlighting.  In the simplest case,
2684 @var{facespec} is a Lisp variable (a symbol) whose value is a face
2685 name.
2687 @example
2688 ;; @r{Highlight occurrences of @samp{fubar},}
2689 ;; @r{using the face which is the value of @code{fubar-face}.}
2690 ("fubar" . fubar-face)
2691 @end example
2693 However, @var{facespec} can also evaluate to a list of this form:
2695 @example
2696 (face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{})
2697 @end example
2699 @noindent
2700 to specify the face @var{face} and various additional text properties
2701 to put on the text that matches.  If you do this, be sure to add the
2702 other text property names that you set in this way to the value of
2703 @code{font-lock-extra-managed-props} so that the properties will also
2704 be cleared out when they are no longer appropriate.  Alternatively,
2705 you can set the variable @code{font-lock-unfontify-region-function} to
2706 a function that clears these properties.  @xref{Other Font Lock
2707 Variables}.
2709 @item (@var{matcher} . @var{subexp-highlighter})
2710 In this kind of element, @var{subexp-highlighter} is a list
2711 which specifies how to highlight matches found by @var{matcher}.
2712 It has the form:
2714 @example
2715 (@var{subexp} @var{facespec} [@var{override} [@var{laxmatch}]])
2716 @end example
2718 The @sc{car}, @var{subexp}, is an integer specifying which subexpression
2719 of the match to fontify (0 means the entire matching text).  The second
2720 subelement, @var{facespec}, is an expression whose value specifies the
2721 face, as described above.
2723 The last two values in @var{subexp-highlighter}, @var{override} and
2724 @var{laxmatch}, are optional flags.  If @var{override} is @code{t},
2725 this element can override existing fontification made by previous
2726 elements of @code{font-lock-keywords}.  If it is @code{keep}, then
2727 each character is fontified if it has not been fontified already by
2728 some other element.  If it is @code{prepend}, the face specified by
2729 @var{facespec} is added to the beginning of the @code{font-lock-face}
2730 property.  If it is @code{append}, the face is added to the end of the
2731 @code{font-lock-face} property.
2733 If @var{laxmatch} is non-@code{nil}, it means there should be no error
2734 if there is no subexpression numbered @var{subexp} in @var{matcher}.
2735 Obviously, fontification of the subexpression numbered @var{subexp} will
2736 not occur.  However, fontification of other subexpressions (and other
2737 regexps) will continue.  If @var{laxmatch} is @code{nil}, and the
2738 specified subexpression is missing, then an error is signaled which
2739 terminates search-based fontification.
2741 Here are some examples of elements of this kind, and what they do:
2743 @smallexample
2744 ;; @r{Highlight occurrences of either @samp{foo} or @samp{bar}, using}
2745 ;; @r{@code{foo-bar-face}, even if they have already been highlighted.}
2746 ;; @r{@code{foo-bar-face} should be a variable whose value is a face.}
2747 ("foo\\|bar" 0 foo-bar-face t)
2749 ;; @r{Highlight the first subexpression within each occurrence}
2750 ;; @r{that the function @code{fubar-match} finds,}
2751 ;; @r{using the face which is the value of @code{fubar-face}.}
2752 (fubar-match 1 fubar-face)
2753 @end smallexample
2755 @item (@var{matcher} . @var{anchored-highlighter})
2756 In this kind of element, @var{anchored-highlighter} specifies how to
2757 highlight text that follows a match found by @var{matcher}.  So a
2758 match found by @var{matcher} acts as the anchor for further searches
2759 specified by @var{anchored-highlighter}.  @var{anchored-highlighter}
2760 is a list of the following form:
2762 @example
2763 (@var{anchored-matcher} @var{pre-form} @var{post-form}
2764                         @var{subexp-highlighters}@dots{})
2765 @end example
2767 Here, @var{anchored-matcher}, like @var{matcher}, is either a regular
2768 expression or a function.  After a match of @var{matcher} is found,
2769 point is at the end of the match.  Now, Font Lock evaluates the form
2770 @var{pre-form}.  Then it searches for matches of
2771 @var{anchored-matcher} and uses @var{subexp-highlighters} to highlight
2772 these.  A @var{subexp-highlighter} is as described above.  Finally,
2773 Font Lock evaluates @var{post-form}.
2775 The forms @var{pre-form} and @var{post-form} can be used to initialize
2776 before, and cleanup after, @var{anchored-matcher} is used.  Typically,
2777 @var{pre-form} is used to move point to some position relative to the
2778 match of @var{matcher}, before starting with @var{anchored-matcher}.
2779 @var{post-form} might be used to move back, before resuming with
2780 @var{matcher}.
2782 After Font Lock evaluates @var{pre-form}, it does not search for
2783 @var{anchored-matcher} beyond the end of the line.  However, if
2784 @var{pre-form} returns a buffer position that is greater than the
2785 position of point after @var{pre-form} is evaluated, then the position
2786 returned by @var{pre-form} is used as the limit of the search instead.
2787 It is generally a bad idea to return a position greater than the end
2788 of the line; in other words, the @var{anchored-matcher} search should
2789 not span lines.
2791 For example,
2793 @smallexample
2794 ;; @r{Highlight occurrences of the word @samp{item} following}
2795 ;; @r{an occurrence of the word @samp{anchor} (on the same line)}
2796 ;; @r{in the value of @code{item-face}.}
2797 ("\\<anchor\\>" "\\<item\\>" nil nil (0 item-face))
2798 @end smallexample
2800 Here, @var{pre-form} and @var{post-form} are @code{nil}.  Therefore
2801 searching for @samp{item} starts at the end of the match of
2802 @samp{anchor}, and searching for subsequent instances of @samp{anchor}
2803 resumes from where searching for @samp{item} concluded.
2805 @item (@var{matcher} @var{highlighters}@dots{})
2806 This sort of element specifies several @var{highlighter} lists for a
2807 single @var{matcher}.  A @var{highlighter} list can be of the type
2808 @var{subexp-highlighter} or @var{anchored-highlighter} as described
2809 above.
2811 For example,
2813 @smallexample
2814 ;; @r{Highlight occurrences of the word @samp{anchor} in the value}
2815 ;; @r{of @code{anchor-face}, and subsequent occurrences of the word}
2816 ;; @r{@samp{item} (on the same line) in the value of @code{item-face}.}
2817 ("\\<anchor\\>" (0 anchor-face)
2818                 ("\\<item\\>" nil nil (0 item-face)))
2819 @end smallexample
2821 @item (eval . @var{form})
2822 Here @var{form} is an expression to be evaluated the first time
2823 this value of @code{font-lock-keywords} is used in a buffer.
2824 Its value should have one of the forms described in this table.
2825 @end table
2827 @strong{Warning:} Do not design an element of @code{font-lock-keywords}
2828 to match text which spans lines; this does not work reliably.
2829 For details, see @xref{Multiline Font Lock}.
2831 You can use @var{case-fold} in @code{font-lock-defaults} to specify
2832 the value of @code{font-lock-keywords-case-fold-search} which says
2833 whether search-based fontification should be case-insensitive.
2835 @defvar font-lock-keywords-case-fold-search
2836 Non-@code{nil} means that regular expression matching for the sake of
2837 @code{font-lock-keywords} should be case-insensitive.
2838 @end defvar
2840 @node Customizing Keywords
2841 @subsection Customizing Search-Based Fontification
2843   You can use @code{font-lock-add-keywords} to add additional
2844 search-based fontification rules to a major mode, and
2845 @code{font-lock-remove-keywords} to remove rules.
2847 @defun font-lock-add-keywords mode keywords &optional how
2848 This function adds highlighting @var{keywords}, for the current buffer
2849 or for major mode @var{mode}.  The argument @var{keywords} should be a
2850 list with the same format as the variable @code{font-lock-keywords}.
2852 If @var{mode} is a symbol which is a major mode command name, such as
2853 @code{c-mode}, the effect is that enabling Font Lock mode in
2854 @var{mode} will add @var{keywords} to @code{font-lock-keywords}.
2855 Calling with a non-@code{nil} value of @var{mode} is correct only in
2856 your @file{~/.emacs} file.
2858 If @var{mode} is @code{nil}, this function adds @var{keywords} to
2859 @code{font-lock-keywords} in the current buffer.  This way of calling
2860 @code{font-lock-add-keywords} is usually used in mode hook functions.
2862 By default, @var{keywords} are added at the beginning of
2863 @code{font-lock-keywords}.  If the optional argument @var{how} is
2864 @code{set}, they are used to replace the value of
2865 @code{font-lock-keywords}.  If @var{how} is any other non-@code{nil}
2866 value, they are added at the end of @code{font-lock-keywords}.
2868 Some modes provide specialized support you can use in additional
2869 highlighting patterns.  See the variables
2870 @code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types},
2871 and @code{java-font-lock-extra-types}, for example.
2873 @strong{Warning:} Major mode commands must not call
2874 @code{font-lock-add-keywords} under any circumstances, either directly
2875 or indirectly, except through their mode hooks.  (Doing so would lead to
2876 incorrect behavior for some minor modes.)  They should set up their
2877 rules for search-based fontification by setting
2878 @code{font-lock-keywords}.
2879 @end defun
2881 @defun font-lock-remove-keywords mode keywords
2882 This function removes @var{keywords} from @code{font-lock-keywords}
2883 for the current buffer or for major mode @var{mode}.  As in
2884 @code{font-lock-add-keywords}, @var{mode} should be a major mode
2885 command name or @code{nil}.  All the caveats and requirements for
2886 @code{font-lock-add-keywords} apply here too.
2887 @end defun
2889   For example, the following code adds two fontification patterns for C
2890 mode: one to fontify the word @samp{FIXME}, even in comments, and
2891 another to fontify the words @samp{and}, @samp{or} and @samp{not} as
2892 keywords.
2894 @smallexample
2895 (font-lock-add-keywords 'c-mode
2896  '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
2897    ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face)))
2898 @end smallexample
2900 @noindent
2901 This example affects only C mode proper.  To add the same patterns to C
2902 mode @emph{and} all modes derived from it, do this instead:
2904 @smallexample
2905 (add-hook 'c-mode-hook
2906  (lambda ()
2907   (font-lock-add-keywords nil
2908    '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
2909      ("\\<\\(and\\|or\\|not\\)\\>" .
2910       font-lock-keyword-face)))))
2911 @end smallexample
2913 @node Other Font Lock Variables
2914 @subsection Other Font Lock Variables
2916   This section describes additional variables that a major mode can
2917 set by means of @var{other-vars} in @code{font-lock-defaults}
2918 (@pxref{Font Lock Basics}).
2920 @defvar font-lock-mark-block-function
2921 If this variable is non-@code{nil}, it should be a function that is
2922 called with no arguments, to choose an enclosing range of text for
2923 refontification for the command @kbd{M-o M-o}
2924 (@code{font-lock-fontify-block}).
2926 The function should report its choice by placing the region around it.
2927 A good choice is a range of text large enough to give proper results,
2928 but not too large so that refontification becomes slow.  Typical values
2929 are @code{mark-defun} for programming modes or @code{mark-paragraph} for
2930 textual modes.
2931 @end defvar
2933 @defvar font-lock-extra-managed-props
2934 This variable specifies additional properties (other than
2935 @code{font-lock-face}) that are being managed by Font Lock mode.  It
2936 is used by @code{font-lock-default-unfontify-region}, which normally
2937 only manages the @code{font-lock-face} property.  If you want Font
2938 Lock to manage other properties as well, you must specify them in a
2939 @var{facespec} in @code{font-lock-keywords} as well as add them to
2940 this list.  @xref{Search-based Fontification}.
2941 @end defvar
2943 @defvar font-lock-fontify-buffer-function
2944 Function to use for fontifying the buffer.  The default value is
2945 @code{font-lock-default-fontify-buffer}.
2946 @end defvar
2948 @defvar font-lock-unfontify-buffer-function
2949 Function to use for unfontifying the buffer.  This is used when
2950 turning off Font Lock mode.  The default value is
2951 @code{font-lock-default-unfontify-buffer}.
2952 @end defvar
2954 @defvar font-lock-fontify-region-function
2955 Function to use for fontifying a region.  It should take two
2956 arguments, the beginning and end of the region, and an optional third
2957 argument @var{verbose}.  If @var{verbose} is non-@code{nil}, the
2958 function should print status messages.  The default value is
2959 @code{font-lock-default-fontify-region}.
2960 @end defvar
2962 @defvar font-lock-unfontify-region-function
2963 Function to use for unfontifying a region.  It should take two
2964 arguments, the beginning and end of the region.  The default value is
2965 @code{font-lock-default-unfontify-region}.
2966 @end defvar
2968 @defun jit-lock-register function &optional contextual
2969 This function tells Font Lock mode to run the Lisp function
2970 @var{function} any time it has to fontify or refontify part of the
2971 current buffer.  It calls @var{function} before calling the default
2972 fontification functions, and gives it two arguments, @var{start} and
2973 @var{end}, which specify the region to be fontified or refontified.
2975 The optional argument @var{contextual}, if non-@code{nil}, forces Font
2976 Lock mode to always refontify a syntactically relevant part of the
2977 buffer, and not just the modified lines.  This argument can usually be
2978 omitted.
2979 @end defun
2981 @defun jit-lock-unregister function
2982 If @var{function} was previously registered as a fontification
2983 function using @code{jit-lock-register}, this function unregisters it.
2984 @end defun
2986 @node Levels of Font Lock
2987 @subsection Levels of Font Lock
2989   Some major modes offer three different levels of fontification.  You
2990 can define multiple levels by using a list of symbols for @var{keywords}
2991 in @code{font-lock-defaults}.  Each symbol specifies one level of
2992 fontification; it is up to the user to choose one of these levels,
2993 normally by setting @code{font-lock-maximum-decoration} (@pxref{Font
2994 Lock,,, emacs, the GNU Emacs Manual}).  The chosen level's symbol value
2995 is used to initialize @code{font-lock-keywords}.
2997   Here are the conventions for how to define the levels of
2998 fontification:
3000 @itemize @bullet
3001 @item
3002 Level 1: highlight function declarations, file directives (such as include or
3003 import directives), strings and comments.  The idea is speed, so only
3004 the most important and top-level components are fontified.
3006 @item
3007 Level 2: in addition to level 1, highlight all language keywords,
3008 including type names that act like keywords, as well as named constant
3009 values.  The idea is that all keywords (either syntactic or semantic)
3010 should be fontified appropriately.
3012 @item
3013 Level 3: in addition to level 2, highlight the symbols being defined in
3014 function and variable declarations, and all builtin function names,
3015 wherever they appear.
3016 @end itemize
3018 @node Precalculated Fontification
3019 @subsection Precalculated Fontification
3021   Some major modes such as @code{list-buffers} and @code{occur}
3022 construct the buffer text programmatically.  The easiest way for them
3023 to support Font Lock mode is to specify the faces of text when they
3024 insert the text in the buffer.
3026   The way to do this is to specify the faces in the text with the
3027 special text property @code{font-lock-face} (@pxref{Special
3028 Properties}).  When Font Lock mode is enabled, this property controls
3029 the display, just like the @code{face} property.  When Font Lock mode
3030 is disabled, @code{font-lock-face} has no effect on the display.
3032   It is ok for a mode to use @code{font-lock-face} for some text and
3033 also use the normal Font Lock machinery.  But if the mode does not use
3034 the normal Font Lock machinery, it should not set the variable
3035 @code{font-lock-defaults}.
3037 @node Faces for Font Lock
3038 @subsection Faces for Font Lock
3039 @cindex faces for font lock
3040 @cindex font lock faces
3042   Font Lock mode can highlight using any face, but Emacs defines several
3043 faces specifically for Font Lock to use to highlight text.  These
3044 @dfn{Font Lock faces} are listed below.  They can also be used by major
3045 modes for syntactic highlighting outside of Font Lock mode (@pxref{Major
3046 Mode Conventions}).
3048   Each of these symbols is both a face name, and a variable whose
3049 default value is the symbol itself.  Thus, the default value of
3050 @code{font-lock-comment-face} is @code{font-lock-comment-face}.
3052   The faces are listed with descriptions of their typical usage, and in
3053 order of greater to lesser ``prominence''.  If a mode's syntactic
3054 categories do not fit well with the usage descriptions, the faces can be
3055 assigned using the ordering as a guide.
3057 @table @code
3058 @item font-lock-warning-face
3059 @vindex font-lock-warning-face
3060 for a construct that is peculiar, or that greatly changes the meaning of
3061 other text, like @samp{;;;###autoload} in Emacs Lisp and @samp{#error}
3062 in C.
3064 @item font-lock-function-name-face
3065 @vindex font-lock-function-name-face
3066 for the name of a function being defined or declared.
3068 @item font-lock-variable-name-face
3069 @vindex font-lock-variable-name-face
3070 for the name of a variable being defined or declared.
3072 @item font-lock-keyword-face
3073 @vindex font-lock-keyword-face
3074 for a keyword with special syntactic significance, like @samp{for} and
3075 @samp{if} in C.
3077 @item font-lock-comment-face
3078 @vindex font-lock-comment-face
3079 for comments.
3081 @item font-lock-comment-delimiter-face
3082 @vindex font-lock-comment-delimiter-face
3083 for comments delimiters, like @samp{/*} and @samp{*/} in C@.  On most
3084 terminals, this inherits from @code{font-lock-comment-face}.
3086 @item font-lock-type-face
3087 @vindex font-lock-type-face
3088 for the names of user-defined data types.
3090 @item font-lock-constant-face
3091 @vindex font-lock-constant-face
3092 for the names of constants, like @samp{NULL} in C.
3094 @item font-lock-builtin-face
3095 @vindex font-lock-builtin-face
3096 for the names of built-in functions.
3098 @item font-lock-preprocessor-face
3099 @vindex font-lock-preprocessor-face
3100 for preprocessor commands.  This inherits, by default, from
3101 @code{font-lock-builtin-face}.
3103 @item font-lock-string-face
3104 @vindex font-lock-string-face
3105 for string constants.
3107 @item font-lock-doc-face
3108 @vindex font-lock-doc-face
3109 for documentation strings in the code.  This inherits, by default, from
3110 @code{font-lock-string-face}.
3112 @item font-lock-negation-char-face
3113 @vindex font-lock-negation-char-face
3114 for easily-overlooked negation characters.
3115 @end table
3117 @node Syntactic Font Lock
3118 @subsection Syntactic Font Lock
3119 @cindex syntactic font lock
3121 Syntactic fontification uses a syntax table (@pxref{Syntax Tables}) to
3122 find and highlight syntactically relevant text.  If enabled, it runs
3123 prior to search-based fontification.  The variable
3124 @code{font-lock-syntactic-face-function}, documented below, determines
3125 which syntactic constructs to highlight.  There are several variables
3126 that affect syntactic fontification; you should set them by means of
3127 @code{font-lock-defaults} (@pxref{Font Lock Basics}).
3129   Whenever Font Lock mode performs syntactic fontification on a stretch
3130 of text, it first calls the function specified by
3131 @code{syntax-propertize-function}.  Major modes can use this to apply
3132 @code{syntax-table} text properties to override the buffer's syntax
3133 table in special cases.  @xref{Syntax Properties}.
3135 @defvar font-lock-keywords-only
3136 If the value of this variable is non-@code{nil}, Font Lock does not do
3137 syntactic fontification, only search-based fontification based on
3138 @code{font-lock-keywords}.  It is normally set by Font Lock mode based
3139 on the @var{keywords-only} element in @code{font-lock-defaults}.
3140 @end defvar
3142 @defvar font-lock-syntax-table
3143 This variable holds the syntax table to use for fontification of
3144 comments and strings.  It is normally set by Font Lock mode based on the
3145 @var{syntax-alist} element in @code{font-lock-defaults}.  If this value
3146 is @code{nil}, syntactic fontification uses the buffer's syntax table
3147 (the value returned by the function @code{syntax-table}; @pxref{Syntax
3148 Table Functions}).
3149 @end defvar
3151 @defvar font-lock-beginning-of-syntax-function
3152 If this variable is non-@code{nil}, it should be a function to move
3153 point back to a position that is syntactically at ``top level'' and
3154 outside of strings or comments.  The value is normally set through an
3155 @var{other-vars} element in @code{font-lock-defaults}.  If it is
3156 @code{nil}, Font Lock uses @code{syntax-begin-function} to move back
3157 outside of any comment, string, or sexp (@pxref{Position Parse}).
3159 This variable is semi-obsolete; we usually recommend setting
3160 @code{syntax-begin-function} instead.  One of its uses is to tune the
3161 behavior of syntactic fontification, e.g., to ensure that different
3162 kinds of strings or comments are highlighted differently.
3164 The specified function is called with no arguments.  It should leave
3165 point at the beginning of any enclosing syntactic block.  Typical values
3166 are @code{beginning-of-line} (used when the start of the line is known
3167 to be outside a syntactic block), or @code{beginning-of-defun} for
3168 programming modes, or @code{backward-paragraph} for textual modes.
3169 @end defvar
3171 @defvar font-lock-syntactic-face-function
3172 If this variable is non-@code{nil}, it should be a function to determine
3173 which face to use for a given syntactic element (a string or a comment).
3174 The value is normally set through an @var{other-vars} element in
3175 @code{font-lock-defaults}.
3177 The function is called with one argument, the parse state at point
3178 returned by @code{parse-partial-sexp}, and should return a face.  The
3179 default value returns @code{font-lock-comment-face} for comments and
3180 @code{font-lock-string-face} for strings (@pxref{Faces for Font Lock}).
3181 @end defvar
3183 @node Multiline Font Lock
3184 @subsection Multiline Font Lock Constructs
3185 @cindex multiline font lock
3187   Normally, elements of @code{font-lock-keywords} should not match
3188 across multiple lines; that doesn't work reliably, because Font Lock
3189 usually scans just part of the buffer, and it can miss a multi-line
3190 construct that crosses the line boundary where the scan starts.  (The
3191 scan normally starts at the beginning of a line.)
3193   Making elements that match multiline constructs work properly has
3194 two aspects: correct @emph{identification} and correct
3195 @emph{rehighlighting}.  The first means that Font Lock finds all
3196 multiline constructs.  The second means that Font Lock will correctly
3197 rehighlight all the relevant text when a multiline construct is
3198 changed---for example, if some of the text that was previously part of
3199 a multiline construct ceases to be part of it.  The two aspects are
3200 closely related, and often getting one of them to work will appear to
3201 make the other also work.  However, for reliable results you must
3202 attend explicitly to both aspects.
3204   There are three ways to ensure correct identification of multiline
3205 constructs:
3207 @itemize
3208 @item
3209 Add a function to @code{font-lock-extend-region-functions} that does
3210 the @emph{identification} and extends the scan so that the scanned
3211 text never starts or ends in the middle of a multiline construct.
3212 @item
3213 Use the @code{font-lock-fontify-region-function} hook similarly to
3214 extend the scan so that the scanned text never starts or ends in the
3215 middle of a multiline construct.
3216 @item
3217 Somehow identify the multiline construct right when it gets inserted
3218 into the buffer (or at any point after that but before font-lock
3219 tries to highlight it), and mark it with a @code{font-lock-multiline}
3220 which will instruct font-lock not to start or end the scan in the
3221 middle of the construct.
3222 @end itemize
3224   There are three ways to do rehighlighting of multiline constructs:
3226 @itemize
3227 @item
3228 Place a @code{font-lock-multiline} property on the construct.  This
3229 will rehighlight the whole construct if any part of it is changed.  In
3230 some cases you can do this automatically by setting the
3231 @code{font-lock-multiline} variable, which see.
3232 @item
3233 Make sure @code{jit-lock-contextually} is set and rely on it doing its
3234 job.  This will only rehighlight the part of the construct that
3235 follows the actual change, and will do it after a short delay.
3236 This only works if the highlighting of the various parts of your
3237 multiline construct never depends on text in subsequent lines.
3238 Since @code{jit-lock-contextually} is activated by default, this can
3239 be an attractive solution.
3240 @item
3241 Place a @code{jit-lock-defer-multiline} property on the construct.
3242 This works only if @code{jit-lock-contextually} is used, and with the
3243 same delay before rehighlighting, but like @code{font-lock-multiline},
3244 it also handles the case where highlighting depends on
3245 subsequent lines.
3246 @end itemize
3248 @menu
3249 * Font Lock Multiline::         Marking multiline chunks with a text property.
3250 * Region to Refontify::         Controlling which region gets refontified
3251                                   after a buffer change.
3252 @end menu
3254 @node Font Lock Multiline
3255 @subsubsection Font Lock Multiline
3257   One way to ensure reliable rehighlighting of multiline Font Lock
3258 constructs is to put on them the text property @code{font-lock-multiline}.
3259 It should be present and non-@code{nil} for text that is part of a
3260 multiline construct.
3262   When Font Lock is about to highlight a range of text, it first
3263 extends the boundaries of the range as necessary so that they do not
3264 fall within text marked with the @code{font-lock-multiline} property.
3265 Then it removes any @code{font-lock-multiline} properties from the
3266 range, and highlights it.  The highlighting specification (mostly
3267 @code{font-lock-keywords}) must reinstall this property each time,
3268 whenever it is appropriate.
3270   @strong{Warning:} don't use the @code{font-lock-multiline} property
3271 on large ranges of text, because that will make rehighlighting slow.
3273 @defvar font-lock-multiline
3274 If the @code{font-lock-multiline} variable is set to @code{t}, Font
3275 Lock will try to add the @code{font-lock-multiline} property
3276 automatically on multiline constructs.  This is not a universal
3277 solution, however, since it slows down Font Lock somewhat.  It can
3278 miss some multiline constructs, or make the property larger or smaller
3279 than necessary.
3281 For elements whose @var{matcher} is a function, the function should
3282 ensure that submatch 0 covers the whole relevant multiline construct,
3283 even if only a small subpart will be highlighted.  It is often just as
3284 easy to add the @code{font-lock-multiline} property by hand.
3285 @end defvar
3287   The @code{font-lock-multiline} property is meant to ensure proper
3288 refontification; it does not automatically identify new multiline
3289 constructs.  Identifying the requires that Font Lock mode operate on
3290 large enough chunks at a time.  This will happen by accident on many
3291 cases, which may give the impression that multiline constructs magically
3292 work.  If you set the @code{font-lock-multiline} variable
3293 non-@code{nil}, this impression will be even stronger, since the
3294 highlighting of those constructs which are found will be properly
3295 updated from then on.  But that does not work reliably.
3297   To find multiline constructs reliably, you must either manually place
3298 the @code{font-lock-multiline} property on the text before Font Lock
3299 mode looks at it, or use @code{font-lock-fontify-region-function}.
3301 @node Region to Refontify
3302 @subsubsection Region to Fontify after a Buffer Change
3304   When a buffer is changed, the region that Font Lock refontifies is
3305 by default the smallest sequence of whole lines that spans the change.
3306 While this works well most of the time, sometimes it doesn't---for
3307 example, when a change alters the syntactic meaning of text on an
3308 earlier line.
3310   You can enlarge (or even reduce) the region to refontify by setting
3311 the following variable:
3313 @defvar font-lock-extend-after-change-region-function
3314 This buffer-local variable is either @code{nil} or a function for Font
3315 Lock mode to call to determine the region to scan and fontify.
3317 The function is given three parameters, the standard @var{beg},
3318 @var{end}, and @var{old-len} from @code{after-change-functions}
3319 (@pxref{Change Hooks}).  It should return either a cons of the
3320 beginning and end buffer positions (in that order) of the region to
3321 fontify, or @code{nil} (which means choose the region in the standard
3322 way).  This function needs to preserve point, the match-data, and the
3323 current restriction.  The region it returns may start or end in the
3324 middle of a line.
3326 Since this function is called after every buffer change, it should be
3327 reasonably fast.
3328 @end defvar
3330 @node Auto-Indentation
3331 @section Automatic Indentation of code
3333 For programming languages, an important feature of a major mode is to
3334 provide automatic indentation.  This is controlled in Emacs by
3335 @code{indent-line-function} (@pxref{Mode-Specific Indent}).
3336 Writing a good indentation function can be difficult and to a large
3337 extent it is still a black art.
3339 Many major mode authors will start by writing a simple indentation
3340 function that works for simple cases, for example by comparing with the
3341 indentation of the previous text line.  For most programming languages
3342 that are not really line-based, this tends to scale very poorly:
3343 improving such a function to let it handle more diverse situations tends
3344 to become more and more difficult, resulting in the end with a large,
3345 complex, unmaintainable indentation function which nobody dares to touch.
3347 A good indentation function will usually need to actually parse the
3348 text, according to the syntax of the language.  Luckily, it is not
3349 necessary to parse the text in as much detail as would be needed
3350 for a compiler, but on the other hand, the parser embedded in the
3351 indentation code will want to be somewhat friendly to syntactically
3352 incorrect code.
3354 Good maintainable indentation functions usually fall into two categories:
3355 either parsing forward from some ``safe'' starting point until the
3356 position of interest, or parsing backward from the position of interest.
3357 Neither of the two is a clearly better choice than the other: parsing
3358 backward is often more difficult than parsing forward because
3359 programming languages are designed to be parsed forward, but for the
3360 purpose of indentation it has the advantage of not needing to
3361 guess a ``safe'' starting point, and it generally enjoys the property
3362 that only a minimum of text will be analyzed to decide the indentation
3363 of a line, so indentation will tend to be unaffected by syntax errors in
3364 some earlier unrelated piece of code.  Parsing forward on the other hand
3365 is usually easier and has the advantage of making it possible to
3366 reindent efficiently a whole region at a time, with a single parse.
3368 Rather than write your own indentation function from scratch, it is
3369 often preferable to try and reuse some existing ones or to rely
3370 on a generic indentation engine.  There are sadly few such
3371 engines.  The CC-mode indentation code (used with C, C++, Java, Awk
3372 and a few other such modes) has been made more generic over the years,
3373 so if your language seems somewhat similar to one of those languages,
3374 you might try to use that engine.  @c FIXME: documentation?
3375 Another one is SMIE which takes an approach in the spirit
3376 of Lisp sexps and adapts it to non-Lisp languages.
3378 @menu
3379 * SMIE::                        A simple minded indentation engine.
3380 @end menu
3382 @node SMIE
3383 @subsection Simple Minded Indentation Engine
3384 @cindex SMIE
3386 SMIE is a package that provides a generic navigation and indentation
3387 engine.  Based on a very simple parser using an ``operator precedence
3388 grammar'', it lets major modes extend the sexp-based navigation of Lisp
3389 to non-Lisp languages as well as provide a simple to use but reliable
3390 auto-indentation.
3392 Operator precedence grammar is a very primitive technology for parsing
3393 compared to some of the more common techniques used in compilers.
3394 It has the following characteristics: its parsing power is very limited,
3395 and it is largely unable to detect syntax errors, but it has the
3396 advantage of being algorithmically efficient and able to parse forward
3397 just as well as backward.  In practice that means that SMIE can use it
3398 for indentation based on backward parsing, that it can provide both
3399 @code{forward-sexp} and @code{backward-sexp} functionality, and that it
3400 will naturally work on syntactically incorrect code without any extra
3401 effort.  The downside is that it also means that most programming
3402 languages cannot be parsed correctly using SMIE, at least not without
3403 resorting to some special tricks (@pxref{SMIE Tricks}).
3405 @menu
3406 * SMIE setup::                  SMIE setup and features.
3407 * Operator Precedence Grammars::  A very simple parsing technique.
3408 * SMIE Grammar::                Defining the grammar of a language.
3409 * SMIE Lexer::                  Defining tokens.
3410 * SMIE Tricks::                 Working around the parser's limitations.
3411 * SMIE Indentation::            Specifying indentation rules.
3412 * SMIE Indentation Helpers::    Helper functions for indentation rules.
3413 * SMIE Indentation Example::    Sample indentation rules.
3414 @end menu
3416 @node SMIE setup
3417 @subsubsection SMIE Setup and Features
3419 SMIE is meant to be a one-stop shop for structural navigation and
3420 various other features which rely on the syntactic structure of code, in
3421 particular automatic indentation.  The main entry point is
3422 @code{smie-setup} which is a function typically called while setting
3423 up a major mode.
3425 @defun smie-setup grammar rules-function &rest keywords
3426 Setup SMIE navigation and indentation.
3427 @var{grammar} is a grammar table generated by @code{smie-prec2->grammar}.
3428 @var{rules-function} is a set of indentation rules for use on
3429 @code{smie-rules-function}.
3430 @var{keywords} are additional arguments, which can include the following
3431 keywords:
3432 @itemize
3433 @item
3434 @code{:forward-token} @var{fun}: Specify the forward lexer to use.
3435 @item
3436 @code{:backward-token} @var{fun}: Specify the backward lexer to use.
3437 @end itemize
3438 @end defun
3440 Calling this function is sufficient to make commands such as
3441 @code{forward-sexp}, @code{backward-sexp}, and @code{transpose-sexps} be
3442 able to properly handle structural elements other than just the paired
3443 parentheses already handled by syntax tables.  For example, if the
3444 provided grammar is precise enough, @code{transpose-sexps} can correctly
3445 transpose the two arguments of a @code{+} operator, taking into account
3446 the precedence rules of the language.
3448 Calling `smie-setup' is also sufficient to make TAB indentation work in
3449 the expected way, extends @code{blink-matching-paren} to apply to
3450 elements like @code{begin...end}, and provides some commands that you
3451 can bind in the major mode keymap.
3453 @deffn Command smie-close-block
3454 This command closes the most recently opened (and not yet closed) block.
3455 @end deffn
3457 @deffn Command smie-down-list &optional arg
3458 This command is like @code{down-list} but it also pays attention to
3459 nesting of tokens other than parentheses, such as @code{begin...end}.
3460 @end deffn
3462 @node Operator Precedence Grammars
3463 @subsubsection Operator Precedence Grammars
3465 SMIE's precedence grammars simply give to each token a pair of
3466 precedences: the left-precedence and the right-precedence.  We say
3467 @code{T1 < T2} if the right-precedence of token @code{T1} is less than
3468 the left-precedence of token @code{T2}.  A good way to read this
3469 @code{<} is as a kind of parenthesis: if we find @code{... T1 something
3470 T2 ...}  then that should be parsed as @code{... T1 (something T2 ...}
3471 rather than as @code{... T1 something) T2 ...}.  The latter
3472 interpretation would be the case if we had @code{T1 > T2}.  If we have
3473 @code{T1 = T2}, it means that token T2 follows token T1 in the same
3474 syntactic construction, so typically we have @code{"begin" = "end"}.
3475 Such pairs of precedences are sufficient to express left-associativity
3476 or right-associativity of infix operators, nesting of tokens like
3477 parentheses and many other cases.
3479 @c Let's leave this undocumented to leave it more open for change!
3480 @c @defvar smie-grammar
3481 @c The value of this variable is an alist specifying the left and right
3482 @c precedence of each token.  It is meant to be initialized by using one of
3483 @c the functions below.
3484 @c @end defvar
3486 @defun smie-prec2->grammar table
3487 This function takes a @emph{prec2} grammar @var{table} and returns an
3488 alist suitable for use in @code{smie-setup}.  The @emph{prec2}
3489 @var{table} is itself meant to be built by one of the functions below.
3490 @end defun
3492 @defun smie-merge-prec2s &rest tables
3493 This function takes several @emph{prec2} @var{tables} and merges them
3494 into a new @emph{prec2} table.
3495 @end defun
3497 @defun smie-precs->prec2 precs
3498 This function builds a @emph{prec2} table from a table of precedences
3499 @var{precs}.  @var{precs} should be a list, sorted by precedence (for
3500 example @code{"+"} will come before @code{"*"}), of elements of the form
3501 @code{(@var{assoc} @var{op} ...)}, where each @var{op} is a token that
3502 acts as an operator; @var{assoc} is their associativity, which can be
3503 either @code{left}, @code{right}, @code{assoc}, or @code{nonassoc}.
3504 All operators in a given element share the same precedence level
3505 and associativity.
3506 @end defun
3508 @defun smie-bnf->prec2 bnf &rest resolvers
3509 This function lets you specify the grammar using a BNF notation.
3510 It accepts a @var{bnf} description of the grammar along with a set of
3511 conflict resolution rules @var{resolvers}, and
3512 returns a @emph{prec2} table.
3514 @var{bnf} is a list of nonterminal definitions of the form
3515 @code{(@var{nonterm} @var{rhs1} @var{rhs2} ...)} where each @var{rhs}
3516 is a (non-empty) list of terminals (aka tokens) or non-terminals.
3518 Not all grammars are accepted:
3519 @itemize
3520 @item
3521 An @var{rhs} cannot be an empty list (an empty list is never needed,
3522 since SMIE allows all non-terminals to match the empty string anyway).
3523 @item
3524 An @var{rhs} cannot have 2 consecutive non-terminals: each pair of
3525 non-terminals needs to be separated by a terminal (aka token).
3526 This is a fundamental limitation of operator precedence grammars.
3527 @end itemize
3529 Additionally, conflicts can occur:
3530 @itemize
3531 @item
3532 The returned @emph{prec2} table holds constraints between pairs of tokens, and
3533 for any given pair only one constraint can be present: T1 < T2,
3534 T1 = T2, or T1 > T2.
3535 @item
3536 A token can be an @code{opener} (something similar to an open-paren),
3537 a @code{closer} (like a close-paren), or @code{neither} of the two
3538 (e.g., an infix operator, or an inner token like @code{"else"}).
3539 @end itemize
3541 Precedence conflicts can be resolved via @var{resolvers}, which
3542 is a list of @emph{precs} tables (see @code{smie-precs->prec2}): for
3543 each precedence conflict, if those @code{precs} tables
3544 specify a particular constraint, then the conflict is resolved by using
3545 this constraint instead, else a conflict is reported and one of the
3546 conflicting constraints is picked arbitrarily and the others are
3547 simply ignored.
3548 @end defun
3550 @node SMIE Grammar
3551 @subsubsection Defining the Grammar of a Language
3552 @cindex SMIE grammar
3553 @cindex grammar, SMIE
3555 The usual way to define the SMIE grammar of a language is by
3556 defining a new global variable that holds the precedence table by
3557 giving a set of BNF rules.
3558 For example, the grammar definition for a small Pascal-like language
3559 could look like:
3560 @example
3561 @group
3562 (require 'smie)
3563 (defvar sample-smie-grammar
3564   (smie-prec2->grammar
3565    (smie-bnf->prec2
3566 @end group
3567 @group
3568     '((id)
3569       (inst ("begin" insts "end")
3570             ("if" exp "then" inst "else" inst)
3571             (id ":=" exp)
3572             (exp))
3573       (insts (insts ";" insts) (inst))
3574       (exp (exp "+" exp)
3575            (exp "*" exp)
3576            ("(" exps ")"))
3577       (exps (exps "," exps) (exp)))
3578 @end group
3579 @group
3580     '((assoc ";"))
3581     '((assoc ","))
3582     '((assoc "+") (assoc "*")))))
3583 @end group
3584 @end example
3586 @noindent
3587 A few things to note:
3589 @itemize
3590 @item
3591 The above grammar does not explicitly mention the syntax of function
3592 calls: SMIE will automatically allow any sequence of sexps, such as
3593 identifiers, balanced parentheses, or @code{begin ... end} blocks
3594 to appear anywhere anyway.
3595 @item
3596 The grammar category @code{id} has no right hand side: this does not
3597 mean that it can match only the empty string, since as mentioned any
3598 sequence of sexps can appear anywhere anyway.
3599 @item
3600 Because non terminals cannot appear consecutively in the BNF grammar, it
3601 is difficult to correctly handle tokens that act as terminators, so the
3602 above grammar treats @code{";"} as a statement @emph{separator} instead,
3603 which SMIE can handle very well.
3604 @item
3605 Separators used in sequences (such as @code{","} and @code{";"} above)
3606 are best defined with BNF rules such as @code{(foo (foo "separator" foo) ...)}
3607 which generate precedence conflicts which are then resolved by giving
3608 them an explicit @code{(assoc "separator")}.
3609 @item
3610 The @code{("(" exps ")")} rule was not needed to pair up parens, since
3611 SMIE will pair up any characters that are marked as having paren syntax
3612 in the syntax table.  What this rule does instead (together with the
3613 definition of @code{exps}) is to make it clear that @code{","} should
3614 not appear outside of parentheses.
3615 @item
3616 Rather than have a single @emph{precs} table to resolve conflicts, it is
3617 preferable to have several tables, so as to let the BNF part of the
3618 grammar specify relative precedences where possible.
3619 @item
3620 Unless there is a very good reason to prefer @code{left} or
3621 @code{right}, it is usually preferable to mark operators as associative,
3622 using @code{assoc}.  For that reason @code{"+"} and @code{"*"} are
3623 defined above as @code{assoc}, although the language defines them
3624 formally as left associative.
3625 @end itemize
3627 @node SMIE Lexer
3628 @subsubsection Defining Tokens
3629 @cindex SMIE lexer
3630 @cindex defining tokens, SMIE
3632 SMIE comes with a predefined lexical analyzer which uses syntax tables
3633 in the following way: any sequence of characters that have word or
3634 symbol syntax is considered a token, and so is any sequence of
3635 characters that have punctuation syntax.  This default lexer is
3636 often a good starting point but is rarely actually correct for any given
3637 language.  For example, it will consider @code{"2,+3"} to be composed
3638 of 3 tokens: @code{"2"}, @code{",+"}, and @code{"3"}.
3640 To describe the lexing rules of your language to SMIE, you need
3641 2 functions, one to fetch the next token, and another to fetch the
3642 previous token.  Those functions will usually first skip whitespace and
3643 comments and then look at the next chunk of text to see if it
3644 is a special token.  If so it should skip the token and
3645 return a description of this token.  Usually this is simply the string
3646 extracted from the buffer, but it can be anything you want.
3647 For example:
3648 @example
3649 @group
3650 (defvar sample-keywords-regexp
3651   (regexp-opt '("+" "*" "," ";" ">" ">=" "<" "<=" ":=" "=")))
3652 @end group
3653 @group
3654 (defun sample-smie-forward-token ()
3655   (forward-comment (point-max))
3656   (cond
3657    ((looking-at sample-keywords-regexp)
3658     (goto-char (match-end 0))
3659     (match-string-no-properties 0))
3660    (t (buffer-substring-no-properties
3661        (point)
3662        (progn (skip-syntax-forward "w_")
3663               (point))))))
3664 @end group
3665 @group
3666 (defun sample-smie-backward-token ()
3667   (forward-comment (- (point)))
3668   (cond
3669    ((looking-back sample-keywords-regexp (- (point) 2) t)
3670     (goto-char (match-beginning 0))
3671     (match-string-no-properties 0))
3672    (t (buffer-substring-no-properties
3673        (point)
3674        (progn (skip-syntax-backward "w_")
3675               (point))))))
3676 @end group
3677 @end example
3679 Notice how those lexers return the empty string when in front of
3680 parentheses.  This is because SMIE automatically takes care of the
3681 parentheses defined in the syntax table.  More specifically if the lexer
3682 returns nil or an empty string, SMIE tries to handle the corresponding
3683 text as a sexp according to syntax tables.
3685 @node SMIE Tricks
3686 @subsubsection Living With a Weak Parser
3688 The parsing technique used by SMIE does not allow tokens to behave
3689 differently in different contexts.  For most programming languages, this
3690 manifests itself by precedence conflicts when converting the
3691 BNF grammar.
3693 Sometimes, those conflicts can be worked around by expressing the
3694 grammar slightly differently.  For example, for Modula-2 it might seem
3695 natural to have a BNF grammar that looks like this:
3697 @example
3698   ...
3699   (inst ("IF" exp "THEN" insts "ELSE" insts "END")
3700         ("CASE" exp "OF" cases "END")
3701         ...)
3702   (cases (cases "|" cases)
3703          (caselabel ":" insts)
3704          ("ELSE" insts))
3705   ...
3706 @end example
3708 But this will create conflicts for @code{"ELSE"}: on the one hand, the
3709 IF rule implies (among many other things) that @code{"ELSE" = "END"};
3710 but on the other hand, since @code{"ELSE"} appears within @code{cases},
3711 which appears left of @code{"END"}, we also have @code{"ELSE" > "END"}.
3712 We can solve the conflict either by using:
3713 @example
3714   ...
3715   (inst ("IF" exp "THEN" insts "ELSE" insts "END")
3716         ("CASE" exp "OF" cases "END")
3717         ("CASE" exp "OF" cases "ELSE" insts "END")
3718         ...)
3719   (cases (cases "|" cases) (caselabel ":" insts))
3720   ...
3721 @end example
3723 @example
3724   ...
3725   (inst ("IF" exp "THEN" else "END")
3726         ("CASE" exp "OF" cases "END")
3727         ...)
3728   (else (insts "ELSE" insts))
3729   (cases (cases "|" cases) (caselabel ":" insts) (else))
3730   ...
3731 @end example
3733 Reworking the grammar to try and solve conflicts has its downsides, tho,
3734 because SMIE assumes that the grammar reflects the logical structure of
3735 the code, so it is preferable to keep the BNF closer to the intended
3736 abstract syntax tree.
3738 Other times, after careful consideration you may conclude that those
3739 conflicts are not serious and simply resolve them via the
3740 @var{resolvers} argument of @code{smie-bnf->prec2}.  Usually this is
3741 because the grammar is simply ambiguous: the conflict does not affect
3742 the set of programs described by the grammar, but only the way those
3743 programs are parsed.  This is typically the case for separators and
3744 associative infix operators, where you want to add a resolver like
3745 @code{'((assoc "|"))}.  Another case where this can happen is for the
3746 classic @emph{dangling else} problem, where you will use @code{'((assoc
3747 "else" "then"))}.  It can also happen for cases where the conflict is
3748 real and cannot really be resolved, but it is unlikely to pose a problem
3749 in practice.
3751 Finally, in many cases some conflicts will remain despite all efforts to
3752 restructure the grammar.  Do not despair: while the parser cannot be
3753 made more clever, you can make the lexer as smart as you want.  So, the
3754 solution is then to look at the tokens involved in the conflict and to
3755 split one of those tokens into 2 (or more) different tokens.  E.g., if
3756 the grammar needs to distinguish between two incompatible uses of the
3757 token @code{"begin"}, make the lexer return different tokens (say
3758 @code{"begin-fun"} and @code{"begin-plain"}) depending on which kind of
3759 @code{"begin"} it finds.  This pushes the work of distinguishing the
3760 different cases to the lexer, which will thus have to look at the
3761 surrounding text to find ad-hoc clues.
3763 @node SMIE Indentation
3764 @subsubsection Specifying Indentation Rules
3765 @cindex indentation rules, SMIE
3767 Based on the provided grammar, SMIE will be able to provide automatic
3768 indentation without any extra effort.  But in practice, this default
3769 indentation style will probably not be good enough.  You will want to
3770 tweak it in many different cases.
3772 SMIE indentation is based on the idea that indentation rules should be
3773 as local as possible.  To this end, it relies on the idea of
3774 @emph{virtual} indentation, which is the indentation that a particular
3775 program point would have if it were at the beginning of a line.
3776 Of course, if that program point is indeed at the beginning of a line,
3777 its virtual indentation is its current indentation.  But if not, then
3778 SMIE uses the indentation algorithm to compute the virtual indentation
3779 of that point.  Now in practice, the virtual indentation of a program
3780 point does not have to be identical to the indentation it would have if
3781 we inserted a newline before it.  To see how this works, the SMIE rule
3782 for indentation after a @code{@{} in C does not care whether the
3783 @code{@{} is standing on a line of its own or is at the end of the
3784 preceding line.  Instead, these different cases are handled in the
3785 indentation rule that decides how to indent before a @code{@{}.
3787 Another important concept is the notion of @emph{parent}: The
3788 @emph{parent} of a token, is the head token of the nearest enclosing
3789 syntactic construct.  For example, the parent of an @code{else} is the
3790 @code{if} to which it belongs, and the parent of an @code{if}, in turn,
3791 is the lead token of the surrounding construct.  The command
3792 @code{backward-sexp} jumps from a token to its parent, but there are
3793 some caveats: for @emph{openers} (tokens which start a construct, like
3794 @code{if}), you need to start with point before the token, while for
3795 others you need to start with point after the token.
3796 @code{backward-sexp} stops with point before the parent token if that is
3797 the @emph{opener} of the token of interest, and otherwise it stops with
3798 point after the parent token.
3800 SMIE indentation rules are specified using a function that takes two
3801 arguments @var{method} and @var{arg} where the meaning of @var{arg} and the
3802 expected return value depend on @var{method}.
3804 @var{method} can be:
3805 @itemize
3806 @item
3807 @code{:after}, in which case @var{arg} is a token and the function
3808 should return the @var{offset} to use for indentation after @var{arg}.
3809 @item
3810 @code{:before}, in which case @var{arg} is a token and the function
3811 should return the @var{offset} to use to indent @var{arg} itself.
3812 @item
3813 @code{:elem}, in which case the function should return either the offset
3814 to use to indent function arguments (if @var{arg} is the symbol
3815 @code{arg}) or the basic indentation step (if @var{arg} is the symbol
3816 @code{basic}).
3817 @item
3818 @code{:list-intro}, in which case @var{arg} is a token and the function
3819 should return non-@code{nil} if the token is followed by a list of
3820 expressions (not separated by any token) rather than an expression.
3821 @end itemize
3823 When @var{arg} is a token, the function is called with point just before
3824 that token.  A return value of nil always means to fallback on the
3825 default behavior, so the function should return nil for arguments it
3826 does not expect.
3828 @var{offset} can be:
3829 @itemize
3830 @item
3831 @code{nil}: use the default indentation rule.
3832 @item
3833 @code{(column . @var{column})}: indent to column @var{column}.
3834 @item
3835 @var{number}: offset by @var{number}, relative to a base token which is
3836 the current token for @code{:after} and its parent for @code{:before}.
3837 @end itemize
3839 @node SMIE Indentation Helpers
3840 @subsubsection Helper Functions for Indentation Rules
3842 SMIE provides various functions designed specifically for use in the
3843 indentation rules function (several of those functions break if used in
3844 another context).  These functions all start with the prefix
3845 @code{smie-rule-}.
3847 @defun smie-rule-bolp
3848 Return non-@code{nil} if the current token is the first on the line.
3849 @end defun
3851 @defun smie-rule-hanging-p
3852 Return non-@code{nil} if the current token is @emph{hanging}.
3853 A token is @emph{hanging} if it is the last token on the line
3854 and if it is preceded by other tokens: a lone token on a line is not
3855 hanging.
3856 @end defun
3858 @defun smie-rule-next-p &rest tokens
3859 Return non-@code{nil} if the next token is among @var{tokens}.
3860 @end defun
3862 @defun smie-rule-prev-p &rest tokens
3863 Return non-@code{nil} if the previous token is among @var{tokens}.
3864 @end defun
3866 @defun smie-rule-parent-p &rest parents
3867 Return non-@code{nil} if the current token's parent is among @var{parents}.
3868 @end defun
3870 @defun smie-rule-sibling-p
3871 Return non-@code{nil} if the current token's parent is actually a
3872 sibling.  This is the case for example when the parent of a @code{","}
3873 is just the previous @code{","}.
3874 @end defun
3876 @defun smie-rule-parent &optional offset
3877 Return the proper offset to align the current token with the parent.
3878 If non-@code{nil}, @var{offset} should be an integer giving an
3879 additional offset to apply.
3880 @end defun
3882 @defun smie-rule-separator method
3883 Indent current token as a @emph{separator}.
3885 By @emph{separator}, we mean here a token whose sole purpose is to
3886 separate various elements within some enclosing syntactic construct, and
3887 which does not have any semantic significance in itself (i.e., it would
3888 typically not exist as a node in an abstract syntax tree).
3890 Such a token is expected to have an associative syntax and be closely
3891 tied to its syntactic parent.  Typical examples are @code{","} in lists
3892 of arguments (enclosed inside parentheses), or @code{";"} in sequences
3893 of instructions (enclosed in a @code{@{...@}} or @code{begin...end}
3894 block).
3896 @var{method} should be the method name that was passed to
3897 `smie-rules-function'.
3898 @end defun
3900 @node SMIE Indentation Example
3901 @subsubsection Sample Indentation Rules
3903 Here is an example of an indentation function:
3905 @example
3906 (defun sample-smie-rules (kind token)
3907   (pcase (cons kind token)
3908     (`(:elem . basic) sample-indent-basic)
3909     (`(,_ . ",") (smie-rule-separator kind))
3910     (`(:after . ":=") sample-indent-basic)
3911     (`(:before . ,(or `"begin" `"(" `"@{")))
3912      (if (smie-rule-hanging-p) (smie-rule-parent)))
3913     (`(:before . "if")
3914      (and (not (smie-rule-bolp)) (smie-rule-prev-p "else")
3915           (smie-rule-parent)))))
3916 @end example
3918 @noindent
3919 A few things to note:
3921 @itemize
3922 @item
3923 The first case indicates the basic indentation increment to use.
3924 If @code{sample-indent-basic} is nil, then SMIE uses the global
3925 setting @code{smie-indent-basic}.  The major mode could have set
3926 @code{smie-indent-basic} buffer-locally instead, but that
3927 is discouraged.
3929 @item
3930 The rule for the token @code{","} make SMIE try to be more clever when
3931 the comma separator is placed at the beginning of lines.  It tries to
3932 outdent the separator so as to align the code after the comma; for
3933 example:
3935 @example
3936 x = longfunctionname (
3937         arg1
3938       , arg2
3939     );
3940 @end example
3942 @item
3943 The rule for indentation after @code{":="} exists because otherwise
3944 SMIE would treat @code{":="} as an infix operator and would align the
3945 right argument with the left one.
3947 @item
3948 The rule for indentation before @code{"begin"} is an example of the use
3949 of virtual indentation:  This rule is used only when @code{"begin"} is
3950 hanging, which can happen only when @code{"begin"} is not at the
3951 beginning of a line.  So this is not used when indenting
3952 @code{"begin"} itself but only when indenting something relative to this
3953 @code{"begin"}.  Concretely, this rule changes the indentation from:
3955 @example
3956     if x > 0 then begin
3957             dosomething(x);
3958         end
3959 @end example
3961 @example
3962     if x > 0 then begin
3963         dosomething(x);
3964     end
3965 @end example
3967 @item
3968 The rule for indentation before @code{"if"} is similar to the one for
3969 @code{"begin"}, but where the purpose is to treat @code{"else if"}
3970 as a single unit, so as to align a sequence of tests rather than indent
3971 each test further to the right.  This function does this only in the
3972 case where the @code{"if"} is not placed on a separate line, hence the
3973 @code{smie-rule-bolp} test.
3975 If we know that the @code{"else"} is always aligned with its @code{"if"}
3976 and is always at the beginning of a line, we can use a more efficient
3977 rule:
3978 @example
3979 ((equal token "if")
3980  (and (not (smie-rule-bolp))
3981       (smie-rule-prev-p "else")
3982       (save-excursion
3983         (sample-smie-backward-token)
3984         (cons 'column (current-column)))))
3985 @end example
3987 The advantage of this formulation is that it reuses the indentation of
3988 the previous @code{"else"}, rather than going all the way back to the
3989 first @code{"if"} of the sequence.
3990 @end itemize
3992 @node Desktop Save Mode
3993 @section Desktop Save Mode
3994 @cindex desktop save mode
3996 @dfn{Desktop Save Mode} is a feature to save the state of Emacs from
3997 one session to another.  The user-level commands for using Desktop
3998 Save Mode are described in the GNU Emacs Manual (@pxref{Saving Emacs
3999 Sessions,,, emacs, the GNU Emacs Manual}).  Modes whose buffers visit
4000 a file, don't have to do anything to use this feature.
4002 For buffers not visiting a file to have their state saved, the major
4003 mode must bind the buffer local variable @code{desktop-save-buffer} to
4004 a non-@code{nil} value.
4006 @defvar desktop-save-buffer
4007 If this buffer-local variable is non-@code{nil}, the buffer will have
4008 its state saved in the desktop file at desktop save.  If the value is
4009 a function, it is called at desktop save with argument
4010 @var{desktop-dirname}, and its value is saved in the desktop file along
4011 with the state of the buffer for which it was called.  When file names
4012 are returned as part of the auxiliary information, they should be
4013 formatted using the call
4015 @example
4016 (desktop-file-name @var{file-name} @var{desktop-dirname})
4017 @end example
4019 @end defvar
4021 For buffers not visiting a file to be restored, the major mode must
4022 define a function to do the job, and that function must be listed in
4023 the alist @code{desktop-buffer-mode-handlers}.
4025 @defvar desktop-buffer-mode-handlers
4026 Alist with elements
4028 @example
4029 (@var{major-mode} . @var{restore-buffer-function})
4030 @end example
4032 The function @var{restore-buffer-function} will be called with
4033 argument list
4035 @example
4036 (@var{buffer-file-name} @var{buffer-name} @var{desktop-buffer-misc})
4037 @end example
4039 and it should return the restored buffer.
4040 Here @var{desktop-buffer-misc} is the value returned by the function
4041 optionally bound to @code{desktop-save-buffer}.
4042 @end defvar