Major and Minor Modes
*********************

A mode is a set of definitions that customize Emacs and can be turned on and off while you edit.  There are two varieties of modes: major modes, which are mutually exclusive and used for editing particular kinds of text, and minor modes, which provide features that users can enable individually.

This chapter describes how to write both major and minor modes, how to indicate them in the mode line, and how they run hooks supplied by the user.  For related topics such as keymaps and syntax tables, see Keymaps, and Syntax Tables.

Hooks
=====

A hook is a variable where you can store a function or functions to be called on a particular occasion by an existing program.  Emacs provides hooks for the sake of customization.  Most often, hooks are set up in the init file (see Init File), but Lisp programs can set them also. See Standard Hooks, for a list of standard hook variables.

Most of the hooks in Emacs are normal hooks.  These variables contain lists of functions to be called with no arguments.  When the hook name ends in -hook, that tells you it is normal.  We try to make all hooks normal, as much as possible, so that you can use them in a uniform way.

Every major mode function is supposed to run a normal hook called the mode hook as the last step of initialization.  This makes it easy for a user to customize the behavior of the mode, by overriding the buffer-local variable assignments already made by the mode.  Most minor modes also run a mode hook at their end.  But hooks are used in other contexts too.  For example, the hook suspend-hook runs just before Emacs suspends itself (see Suspending Emacs).

The recommended way to add a hook function to a normal hook is by calling add-hook (see below).  The hook functions may be any of the valid kinds of functions that funcall accepts (see What Is a Function).  Most normal hook variables are initially void; add-hook knows how to deal with this.  You can add hooks either globally or buffer-locally with add-hook.

If the hook variable's name does not end with -hook, that indicates it is probably an abnormal hook.  Then you should look at its documentation to see how to use the hook properly.

If the variable's name ends in -functions or -hooks, then the value is a list of functions, but it is abnormal in that either these functions are called with arguments or their values are used in some way.  You can use add-hook to add a function to the list, but you must take care in writing the function.  (A few of these variables, notably those ending in -hooks, are actually normal hooks which were named before we established the convention of using -hook for them.)

If the variable's name ends in -function, then its value is just a single function, not a list of functions.

Here's an example that uses a mode hook to turn on Auto Fill mode when in Lisp Interaction mode:

     (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)

At the appropriate time, Emacs uses the run-hooks function to run particular hooks.

 -- Function: run-hooks &rest hookvars
     This function takes one or more normal hook variable names as arguments, and runs each hook in turn.  Each argument should be a symbol that is a normal hook variable.  These arguments are processed in the order specified.

     If a hook variable has a non-nil value, that value may be a function or a list of functions.  (The former option is considered obsolete.)  If the value is a function (either a lambda expression or a symbol with a function definition), it is called.  If it is a list that isn't a function, its elements are called, consecutively.  All the hook functions are called with no arguments.

 -- Function: run-hook-with-args hook &rest args
     This function is the way to run an abnormal hook and always call all of the hook functions.  It calls each of the hook functions one by one, passing each of them the arguments ARGS.

 -- Function: run-hook-with-args-until-failure hook &rest args
     This function is the way to run an abnormal hook until one of the hook functions fails.  It calls each of the hook functions, passing each of them the arguments ARGS, until some hook function returns nil.  It then stops and returns nil.  If none of the hook functions return nil, it returns a non-nil value.

 -- Function: run-hook-with-args-until-success hook &rest args
     This function is the way to run an abnormal hook until a hook function succeeds.  It calls each of the hook functions, passing each of them the arguments ARGS, until some hook function returns non-nil.  Then it stops, and returns whatever was returned by the last hook function that was called.  If all hook functions return nil, it returns nil as well.

 -- Function: add-hook hook function &optional append local
     This function is the handy way to add function FUNCTION to hook variable HOOK.  You can use it for abnormal hooks as well as for normal hooks.  FUNCTION can be any Lisp function that can accept the proper number of arguments for HOOK.  For example,

          (add-hook 'text-mode-hook 'my-text-hook-function)

     adds my-text-hook-function to the hook called text-mode-hook.

     If FUNCTION is already present in HOOK (comparing using equal), then add-hook does not add it a second time.

     It is best to design your hook functions so that the order in which they are executed does not matter.  Any dependence on the order is ``asking for trouble''.  However, the order is predictable: normally, FUNCTION goes at the front of the hook list, so it will be executed first (barring another add-hook call).  If the optional argument APPEND is non-nil, the new hook function goes at the end of the hook list and will be executed last.

     add-hook can handle the cases where HOOK is void or its value is a single function; it sets or changes the value to a list of functions.

     If LOCAL is non-nil, that says to add FUNCTION to the buffer-local hook list instead of to the global hook list.  If needed, this makes the hook buffer-local and adds t to the buffer-local value.  The latter acts as a flag to run the hook functions in the default value as well as in the local value.

 -- Function: remove-hook hook function &optional local
     This function removes FUNCTION from the hook variable HOOK.  It compares FUNCTION with elements of HOOK using equal, so it works for both symbols and lambda expressions.

     If LOCAL is non-nil, that says to remove FUNCTION from the buffer-local hook list instead of from the global hook list.

Major Modes
===========

Major modes specialize Emacs for editing particular kinds of text. Each buffer has only one major mode at a time.  For each major mode there is a function to switch to that mode in the current buffer; its name should end in -mode.  These functions work by setting buffer-local variable bindings and other data associated with the buffer, such as a local keymap.  The effect lasts until you switch to another major mode in the same buffer.

Major Mode Basics
-----------------

The least specialized major mode is called Fundamental mode. This mode has no mode-specific definitions or variable settings, so each Emacs command behaves in its default manner, and each option is in its default state.  All other major modes redefine various keys and options. For example, Lisp Interaction mode provides special key bindings for C-j (eval-print-last-sexp), TAB (lisp-indent-line), and other keys.

When you need to write several editing commands to help you perform a specialized editing task, creating a new major mode is usually a good idea.  In practice, writing a major mode is easy (in contrast to writing a minor mode, which is often difficult).

If the new mode is similar to an old one, it is often unwise to modify the old one to serve two purposes, since it may become harder to use and maintain.  Instead, copy and rename an existing major mode definition and alter the copy---or define a derived mode (see Derived Modes).  For example, Rmail Edit mode, which is in emacs/lisp/mail/rmailedit.el, is a major mode that is very similar to Text mode except that it provides two additional commands.  Its definition is distinct from that of Text mode, but uses that of Text mode.

Even if the new mode is not an obvious derivative of any other mode, it is convenient to use define-derived-mode with a nil parent argument, since it automatically enforces the most important coding conventions for you.

For a very simple programming language major mode that handles comments and fontification, you can use define-generic-mode. See Generic Modes.

Rmail Edit mode offers an example of changing the major mode temporarily for a buffer, so it can be edited in a different way (with ordinary Emacs commands rather than Rmail commands).  In such cases, the temporary major mode usually provides a command to switch back to the buffer's usual mode (Rmail mode, in this case).  You might be tempted to present the temporary redefinitions inside a recursive edit and restore the usual ones when the user exits; but this is a bad idea because it constrains the user's options when it is done in more than one buffer: recursive edits must be exited most-recently-entered first.  Using an alternative major mode avoids this limitation.  See Recursive Editing.

The standard GNU Emacs Lisp library directory tree contains the code for several major modes, in files such as text-mode.el, texinfo.el, lisp-mode.el, c-mode.el, and rmail.el.  They are found in various subdirectories of the lisp directory.  You can study these libraries to see how modes are written.  Text mode is perhaps the simplest major mode aside from Fundamental mode.  Rmail mode is a complicated and specialized mode.

Major Mode Conventions
----------------------

The code for existing major modes follows various coding conventions, including conventions for local keymap and syntax table initialization, global names, and hooks.  Please follow these conventions when you define a new major mode.

This list of conventions is only partial, because each major mode should aim for consistency in general with other Emacs major modes. This makes Emacs as a whole more coherent.  It is impossible to list here all the possible points where this issue might come up; if the Emacs developers point out an area where your major mode deviates from the usual conventions, please make it compatible.

  * Define a command whose name ends in -mode, with no arguments, that switches to the new mode in the current buffer.  This command should set up the keymap, syntax table, and buffer-local variables in an existing buffer, without changing the buffer's contents.

  * Write a documentation string for this command that describes the special commands available in this mode.  C-h m (describe-mode) in your mode will display this string.

     The documentation string may include the special documentation substrings, \[COMMAND], \{KEYMAP}, and \<KEYMAP>, which enable the documentation to adapt automatically to the user's own key bindings.  See Keys in Documentation.

  * The major mode command should start by calling kill-all-local-variables.  This is what gets rid of the buffer-local variables of the major mode previously in effect.

  * The major mode command should set the variable major-mode to the major mode command symbol.  This is how describe-mode discovers which documentation to print.

  * The major mode command should set the variable mode-name to the ``pretty'' name of the mode, as a string.  This string appears in the mode line.

  * Since all global names are in the same name space, all the global variables, constants, and functions that are part of the mode should have names that start with the major mode name (or with an abbreviation of it if the name is long).  See Coding Conventions.

  * In a major mode for editing some kind of structured text, such as a programming language, indentation of text according to structure is probably useful.  So the mode should set indent-line-function to a suitable function, and probably customize other variables for indentation.

  * The major mode should usually have its own keymap, which is used as the local keymap in all buffers in that mode.  The major mode command should call use-local-map to install this local map.  See Active Keymaps, for more information.

     This keymap should be stored permanently in a global variable named MODENAME-mode-map.  Normally the library that defines the mode sets this variable.

     See Tips for Defining, for advice about how to write the code to set up the mode's keymap variable.

  * The key sequences bound in a major mode keymap should usually start with C-c, followed by a control character, a digit, or {, }, <, >, : or ;.  The other punctuation characters are reserved for minor modes, and ordinary letters are reserved for users.

     A major mode can also rebind the keys M-n, M-p and M-s.  The bindings for M-n and M-p should normally be some kind of ``moving forward and backward,'' but this does not necessarily mean cursor motion.

     It is legitimate for a major mode to rebind a standard key sequence if it provides a command that does ``the same job'' in a way better suited to the text this mode is used for.  For example, a major mode for editing a programming language might redefine C-M-a to ``move to the beginning of a function'' in a way that works better for that language.

     It is also legitimate for a major mode to rebind a standard key sequence whose standard meaning is rarely useful in that mode.  For instance, minibuffer modes rebind M-r, whose standard meaning is rarely of any use in the minibuffer.  Major modes such as Dired or Rmail that do not allow self-insertion of text can reasonably redefine letters and other printing characters as special commands.

  * Major modes must not define RET to do anything other than insert a newline.  The command to insert a newline and then indent is C-j.  Please keep this distinction uniform for all major modes.

  * Major modes should not alter options that are primarily a matter of user preference, such as whether Auto-Fill mode is enabled.  Leave this to each user to decide.  However, a major mode should customize other variables so that Auto-Fill mode will work usefully if the user decides to use it.

  * The mode may have its own syntax table or may share one with other related modes.  If it has its own syntax table, it should store this in a variable named MODENAME-mode-syntax-table.  See Syntax Tables.

  * If the mode handles a language that has a syntax for comments, it should set the variables that define the comment syntax.  See Options Controlling Comments (The GNU Emacs Manual).

  * The mode may have its own abbrev table or may share one with other related modes.  If it has its own abbrev table, it should store this in a variable named MODENAME-mode-abbrev-table.  If the major mode command defines any abbrevs itself, it should pass t for the SYSTEM-FLAG argument to define-abbrev. See Defining Abbrevs.

  * The mode should specify how to do highlighting for Font Lock mode, by setting up a buffer-local value for the variable font-lock-defaults (see Font Lock Mode).

  * The mode should specify how Imenu should find the definitions or sections of a buffer, by setting up a buffer-local value for the variable imenu-generic-expression, for the two variables imenu-prev-index-position-function and imenu-extract-index-name-function, or for the variable imenu-create-index-function (see Imenu).

  * The mode can specify a local value for eldoc-documentation-function to tell ElDoc mode how to handle this mode.

  * Use defvar or defcustom to set mode-related variables, so that they are not reinitialized if they already have a value.  (Such reinitialization could discard customizations made by the user.)

  * To make a buffer-local binding for an Emacs customization variable, use make-local-variable in the major mode command, not make-variable-buffer-local.  The latter function would make the variable local to every buffer in which it is subsequently set, which would affect buffers that do not use this mode.  It is undesirable for a mode to have such global effects.  See Buffer-Local Variables.

     With rare exceptions, the only reasonable way to use make-variable-buffer-local in a Lisp package is for a variable which is used only within that package.  Using it on a variable used by other packages would interfere with them.

  * Each major mode should have a mode hook named MODENAME-mode-hook.  The major mode command should run that hook, with run-mode-hooks, as the very last thing it does.  See Mode Hooks.

  * The major mode command may start by calling some other major mode command (called the parent mode) and then alter some of its settings.  A mode that does this is called a derived mode.  The recommended way to define one is to use define-derived-mode, but this is not required.  Such a mode should call the parent mode command inside a delay-mode-hooks form.  (Using define-derived-mode does this automatically.)  See Derived Modes, and Mode Hooks.

  * If something special should be done if the user switches a buffer from this mode to any other major mode, this mode can set up a buffer-local value for change-major-mode-hook (see Creating Buffer-Local).

  * If this mode is appropriate only for specially-prepared text, then the major mode command symbol should have a property named mode-class with value special, put on as follows:

          (put 'funny-mode 'mode-class 'special)

     This tells Emacs that new buffers created while the current buffer is in Funny mode should not inherit Funny mode, in case default-major-mode is nil.  Modes such as Dired, Rmail, and Buffer List use this feature.

  * If you want to make the new mode the default for files with certain recognizable names, add an element to auto-mode-alist to select the mode for those file names (see Auto Major Mode).  If you define the mode command to autoload, you should add this element in the same file that calls autoload.  If you use an autoload cookie for the mode command, you can also use an autoload cookie for the form that adds the element (see autoload cookie).  If you do not autoload the mode command, it is sufficient to add the element in the file that contains the mode definition.

  * In the comments that document the file, you should provide a sample autoload form and an example of how to add to auto-mode-alist, that users can include in their init files (see Init File).

  * The top-level forms in the file defining the mode should be written so that they may be evaluated more than once without adverse consequences. Even if you never load the file more than once, someone else will.

Major Mode Examples
-------------------

Text mode is perhaps the simplest mode besides Fundamental mode. Here are excerpts from  text-mode.el that illustrate many of the conventions listed above:

     ;; Create the syntax table for this mode.
     (defvar text-mode-syntax-table
       (let ((st (make-syntax-table)))
         (modify-syntax-entry ?\" ".   " st)
         (modify-syntax-entry ?\\ ".   " st)
         ;; We add `p' so that M-c on 'hello' leads to 'Hello' rather than 'hello'.
         (modify-syntax-entry ?' "w p" st)
         st)
       "Syntax table used while in `text-mode'.")

     ;; Create the keymap for this mode.

     (defvar text-mode-map
       (let ((map (make-sparse-keymap)))
         (define-key map "\e\t" 'ispell-complete-word)
         (define-key map "\es" 'center-line)
         (define-key map "\eS" 'center-paragraph)
         map)
       "Keymap for `text-mode'.
     Many other modes, such as `mail-mode', `outline-mode' and `indented-text-mode',
     inherit all the commands defined in this map.")

Here is how the actual mode command is defined now:

     (define-derived-mode text-mode nil "Text"
       "Major mode for editing text written for humans to read.
     In this mode, paragraphs are delimited only by blank or white lines.
     You can thus get the full benefit of adaptive filling
      (see the variable `adaptive-fill-mode').
     \\{text-mode-map}
     Turning on Text mode runs the normal hook `text-mode-hook'."

       (make-local-variable 'text-mode-variant)
       (setq text-mode-variant t)
       ;; These two lines are a feature added recently.
       (set (make-local-variable 'require-final-newline)
            mode-require-final-newline)
       (set (make-local-variable 'indent-line-function) 'indent-relative))

But here is how it was defined formerly, before define-derived-mode existed:

     ;; This isn't needed nowadays, since define-derived-mode does it.
     (defvar text-mode-abbrev-table nil
       "Abbrev table used while in text mode.")
     (define-abbrev-table 'text-mode-abbrev-table ())

     (defun text-mode ()
       "Major mode for editing text intended for humans to read...
      Special commands: \\{text-mode-map}

     Turning on text-mode runs the hook `text-mode-hook'."
       (interactive)
       (kill-all-local-variables)
       (use-local-map text-mode-map)

       (setq local-abbrev-table text-mode-abbrev-table)
       (set-syntax-table text-mode-syntax-table)

       ;; These four lines are absent from the current version
       ;; not because this is done some other way, but rather
       ;; because nowadays Text mode uses the normal definition of paragraphs.
       (make-local-variable 'paragraph-start)
       (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter))
       (make-local-variable 'paragraph-separate)
       (setq paragraph-separate paragraph-start)
       (make-local-variable 'indent-line-function)
       (setq indent-line-function 'indent-relative-maybe)

       (setq mode-name "Text")
       (setq major-mode 'text-mode)
       (run-mode-hooks 'text-mode-hook)) ; Finally, this permits the user to
                                         ;   customize the mode with a hook.

The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp Interaction mode) have more features than Text mode and the code is correspondingly more complicated.  Here are excerpts from lisp-mode.el that illustrate how these modes are written.

     ;; Create mode-specific table variables.
     (defvar lisp-mode-syntax-table nil "")
     (defvar lisp-mode-abbrev-table nil "")

     (defvar emacs-lisp-mode-syntax-table
       (let ((table (make-syntax-table)))
         (let ((i 0))

           ;; Set syntax of chars up to 0 to say they are
           ;;   part of symbol names but not words.
           ;;   (The digit 0 is 48 in the ASCII character set.)
           (while (< i ?0)
     	(modify-syntax-entry i "_   " table)
     	(setq i (1+ i)))
           ;; ... similar code follows for other character ranges.

           ;; Then set the syntax codes for characters that are special in Lisp.
           (modify-syntax-entry ?  "    " table)
           (modify-syntax-entry ?\t "    " table)
           (modify-syntax-entry ?\f "    " table)
           (modify-syntax-entry ?\n ">   " table)

           ;; Give CR the same syntax as newline, for selective-display.
           (modify-syntax-entry ?\^m ">   " table)
           (modify-syntax-entry ?\; "<   " table)
           (modify-syntax-entry ?` "'   " table)
           (modify-syntax-entry ?' "'   " table)
           (modify-syntax-entry ?, "'   " table)

           ;; ...likewise for many other characters...
           (modify-syntax-entry ?\( "()  " table)
           (modify-syntax-entry ?\) ")(  " table)
           (modify-syntax-entry ?\[ "(]  " table)
           (modify-syntax-entry ?\] ")[  " table))
         table))

     ;; Create an abbrev table for lisp-mode.
     (define-abbrev-table 'lisp-mode-abbrev-table ())

Much code is shared among the three Lisp modes.  The following function sets various variables; it is called by each of the major Lisp mode functions:

     (defun lisp-mode-variables (lisp-syntax)
       (when lisp-syntax
         (set-syntax-table lisp-mode-syntax-table))
       (setq local-abbrev-table lisp-mode-abbrev-table)
       ...

Functions such as forward-paragraph use the value of the paragraph-start variable.  Since Lisp code is different from ordinary text, the paragraph-start variable needs to be set specially to handle Lisp.  Also, comments are indented in a special fashion in Lisp and the Lisp modes need their own mode-specific comment-indent-function.  The code to set these variables is the rest of lisp-mode-variables.

       (make-local-variable 'paragraph-start)
       (setq paragraph-start (concat page-delimiter "\\|$" ))
       (make-local-variable 'paragraph-separate)
       (setq paragraph-separate paragraph-start)
       ...

       (make-local-variable 'comment-indent-function)
       (setq comment-indent-function 'lisp-comment-indent))
       ...

Each of the different Lisp modes has a slightly different keymap.  For example, Lisp mode binds C-c C-z to run-lisp, but the other Lisp modes do not.  However, all Lisp modes have some commands in common.  The following code sets up the common commands:

     (defvar shared-lisp-mode-map ()
       "Keymap for commands shared by all sorts of Lisp modes.")

     ;; Putting this if after the defvar is an older style.
     (if shared-lisp-mode-map
         ()
        (setq shared-lisp-mode-map (make-sparse-keymap))
        (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp)
        (define-key shared-lisp-mode-map "\177"
                    'backward-delete-char-untabify))

And here is the code to set up the keymap for Lisp mode:

     (defvar lisp-mode-map ()
       "Keymap for ordinary Lisp mode...")

     (if lisp-mode-map
         ()
       (setq lisp-mode-map (make-sparse-keymap))
       (set-keymap-parent lisp-mode-map shared-lisp-mode-map)
       (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun)
       (define-key lisp-mode-map "\C-c\C-z" 'run-lisp))

Finally, here is the complete major mode function definition for Lisp mode.

     (defun lisp-mode ()
       "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
     Commands:
     Delete converts tabs to spaces as it moves back.
     Blank lines separate paragraphs.  Semicolons start comments.
     \\{lisp-mode-map}
     Note that `run-lisp' may be used either to start an inferior Lisp job
     or to switch back to an existing one.

     Entry to this mode calls the value of `lisp-mode-hook'
     if that value is non-nil."
       (interactive)
       (kill-all-local-variables)

       (use-local-map lisp-mode-map)          ; Select the mode's keymap.
       (setq major-mode 'lisp-mode)           ; This is how describe-mode
                                              ;   finds out what to describe.
       (setq mode-name "Lisp")                ; This goes into the mode line.
       (lisp-mode-variables t)                ; This defines various variables.
       (make-local-variable 'comment-start-skip)
       (setq comment-start-skip
             "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *")
       (make-local-variable 'font-lock-keywords-case-fold-search)
       (setq font-lock-keywords-case-fold-search t)

       (setq imenu-case-fold-search t)
       (set-syntax-table lisp-mode-syntax-table)
       (run-mode-hooks 'lisp-mode-hook))           ; This permits the user to use a
                                              ;   hook to customize the mode.

How Emacs Chooses a Major Mode
------------------------------

Based on information in the file name or in the file itself, Emacs automatically selects a major mode for the new buffer when a file is visited.  It also processes local variables specified in the file text.

 -- Command: fundamental-mode
     Fundamental mode is a major mode that is not specialized for anything in particular.  Other major modes are defined in effect by comparison with this one---their definitions say what to change, starting from Fundamental mode.  The fundamental-mode function does not run any mode hooks; you're not supposed to customize it.  (If you want Emacs to behave differently in Fundamental mode, change the global state of Emacs.)

 -- Command: normal-mode &optional find-file
     This function establishes the proper major mode and buffer-local variable bindings for the current buffer.  First it calls set-auto-mode (see below), then it runs hack-local-variables to parse, and bind or evaluate as appropriate, the file's local variables (see File Local Variables).

     If the FIND-FILE argument to normal-mode is non-nil, normal-mode assumes that the find-file function is calling it.  In this case, it may process local variables in the -*- line or at the end of the file.  The variable enable-local-variables controls whether to do so.  See Local Variables in Files (The GNU Emacs Manual), for the syntax of the local variables section of a file.

     If you run normal-mode interactively, the argument FIND-FILE is normally nil.  In this case, normal-mode unconditionally processes any file local variables.

     If normal-mode processes the local variables list and this list specifies a major mode, that mode overrides any mode chosen by set-auto-mode.  If neither set-auto-mode nor hack-local-variables specify a major mode, the buffer stays in the major mode determined by default-major-mode (see below).

     normal-mode uses condition-case around the call to the major mode function, so errors are caught and reported as a File mode specification error,  followed by the original error message.

 -- Function: set-auto-mode &optional keep-mode-if-same
     This function selects the major mode that is appropriate for the current buffer.  It bases its decision (in order of precedence) on the -*- line, on the #! line (using interpreter-mode-alist), on the text at the beginning of the buffer (using magic-mode-alist), and finally on the visited file name (using auto-mode-alist).  See How Major Modes are Chosen (The GNU Emacs Manual).  However, this function does not look for the mode: local variable near the end of a file; the hack-local-variables function does that. If enable-local-variables is nil, set-auto-mode does not check the -*- line for a mode tag either.

     If KEEP-MODE-IF-SAME is non-nil, this function does not call the mode command if the buffer is already in the proper major mode.  For instance, set-visited-file-name sets this to t to avoid killing buffer local variables that the user may have set.

 -- User Option: default-major-mode
     This variable holds the default major mode for new buffers.  The standard value is fundamental-mode.

     If the value of default-major-mode is nil, Emacs uses the (previously) current buffer's major mode as the default major mode of a new buffer.  However, if that major mode symbol has a mode-class property with value special, then it is not used for new buffers; Fundamental mode is used instead.  The modes that have this property are those such as Dired and Rmail that are useful only with text that has been specially prepared.

 -- Function: set-buffer-major-mode buffer
     This function sets the major mode of BUFFER to the value of default-major-mode; if that variable is nil, it uses the current buffer's major mode (if that is suitable).  As an exception, if BUFFER's name is *scratch*, it sets the mode to initial-major-mode.

     The low-level primitives for creating buffers do not use this function, but medium-level commands such as switch-to-buffer and find-file-noselect use it whenever they create buffers.

 -- User Option: initial-major-mode
     The value of this variable determines the major mode of the initial *scratch* buffer.  The value should be a symbol that is a major mode command.  The default value is lisp-interaction-mode.

 -- Variable: interpreter-mode-alist
     This variable specifies major modes to use for scripts that specify a command interpreter in a #! line.  Its value is an alist with elements of the form (INTERPRETER . MODE); for example, ("perl" . perl-mode) is one element present by default.  The element says to use mode MODE if the file specifies an interpreter which matches INTERPRETER.

 -- Variable: magic-mode-alist
     This variable's value is an alist with elements of the form (REGEXP .  FUNCTION), where REGEXP is a regular expression and FUNCTION is a function or nil. After visiting a file, set-auto-mode calls FUNCTION if the text at the beginning of the buffer matches REGEXP and FUNCTION is non-nil; if FUNCTION is nil, auto-mode-alist gets to decide the mode.

 -- Variable: auto-mode-alist
     This variable contains an association list of file name patterns (regular expressions) and corresponding major mode commands.  Usually, the file name patterns test for suffixes, such as .el and .c, but this need not be the case.  An ordinary element of the alist looks like (REGEXP .  MODE-FUNCTION).

     For example,

          (("\\`/tmp/fol/" . text-mode)
           ("\\.texinfo\\'" . texinfo-mode)
           ("\\.texi\\'" . texinfo-mode)

           ("\\.el\\'" . emacs-lisp-mode)
           ("\\.c\\'" . c-mode)
           ("\\.h\\'" . c-mode)
           ...)

     When you visit a file whose expanded file name (see File Name Expansion), with version numbers and backup suffixes removed using file-name-sans-versions (see File Name Components), matches a REGEXP, set-auto-mode calls the corresponding MODE-FUNCTION.  This feature enables Emacs to select the proper major mode for most files.

     If an element of auto-mode-alist has the form (REGEXP FUNCTION t), then after calling FUNCTION, Emacs searches auto-mode-alist again for a match against the portion of the file name that did not match before.  This feature is useful for uncompression packages: an entry of the form ("\\.gz\\'" FUNCTION t) can uncompress the file and then put the uncompressed file in the proper mode according to the name sans .gz.

     Here is an example of how to prepend several pattern pairs to auto-mode-alist.  (You might use this sort of expression in your init file.)

          (setq auto-mode-alist
            (append
             ;; File name (within directory) starts with a dot.
             '(("/\\.[^/]*\\'" . fundamental-mode)
               ;; File name has no dot.
               ("[^\\./]*\\'" . fundamental-mode)
               ;; File name ends in .C.
               ("\\.C\\'" . c++-mode))
             auto-mode-alist))

Getting Help about a Major Mode
-------------------------------

The describe-mode function is used to provide information about major modes.  It is normally called with C-h m.  The describe-mode function uses the value of major-mode, which is why every major mode function needs to set the major-mode variable.

 -- Command: describe-mode
     This function displays the documentation of the current major mode.

     The describe-mode function calls the documentation function using the value of major-mode as an argument.  Thus, it displays the documentation string of the major mode function. (see Accessing Documentation.)

 -- Variable: major-mode
     This buffer-local variable holds the symbol for the current buffer's major mode.  This symbol should have a function definition that is the command to switch to that major mode.  The describe-mode function uses the documentation string of the function as the documentation of the major mode.

Defining Derived Modes
----------------------

It's often useful to define a new major mode in terms of an existing one.  An easy way to do this is to use define-derived-mode.

 -- Macro: define-derived-mode variant parent name docstring keyword-args... body...
     This construct defines VARIANT as a major mode command, using NAME as the string form of the mode name.  VARIANT and PARENT should be unquoted symbols.

     The new command VARIANT is defined to call the function PARENT, then override certain aspects of that parent mode:

       * The new mode has its own sparse keymap, named VARIANT-map.  define-derived-mode makes the parent mode's keymap the parent of the new map, unless VARIANT-map is already set and already has a parent.

       * The new mode has its own syntax table, kept in the variable VARIANT-syntax-table, unless you override this using the :syntax-table keyword (see below).  define-derived-mode makes the parent mode's syntax-table the parent of VARIANT-syntax-table, unless the latter is already set and already has a parent different from the standard syntax table.

       * The new mode has its own abbrev table, kept in the variable VARIANT-abbrev-table, unless you override this using the :abbrev-table keyword (see below).

       * The new mode has its own mode hook, VARIANT-hook.  It runs this hook, after running the hooks of its ancestor modes, with run-mode-hooks, as the last thing it does. See Mode Hooks.

     In addition, you can specify how to override other aspects of PARENT with BODY.  The command VARIANT evaluates the forms in BODY after setting up all its usual overrides, just before running the mode hooks.

     You can also specify nil for PARENT.  This gives the new mode no parent.  Then define-derived-mode behaves as described above, but, of course, omits all actions connected with PARENT.

     The argument DOCSTRING specifies the documentation string for the new mode.  define-derived-mode adds some general information about the mode's hook, followed by the mode's keymap, at the end of this docstring.  If you omit DOCSTRING, define-derived-mode generates a documentation string.

     The KEYWORD-ARGS are pairs of keywords and values.  The values are evaluated.  The following keywords are currently supported:

     :syntax-table
          You can use this to explicitly specify a syntax table for the new mode.  If you specify a nil value, the new mode uses the same syntax table as PARENT, or the standard syntax table if PARENT is nil.  (Note that this does not follow the convention used for non-keyword arguments that a nil value is equivalent with not specifying the argument.)

     :abbrev-table
          You can use this to explicitly specify an abbrev table for the new mode.  If you specify a nil value, the new mode uses the same abbrev table as PARENT, or fundamental-mode-abbrev-table if PARENT is nil.  (Again, a nil value is not equivalent to not specifying this keyword.)

     :group
          If this is specified, the value should be the customization group for this mode.  (Not all major modes have one.)  Only the (still experimental and unadvertised) command customize-mode currently uses this.  define-derived-mode does not automatically define the specified customization group.

     Here is a hypothetical example:

          (define-derived-mode hypertext-mode
            text-mode "Hypertext"
            "Major mode for hypertext.
          \\{hypertext-mode-map}"
            (setq case-fold-search nil))

          (define-key hypertext-mode-map
            [down-mouse-3] 'do-hyper-link)

     Do not write an interactive spec in the definition; define-derived-mode does that automatically.

Generic Modes
-------------

Generic modes are simple major modes with basic support for comment syntax and Font Lock mode.  They are primarily useful for configuration files.  To define a generic mode, use the macro define-generic-mode.  See the file generic-x.el for some examples of the use of define-generic-mode.

 -- Macro: define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring
     This macro creates a new generic mode.  The argument MODE (an unquoted symbol) is the major mode command.  The optional argument DOCSTRING is the documentation for the mode command.  If you do not supply it, define-generic-mode uses a default documentation string instead.

     COMMENT-LIST is a list in which each element is either a character, a string of one or two characters, or a cons cell.  A character or a string is set up in the mode's syntax table as a ``comment starter.''  If the entry is a cons cell, the CAR is set up as a ``comment starter'' and the CDR as a ``comment ender.'' (Use nil for the latter if you want comments to end at the end of the line.)  Note that the syntax table has limitations about what comment starters and enders are actually possible.  See Syntax Tables.

     KEYWORD-LIST is a list of keywords to highlight with font-lock-keyword-face.  Each keyword should be a string. FONT-LOCK-LIST is a list of additional expressions to highlight. Each element of this list should have the same form as an element of font-lock-keywords.  See Search-based Fontification.

     AUTO-MODE-LIST is a list of regular expressions to add to the variable auto-mode-alist.  These regular expressions are added when Emacs runs the macro expansion.

     FUNCTION-LIST is a list of functions to call to do some additional setup.  The mode command calls these functions just before it runs the mode hook variable MODE-hook.

Mode Hooks
----------

The two last things a major mode function should do is run its mode hook and finally the mode independent normal hook after-change-major-mode-hook.  If the major mode is a derived mode, that is if it calls another major mode (the parent mode) in its body, then the parent's mode hook is run just before the derived mode's hook.  Neither the parent's mode hook nor after-change-major-mode-hook are run at the end of the actual call to the parent mode.  This applies recursively if the parent mode has itself a parent.  That is, the mode hooks of all major modes called directly or indirectly by the major mode function are all run in sequence at the end, just before after-change-major-mode-hook.

These conventions are new in Emacs 22, and some major modes implemented by users do not follow them yet.  So if you put a function onto after-change-major-mode-hook, keep in mind that some modes will fail to run it.  If a user complains about that, you can respond, ``That major mode fails to follow Emacs conventions, and that's why it fails to work.  Please fix the major mode.''  In most cases, that is good enough, so go ahead and use after-change-major-mode-hook. However, if a certain feature needs to be completely reliable, it should not use after-change-major-mode-hook as of yet.

When you defined a major mode using define-derived-mode, it automatically makes sure these conventions are followed.  If you define a major mode ``from scratch'', not using define-derived-mode, make sure the major mode command follows these and other conventions.  See Major Mode Conventions.  You use these functions to do it properly.

 -- Function: run-mode-hooks &rest hookvars
     Major modes should run their mode hook using this function.  It is similar to run-hooks (see Hooks), but it also runs after-change-major-mode-hook.

     When the call to this function is dynamically inside a delay-mode-hooks form, this function does not run any hooks. Instead, it arranges for the next call to run-mode-hooks to run HOOKVARS.

 -- Macro: delay-mode-hooks body...
     This macro executes BODY like progn, but all calls to run-mode-hooks inside BODY delay running their hooks. They will be run by the first call to run-mode-hooks after exit from delay-mode-hooks.  This is the proper way for a major mode command to invoke its parent mode.

 -- Variable: after-change-major-mode-hook
     Every major mode function should run this normal hook at its very end. It normally does not need to do so explicitly.  Indeed, a major mode function should normally run its mode hook with run-mode-hooks as the very last thing it does, and the last thing run-mode-hooks does is run after-change-major-mode-hook.

Minor Modes
===========

A minor mode provides features that users may enable or disable independently of the choice of major mode.  Minor modes can be enabled individually or in combination.  Minor modes would be better named ``generally available, optional feature modes,'' except that such a name would be unwieldy.

A minor mode is not usually meant as a variation of a single major mode. Usually they are general and can apply to many major modes.  For example, Auto Fill mode works with any major mode that permits text insertion.  To be general, a minor mode must be effectively independent of the things major modes do.

A minor mode is often much more difficult to implement than a major mode.  One reason is that you should be able to activate and deactivate minor modes in any order.  A minor mode should be able to have its desired effect regardless of the major mode and regardless of the other minor modes in effect.

Often the biggest problem in implementing a minor mode is finding a way to insert the necessary hook into the rest of Emacs.  Minor mode keymaps make this easier than it used to be.

 -- Variable: minor-mode-list
     The value of this variable is a list of all minor mode commands.

Conventions for Writing Minor Modes
-----------------------------------

There are conventions for writing minor modes just as there are for major modes.  Several of the major mode conventions apply to minor modes as well: those regarding the name of the mode initialization function, the names of global symbols, the use of a hook at the end of the initialization function, and the use of keymaps and other tables.

In addition, there are several conventions that are specific to minor modes.  (The easiest way to follow all the conventions is to use the macro define-minor-mode; Defining Minor Modes.)

  * Make a variable whose name ends in -mode to control the minor mode.  We call this the mode variable.  The minor mode command should set this variable (nil to disable; anything else to enable).

     If possible, implement the mode so that setting the variable automatically enables or disables the mode.  Then the minor mode command does not need to do anything except set the variable.

     This variable is used in conjunction with the minor-mode-alist to display the minor mode name in the mode line.  It can also enable or disable a minor mode keymap.  Individual commands or hooks can also check the variable's value.

     If you want the minor mode to be enabled separately in each buffer, make the variable buffer-local.

  * Define a command whose name is the same as the mode variable. Its job is to enable and disable the mode by setting the variable.

     The command should accept one optional argument.  If the argument is nil, it should toggle the mode (turn it on if it is off, and off if it is on).  It should turn the mode on if the argument is a positive integer, the symbol t, or a list whose CAR is one of those.  It should turn the mode off if the argument is a negative integer or zero, the symbol -, or a list whose CAR is a negative integer or zero.  The meaning of other arguments is not specified.

     Here is an example taken from the definition of transient-mark-mode. It shows the use of transient-mark-mode as a variable that enables or disables the mode's behavior, and also shows the proper way to toggle, enable or disable the minor mode based on the raw prefix argument value.

          (setq transient-mark-mode
                (if (null arg) (not transient-mark-mode)
                  (> (prefix-numeric-value arg) 0)))

  * Add an element to minor-mode-alist for each minor mode (see Definition of minor-mode-alist), if you want to indicate the minor mode in the mode line.  This element should be a list of the following form:

          (MODE-VARIABLE STRING)

     Here MODE-VARIABLE is the variable that controls enabling of the minor mode, and STRING is a short string, starting with a space, to represent the mode in the mode line.  These strings must be short so that there is room for several of them at once.

     When you add an element to minor-mode-alist, use assq to check for an existing element, to avoid duplication.  For example:

          (unless (assq 'leif-mode minor-mode-alist)
            (setq minor-mode-alist
                  (cons '(leif-mode " Leif") minor-mode-alist)))

     or like this, using add-to-list (see Setting Variables):

          (add-to-list 'minor-mode-alist '(leif-mode " Leif"))

Global minor modes distributed with Emacs should if possible support enabling and disabling via Custom (see Customization).  To do this, the first step is to define the mode variable with defcustom, and specify :type boolean.

If just setting the variable is not sufficient to enable the mode, you should also specify a :set method which enables the mode by invoking the mode command.  Note in the variable's documentation string that setting the variable other than via Custom may not take effect.

Also mark the definition with an autoload cookie (see autoload cookie), and specify a :require so that customizing the variable will load the library that defines the mode.  This will copy suitable definitions into loaddefs.el so that users can use customize-option to enable the mode.  For example:

     ;;;###autoload
     (defcustom msb-mode nil
       "Toggle msb-mode.
     Setting this variable directly does not take effect;
     use either \\[customize] or the function `msb-mode'."
       :set 'custom-set-minor-mode
       :initialize 'custom-initialize-default
       :version "20.4"
       :type    'boolean
       :group   'msb
       :require 'msb)

Keymaps and Minor Modes
-----------------------

Each minor mode can have its own keymap, which is active when the mode is enabled.  To set up a keymap for a minor mode, add an element to the alist minor-mode-map-alist.  See Definition of minor-mode-map-alist.

One use of minor mode keymaps is to modify the behavior of certain self-inserting characters so that they do something else as well as self-insert.  In general, this is the only way to do that, since the facilities for customizing self-insert-command are limited to special cases (designed for abbrevs and Auto Fill mode).  (Do not try substituting your own definition of self-insert-command for the standard one.  The editor command loop handles this function specially.)

The key sequences bound in a minor mode should consist of C-c followed by a punctuation character other than {, }, <, >, :, and ;.  (Those few punctuation characters are reserved for major modes.)

Defining Minor Modes
--------------------

The macro define-minor-mode offers a convenient way of implementing a mode in one self-contained definition.

 -- Macro: define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args... body...
     This macro defines a new minor mode whose name is MODE (a symbol).  It defines a command named MODE to toggle the minor mode, with DOC as its documentation string.  It also defines a variable named MODE, which is set to t or nil by enabling or disabling the mode.  The variable is initialized to INIT-VALUE.  Except in unusual circumstances (see below), this value must be nil.

     The string LIGHTER says what to display in the mode line when the mode is enabled; if it is nil, the mode is not displayed in the mode line.

     The optional argument KEYMAP specifies the keymap for the minor mode. It can be a variable name, whose value is the keymap, or it can be an alist specifying bindings in this form:

          (KEY-SEQUENCE . DEFINITION)

     The above three arguments INIT-VALUE, LIGHTER, and KEYMAP can be (partially) omitted when KEYWORD-ARGS are used.  The KEYWORD-ARGS consist of keywords followed by corresponding values.  A few keywords have special meanings:

     :group GROUP
          Custom group name to use in all generated defcustom forms. Defaults to MODE without the possible trailing -mode. Warning: don't use this default group name unless you have written a defgroup to define that group properly.  See Group Definitions.

     :global GLOBAL
          If non-nil specifies that the minor mode should be global.  By default, minor modes defined with define-minor-mode are buffer-local.

     :init-value INIT-VALUE
          This is equivalent to specifying INIT-VALUE positionally.

     :lighter LIGHTER
          This is equivalent to specifying LIGHTER positionally.

     :keymap KEYMAP
          This is equivalent to specifying KEYMAP positionally.

     Any other keyword arguments are passed directly to the defcustom generated for the variable MODE.

     The command named MODE first performs the standard actions such as setting the variable named MODE and then executes the BODY forms, if any.  It finishes by running the mode hook variable MODE-hook.

The initial value must be nil except in cases where (1) the mode is preloaded in Emacs, or (2) it is painless for loading to enable the mode even though the user did not request it.  For instance, if the mode has no effect unless something else is enabled, and will always be loaded by that time, enabling it by default is harmless.  But these are unusual circumstances.  Normally, the initial value must be nil.

The name easy-mmode-define-minor-mode is an alias for this macro.

Here is an example of using define-minor-mode:

     (define-minor-mode hungry-mode
       "Toggle Hungry mode.
     With no argument, this command toggles the mode.
     Non-null prefix argument turns on the mode.
     Null prefix argument turns off the mode.

     When Hungry mode is enabled, the control delete key
     gobbles all preceding whitespace except the last.
     See the command \\[hungry-electric-delete]."
      ;; The initial value.
      nil
      ;; The indicator for the mode line.
      " Hungry"
      ;; The minor mode bindings.
      '(("\C-\^?" . hungry-electric-delete))
      :group 'hunger)

This defines a minor mode named ``Hungry mode'', a command named hungry-mode to toggle it, a variable named hungry-mode which indicates whether the mode is enabled, and a variable named hungry-mode-map which holds the keymap that is active when the mode is enabled.  It initializes the keymap with a key binding for C-DEL.  It puts the variable hungry-mode into custom group hunger.  There are no BODY forms---many minor modes don't need any.

Here's an equivalent way to write it:

     (define-minor-mode hungry-mode
       "Toggle Hungry mode.
     With no argument, this command toggles the mode.
     Non-null prefix argument turns on the mode.
     Null prefix argument turns off the mode.

     When Hungry mode is enabled, the control delete key
     gobbles all preceding whitespace except the last.
     See the command \\[hungry-electric-delete]."
      ;; The initial value.
      :init-value nil
      ;; The indicator for the mode line.
      :lighter " Hungry"
      ;; The minor mode bindings.
      :keymap
      '(("\C-\^?" . hungry-electric-delete)
        ("\C-\M-\^?"
         . (lambda ()
             (interactive)
             (hungry-electric-delete t))))
      :group 'hunger)

 -- Macro: define-global-minor-mode global-mode mode turn-on keyword-args...
     This defines a global minor mode named GLOBAL-MODE whose meaning is to enable the buffer-local minor mode MODE in every buffer. To turn on the minor mode in a buffer, it uses the function TURN-ON; to turn off the minor mode, it calls mode with -1 as argument.

     Use :group GROUP in KEYWORD-ARGS to specify the custom group for the mode variable of the global minor mode.

Mode-Line Format
================

Each Emacs window (aside from minibuffer windows) typically has a mode line at the bottom, which displays status information about the buffer displayed in the window.  The mode line contains information about the buffer, such as its name, associated file, depth of recursive editing, and major and minor modes.  A window can also have a header line, which is much like the mode line but appears at the top of the window.

This section describes how to control the contents of the mode line and header line.  We include it in this chapter because much of the information displayed in the mode line relates to the enabled major and minor modes.

Mode Line Basics
----------------

mode-line-format is a buffer-local variable that holds a mode line construct, a kind of template, which controls the display the mode line of the current buffer.  All windows for the same buffer use the same mode-line-format, so their mode lines appear the same---except for scrolling percentages, and line and column numbers, since those depend on point and on how the window is scrolled.  The value of header-line-format specifies the buffer's header line in the same way, with a mode line construct.

For efficiency, Emacs does not recompute the mode line and header line of a window in every redisplay.  It does so when circumstances appear to call for it---for instance, if you change the window configuration, switch buffers, narrow or widen the buffer, scroll, or change the buffer's modification status.  If you modify any of the variables referenced by mode-line-format (see Mode Line Variables), or any other variables and data structures that affect how text is displayed (see Display), you may want to force an update of the mode line so as to display the new information or display it in the new way.

 -- Function: force-mode-line-update &optional all
     Force redisplay of the current buffer's mode line and header line. The next redisplay will update the mode line and header line based on the latest values of all relevant variables.  With optional non-nil ALL, force redisplay of all mode lines and header lines.

     This function also forces recomputation of the menu bar menus and the frame title.

The selected window's mode line is usually displayed in a different color using the face mode-line.  Other windows' mode lines appear in the face mode-line-inactive instead.  See Faces.

The Data Structure of the Mode Line
-----------------------------------

The mode-line contents are controlled by a data structure called a mode-line construct, made up of lists, strings, symbols, and numbers kept in buffer-local variables.  Each data type has a specific meaning for the mode-line appearance, as described below.  The same data structure is used for constructing frame titles (see Frame Titles) and header lines (see Header Lines).

A mode-line construct may be as simple as a fixed string of text, but it usually specifies how to combine fixed strings with variables' values to construct the text.  Many of these variables are themselves defined to have mode-line constructs as their values.

Here are the meanings of various data types as mode-line constructs:

STRING
     A string as a mode-line construct appears verbatim in the mode line except for %-constructs in it.  These stand for substitution of other data; see %-Constructs.

     If the string has face properties, they are copied into the mode line contents too (see Properties in Mode).  Any characters in the mode line which have no face properties are displayed, by default, in the face mode-line or mode-line-inactive (see Standard Faces (The GNU Emacs Manual)).

SYMBOL
     A symbol as a mode-line construct stands for its value.  The value of SYMBOL is used as a mode-line construct, in place of SYMBOL. However, the symbols t and nil are ignored, as is any symbol whose value is void.

     There is one exception: if the value of SYMBOL is a string, it is displayed verbatim: the %-constructs are not recognized.

     Unless SYMBOL is marked as ``risky'' (i.e., it has a non-nil risky-local-variable property), all text properties specified in SYMBOL's value are ignored.  This includes the text properties of strings in SYMBOL's value, as well as all :eval and :propertize forms in it.

(STRING REST...)
(LIST REST...)
     A list whose first element is a string or list means to process all the elements recursively and concatenate the results.  This is the most common form of mode-line construct.

(:eval FORM)
     A list whose first element is the symbol :eval says to evaluate FORM, and use the result as a string to display.  Make sure this evaluation cannot load any files, as doing so could cause infinite recursion.

(:propertize ELT PROPS...)
     A list whose first element is the symbol :propertize says to process the mode-line construct ELT recursively, then add the text properties specified by PROPS to the result.  The argument PROPS should consist of zero or more pairs TEXT-PROPERTY VALUE.  (This feature is new as of Emacs 22.1.)

(SYMBOL THEN ELSE)
     A list whose first element is a symbol that is not a keyword specifies a conditional.  Its meaning depends on the value of SYMBOL.  If SYMBOL has a non-nil value, the second element, THEN, is processed recursively as a mode-line element. Otherwise, the third element, ELSE, is processed recursively. You may omit ELSE; then the mode-line element displays nothing if the value of SYMBOL is nil or void.

(WIDTH REST...)
     A list whose first element is an integer specifies truncation or padding of the results of REST.  The remaining elements REST are processed recursively as mode-line constructs and concatenated together.  When WIDTH is positive, the result is space filled on the right if its width is less than WIDTH.  When WIDTH is negative, the result is truncated on the right to -WIDTH columns if its width exceeds -WIDTH.

     For example, the usual way to show what percentage of a buffer is above the top of the window is to use a list like this: (-3 "%p").

The Top Level of Mode Line Control
----------------------------------

The variable in overall control of the mode line is mode-line-format.

 -- Variable: mode-line-format
     The value of this variable is a mode-line construct that controls the contents of the mode-line.  It is always buffer-local in all buffers.

     If you set this variable to nil in a buffer, that buffer does not have a mode line.  (A window that is just one line tall never displays a mode line.)

The default value of mode-line-format is designed to use the values of other variables such as mode-line-position and mode-line-modes (which in turn incorporates the values of the variables mode-name and minor-mode-alist).  Very few modes need to alter mode-line-format itself.  For most purposes, it is sufficient to alter some of the variables that mode-line-format either directly or indirectly refers to.

If you do alter mode-line-format itself, the new value should use the same variables that appear in the default value (see Mode Line Variables), rather than duplicating their contents or displaying the information in another fashion.  This way, customizations made by the user or by Lisp programs (such as display-time and major modes) via changes to those variables remain effective.

Here is an example of a mode-line-format that might be useful for shell-mode, since it contains the host name and default directory.

     (setq mode-line-format
       (list "-"
        'mode-line-mule-info
        'mode-line-modified
        'mode-line-frame-identification
        "%b--"

        ;; Note that this is evaluated while making the list.
        ;; It makes a mode-line construct which is just a string.
        (getenv "HOST")

        ":"
        'default-directory
        "   "
        'global-mode-string
        "   %[("
        '(:eval (mode-line-mode-name))
        'mode-line-process
        'minor-mode-alist
        "%n"
        ")%]--"

        '(which-func-mode ("" which-func-format "--"))
        '(line-number-mode "L%l--")
        '(column-number-mode "C%c--")
        '(-3 "%p")
        "-%-"))

(The variables line-number-mode, column-number-mode and which-func-mode enable particular minor modes; as usual, these variable names are also the minor mode command names.)

Variables Used in the Mode Line
-------------------------------

This section describes variables incorporated by the standard value of mode-line-format into the text of the mode line.  There is nothing inherently special about these variables; any other variables could have the same effects on the mode line if mode-line-format's value were changed to use them.  However, various parts of Emacs set these variables on the understanding that they will control parts of the mode line; therefore, practically speaking, it is essential for the mode line to use them.

 -- Variable: mode-line-mule-info
     This variable holds the value of the mode-line construct that displays information about the language environment, buffer coding system, and current input method.  See Non-ASCII Characters.

 -- Variable: mode-line-modified
     This variable holds the value of the mode-line construct that displays whether the current buffer is modified.

     The default value of mode-line-modified is ("%1*%1+"). This means that the mode line displays ** if the buffer is modified, -- if the buffer is not modified, %% if the buffer is read only, and %* if the buffer is read only and modified.

     Changing this variable does not force an update of the mode line.

 -- Variable: mode-line-frame-identification
     This variable identifies the current frame.  The default value is "  " if you are using a window system which can show multiple frames, or "-%F  " on an ordinary terminal which shows only one frame at a time.

 -- Variable: mode-line-buffer-identification
     This variable identifies the buffer being displayed in the window.  Its default value is ("%12b"), which displays the buffer name, padded with spaces to at least 12 columns.

 -- Variable: mode-line-position
     This variable indicates the position in the buffer.  Here is a simplified version of its default value.  The actual default value also specifies addition of the help-echo text property.

          ((-3 "%p")
           (size-indication-mode (8 " of %I"))

           (line-number-mode
            ((column-number-mode
              (10 " (%l,%c)")
              (6 " L%l")))
            ((column-number-mode
              (5 " C%c")))))

     This means that mode-line-position displays at least the buffer percentage and possibly the buffer size, the line number and the column number.

 -- Variable: vc-mode
     The variable vc-mode, buffer-local in each buffer, records whether the buffer's visited file is maintained with version control, and, if so, which kind.  Its value is a string that appears in the mode line, or nil for no version control.

 -- Variable: mode-line-modes
     This variable displays the buffer's major and minor modes.  Here is a simplified version of its default value.  The real default value also specifies addition of text properties.

          ("%[(" mode-name
           mode-line-process minor-mode-alist
           "%n" ")%]--")

     So mode-line-modes normally also displays the recursive editing level, information on the process status and whether narrowing is in effect.

The following three variables are used in mode-line-modes:

 -- Variable: mode-name
     This buffer-local variable holds the ``pretty'' name of the current buffer's major mode.  Each major mode should set this variable so that the mode name will appear in the mode line.

 -- Variable: mode-line-process
     This buffer-local variable contains the mode-line information on process status in modes used for communicating with subprocesses.  It is displayed immediately following the major mode name, with no intervening space.  For example, its value in the *shell* buffer is (":%s"), which allows the shell to display its status along with the major mode as: (Shell:run).  Normally this variable is nil.

 -- Variable: minor-mode-alist
     This variable holds an association list whose elements specify how the mode line should indicate that a minor mode is active.  Each element of the minor-mode-alist should be a two-element list:

          (MINOR-MODE-VARIABLE MODE-LINE-STRING)

     More generally, MODE-LINE-STRING can be any mode-line spec.  It appears in the mode line when the value of MINOR-MODE-VARIABLE is non-nil, and not otherwise.  These strings should begin with spaces so that they don't run together.  Conventionally, the MINOR-MODE-VARIABLE for a specific mode is set to a non-nil value when that minor mode is activated.

     minor-mode-alist itself is not buffer-local.  Each variable mentioned in the alist should be buffer-local if its minor mode can be enabled separately in each buffer.

 -- Variable: global-mode-string
     This variable holds a mode-line spec that, by default, appears in the mode line just after the which-func-mode minor mode if set, else after mode-line-modes.  The command display-time sets global-mode-string to refer to the variable display-time-string, which holds a string containing the time and load information.

     The %M construct substitutes the value of global-mode-string, but that is obsolete, since the variable is included in the mode line from mode-line-format.

The variable default-mode-line-format is where mode-line-format usually gets its value:

 -- Variable: default-mode-line-format
     This variable holds the default mode-line-format for buffers that do not override it.  This is the same as (default-value 'mode-line-format).

     Here is a simplified version of the default value of default-mode-line-format.  The real default value also specifies addition of text properties.

          ("-"
           mode-line-mule-info
           mode-line-modified
           mode-line-frame-identification
           mode-line-buffer-identification

           "   "
           mode-line-position
           (vc-mode vc-mode)
           "   "

           mode-line-modes
           (which-func-mode ("" which-func-format "--"))
           (global-mode-string ("--" global-mode-string))
           "-%-")

%-Constructs in the Mode Line
-----------------------------

Strings used as mode-line constructs can use certain %-constructs to substitute various kinds of data.  Here is a list of the defined %-constructs, and what they mean.  In any construct except %%, you can add a decimal integer after the % to specify a minimum field width.  If the width is less, the field is padded with spaces to the right.

%b
     The current buffer name, obtained with the buffer-name function. See Buffer Names.

%c
     The current column number of point.

%f
     The visited file name, obtained with the buffer-file-name function.  See Buffer File Name.

%F
     The title (only on a window system) or the name of the selected frame. See Basic Parameters.

%i
     The size of the accessible part of the current buffer; basically (- (point-max) (point-min)).

%I
     Like %i, but the size is printed in a more readable way by using k for 10^3, M for 10^6, G for 10^9, etc., to abbreviate.

%l
     The current line number of point, counting within the accessible portion of the buffer.

%n
     Narrow when narrowing is in effect; nothing otherwise (see narrow-to-region in Narrowing).

%p
     The percentage of the buffer text above the top of window, or Top, Bottom or All.  Note that the default mode-line specification truncates this to three characters.

%P
     The percentage of the buffer text that is above the bottom of the window (which includes the text visible in the window, as well as the text above the top), plus Top if the top of the buffer is visible on screen; or Bottom or All.

%s
     The status of the subprocess belonging to the current buffer, obtained with process-status.  See Process Information.

%t
     Whether the visited file is a text file or a binary file.  This is a meaningful distinction only on certain operating systems (see MS-DOS File Types).

%*
     % if the buffer is read only (see buffer-read-only);

     * if the buffer is modified (see buffer-modified-p);

     - otherwise.  See Buffer Modification.

%+
     * if the buffer is modified (see buffer-modified-p);

     % if the buffer is read only (see buffer-read-only);

     - otherwise.  This differs from %* only for a modified read-only buffer.  See Buffer Modification.

%&
     * if the buffer is modified, and - otherwise.

%[
     An indication of the depth of recursive editing levels (not counting minibuffer levels): one [ for each editing level. See Recursive Editing.

%]
     One ] for each recursive editing level (not counting minibuffer levels).

%-
     Dashes sufficient to fill the remainder of the mode line.

%%
     The character %---this is how to include a literal % in a string in which %-constructs are allowed.

The following two %-constructs are still supported, but they are obsolete, since you can get the same results with the variables mode-name and global-mode-string.

%m
     The value of mode-name.

%M
     The value of global-mode-string.

Properties in the Mode Line
---------------------------

Certain text properties are meaningful in the mode line.  The face property affects the appearance of text; the help-echo property associates help strings with the text, and local-map can make the text mouse-sensitive.

There are four ways to specify text properties for text in the mode line:

 1. Put a string with a text property directly into the mode-line data structure.

 2. Put a text property on a mode-line %-construct such as %12b; then the expansion of the %-construct will have that same text property.

 3. Use a (:propertize ELT PROPS...) construct to give ELT a text property specified by PROPS.

 4. Use a list containing :eval FORM in the mode-line data structure, and make FORM evaluate to a string that has a text property.

You use the local-map property to specify a keymap.  Like any keymap, it can bind character keys and function keys; but that has no effect, since it is impossible to move point into the mode line.  This keymap can only take real effect for mouse clicks.

When the mode line refers to a variable which does not have a non-nil risky-local-variable property, any text properties given or specified within that variable's values are ignored.  This is because such properties could otherwise specify functions to be called, and those functions could come from file local variables.

Window Header Lines
-------------------

A window can have a header line at the top, just as it can have a mode line at the bottom.  The header line feature works just like the mode-line feature, except that it's controlled by different variables.

 -- Variable: header-line-format
     This variable, local in every buffer, specifies how to display the header line, for windows displaying the buffer.  The format of the value is the same as for mode-line-format (see Mode Line Data).

 -- Variable: default-header-line-format
     This variable holds the default header-line-format for buffers that do not override it.  This is the same as (default-value 'header-line-format).

     It is normally nil, so that ordinary buffers have no header line.

A window that is just one line tall never displays a header line.  A window that is two lines tall cannot display both a mode line and a header line at once; if it has a mode line, then it does not display a header line.

Emulating Mode-Line Formatting
------------------------------

You can use the function format-mode-line to compute the text that would appear in a mode line or header line based on a certain mode-line specification.

 -- Function: format-mode-line format &optional face window buffer
     This function formats a line of text according to FORMAT as if it were generating the mode line for WINDOW, but instead of displaying the text in the mode line or the header line, it returns the text as a string.  The argument WINDOW defaults to the selected window.  If BUFFER is non-nil, all the information used is taken from BUFFER; by default, it comes from WINDOW's buffer.

     The value string normally has text properties that correspond to the faces, keymaps, etc., that the mode line would have.  And any character for which no face property is specified gets a default value which is usually FACE.  (If FACE is t, that stands for either mode-line if WINDOW is selected, otherwise mode-line-inactive.  If FACE is nil or omitted, that stands for no face property.)

     However, if FACE is an integer, the value has no text properties.

     For example, (format-mode-line header-line-format) returns the text that would appear in the selected window's header line ("" if it has no header line).  (format-mode-line header-line-format 'header-line) returns the same text, with each character carrying the face that it will have in the header line itself.

Imenu
=====

Imenu is a feature that lets users select a definition or section in the buffer, from a menu which lists all of them, to go directly to that location in the buffer.  Imenu works by constructing a buffer index which lists the names and buffer positions of the definitions, or other named portions of the buffer; then the user can choose one of them and move point to it.  Major modes can add a menu bar item to use Imenu using imenu-add-to-menubar.

 -- Function: imenu-add-to-menubar name
     This function defines a local menu bar item named NAME to run Imenu.

The user-level commands for using Imenu are described in the Emacs Manual (see Imenu (the Emacs Manual)).  This section explains how to customize Imenu's method of finding definitions or buffer portions for a particular major mode.

The usual and simplest way is to set the variable imenu-generic-expression:

 -- Variable: imenu-generic-expression
     This variable, if non-nil, is a list that specifies regular expressions for finding definitions for Imenu.  Simple elements of imenu-generic-expression look like this:

          (MENU-TITLE REGEXP INDEX)

     Here, if MENU-TITLE is non-nil, it says that the matches for this element should go in a submenu of the buffer index; MENU-TITLE itself specifies the name for the submenu.  If MENU-TITLE is nil, the matches for this element go directly in the top level of the buffer index.

     The second item in the list, REGEXP, is a regular expression (see Regular Expressions); anything in the buffer that it matches is considered a definition, something to mention in the buffer index. The third item, INDEX, is a non-negative integer that indicates which subexpression in REGEXP matches the definition's name.

     An element can also look like this:

          (MENU-TITLE REGEXP INDEX FUNCTION ARGUMENTS...)

     Each match for this element creates an index item, and when the index item is selected by the user, it calls FUNCTION with arguments consisting of the item name, the buffer position, and ARGUMENTS.

     For Emacs Lisp mode, imenu-generic-expression could look like this:

          ((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
          \\s-+\\([-A-Za-z0-9+]+\\)" 2)

           ("*Vars*" "^\\s-*(def\\(var\\|const\\)\
          \\s-+\\([-A-Za-z0-9+]+\\)" 2)

           ("*Types*"
            "^\\s-*\
          (def\\(type\\|struct\\|class\\|ine-condition\\)\
          \\s-+\\([-A-Za-z0-9+]+\\)" 2))

     Setting this variable makes it buffer-local in the current buffer.

 -- Variable: imenu-case-fold-search
     This variable controls whether matching against the regular expressions in the value of imenu-generic-expression is case-sensitive: t, the default, means matching should ignore case.

     Setting this variable makes it buffer-local in the current buffer.

 -- Variable: imenu-syntax-alist
     This variable is an alist of syntax table modifiers to use while processing imenu-generic-expression, to override the syntax table of the current buffer.  Each element should have this form:

          (CHARACTERS . SYNTAX-DESCRIPTION)

     The CAR, CHARACTERS, can be either a character or a string. The element says to give that character or characters the syntax specified by SYNTAX-DESCRIPTION, which is passed to modify-syntax-entry (see Syntax Table Functions).

     This feature is typically used to give word syntax to characters which normally have symbol syntax, and thus to simplify imenu-generic-expression and speed up matching. For example, Fortran mode uses it this way:

          (setq imenu-syntax-alist '(("_$" . "w")))

     The imenu-generic-expression regular expressions can then use \\sw+ instead of \\(\\sw\\|\\s_\\)+.  Note that this technique may be inconvenient when the mode needs to limit the initial character of a name to a smaller set of characters than are allowed in the rest of a name.

     Setting this variable makes it buffer-local in the current buffer.

Another way to customize Imenu for a major mode is to set the variables imenu-prev-index-position-function and imenu-extract-index-name-function:

 -- Variable: imenu-prev-index-position-function
     If this variable is non-nil, its value should be a function that finds the next ``definition'' to put in the buffer index, scanning backward in the buffer from point.  It should return nil if it doesn't find another ``definition'' before point.  Otherwise it should leave point at the place it finds a ``definition'' and return any non-nil value.

     Setting this variable makes it buffer-local in the current buffer.

 -- Variable: imenu-extract-index-name-function
     If this variable is non-nil, its value should be a function to return the name for a definition, assuming point is in that definition as the imenu-prev-index-position-function function would leave it.

     Setting this variable makes it buffer-local in the current buffer.

The last way to customize Imenu for a major mode is to set the variable imenu-create-index-function:

 -- Variable: imenu-create-index-function
     This variable specifies the function to use for creating a buffer index.  The function should take no arguments, and return an index alist for the current buffer.  It is called within save-excursion, so where it leaves point makes no difference.

     The index alist can have three types of elements.  Simple elements look like this:

          (INDEX-NAME . INDEX-POSITION)

     Selecting a simple element has the effect of moving to position INDEX-POSITION in the buffer.  Special elements look like this:

          (INDEX-NAME INDEX-POSITION FUNCTION ARGUMENTS...)

     Selecting a special element performs:

          (funcall FUNCTION
                   INDEX-NAME INDEX-POSITION ARGUMENTS...)

     A nested sub-alist element looks like this:

          (MENU-TITLE SUB-ALIST)

     It creates the submenu MENU-TITLE specified by SUB-ALIST.

     The default value of imenu-create-index-function is imenu-default-create-index-function.  This function calls the value of imenu-prev-index-position-function and the value of imenu-extract-index-name-function to produce the index alist. However, if either of these two variables is nil, the default function uses imenu-generic-expression instead.

     Setting this variable makes it buffer-local in the current buffer.

Font Lock Mode
==============

Font Lock mode is a feature that automatically attaches face properties to certain parts of the buffer based on their syntactic role.  How it parses the buffer depends on the major mode; most major modes define syntactic criteria for which faces to use in which contexts.  This section explains how to customize Font Lock for a particular major mode.

Font Lock mode finds text to highlight in two ways: through syntactic parsing based on the syntax table, and through searching (usually for regular expressions).  Syntactic fontification happens first; it finds comments and string constants and highlights them. Search-based fontification happens second.

Font Lock Basics
----------------

There are several variables that control how Font Lock mode highlights text.  But major modes should not set any of these variables directly. Instead, they should set font-lock-defaults as a buffer-local variable.  The value assigned to this variable is used, if and when Font Lock mode is enabled, to set all the other variables.

 -- Variable: font-lock-defaults
     This variable is set by major modes, as a buffer-local variable, to specify how to fontify text in that mode.  It automatically becomes buffer-local when you set it.  The value should look like this:

          (KEYWORDS [KEYWORDS-ONLY [CASE-FOLD
           [SYNTAX-ALIST [SYNTAX-BEGIN OTHER-VARS...]]]])

     The first element, KEYWORDS, indirectly specifies the value of font-lock-keywords which directs search-based fontification. It can be a symbol, a variable or a function whose value is the list to use for font-lock-keywords.  It can also be a list of several such symbols, one for each possible level of fontification. The first symbol specifies how to do level 1 fontification, the second symbol how to do level 2, and so on.  See Levels of Font Lock.

     The second element, KEYWORDS-ONLY, specifies the value of the variable font-lock-keywords-only.  If this is non-nil, syntactic fontification (of strings and comments) is not performed. See Syntactic Font Lock.

     The third element, CASE-FOLD, specifies the value of font-lock-keywords-case-fold-search.  If it is non-nil, Font Lock mode ignores case when searching as directed by font-lock-keywords.

     If the fourth element, SYNTAX-ALIST, is non-nil, it should be a list of cons cells of the form (CHAR-OR-STRING . STRING).  These are used to set up a syntax table for syntactic fontification (see Syntax Table Functions).  The resulting syntax table is stored in font-lock-syntax-table.

     The fifth element, SYNTAX-BEGIN, specifies the value of font-lock-beginning-of-syntax-function.  We recommend setting this variable to nil and using syntax-begin-function instead.

     All the remaining elements (if any) are collectively called OTHER-VARS.  Each of these elements should have the form (VARIABLE . VALUE)---which means, make VARIABLE buffer-local and then set it to VALUE.  You can use these OTHER-VARS to set other variables that affect fontification, aside from those you can control with the first five elements.  See Other Font Lock Variables.

Search-based Fontification
--------------------------

The most important variable for customizing Font Lock mode is font-lock-keywords.  It specifies the search criteria for search-based fontification.  You should specify the value of this variable with KEYWORDS in font-lock-defaults.

 -- Variable: font-lock-keywords
     This variable's value is a list of the keywords to highlight.  Be careful when composing regular expressions for this list; a poorly written pattern can dramatically slow things down!

Each element of font-lock-keywords specifies how to find certain cases of text, and how to highlight those cases.  Font Lock mode processes the elements of font-lock-keywords one by one, and for each element, it finds and handles all matches.  Ordinarily, once part of the text has been fontified already, this cannot be overridden by a subsequent match in the same text; but you can specify different behavior using the OVERRIDE element of a SUBEXP-HIGHLIGHTER.

Each element of font-lock-keywords should have one of these forms:

REGEXP
     Highlight all matches for REGEXP using font-lock-keyword-face.  For example,

          ;; Highlight occurrences of the word foo
          ;; using font-lock-keyword-face.
          "\\<foo\\>"

     The function regexp-opt (see Regexp Functions) is useful for calculating optimal regular expressions to match a number of different keywords.

FUNCTION
     Find text by calling FUNCTION, and highlight the matches it finds using font-lock-keyword-face.

     When FUNCTION is called, it receives one argument, the limit of the search; it should begin searching at point, and not search beyond the limit.  It should return non-nil if it succeeds, and set the match data to describe the match that was found.  Returning nil indicates failure of the search.

     Fontification will call FUNCTION repeatedly with the same limit, and with point where the previous invocation left it, until FUNCTION fails.  On failure, FUNCTION need not reset point in any particular way.

(MATCHER . SUBEXP)
     In this kind of element, MATCHER is either a regular expression or a function, as described above.  The CDR, SUBEXP, specifies which subexpression of MATCHER should be highlighted (instead of the entire text that MATCHER matched).

          ;; Highlight the bar in each occurrence of fubar,
          ;; using font-lock-keyword-face.
          ("fu\\(bar\\)" . 1)

     If you use regexp-opt to produce the regular expression MATCHER, you can use regexp-opt-depth (see Regexp Functions) to calculate the value for SUBEXP.

(MATCHER . FACESPEC)
     In this kind of element, FACESPEC is an expression whose value specifies the face to use for highlighting.  In the simplest case, FACESPEC is a Lisp variable (a symbol) whose value is a face name.

          ;; Highlight occurrences of fubar,
          ;; using the face which is the value of fubar-face.
          ("fubar" . fubar-face)

     However, FACESPEC can also evaluate to a list of this form:

          (face FACE PROP1 VAL1 PROP2 VAL2...)

     to specify the face FACE and various additional text properties to put on the text that matches.  If you do this, be sure to add the other text property names that you set in this way to the value of font-lock-extra-managed-props so that the properties will also be cleared out when they are no longer appropriate.  Alternatively, you can set the variable font-lock-unfontify-region-function to a function that clears these properties.  See Other Font Lock Variables.

(MATCHER . SUBEXP-HIGHLIGHTER)
     In this kind of element, SUBEXP-HIGHLIGHTER is a list which specifies how to highlight matches found by MATCHER. It has the form:

          (SUBEXP FACESPEC [[OVERRIDE [LAXMATCH]])

     The CAR, SUBEXP, is an integer specifying which subexpression of the match to fontify (0 means the entire matching text).  The second subelement, FACESPEC, is an expression whose value specifies the face, as described above.

     The last two values in SUBEXP-HIGHLIGHTER, OVERRIDE and LAXMATCH, are optional flags.  If OVERRIDE is t, this element can override existing fontification made by previous elements of font-lock-keywords.  If it is keep, then each character is fontified if it has not been fontified already by some other element.  If it is prepend, the face specified by FACESPEC is added to the beginning of the font-lock-face property.  If it is append, the face is added to the end of the font-lock-face property.

     If LAXMATCH is non-nil, it means there should be no error if there is no subexpression numbered SUBEXP in MATCHER. Obviously, fontification of the subexpression numbered SUBEXP will not occur.  However, fontification of other subexpressions (and other regexps) will continue.  If LAXMATCH is nil, and the specified subexpression is missing, then an error is signaled which terminates search-based fontification.

     Here are some examples of elements of this kind, and what they do:

          ;; Highlight occurrences of either foo or bar, using
          ;; foo-bar-face, even if they have already been highlighted.
          ;; foo-bar-face should be a variable whose value is a face.
          ("foo\\|bar" 0 foo-bar-face t)

          ;; Highlight the first subexpression within each occurrence
          ;; that the function fubar-match finds,
          ;; using the face which is the value of fubar-face.
          (fubar-match 1 fubar-face)

(MATCHER . ANCHORED-HIGHLIGHTER)
     In this kind of element, ANCHORED-HIGHLIGHTER specifies how to highlight text that follows a match found by MATCHER.  So a match found by MATCHER acts as the anchor for further searches specified by ANCHORED-HIGHLIGHTER.  ANCHORED-HIGHLIGHTER is a list of the following form:

          (ANCHORED-MATCHER PRE-FORM POST-FORM
                                  SUBEXP-HIGHLIGHTERS...)

     Here, ANCHORED-MATCHER, like MATCHER, is either a regular expression or a function.  After a match of MATCHER is found, point is at the end of the match.  Now, Font Lock evaluates the form PRE-FORM.  Then it searches for matches of ANCHORED-MATCHER and uses SUBEXP-HIGHLIGHTERS to highlight these.  A SUBEXP-HIGHLIGHTER is as described above.  Finally, Font Lock evaluates POST-FORM.

     The forms PRE-FORM and POST-FORM can be used to initialize before, and cleanup after, ANCHORED-MATCHER is used.  Typically, PRE-FORM is used to move point to some position relative to the match of MATCHER, before starting with ANCHORED-MATCHER. POST-FORM might be used to move back, before resuming with MATCHER.

     After Font Lock evaluates PRE-FORM, it does not search for ANCHORED-MATCHER beyond the end of the line.  However, if PRE-FORM returns a buffer position that is greater than the position of point after PRE-FORM is evaluated, then the position returned by PRE-FORM is used as the limit of the search instead. It is generally a bad idea to return a position greater than the end of the line; in other words, the ANCHORED-MATCHER search should not span lines.

     For example,

          ;; Highlight occurrences of the word item following
          ;; an occurrence of the word anchor (on the same line)
          ;; in the value of item-face.
          ("\\<anchor\\>" "\\<item\\>" nil nil (0 item-face))

     Here, PRE-FORM and POST-FORM are nil.  Therefore searching for item starts at the end of the match of anchor, and searching for subsequent instances of anchor resumes from where searching for item concluded.

(MATCHER HIGHLIGHTERS...)
     This sort of element specifies several HIGHLIGHTER lists for a single MATCHER.  A HIGHLIGHTER list can be of the type SUBEXP-HIGHLIGHTER or ANCHORED-HIGHLIGHTER as described above.

     For example,

          ;; Highlight occurrences of the word anchor in the value
          ;; of anchor-face, and subsequent occurrences of the word
          ;; item (on the same line) in the value of item-face.
          ("\\<anchor\\>" (0 anchor-face)
                          ("\\<item\\>" nil nil (0 item-face)))

(eval . FORM)
     Here FORM is an expression to be evaluated the first time this value of font-lock-keywords is used in a buffer. Its value should have one of the forms described in this table.

Warning: Do not design an element of font-lock-keywords to match text which spans lines; this does not work reliably. For details, see Multi line Font Lock Elements.

You can use CASE-FOLD in font-lock-defaults to specify the value of font-lock-keywords-case-fold-search which says whether search-based fontification should be case-insensitive.

 -- Variable: font-lock-keywords-case-fold-search
     Non-nil means that regular expression matching for the sake of font-lock-keywords should be case-insensitive.

Customizing Search-Based Fontification
--------------------------------------

You can use font-lock-add-keywords to add additional search-based fontification rules to a major mode, and font-lock-remove-keywords to removes rules.

 -- Function: font-lock-add-keywords mode keywords &optional how
     This function adds highlighting KEYWORDS, for the current buffer or for major mode MODE.  The argument KEYWORDS should be a list with the same format as the variable font-lock-keywords.

     If MODE is a symbol which is a major mode command name, such as c-mode, the effect is that enabling Font Lock mode in MODE will add KEYWORDS to font-lock-keywords. Calling with a non-nil value of MODE is correct only in your ~/.emacs file.

     If MODE is nil, this function adds KEYWORDS to font-lock-keywords in the current buffer.  This way of calling font-lock-add-keywords is usually used in mode hook functions.

     By default, KEYWORDS are added at the beginning of font-lock-keywords.  If the optional argument HOW is set, they are used to replace the value of font-lock-keywords.  If HOW is any other non-nil value, they are added at the end of font-lock-keywords.

     Some modes provide specialized support you can use in additional highlighting patterns.  See the variables c-font-lock-extra-types, c++-font-lock-extra-types, and java-font-lock-extra-types, for example.

     Warning: major mode functions must not call font-lock-add-keywords under any circumstances, either directly or indirectly, except through their mode hooks.  (Doing so would lead to incorrect behavior for some minor modes.)  They should set up their rules for search-based fontification by setting font-lock-keywords.

 -- Function: font-lock-remove-keywords mode keywords
     This function removes KEYWORDS from font-lock-keywords for the current buffer or for major mode MODE.  As in font-lock-add-keywords, MODE should be a major mode command name or nil.  All the caveats and requirements for font-lock-add-keywords apply here too.

For example, this code

     (font-lock-add-keywords 'c-mode
      '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
        ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face)))

adds two fontification patterns for C mode: one to fontify the word FIXME, even in comments, and another to fontify the words and, or and not as keywords.

That example affects only C mode proper.  To add the same patterns to C mode and all modes derived from it, do this instead:

     (add-hook 'c-mode-hook
      (lambda ()
       (font-lock-add-keywords nil
        '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
          ("\\<\\(and\\|or\\|not\\)\\>" .
           font-lock-keyword-face)))))

Other Font Lock Variables
-------------------------

This section describes additional variables that a major mode can set by means of OTHER-VARS in font-lock-defaults (see Font Lock Basics).

 -- Variable: font-lock-mark-block-function
     If this variable is non-nil, it should be a function that is called with no arguments, to choose an enclosing range of text for refontification for the command M-o M-o (font-lock-fontify-block).

     The function should report its choice by placing the region around it. A good choice is a range of text large enough to give proper results, but not too large so that refontification becomes slow.  Typical values are mark-defun for programming modes or mark-paragraph for textual modes.

 -- Variable: font-lock-extra-managed-props
     This variable specifies additional properties (other than font-lock-face) that are being managed by Font Lock mode.  It is used by font-lock-default-unfontify-region, which normally only manages the font-lock-face property.  If you want Font Lock to manage other properties as well, you must specify them in a FACESPEC in font-lock-keywords as well as add them to this list.  See Search-based Fontification.

 -- Variable: font-lock-fontify-buffer-function
     Function to use for fontifying the buffer.  The default value is font-lock-default-fontify-buffer.

 -- Variable: font-lock-unfontify-buffer-function
     Function to use for unfontifying the buffer.  This is used when turning off Font Lock mode.  The default value is font-lock-default-unfontify-buffer.

 -- Variable: font-lock-fontify-region-function
     Function to use for fontifying a region.  It should take two arguments, the beginning and end of the region, and an optional third argument VERBOSE.  If VERBOSE is non-nil, the function should print status messages.  The default value is font-lock-default-fontify-region.

 -- Variable: font-lock-unfontify-region-function
     Function to use for unfontifying a region.  It should take two arguments, the beginning and end of the region.  The default value is font-lock-default-unfontify-region.

Levels of Font Lock
-------------------

Many major modes offer three different levels of fontification.  You can define multiple levels by using a list of symbols for KEYWORDS in font-lock-defaults.  Each symbol specifies one level of fontification; it is up to the user to choose one of these levels.  The chosen level's symbol value is used to initialize font-lock-keywords.

Here are the conventions for how to define the levels of fontification:

  * Level 1: highlight function declarations, file directives (such as include or import directives), strings and comments.  The idea is speed, so only the most important and top-level components are fontified.

  * Level 2: in addition to level 1, highlight all language keywords, including type names that act like keywords, as well as named constant values.  The idea is that all keywords (either syntactic or semantic) should be fontified appropriately.

  * Level 3: in addition to level 2, highlight the symbols being defined in function and variable declarations, and all builtin function names, wherever they appear.

Precalculated Fontification
---------------------------

In addition to using font-lock-defaults for search-based fontification, you may use the special character property font-lock-face (see Special Properties).  This property acts just like the explicit face property, but its activation is toggled when the user calls M-x font-lock-mode.  Using font-lock-face is especially convenient for special modes which construct their text programmatically, such as list-buffers and occur.

If your mode does not use any of the other machinery of Font Lock (i.e. it only uses the font-lock-face property), it should not set the variable font-lock-defaults.  That way, it will not cause loading of the font-lock library.

Faces for Font Lock
-------------------

You can make Font Lock mode use any face, but several faces are defined specifically for Font Lock mode.  Each of these symbols is both a face name, and a variable whose default value is the symbol itself. Thus, the default value of font-lock-comment-face is font-lock-comment-face.  This means you can write font-lock-comment-face in a context such as font-lock-keywords where a face-name-valued expression is used.

font-lock-comment-face
     Used (typically) for comments.

font-lock-comment-delimiter-face
     Used (typically) for comments delimiters.

font-lock-doc-face
     Used (typically) for documentation strings in the code.

font-lock-string-face
     Used (typically) for string constants.

font-lock-keyword-face
     Used (typically) for keywords---names that have special syntactic significance, like for and if in C.

font-lock-builtin-face
     Used (typically) for built-in function names.

font-lock-function-name-face
     Used (typically) for the name of a function being defined or declared, in a function definition or declaration.

font-lock-variable-name-face
     Used (typically) for the name of a variable being defined or declared, in a variable definition or declaration.

font-lock-type-face
     Used (typically) for names of user-defined data types, where they are defined and where they are used.

font-lock-constant-face
     Used (typically) for constant names.

font-lock-preprocessor-face
     Used (typically) for preprocessor commands.

font-lock-warning-face
     Used (typically) for constructs that are peculiar, or that greatly change the meaning of other text.  For example, this is used for ;;;###autoload cookies in Emacs Lisp, and for #error directives in C.

Syntactic Font Lock
-------------------

Syntactic fontification uses the syntax table to find comments and string constants (see Syntax Tables).  It highlights them using font-lock-comment-face and font-lock-string-face (see Faces for Font Lock).  There are several variables that affect syntactic fontification; you should set them by means of font-lock-defaults (see Font Lock Basics).

 -- Variable: font-lock-keywords-only
     Non-nil means Font Lock should not do syntactic fontification; it should only fontify based on font-lock-keywords.  The normal way for a mode to set this variable to t is with KEYWORDS-ONLY in font-lock-defaults.

 -- Variable: font-lock-syntax-table
     This variable holds the syntax table to use for fontification of comments and strings.  Specify it using SYNTAX-ALIST in font-lock-defaults.

 -- Variable: font-lock-beginning-of-syntax-function
     If this variable is non-nil, it should be a function to move point back to a position that is syntactically at ``top level'' and outside of strings or comments.  Font Lock uses this when necessary to get the right results for syntactic fontification.

     This function is called with no arguments.  It should leave point at the beginning of any enclosing syntactic block.  Typical values are beginning-of-line (used when the start of the line is known to be outside a syntactic block), or beginning-of-defun for programming modes, or backward-paragraph for textual modes.

     If the value is nil, Font Lock uses syntax-begin-function to move back outside of any comment, string, or sexp.  This variable is semi-obsolete; we recommend setting syntax-begin-function instead.

     Specify this variable using SYNTAX-BEGIN in font-lock-defaults.

 -- Variable: font-lock-syntactic-face-function
     A function to determine which face to use for a given syntactic element (a string or a comment).  The function is called with one argument, the parse state at point returned by parse-partial-sexp, and should return a face.  The default value returns font-lock-comment-face for comments and font-lock-string-face for strings.

     This can be used to highlighting different kinds of strings or comments differently.  It is also sometimes abused together with font-lock-syntactic-keywords to highlight elements that span multiple lines, but this is too obscure to document in this manual.

     Specify this variable using OTHER-VARS in font-lock-defaults.

Setting Syntax Properties
-------------------------

Font Lock mode can be used to update syntax-table properties automatically (see Syntax Properties).  This is useful in languages for which a single syntax table by itself is not sufficient.

 -- Variable: font-lock-syntactic-keywords
     This variable enables and controls updating syntax-table properties by Font Lock.  Its value should be a list of elements of this form:

          (MATCHER SUBEXP SYNTAX OVERRIDE LAXMATCH)

     The parts of this element have the same meanings as in the corresponding sort of element of font-lock-keywords,

          (MATCHER SUBEXP FACESPEC OVERRIDE LAXMATCH)

     However, instead of specifying the value FACESPEC to use for the face property, it specifies the value SYNTAX to use for the syntax-table property.  Here, SYNTAX can be a string (as taken by modify-syntax-entry), a syntax table, a cons cell (as returned by string-to-syntax), or an expression whose value is one of those two types.  OVERRIDE cannot be prepend or append.

     For example, an element of the form:

          ("\\$\\(#\\)" 1 ".")

     highlights syntactically a hash character when following a dollar character, with a SYNTAX of "." (meaning punctuation syntax). Assuming that the buffer syntax table specifies hash characters to have comment start syntax, the element will only highlight hash characters that do not follow dollar characters as comments syntactically.

     An element of the form:

           ("\\('\\).\\('\\)"
            (1 "\"")
            (2 "\""))

     highlights syntactically both single quotes which surround a single character, with a SYNTAX of "\"" (meaning string quote syntax). Assuming that the buffer syntax table does not specify single quotes to have quote syntax, the element will only highlight single quotes of the form 'C' as strings syntactically.  Other forms, such as foo'bar or 'fubar', will not be highlighted as strings.

     Major modes normally set this variable with OTHER-VARS in font-lock-defaults.

Multi line Font Lock Elements
-----------------------------

Normally, Font Lock elements specified via font-lock-keywords should not match across multiple lines.  If they do, Font Lock may fail to highlight them properly.  This is fundamentally due to the fact that Font Lock does not always look at the whole buffer at a time, for obvious performance reasons, and instead only looks at a small chunk at a time.  In order for the highlight to be correct, a chunk should not straddle an element matched by font-lock-keywords.  The default heuristic used for this is to start and end chunks at the beginning resp. end of a line.

To work around this limitations, a few tools are provided.

Font Lock Multiline
...................

In order to make it possible to properly highlight elements that span multiple lines, Font Lock obeys a special text property font-lock-multiline which if non-nil indicates that this piece of text is part of a multiline construct.  So when Font Lock is asked to highlight a region, it first verifies the two boundaries and extends them as needed so they do not fall in the middle of a piece of text marked with the font-lock-multiline property. Immediately after that, it also erases all font-lock-multiline properties from the region it is about to highlight, so it is the responsability of the highlighting specification (mostly font-lock-keywords) to make sure that this property is re-added where needed so as to inform the next round of Font Locking of the presence of a multiline construct.

It is important to understand that the font-lock-multiline property should preferably only be used on Font Lock elements of moderate size: every time that text is modified within the multiline elements (or nearby), the whole multiline element will be completely re-highlighted, so if its size is large, the time to font-lock may render editing painfully slow.

 -- Variable: font-lock-multiline
     If the font-lock-multiline variable is set to t, Font Lock will try to automatically add the font-lock-multiline property on the keywords that span several lines.  This is no silver bullet however since it slows down Font Lock somewhat, and still does not always find all multiline constructs, especially when used with Jit Lock, which is enabled by default.

Region to Fontify after a Buffer Change
.......................................

When a buffer is changed, the region that Font Lock refontifies is by default the smallest sequence of whole lines that spans the change. While this works well most of the time, sometimes it doesn't---for example, when a buffer change has changed the syntactic meaning of text on an earlier line.

You can enlarge (or even reduce) the region to fontify by setting the following variables:

 -- Variable: font-lock-extend-region-function
     This buffer-local variable is either nil or is a function that determines the region to fontify, which Emacs then calls after each buffer change.

     The function is given three parameters, the standard BEG, END, and OLD-LEN from after-change-functions (see Change Hooks).  It should return either a cons of the beginning and end buffer positions (in that order) of the region to fontify, or nil (which directs the caller to fontify the default region).  This function needs to preserve point, the match-data, and the current restriction. The region it returns may start or end in the middle of a line.

     Since this function is called after every buffer change, it should be reasonably fast.

Desktop Save Mode
=================

Desktop Save Mode is a feature to save the state of Emacs from one session to another.  The user-level commands for using Desktop Save Mode are described in the GNU Emacs Manual (see Saving Emacs Sessions (the GNU Emacs Manual)).  Modes whose buffers visit a file, don't have to do anything to use this feature.

For buffers not visiting a file to have their state saved, the major mode must bind the buffer local variable desktop-save-buffer to a non-nil value.

 -- Variable: desktop-save-buffer
     If this buffer-local variable is non-nil, the buffer will have its state saved in the desktop file at desktop save.  If the value is a function, it is called at desktop save with argument DESKTOP-DIRNAME, and its value is saved in the desktop file along with the state of the buffer for which it was called.  When file names are returned as part of the auxiliary information, they should be formatted using the call

          (desktop-file-name FILE-NAME DESKTOP-DIRNAME)

For buffers not visiting a file to be restored, the major mode must define a function to do the job, and that function must be listed in the alist desktop-buffer-mode-handlers.

 -- Variable: desktop-buffer-mode-handlers
     Alist with elements

          (MAJOR-MODE . RESTORE-BUFFER-FUNCTION)

     The function RESTORE-BUFFER-FUNCTION will be called with argument list

          (BUFFER-FILE-NAME BUFFER-NAME DESKTOP-BUFFER-MISC)

     and it should return the restored buffer. Here DESKTOP-BUFFER-MISC is the value returned by the function optionally bound to desktop-save-buffer.