Mercurial > emacs
changeset 84089:b9cb597718e5
Move here from ../../lispref
| author | Glenn Morris <rgm@gnu.org> |
|---|---|
| date | Thu, 06 Sep 2007 04:22:10 +0000 |
| parents | 2e38ef4443ea |
| children | e7e0d9a379c7 |
| files | doc/lispref/modes.texi |
| diffstat | 1 files changed, 3271 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispref/modes.texi Thu Sep 06 04:22:10 2007 +0000 @@ -0,0 +1,3271 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/modes +@node Modes, Documentation, Keymaps, Top +@chapter Major and Minor Modes +@cindex mode + + A @dfn{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: +@dfn{major modes}, which are mutually exclusive and used for editing +particular kinds of text, and @dfn{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 +@ref{Keymaps}, and @ref{Syntax Tables}. + +@menu +* Hooks:: How to use hooks; how to write code that provides hooks. +* Major Modes:: Defining major modes. +* Minor Modes:: Defining minor modes. +* Mode Line Format:: Customizing the text that appears in the mode line. +* Imenu:: How a mode can provide a menu + of definitions in the buffer. +* Font Lock Mode:: How modes can highlight text according to syntax. +* Desktop Save Mode:: How modes can have buffer state saved between + Emacs sessions. +@end menu + +@node Hooks +@section Hooks +@cindex hooks + + A @dfn{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 (@pxref{Init File}), but Lisp programs can set them also. +@xref{Standard Hooks}, for a list of standard hook variables. + +@cindex normal hook + Most of the hooks in Emacs are @dfn{normal hooks}. These variables +contain lists of functions to be called with no arguments. By +convention, whenever the hook name ends in @samp{-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 @dfn{mode hook} as the one of the last steps 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 mode functions also run a mode hook at the end. +But hooks are used in other contexts too. For example, the hook +@code{suspend-hook} runs just before Emacs suspends itself +(@pxref{Suspending Emacs}). + + The recommended way to add a hook function to a normal hook is by +calling @code{add-hook} (see below). The hook functions may be any of +the valid kinds of functions that @code{funcall} accepts (@pxref{What +Is a Function}). Most normal hook variables are initially void; +@code{add-hook} knows how to deal with this. You can add hooks either +globally or buffer-locally with @code{add-hook}. + +@cindex abnormal hook + If the hook variable's name does not end with @samp{-hook}, that +indicates it is probably an @dfn{abnormal hook}. That means the hook +functions are called with arguments, or their return values are used +in some way. The hook's documentation says how the functions are +called. You can use @code{add-hook} to add a function to an abnormal +hook, but you must write the function to follow the hook's calling +convention. + + By convention, abnormal hook names end in @samp{-functions} or +@samp{-hooks}. If the variable's name ends in @samp{-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: + +@example +(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill) +@end example + + At the appropriate time, Emacs uses the @code{run-hooks} function to +run particular hooks. + +@defun 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-@code{nil} value, that value should be a +list of functions. @code{run-hooks} calls all the functions, one by +one, with no arguments. + +The hook variable's value can also be a single function---either a +lambda expression or a symbol with a function definition---which +@code{run-hooks} calls. But this usage is obsolete. +@end defun + +@defun 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 @var{args}. +@end defun + +@defun 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 @var{args}, until some hook function returns +@code{nil}. It then stops and returns @code{nil}. If none of the +hook functions return @code{nil}, it returns a non-@code{nil} value. +@end defun + +@defun 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 @var{args}, until some hook function returns +non-@code{nil}. Then it stops, and returns whatever was returned by +the last hook function that was called. If all hook functions return +@code{nil}, it returns @code{nil} as well. +@end defun + +@defun add-hook hook function &optional append local +This function is the handy way to add function @var{function} to hook +variable @var{hook}. You can use it for abnormal hooks as well as for +normal hooks. @var{function} can be any Lisp function that can accept +the proper number of arguments for @var{hook}. For example, + +@example +(add-hook 'text-mode-hook 'my-text-hook-function) +@end example + +@noindent +adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}. + +If @var{function} is already present in @var{hook} (comparing using +@code{equal}), then @code{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, +@var{function} goes at the front of the hook list, so it will be +executed first (barring another @code{add-hook} call). If the optional +argument @var{append} is non-@code{nil}, the new hook function goes at +the end of the hook list and will be executed last. + +@code{add-hook} can handle the cases where @var{hook} is void or its +value is a single function; it sets or changes the value to a list of +functions. + +If @var{local} is non-@code{nil}, that says to add @var{function} to +the buffer-local hook list instead of to the global hook list. If +needed, this makes the hook buffer-local and adds @code{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. +@end defun + +@defun remove-hook hook function &optional local +This function removes @var{function} from the hook variable +@var{hook}. It compares @var{function} with elements of @var{hook} +using @code{equal}, so it works for both symbols and lambda +expressions. + +If @var{local} is non-@code{nil}, that says to remove @var{function} +from the buffer-local hook list instead of from the global hook list. +@end defun + +@node Major Modes +@section Major Modes +@cindex major mode + + 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 @samp{-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. + +@menu +* Major Mode Basics:: +* Major Mode Conventions:: Coding conventions for keymaps, etc. +* Auto Major Mode:: How Emacs chooses the major mode automatically. +* Mode Help:: Finding out how to use a mode. +* Derived Modes:: Defining a new major mode based on another major + mode. +* Generic Modes:: Defining a simple major mode that supports + comment syntax and Font Lock mode. +* Mode Hooks:: Hooks run at the end of major mode functions. +* Example Major Modes:: Text mode and Lisp modes. +@end menu + +@node Major Mode Basics +@subsection Major Mode Basics +@cindex Fundamental mode + + The least specialized major mode is called @dfn{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 +@kbd{C-j} (@code{eval-print-last-sexp}), @key{TAB} +(@code{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 use @code{define-derived-mode} to +define a @dfn{derived mode} (@pxref{Derived Modes}). For example, +Rmail Edit mode 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 @code{define-derived-mode} with a @code{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 @code{define-generic-mode}. +@xref{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. @xref{Recursive +Editing}. + + The standard GNU Emacs Lisp library directory tree contains the code +for several major modes, in files such as @file{text-mode.el}, +@file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and +@file{rmail.el}. They are found in various subdirectories of the +@file{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. + +@node Major Mode Conventions +@subsection Major Mode Conventions +@cindex major mode conventions +@cindex conventions for writing major modes + + 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. (Fundamental mode is an exception to many +of these conventions, because its definition is to present the global +state of Emacs.) + + 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. + +@itemize @bullet +@item +Define a command whose name ends in @samp{-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. + +@item +Write a documentation string for this command that describes the +special commands available in this mode. @kbd{C-h m} +(@code{describe-mode}) in your mode will display this string. + +The documentation string may include the special documentation +substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and +@samp{\<@var{keymap}>}, which enable the documentation to adapt +automatically to the user's own key bindings. @xref{Keys in +Documentation}. + +@item +The major mode command should start by calling +@code{kill-all-local-variables}. This runs the normal hook +@code{change-major-mode-hook}, then gets rid of the buffer-local +variables of the major mode previously in effect. @xref{Creating +Buffer-Local}. + +@item +The major mode command should set the variable @code{major-mode} to the +major mode command symbol. This is how @code{describe-mode} discovers +which documentation to print. + +@item +The major mode command should set the variable @code{mode-name} to the +``pretty'' name of the mode, as a string. This string appears in the +mode line. + +@item +@cindex functions in modes +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). @xref{Coding Conventions}. + +@item +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 @code{indent-line-function} +to a suitable function, and probably customize other variables +for indentation. + +@item +@cindex keymaps in modes +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 @code{use-local-map} to install this local map. @xref{Active +Keymaps}, for more information. + +This keymap should be stored permanently in a global variable named +@code{@var{modename}-mode-map}. Normally the library that defines the +mode sets this variable. + +@xref{Tips for Defining}, for advice about how to write the code to set +up the mode's keymap variable. + +@item +The key sequences bound in a major mode keymap should usually start with +@kbd{C-c}, followed by a control character, a digit, or @kbd{@{}, +@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}. The other punctuation +characters are reserved for minor modes, and ordinary letters are +reserved for users. + +A major mode can also rebind the keys @kbd{M-n}, @kbd{M-p} and +@kbd{M-s}. The bindings for @kbd{M-n} and @kbd{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 @kbd{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 @kbd{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. + +@item +Major modes modes for editing text should not define @key{RET} to do +anything other than insert a newline. However, it is ok for +specialized modes for text that users don't directly edit, such as +Dired and Info modes, to redefine @key{RET} to do something entirely +different. + +@item +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 @emph{if} the user +decides to use it. + +@item +@cindex syntax tables in modes +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 @code{@var{modename}-mode-syntax-table}. @xref{Syntax +Tables}. + +@item +If the mode handles a language that has a syntax for comments, it should +set the variables that define the comment syntax. @xref{Options for +Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}. + +@item +@cindex abbrev tables in modes +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 @code{@var{modename}-mode-abbrev-table}. If the +major mode command defines any abbrevs itself, it should pass @code{t} +for the @var{system-flag} argument to @code{define-abbrev}. +@xref{Defining Abbrevs}. + +@item +The mode should specify how to do highlighting for Font Lock mode, by +setting up a buffer-local value for the variable +@code{font-lock-defaults} (@pxref{Font Lock Mode}). + +@item +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 @code{imenu-generic-expression}, for the two variables +@code{imenu-prev-index-position-function} and +@code{imenu-extract-index-name-function}, or for the variable +@code{imenu-create-index-function} (@pxref{Imenu}). + +@item +The mode can specify a local value for +@code{eldoc-documentation-function} to tell ElDoc mode how to handle +this mode. + +@item +Use @code{defvar} or @code{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.) + +@item +@cindex buffer-local variables in modes +To make a buffer-local binding for an Emacs customization variable, use +@code{make-local-variable} in the major mode command, not +@code{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. @xref{Buffer-Local Variables}. + +With rare exceptions, the only reasonable way to use +@code{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. + +@item +@cindex mode hook +@cindex major mode hook +Each major mode should have a normal @dfn{mode hook} named +@code{@var{modename}-mode-hook}. The very last thing the major mode command +should do is to call @code{run-mode-hooks}. This runs the mode hook, +and then runs the normal hook @code{after-change-major-mode-hook}. +@xref{Mode Hooks}. + +@item +The major mode command may start by calling some other major mode +command (called the @dfn{parent mode}) and then alter some of its +settings. A mode that does this is called a @dfn{derived mode}. The +recommended way to define one is to use @code{define-derived-mode}, +but this is not required. Such a mode should call the parent mode +command inside a @code{delay-mode-hooks} form. (Using +@code{define-derived-mode} does this automatically.) @xref{Derived +Modes}, and @ref{Mode Hooks}. + +@item +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 @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}). + +@item +If this mode is appropriate only for specially-prepared text, then the +major mode command symbol should have a property named @code{mode-class} +with value @code{special}, put on as follows: + +@kindex mode-class @r{(property)} +@cindex @code{special} +@example +(put 'funny-mode 'mode-class 'special) +@end example + +@noindent +This tells Emacs that new buffers created while the current buffer is +in Funny mode should not inherit Funny mode, in case +@code{default-major-mode} is @code{nil}. Modes such as Dired, Rmail, +and Buffer List use this feature. + +@item +If you want to make the new mode the default for files with certain +recognizable names, add an element to @code{auto-mode-alist} to select +the mode for those file names (@pxref{Auto Major Mode}). If you +define the mode command to autoload, you should add this element in +the same file that calls @code{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 (@pxref{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. + +@item +In the comments that document the file, you should provide a sample +@code{autoload} form and an example of how to add to +@code{auto-mode-alist}, that users can include in their init files +(@pxref{Init File}). + +@item +@cindex mode loading +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. +@end itemize + +@node Auto Major Mode +@subsection How Emacs Chooses a Major Mode +@cindex major mode, automatic selection + + 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. + +@deffn 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 @code{fundamental-mode} function does @emph{not} +run any mode hooks; you're not supposed to customize it. (If you want Emacs +to behave differently in Fundamental mode, change the @emph{global} +state of Emacs.) +@end deffn + +@deffn 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 @code{set-auto-mode} +(see below), then it runs @code{hack-local-variables} to parse, and +bind or evaluate as appropriate, the file's local variables +(@pxref{File Local Variables}). + +If the @var{find-file} argument to @code{normal-mode} is non-@code{nil}, +@code{normal-mode} assumes that the @code{find-file} function is calling +it. In this case, it may process local variables in the @samp{-*-} +line or at the end of the file. The variable +@code{enable-local-variables} controls whether to do so. @xref{File +Variables, , Local Variables in Files, emacs, The GNU Emacs Manual}, +for the syntax of the local variables section of a file. + +If you run @code{normal-mode} interactively, the argument +@var{find-file} is normally @code{nil}. In this case, +@code{normal-mode} unconditionally processes any file local variables. + +If @code{normal-mode} processes the local variables list and this list +specifies a major mode, that mode overrides any mode chosen by +@code{set-auto-mode}. If neither @code{set-auto-mode} nor +@code{hack-local-variables} specify a major mode, the buffer stays in +the major mode determined by @code{default-major-mode} (see below). + +@cindex file mode specification error +@code{normal-mode} uses @code{condition-case} around the call to the +major mode function, so errors are caught and reported as a @samp{File +mode specification error}, followed by the original error message. +@end deffn + +@defun set-auto-mode &optional keep-mode-if-same +@cindex visited file mode + This function selects the major mode that is appropriate for the +current buffer. It bases its decision (in order of precedence) on +the @w{@samp{-*-}} line, on the @w{@samp{#!}} line (using +@code{interpreter-mode-alist}), on the text at the beginning of the +buffer (using @code{magic-mode-alist}), and finally on the visited +file name (using @code{auto-mode-alist}). @xref{Choosing Modes, , How +Major Modes are Chosen, emacs, The GNU Emacs Manual}. However, this +function does not look for the @samp{mode:} local variable near the +end of a file; the @code{hack-local-variables} function does that. +If @code{enable-local-variables} is @code{nil}, @code{set-auto-mode} +does not check the @w{@samp{-*-}} line for a mode tag either. + +If @var{keep-mode-if-same} is non-@code{nil}, this function does not +call the mode command if the buffer is already in the proper major +mode. For instance, @code{set-visited-file-name} sets this to +@code{t} to avoid killing buffer local variables that the user may +have set. +@end defun + +@defopt default-major-mode +This variable holds the default major mode for new buffers. The +standard value is @code{fundamental-mode}. + +If the value of @code{default-major-mode} is @code{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 @code{mode-class} +property with value @code{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. +@end defopt + +@defun set-buffer-major-mode buffer +This function sets the major mode of @var{buffer} to the value of +@code{default-major-mode}; if that variable is @code{nil}, it uses the +current buffer's major mode (if that is suitable). As an exception, +if @var{buffer}'s name is @samp{*scratch*}, it sets the mode to +@code{initial-major-mode}. + +The low-level primitives for creating buffers do not use this function, +but medium-level commands such as @code{switch-to-buffer} and +@code{find-file-noselect} use it whenever they create buffers. +@end defun + +@defopt initial-major-mode +@cindex @samp{*scratch*} +The value of this variable determines the major mode of the initial +@samp{*scratch*} buffer. The value should be a symbol that is a major +mode command. The default value is @code{lisp-interaction-mode}. +@end defopt + +@defvar interpreter-mode-alist +This variable specifies major modes to use for scripts that specify a +command interpreter in a @samp{#!} line. Its value is an alist with +elements of the form @code{(@var{interpreter} . @var{mode})}; for +example, @code{("perl" . perl-mode)} is one element present by +default. The element says to use mode @var{mode} if the file +specifies an interpreter which matches @var{interpreter}. +@end defvar + +@defvar magic-mode-alist +This variable's value is an alist with elements of the form +@code{(@var{regexp} . @var{function})}, where @var{regexp} is a +regular expression and @var{function} is a function or @code{nil}. +After visiting a file, @code{set-auto-mode} calls @var{function} if +the text at the beginning of the buffer matches @var{regexp} and +@var{function} is non-@code{nil}; if @var{function} is @code{nil}, +@code{auto-mode-alist} gets to decide the mode. +@end defvar + +@defvar magic-fallback-mode-alist +This works like @code{magic-mode-alist}, except that it is handled +only if @code{auto-mode-alist} does not specify a mode for this file. +@end defvar + +@defvar 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 @samp{.el} and +@samp{.c}, but this need not be the case. An ordinary element of the +alist looks like @code{(@var{regexp} . @var{mode-function})}. + +For example, + +@smallexample +@group +(("\\`/tmp/fol/" . text-mode) + ("\\.texinfo\\'" . texinfo-mode) + ("\\.texi\\'" . texinfo-mode) +@end group +@group + ("\\.el\\'" . emacs-lisp-mode) + ("\\.c\\'" . c-mode) + ("\\.h\\'" . c-mode) + @dots{}) +@end group +@end smallexample + +When you visit a file whose expanded file name (@pxref{File Name +Expansion}), with version numbers and backup suffixes removed using +@code{file-name-sans-versions} (@pxref{File Name Components}), matches +a @var{regexp}, @code{set-auto-mode} calls the corresponding +@var{mode-function}. This feature enables Emacs to select the proper +major mode for most files. + +If an element of @code{auto-mode-alist} has the form @code{(@var{regexp} +@var{function} t)}, then after calling @var{function}, Emacs searches +@code{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 @code{("\\.gz\\'" +@var{function} t)} can uncompress the file and then put the uncompressed +file in the proper mode according to the name sans @samp{.gz}. + +Here is an example of how to prepend several pattern pairs to +@code{auto-mode-alist}. (You might use this sort of expression in your +init file.) + +@smallexample +@group +(setq auto-mode-alist + (append + ;; @r{File name (within directory) starts with a dot.} + '(("/\\.[^/]*\\'" . fundamental-mode) + ;; @r{File name has no dot.} + ("[^\\./]*\\'" . fundamental-mode) + ;; @r{File name ends in @samp{.C}.} + ("\\.C\\'" . c++-mode)) + auto-mode-alist)) +@end group +@end smallexample +@end defvar + +@node Mode Help +@subsection Getting Help about a Major Mode +@cindex mode help +@cindex help for major mode +@cindex documentation for major mode + + The @code{describe-mode} function is used to provide information +about major modes. It is normally called with @kbd{C-h m}. The +@code{describe-mode} function uses the value of @code{major-mode}, +which is why every major mode function needs to set the +@code{major-mode} variable. + +@deffn Command describe-mode +This function displays the documentation of the current major mode. + +The @code{describe-mode} function calls the @code{documentation} +function using the value of @code{major-mode} as an argument. Thus, it +displays the documentation string of the major mode function. +(@xref{Accessing Documentation}.) +@end deffn + +@defvar 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 @code{describe-mode} +function uses the documentation string of the function as the +documentation of the major mode. +@end defvar + +@node Derived Modes +@subsection Defining Derived Modes +@cindex derived mode + + 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 @code{define-derived-mode}. + +@defmac define-derived-mode variant parent name docstring keyword-args@dots{} body@dots{} +This construct defines @var{variant} as a major mode command, using +@var{name} as the string form of the mode name. @var{variant} and +@var{parent} should be unquoted symbols. + +The new command @var{variant} is defined to call the function +@var{parent}, then override certain aspects of that parent mode: + +@itemize @bullet +@item +The new mode has its own sparse keymap, named +@code{@var{variant}-map}. @code{define-derived-mode} +makes the parent mode's keymap the parent of the new map, unless +@code{@var{variant}-map} is already set and already has a parent. + +@item +The new mode has its own syntax table, kept in the variable +@code{@var{variant}-syntax-table}, unless you override this using the +@code{:syntax-table} keyword (see below). @code{define-derived-mode} +makes the parent mode's syntax-table the parent of +@code{@var{variant}-syntax-table}, unless the latter is already set +and already has a parent different from the standard syntax table. + +@item +The new mode has its own abbrev table, kept in the variable +@code{@var{variant}-abbrev-table}, unless you override this using the +@code{:abbrev-table} keyword (see below). + +@item +The new mode has its own mode hook, @code{@var{variant}-hook}. It +runs this hook, after running the hooks of its ancestor modes, with +@code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}. +@end itemize + +In addition, you can specify how to override other aspects of +@var{parent} with @var{body}. The command @var{variant} +evaluates the forms in @var{body} after setting up all its usual +overrides, just before running the mode hooks. + +You can also specify @code{nil} for @var{parent}. This gives the new +mode no parent. Then @code{define-derived-mode} behaves as described +above, but, of course, omits all actions connected with @var{parent}. + +The argument @var{docstring} specifies the documentation string for +the new mode. @code{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 @var{docstring}, +@code{define-derived-mode} generates a documentation string. + +The @var{keyword-args} are pairs of keywords and values. The values +are evaluated. The following keywords are currently supported: + +@table @code +@item :syntax-table +You can use this to explicitly specify a syntax table for the new +mode. If you specify a @code{nil} value, the new mode uses the same +syntax table as @var{parent}, or the standard syntax table if +@var{parent} is @code{nil}. (Note that this does @emph{not} follow +the convention used for non-keyword arguments that a @code{nil} value +is equivalent with not specifying the argument.) + +@item :abbrev-table +You can use this to explicitly specify an abbrev table for the new +mode. If you specify a @code{nil} value, the new mode uses the same +abbrev table as @var{parent}, or @code{fundamental-mode-abbrev-table} +if @var{parent} is @code{nil}. (Again, a @code{nil} value is +@emph{not} equivalent to not specifying this keyword.) + +@item :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 @code{customize-mode} currently +uses this. @code{define-derived-mode} does @emph{not} automatically +define the specified customization group. +@end table + +Here is a hypothetical example: + +@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) +@end example + +Do not write an @code{interactive} spec in the definition; +@code{define-derived-mode} does that automatically. +@end defmac + +@node Generic Modes +@subsection Generic Modes +@cindex generic mode + + @dfn{Generic modes} are simple major modes with basic support for +comment syntax and Font Lock mode. To define a generic mode, use the +macro @code{define-generic-mode}. See the file @file{generic-x.el} +for some examples of the use of @code{define-generic-mode}. + +@defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring +This macro defines a generic mode command named @var{mode} (a symbol, +not quoted). The optional argument @var{docstring} is the +documentation for the mode command. If you do not supply it, +@code{define-generic-mode} generates one by default. + +The argument @var{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 @sc{car} is set +up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.'' +(Use @code{nil} for the latter if you want comments to end at the end +of the line.) Note that the syntax table mechanism has limitations +about what comment starters and enders are actually possible. +@xref{Syntax Tables}. + +The argument @var{keyword-list} is a list of keywords to highlight +with @code{font-lock-keyword-face}. Each keyword should be a string. +Meanwhile, @var{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 @code{font-lock-keywords}. @xref{Search-based +Fontification}. + +The argument @var{auto-mode-list} is a list of regular expressions to +add to the variable @code{auto-mode-alist}. They are added by the execution +of the @code{define-generic-mode} form, not by expanding the macro call. + +Finally, @var{function-list} is a list of functions for the mode +command to call for additional setup. It calls these functions just +before it runs the mode hook variable @code{@var{mode}-hook}. +@end defmac + +@node Mode Hooks +@subsection Mode Hooks + + Every major mode function should finish by running its mode hook and +the mode-independent normal hook @code{after-change-major-mode-hook}. +It does this by calling @code{run-mode-hooks}. If the major mode is a +derived mode, that is if it calls another major mode (the parent mode) +in its body, it should do this inside @code{delay-mode-hooks} so that +the parent won't run these hooks itself. Instead, the derived mode's +call to @code{run-mode-hooks} runs the parent's mode hook too. +@xref{Major Mode Conventions}. + + Emacs versions before Emacs 22 did not have @code{delay-mode-hooks}. +When user-implemented major modes have not been updated to use it, +they won't entirely follow these conventions: they may run the +parent's mode hook too early, or fail to run +@code{after-change-major-mode-hook}. If you encounter such a major +mode, please correct it to follow these conventions. + + When you defined a major mode using @code{define-derived-mode}, it +automatically makes sure these conventions are followed. If you +define a major mode ``by hand,'' not using @code{define-derived-mode}, +use the following functions to handle these conventions automatically. + +@defun run-mode-hooks &rest hookvars +Major modes should run their mode hook using this function. It is +similar to @code{run-hooks} (@pxref{Hooks}), but it also runs +@code{after-change-major-mode-hook}. + +When this function is called during the execution of a +@code{delay-mode-hooks} form, it does not run the hooks immediately. +Instead, it arranges for the next call to @code{run-mode-hooks} to run +them. +@end defun + +@defmac delay-mode-hooks body@dots{} +When one major mode command calls another, it should do so inside of +@code{delay-mode-hooks}. + +This macro executes @var{body}, but tells all @code{run-mode-hooks} +calls during the execution of @var{body} to delay running their hooks. +The hooks will actually run during the next call to +@code{run-mode-hooks} after the end of the @code{delay-mode-hooks} +construct. +@end defmac + +@defvar after-change-major-mode-hook +This is a normal hook run by @code{run-mode-hooks}. It is run at the +very end of every properly-written major mode function. +@end defvar + +@node Example Major Modes +@subsection Major Mode Examples + + Text mode is perhaps the simplest mode besides Fundamental mode. +Here are excerpts from @file{text-mode.el} that illustrate many of +the conventions listed above: + +@smallexample +@group +;; @r{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) + ;; Add `p' so M-c on `hello' leads to `Hello', not `hello'. + (modify-syntax-entry ?' "w p" st) + st) + "Syntax table used while in `text-mode'.") +@end group + +;; @r{Create the keymap for this mode.} +@group +(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.") +@end group +@end smallexample + + Here is how the actual mode command is defined now: + +@smallexample +@group +(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'." +@end group +@group + (make-local-variable 'text-mode-variant) + (setq text-mode-variant t) + ;; @r{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)) +@end group +@end smallexample + +@noindent +(The last line is redundant nowadays, since @code{indent-relative} is +the default value, and we'll delete it in a future version.) + + Here is how it was defined formerly, before +@code{define-derived-mode} existed: + +@smallexample +@group +;; @r{This isn't needed nowadays, since @code{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 ()) +@end group + +@group +(defun text-mode () + "Major mode for editing text intended for humans to read... + Special commands: \\@{text-mode-map@} +@end group +@group +Turning on text-mode runs the hook `text-mode-hook'." + (interactive) + (kill-all-local-variables) + (use-local-map text-mode-map) +@end group +@group + (setq local-abbrev-table text-mode-abbrev-table) + (set-syntax-table text-mode-syntax-table) +@end group +@group + ;; @r{These four lines are absent from the current version} + ;; @r{not because this is done some other way, but rather} + ;; @r{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) +@end group +@group + (setq mode-name "Text") + (setq major-mode 'text-mode) + (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to} + ; @r{customize the mode with a hook.} +@end group +@end smallexample + +@cindex @file{lisp-mode.el} + 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 +@file{lisp-mode.el} that illustrate how these modes are written. + +@cindex syntax table example +@smallexample +@group +;; @r{Create mode-specific table variables.} +(defvar lisp-mode-syntax-table nil "") +(defvar lisp-mode-abbrev-table nil "") +@end group + +@group +(defvar emacs-lisp-mode-syntax-table + (let ((table (make-syntax-table))) + (let ((i 0)) +@end group + +@group + ;; @r{Set syntax of chars up to @samp{0} to say they are} + ;; @r{part of symbol names but not words.} + ;; @r{(The digit @samp{0} is @code{48} in the @acronym{ASCII} character set.)} + (while (< i ?0) + (modify-syntax-entry i "_ " table) + (setq i (1+ i))) + ;; @r{@dots{} similar code follows for other character ranges.} +@end group +@group + ;; @r{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) +@end group +@group + ;; @r{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) +@end group +@group + ;; @r{@dots{}likewise for many other characters@dots{}} + (modify-syntax-entry ?\( "() " table) + (modify-syntax-entry ?\) ")( " table) + (modify-syntax-entry ?\[ "(] " table) + (modify-syntax-entry ?\] ")[ " table)) + table)) +@end group +@group +;; @r{Create an abbrev table for lisp-mode.} +(define-abbrev-table 'lisp-mode-abbrev-table ()) +@end group +@end smallexample + + The three modes for Lisp share much of their code. For instance, +each calls the following function to set various variables: + +@smallexample +@group +(defun lisp-mode-variables (lisp-syntax) + (when lisp-syntax + (set-syntax-table lisp-mode-syntax-table)) + (setq local-abbrev-table lisp-mode-abbrev-table) + @dots{} +@end group +@end smallexample + + In Lisp and most programming languages, we want the paragraph +commands to treat only blank lines as paragraph separators. And the +modes should understand the Lisp conventions for comments. The rest of +@code{lisp-mode-variables} sets this up: + +@smallexample +@group + (make-local-variable 'paragraph-start) + (setq paragraph-start (concat page-delimiter "\\|$" )) + (make-local-variable 'paragraph-separate) + (setq paragraph-separate paragraph-start) + @dots{} +@end group +@group + (make-local-variable 'comment-indent-function) + (setq comment-indent-function 'lisp-comment-indent)) + @dots{} +@end group +@end smallexample + + Each of the different Lisp modes has a slightly different keymap. For +example, Lisp mode binds @kbd{C-c C-z} to @code{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: + +@smallexample +@group +(defvar shared-lisp-mode-map () + "Keymap for commands shared by all sorts of Lisp modes.") + +;; @r{Putting this @code{if} after the @code{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)) +@end group +@end smallexample + +@noindent +And here is the code to set up the keymap for Lisp mode: + +@smallexample +@group +(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)) +@end group +@end smallexample + + Finally, here is the complete major mode function definition for +Lisp mode. + +@smallexample +@group +(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. +@end group + +@group +Entry to this mode calls the value of `lisp-mode-hook' +if that value is non-nil." + (interactive) + (kill-all-local-variables) +@end group +@group + (use-local-map lisp-mode-map) ; @r{Select the mode's keymap.} + (setq major-mode 'lisp-mode) ; @r{This is how @code{describe-mode}} + ; @r{finds out what to describe.} + (setq mode-name "Lisp") ; @r{This goes into the mode line.} + (lisp-mode-variables t) ; @r{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) +@end group +@group + (setq imenu-case-fold-search t) + (set-syntax-table lisp-mode-syntax-table) + (run-mode-hooks 'lisp-mode-hook)) ; @r{This permits the user to use a} + ; @r{hook to customize the mode.} +@end group +@end smallexample + +@node Minor Modes +@section Minor Modes +@cindex minor mode + + A @dfn{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. + +@defvar minor-mode-list +The value of this variable is a list of all minor mode commands. +@end defvar + +@menu +* Minor Mode Conventions:: Tips for writing a minor mode. +* Keymaps and Minor Modes:: How a minor mode can have its own keymap. +* Defining Minor Modes:: A convenient facility for defining minor modes. +@end menu + +@node Minor Mode Conventions +@subsection Conventions for Writing Minor Modes +@cindex minor mode conventions +@cindex 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 @code{define-minor-mode}; @ref{Defining Minor Modes}.) + +@itemize @bullet +@item +@cindex mode variable +Make a variable whose name ends in @samp{-mode} to control the minor +mode. We call this the @dfn{mode variable}. The minor mode command +should set this variable (@code{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 @code{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. + +@item +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 +@code{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 @code{t}, or a list whose @sc{car} is one +of those. It should turn the mode off if the argument is a negative +integer or zero, the symbol @code{-}, or a list whose @sc{car} is a +negative integer or zero. The meaning of other arguments is not +specified. + +Here is an example taken from the definition of @code{transient-mark-mode}. +It shows the use of @code{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. + +@smallexample +@group +(setq transient-mark-mode + (if (null arg) (not transient-mark-mode) + (> (prefix-numeric-value arg) 0))) +@end group +@end smallexample + +@item +Add an element to @code{minor-mode-alist} for each minor mode +(@pxref{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: + +@smallexample +(@var{mode-variable} @var{string}) +@end smallexample + +Here @var{mode-variable} is the variable that controls enabling of the +minor mode, and @var{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 @code{minor-mode-alist}, use @code{assq} to +check for an existing element, to avoid duplication. For example: + +@smallexample +@group +(unless (assq 'leif-mode minor-mode-alist) + (setq minor-mode-alist + (cons '(leif-mode " Leif") minor-mode-alist))) +@end group +@end smallexample + +@noindent +or like this, using @code{add-to-list} (@pxref{List Variables}): + +@smallexample +@group +(add-to-list 'minor-mode-alist '(leif-mode " Leif")) +@end group +@end smallexample +@end itemize + + Global minor modes distributed with Emacs should if possible support +enabling and disabling via Custom (@pxref{Customization}). To do this, +the first step is to define the mode variable with @code{defcustom}, and +specify @code{:type boolean}. + + If just setting the variable is not sufficient to enable the mode, you +should also specify a @code{: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 (@pxref{autoload cookie}), +and specify a @code{:require} so that customizing the variable will load +the library that defines the mode. This will copy suitable definitions +into @file{loaddefs.el} so that users can use @code{customize-option} to +enable the mode. For example: + +@smallexample +@group + +;;;###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) +@end group +@end smallexample + +@node Keymaps and Minor Modes +@subsection 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 @code{minor-mode-map-alist}. @xref{Definition of minor-mode-map-alist}. + +@cindex @code{self-insert-command}, minor modes + 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 @code{self-insert-command} are limited to +special cases (designed for abbrevs and Auto Fill mode). (Do not try +substituting your own definition of @code{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 @kbd{C-c} +followed by one of @kbd{.,/?`'"[]\|~!#$%^&*()-_+=}. (The other +punctuation characters are reserved for major modes.) + +@node Defining Minor Modes +@subsection Defining Minor Modes + + The macro @code{define-minor-mode} offers a convenient way of +implementing a mode in one self-contained definition. + +@defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args@dots{} body@dots{} +This macro defines a new minor mode whose name is @var{mode} (a +symbol). It defines a command named @var{mode} to toggle the minor +mode, with @var{doc} as its documentation string. It also defines a +variable named @var{mode}, which is set to @code{t} or @code{nil} by +enabling or disabling the mode. The variable is initialized to +@var{init-value}. Except in unusual circumstances (see below), this +value must be @code{nil}. + +The string @var{lighter} says what to display in the mode line +when the mode is enabled; if it is @code{nil}, the mode is not displayed +in the mode line. + +The optional argument @var{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: + +@example +(@var{key-sequence} . @var{definition}) +@end example + +The above three arguments @var{init-value}, @var{lighter}, and +@var{keymap} can be (partially) omitted when @var{keyword-args} are +used. The @var{keyword-args} consist of keywords followed by +corresponding values. A few keywords have special meanings: + +@table @code +@item :group @var{group} +Custom group name to use in all generated @code{defcustom} forms. +Defaults to @var{mode} without the possible trailing @samp{-mode}. +@strong{Warning:} don't use this default group name unless you have +written a @code{defgroup} to define that group properly. @xref{Group +Definitions}. + +@item :global @var{global} +If non-@code{nil}, this specifies that the minor mode should be global +rather than buffer-local. It defaults to @code{nil}. + +One of the effects of making a minor mode global is that the +@var{mode} variable becomes a customization variable. Toggling it +through the Custom interface turns the mode on and off, and its value +can be saved for future Emacs sessions (@pxref{Saving +Customizations,,, emacs, The GNU Emacs Manual}. For the saved +variable to work, you should ensure that the @code{define-minor-mode} +form is evaluated each time Emacs starts; for packages that are not +part of Emacs, the easiest way to do this is to specify a +@code{:require} keyword. + +@item :init-value @var{init-value} +This is equivalent to specifying @var{init-value} positionally. + +@item :lighter @var{lighter} +This is equivalent to specifying @var{lighter} positionally. + +@item :keymap @var{keymap} +This is equivalent to specifying @var{keymap} positionally. +@end table + +Any other keyword arguments are passed directly to the +@code{defcustom} generated for the variable @var{mode}. + +The command named @var{mode} first performs the standard actions such +as setting the variable named @var{mode} and then executes the +@var{body} forms, if any. It finishes by running the mode hook +variable @code{@var{mode}-hook}. +@end defmac + + The initial value must be @code{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 @code{nil}. + +@findex easy-mmode-define-minor-mode + The name @code{easy-mmode-define-minor-mode} is an alias +for this macro. + + Here is an example of using @code{define-minor-mode}: + +@smallexample +(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) +@end smallexample + +@noindent +This defines a minor mode named ``Hungry mode,'' a command named +@code{hungry-mode} to toggle it, a variable named @code{hungry-mode} +which indicates whether the mode is enabled, and a variable named +@code{hungry-mode-map} which holds the keymap that is active when the +mode is enabled. It initializes the keymap with a key binding for +@kbd{C-@key{DEL}}. It puts the variable @code{hungry-mode} into +custom group @code{hunger}. There are no @var{body} forms---many +minor modes don't need any. + + Here's an equivalent way to write it: + +@smallexample +(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) +@end smallexample + +@defmac define-globalized-minor-mode global-mode mode turn-on keyword-args@dots{} +This defines a global toggle named @var{global-mode} whose meaning is +to enable or disable the buffer-local minor mode @var{mode} in all +buffers. To turn on the minor mode in a buffer, it uses the function +@var{turn-on}; to turn off the minor mode, it calls @code{mode} with +@minus{}1 as argument. + +Globally enabling the mode also affects buffers subsequently created +by visiting files, and buffers that use a major mode other than +Fundamental mode; but it does not detect the creation of a new buffer +in Fundamental mode. + +This defines the customization option @var{global-mode} (@pxref{Customization}), +which can be toggled in the Custom interface to turn the minor mode on +and off. As with @code{define-minor-mode}, you should ensure that the +@code{define-globalized-minor-mode} form is evaluated each time Emacs +starts, for example by providing a @code{:require} keyword. + +Use @code{:group @var{group}} in @var{keyword-args} to specify the +custom group for the mode variable of the global minor mode. +@end defmac + +@node Mode Line Format +@section Mode-Line Format +@cindex mode line + + 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 @dfn{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. + +@menu +* Base: Mode Line Basics. Basic ideas of mode line control. +* Data: Mode Line Data. The data structure that controls the mode line. +* Top: Mode Line Top. The top level variable, mode-line-format. +* Mode Line Variables:: Variables used in that data structure. +* %-Constructs:: Putting information into a mode line. +* Properties in Mode:: Using text properties in the mode line. +* Header Lines:: Like a mode line, but at the top. +* Emulating Mode Line:: Formatting text as the mode line would. +@end menu + +@node Mode Line Basics +@subsection Mode Line Basics + + @code{mode-line-format} is a buffer-local variable that holds a +@dfn{mode line construct}, a kind of template, which controls what is +displayed on the mode line of the current buffer. The value of +@code{header-line-format} specifies the buffer's header line in the +same way. All windows for the same buffer use the same +@code{mode-line-format} and @code{header-line-format}. + + For efficiency, Emacs does not continuously recompute the mode +line and header line of a window. 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 @code{mode-line-format} (@pxref{Mode Line +Variables}), or any other variables and data structures that affect +how text is displayed (@pxref{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. + +@defun 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-@code{nil} @var{all}, force redisplay of all mode lines and header +lines. + +This function also forces recomputation of the menu bar menus +and the frame title. +@end defun + + The selected window's mode line is usually displayed in a different +color using the face @code{mode-line}. Other windows' mode lines +appear in the face @code{mode-line-inactive} instead. @xref{Faces}. + +@node Mode Line Data +@subsection The Data Structure of the Mode Line +@cindex mode-line construct + + The mode-line contents are controlled by a data structure called a +@dfn{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 (@pxref{Frame +Titles}) and header lines (@pxref{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: + +@table @code +@cindex percent symbol in mode line +@item @var{string} +A string as a mode-line construct appears verbatim except for +@dfn{@code{%}-constructs} in it. These stand for substitution of +other data; see @ref{%-Constructs}. + +If parts of the string have @code{face} properties, they control +display of the text just as they would text in the buffer. Any +characters which have no @code{face} properties are displayed, by +default, in the face @code{mode-line} or @code{mode-line-inactive} +(@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}). The +@code{help-echo} and @code{local-map} properties in @var{string} have +special meanings. @xref{Properties in Mode}. + +@item @var{symbol} +A symbol as a mode-line construct stands for its value. The value of +@var{symbol} is used as a mode-line construct, in place of @var{symbol}. +However, the symbols @code{t} and @code{nil} are ignored, as is any +symbol whose value is void. + +There is one exception: if the value of @var{symbol} is a string, it is +displayed verbatim: the @code{%}-constructs are not recognized. + +Unless @var{symbol} is marked as ``risky'' (i.e., it has a +non-@code{nil} @code{risky-local-variable} property), all text +properties specified in @var{symbol}'s value are ignored. This +includes the text properties of strings in @var{symbol}'s value, as +well as all @code{:eval} and @code{:propertize} forms in it. (The +reason for this is security: non-risky variables could be set +automatically from file variables without prompting the user.) + +@item (@var{string} @var{rest}@dots{}) +@itemx (@var{list} @var{rest}@dots{}) +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. + +@item (:eval @var{form}) +A list whose first element is the symbol @code{:eval} says to evaluate +@var{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. + +@item (:propertize @var{elt} @var{props}@dots{}) +A list whose first element is the symbol @code{:propertize} says to +process the mode-line construct @var{elt} recursively, then add the text +properties specified by @var{props} to the result. The argument +@var{props} should consist of zero or more pairs @var{text-property} +@var{value}. (This feature is new as of Emacs 22.1.) + +@item (@var{symbol} @var{then} @var{else}) +A list whose first element is a symbol that is not a keyword specifies +a conditional. Its meaning depends on the value of @var{symbol}. If +@var{symbol} has a non-@code{nil} value, the second element, +@var{then}, is processed recursively as a mode-line element. +Otherwise, the third element, @var{else}, is processed recursively. +You may omit @var{else}; then the mode-line element displays nothing +if the value of @var{symbol} is @code{nil} or void. + +@item (@var{width} @var{rest}@dots{}) +A list whose first element is an integer specifies truncation or +padding of the results of @var{rest}. The remaining elements +@var{rest} are processed recursively as mode-line constructs and +concatenated together. When @var{width} is positive, the result is +space filled on the right if its width is less than @var{width}. When +@var{width} is negative, the result is truncated on the right to +@minus{}@var{width} columns if its width exceeds @minus{}@var{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: @code{(-3 "%p")}. +@end table + +@node Mode Line Top +@subsection The Top Level of Mode Line Control + + The variable in overall control of the mode line is +@code{mode-line-format}. + +@defvar 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 @code{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.) +@end defvar + + The default value of @code{mode-line-format} is designed to use the +values of other variables such as @code{mode-line-position} and +@code{mode-line-modes} (which in turn incorporates the values of the +variables @code{mode-name} and @code{minor-mode-alist}). Very few +modes need to alter @code{mode-line-format} itself. For most +purposes, it is sufficient to alter some of the variables that +@code{mode-line-format} either directly or indirectly refers to. + + If you do alter @code{mode-line-format} itself, the new value should +use the same variables that appear in the default value (@pxref{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 @code{display-time} and major +modes) via changes to those variables remain effective. + + Here is an example of a @code{mode-line-format} that might be +useful for @code{shell-mode}, since it contains the host name and default +directory. + +@example +@group +(setq mode-line-format + (list "-" + 'mode-line-mule-info + 'mode-line-modified + 'mode-line-frame-identification + "%b--" +@end group +@group + ;; @r{Note that this is evaluated while making the list.} + ;; @r{It makes a mode-line construct which is just a string.} + (getenv "HOST") +@end group + ":" + 'default-directory + " " + 'global-mode-string + " %[(" + '(:eval (mode-line-mode-name)) + 'mode-line-process + 'minor-mode-alist + "%n" + ")%]--" +@group + '(which-func-mode ("" which-func-format "--")) + '(line-number-mode "L%l--") + '(column-number-mode "C%c--") + '(-3 "%p") + "-%-")) +@end group +@end example + +@noindent +(The variables @code{line-number-mode}, @code{column-number-mode} +and @code{which-func-mode} enable particular minor modes; as usual, +these variable names are also the minor mode command names.) + +@node Mode Line Variables +@subsection Variables Used in the Mode Line + + This section describes variables incorporated by the standard value +of @code{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 +@code{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. + +@defvar 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. @xref{Non-ASCII Characters}. +@end defvar + +@defvar 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 @code{mode-line-modified} is @code{("%1*%1+")}. +This means that the mode line displays @samp{**} if the buffer is +modified, @samp{--} if the buffer is not modified, @samp{%%} if the +buffer is read only, and @samp{%*} if the buffer is read only and +modified. + +Changing this variable does not force an update of the mode line. +@end defvar + +@defvar mode-line-frame-identification +This variable identifies the current frame. The default value is +@code{" "} if you are using a window system which can show multiple +frames, or @code{"-%F "} on an ordinary terminal which shows only one +frame at a time. +@end defvar + +@defvar mode-line-buffer-identification +This variable identifies the buffer being displayed in the window. Its +default value is @code{("%12b")}, which displays the buffer name, padded +with spaces to at least 12 columns. +@end defvar + +@defvar 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 @code{help-echo} text property. + +@example +@group +((-3 "%p") + (size-indication-mode (8 " of %I")) +@end group +@group + (line-number-mode + ((column-number-mode + (10 " (%l,%c)") + (6 " L%l"))) + ((column-number-mode + (5 " C%c"))))) +@end group +@end example + +This means that @code{mode-line-position} displays at least the buffer +percentage and possibly the buffer size, the line number and the column +number. +@end defvar + +@defvar vc-mode +The variable @code{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 @code{nil} for no version control. +@end defvar + +@defvar 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. + +@example +@group +("%[(" mode-name + mode-line-process minor-mode-alist + "%n" ")%]--") +@end group +@end example + +So @code{mode-line-modes} normally also displays the recursive editing +level, information on the process status and whether narrowing is in +effect. +@end defvar + + The following three variables are used in @code{mode-line-modes}: + +@defvar 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. +@end defvar + +@defvar 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 @samp{*shell*} buffer is +@code{(":%s")}, which allows the shell to display its status along +with the major mode as: @samp{(Shell:run)}. Normally this variable +is @code{nil}. +@end defvar + +@defvar minor-mode-alist +@anchor{Definition of 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 @code{minor-mode-alist} should be a two-element list: + +@example +(@var{minor-mode-variable} @var{mode-line-string}) +@end example + +More generally, @var{mode-line-string} can be any mode-line spec. It +appears in the mode line when the value of @var{minor-mode-variable} +is non-@code{nil}, and not otherwise. These strings should begin with +spaces so that they don't run together. Conventionally, the +@var{minor-mode-variable} for a specific mode is set to a +non-@code{nil} value when that minor mode is activated. + +@code{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. +@end defvar + +@defvar global-mode-string +This variable holds a mode-line spec that, by default, appears in the +mode line just after the @code{which-func-mode} minor mode if set, +else after @code{mode-line-modes}. The command @code{display-time} +sets @code{global-mode-string} to refer to the variable +@code{display-time-string}, which holds a string containing the time +and load information. + +The @samp{%M} construct substitutes the value of +@code{global-mode-string}, but that is obsolete, since the variable is +included in the mode line from @code{mode-line-format}. +@end defvar + + The variable @code{default-mode-line-format} is where +@code{mode-line-format} usually gets its value: + +@defvar default-mode-line-format +This variable holds the default @code{mode-line-format} for buffers +that do not override it. This is the same as @code{(default-value +'mode-line-format)}. + +Here is a simplified version of the default value of +@code{default-mode-line-format}. The real default value also +specifies addition of text properties. + +@example +@group +("-" + mode-line-mule-info + mode-line-modified + mode-line-frame-identification + mode-line-buffer-identification +@end group + " " + mode-line-position + (vc-mode vc-mode) + " " +@group + mode-line-modes + (which-func-mode ("" which-func-format "--")) + (global-mode-string ("--" global-mode-string)) + "-%-") +@end group +@end example +@end defvar + +@node %-Constructs +@subsection @code{%}-Constructs in the Mode Line + + Strings used as mode-line constructs can use certain +@code{%}-constructs to substitute various kinds of data. Here is a +list of the defined @code{%}-constructs, and what they mean. In any +construct except @samp{%%}, you can add a decimal integer after the +@samp{%} to specify a minimum field width. If the width is less, the +field is padded with spaces to the right. + +@table @code +@item %b +The current buffer name, obtained with the @code{buffer-name} function. +@xref{Buffer Names}. + +@item %c +The current column number of point. + +@item %e +When Emacs is nearly out of memory for Lisp objects, a brief message +saying so. Otherwise, this is empty. + +@item %f +The visited file name, obtained with the @code{buffer-file-name} +function. @xref{Buffer File Name}. + +@item %F +The title (only on a window system) or the name of the selected frame. +@xref{Basic Parameters}. + +@item %i +The size of the accessible part of the current buffer; basically +@code{(- (point-max) (point-min))}. + +@item %I +Like @samp{%i}, but the size is printed in a more readable way by using +@samp{k} for 10^3, @samp{M} for 10^6, @samp{G} for 10^9, etc., to +abbreviate. + +@item %l +The current line number of point, counting within the accessible portion +of the buffer. + +@item %n +@samp{Narrow} when narrowing is in effect; nothing otherwise (see +@code{narrow-to-region} in @ref{Narrowing}). + +@item %p +The percentage of the buffer text above the @strong{top} of window, or +@samp{Top}, @samp{Bottom} or @samp{All}. Note that the default +mode-line specification truncates this to three characters. + +@item %P +The percentage of the buffer text that is above the @strong{bottom} of +the window (which includes the text visible in the window, as well as +the text above the top), plus @samp{Top} if the top of the buffer is +visible on screen; or @samp{Bottom} or @samp{All}. + +@item %s +The status of the subprocess belonging to the current buffer, obtained with +@code{process-status}. @xref{Process Information}. + +@item %t +Whether the visited file is a text file or a binary file. This is a +meaningful distinction only on certain operating systems (@pxref{MS-DOS +File Types}). + +@item %z +The mnemonics of keyboard, terminal, and buffer coding systems. + +@item %Z +Like @samp{%z}, but including the end-of-line format. + +@item %* +@samp{%} if the buffer is read only (see @code{buffer-read-only}); @* +@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @* +@samp{-} otherwise. @xref{Buffer Modification}. + +@item %+ +@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @* +@samp{%} if the buffer is read only (see @code{buffer-read-only}); @* +@samp{-} otherwise. This differs from @samp{%*} only for a modified +read-only buffer. @xref{Buffer Modification}. + +@item %& +@samp{*} if the buffer is modified, and @samp{-} otherwise. + +@item %[ +An indication of the depth of recursive editing levels (not counting +minibuffer levels): one @samp{[} for each editing level. +@xref{Recursive Editing}. + +@item %] +One @samp{]} for each recursive editing level (not counting minibuffer +levels). + +@item %- +Dashes sufficient to fill the remainder of the mode line. + +@item %% +The character @samp{%}---this is how to include a literal @samp{%} in a +string in which @code{%}-constructs are allowed. +@end table + +The following two @code{%}-constructs are still supported, but they are +obsolete, since you can get the same results with the variables +@code{mode-name} and @code{global-mode-string}. + +@table @code +@item %m +The value of @code{mode-name}. + +@item %M +The value of @code{global-mode-string}. +@end table + +@node Properties in Mode +@subsection Properties in the Mode Line +@cindex text properties in the mode line + + Certain text properties are meaningful in the +mode line. The @code{face} property affects the appearance of text; the +@code{help-echo} property associates help strings with the text, and +@code{local-map} can make the text mouse-sensitive. + + There are four ways to specify text properties for text in the mode +line: + +@enumerate +@item +Put a string with a text property directly into the mode-line data +structure. + +@item +Put a text property on a mode-line %-construct such as @samp{%12b}; then +the expansion of the %-construct will have that same text property. + +@item +Use a @code{(:propertize @var{elt} @var{props}@dots{})} construct to +give @var{elt} a text property specified by @var{props}. + +@item +Use a list containing @code{:eval @var{form}} in the mode-line data +structure, and make @var{form} evaluate to a string that has a text +property. +@end enumerate + + You can use the @code{local-map} property to specify a keymap. This +keymap only takes real effect for mouse clicks; binding character keys +and function keys to it has no effect, since it is impossible to move +point into the mode line. + + When the mode line refers to a variable which does not have a +non-@code{nil} @code{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. + +@node Header Lines +@subsection Window Header Lines +@cindex header line (of a window) +@cindex window header line + + A window can have a @dfn{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. + +@defvar 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 @code{mode-line-format} (@pxref{Mode Line Data}). +@end defvar + +@defvar default-header-line-format +This variable holds the default @code{header-line-format} for buffers +that do not override it. This is the same as @code{(default-value +'header-line-format)}. + +It is normally @code{nil}, so that ordinary buffers have no header line. +@end defvar + + 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. + +@node Emulating Mode Line +@subsection Emulating Mode-Line Formatting + + You can use the function @code{format-mode-line} to compute +the text that would appear in a mode line or header line +based on a certain mode-line specification. + +@defun format-mode-line format &optional face window buffer +This function formats a line of text according to @var{format} as if +it were generating the mode line for @var{window}, but instead of +displaying the text in the mode line or the header line, it returns +the text as a string. The argument @var{window} defaults to the +selected window. If @var{buffer} is non-@code{nil}, all the +information used is taken from @var{buffer}; by default, it comes from +@var{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 @code{face} property is specified gets a default +value which is usually @var{face}. (If @var{face} is @code{t}, +that stands for either @code{mode-line} if @var{window} is selected, +otherwise @code{mode-line-inactive}. If @var{face} is @code{nil} or +omitted, that stands for no face property.) + +However, if @var{face} is an integer, the value has no text properties. + +For example, @code{(format-mode-line header-line-format)} returns the +text that would appear in the selected window's header line (@code{""} +if it has no header line). @code{(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. +@end defun + +@node Imenu +@section Imenu + +@cindex Imenu + @dfn{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 @code{imenu-add-to-menubar}. + +@defun imenu-add-to-menubar name +This function defines a local menu bar item named @var{name} +to run Imenu. +@end defun + + The user-level commands for using Imenu are described in the Emacs +Manual (@pxref{Imenu,, Imenu, emacs, 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 +@code{imenu-generic-expression}: + +@defvar imenu-generic-expression +This variable, if non-@code{nil}, is a list that specifies regular +expressions for finding definitions for Imenu. Simple elements of +@code{imenu-generic-expression} look like this: + +@example +(@var{menu-title} @var{regexp} @var{index}) +@end example + +Here, if @var{menu-title} is non-@code{nil}, it says that the matches +for this element should go in a submenu of the buffer index; +@var{menu-title} itself specifies the name for the submenu. If +@var{menu-title} is @code{nil}, the matches for this element go directly +in the top level of the buffer index. + +The second item in the list, @var{regexp}, is a regular expression +(@pxref{Regular Expressions}); anything in the buffer that it matches +is considered a definition, something to mention in the buffer index. +The third item, @var{index}, is a non-negative integer that indicates +which subexpression in @var{regexp} matches the definition's name. + +An element can also look like this: + +@example +(@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{}) +@end example + +Each match for this element creates an index item, and when the index +item is selected by the user, it calls @var{function} with arguments +consisting of the item name, the buffer position, and @var{arguments}. + +For Emacs Lisp mode, @code{imenu-generic-expression} could look like +this: + +@c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+] +@example +@group +((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\ +\\s-+\\([-A-Za-z0-9+]+\\)" 2) +@end group +@group + ("*Vars*" "^\\s-*(def\\(var\\|const\\)\ +\\s-+\\([-A-Za-z0-9+]+\\)" 2) +@end group +@group + ("*Types*" + "^\\s-*\ +(def\\(type\\|struct\\|class\\|ine-condition\\)\ +\\s-+\\([-A-Za-z0-9+]+\\)" 2)) +@end group +@end example + +Setting this variable makes it buffer-local in the current buffer. +@end defvar + +@defvar imenu-case-fold-search +This variable controls whether matching against the regular +expressions in the value of @code{imenu-generic-expression} is +case-sensitive: @code{t}, the default, means matching should ignore +case. + +Setting this variable makes it buffer-local in the current buffer. +@end defvar + +@defvar imenu-syntax-alist +This variable is an alist of syntax table modifiers to use while +processing @code{imenu-generic-expression}, to override the syntax table +of the current buffer. Each element should have this form: + +@example +(@var{characters} . @var{syntax-description}) +@end example + +The @sc{car}, @var{characters}, can be either a character or a string. +The element says to give that character or characters the syntax +specified by @var{syntax-description}, which is passed to +@code{modify-syntax-entry} (@pxref{Syntax Table Functions}). + +This feature is typically used to give word syntax to characters which +normally have symbol syntax, and thus to simplify +@code{imenu-generic-expression} and speed up matching. +For example, Fortran mode uses it this way: + +@example +(setq imenu-syntax-alist '(("_$" . "w"))) +@end example + +The @code{imenu-generic-expression} regular expressions can then use +@samp{\\sw+} instead of @samp{\\(\\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. +@end defvar + + Another way to customize Imenu for a major mode is to set the +variables @code{imenu-prev-index-position-function} and +@code{imenu-extract-index-name-function}: + +@defvar imenu-prev-index-position-function +If this variable is non-@code{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 @code{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-@code{nil} value. + +Setting this variable makes it buffer-local in the current buffer. +@end defvar + +@defvar imenu-extract-index-name-function +If this variable is non-@code{nil}, its value should be a function to +return the name for a definition, assuming point is in that definition +as the @code{imenu-prev-index-position-function} function would leave +it. + +Setting this variable makes it buffer-local in the current buffer. +@end defvar + + The last way to customize Imenu for a major mode is to set the +variable @code{imenu-create-index-function}: + +@defvar 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 +@code{save-excursion}, so where it leaves point makes no difference. + +The index alist can have three types of elements. Simple elements +look like this: + +@example +(@var{index-name} . @var{index-position}) +@end example + +Selecting a simple element has the effect of moving to position +@var{index-position} in the buffer. Special elements look like this: + +@example +(@var{index-name} @var{index-position} @var{function} @var{arguments}@dots{}) +@end example + +Selecting a special element performs: + +@example +(funcall @var{function} + @var{index-name} @var{index-position} @var{arguments}@dots{}) +@end example + +A nested sub-alist element looks like this: + +@example +(@var{menu-title} @var{sub-alist}) +@end example + +It creates the submenu @var{menu-title} specified by @var{sub-alist}. + +The default value of @code{imenu-create-index-function} is +@code{imenu-default-create-index-function}. This function calls the +value of @code{imenu-prev-index-position-function} and the value of +@code{imenu-extract-index-name-function} to produce the index alist. +However, if either of these two variables is @code{nil}, the default +function uses @code{imenu-generic-expression} instead. + +Setting this variable makes it buffer-local in the current buffer. +@end defvar + +@node Font Lock Mode +@section Font Lock Mode +@cindex Font Lock mode + + @dfn{Font Lock mode} is a feature that automatically attaches +@code{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. + +@menu +* Font Lock Basics:: Overview of customizing Font Lock. +* Search-based Fontification:: Fontification based on regexps. +* Customizing Keywords:: Customizing search-based fontification. +* Other Font Lock Variables:: Additional customization facilities. +* Levels of Font Lock:: Each mode can define alternative levels + so that the user can select more or less. +* Precalculated Fontification:: How Lisp programs that produce the buffer + contents can also specify how to fontify it. +* Faces for Font Lock:: Special faces specifically for Font Lock. +* Syntactic Font Lock:: Fontification based on syntax tables. +* Setting Syntax Properties:: Defining character syntax based on context + using the Font Lock mechanism. +* Multiline Font Lock:: How to coerce Font Lock into properly + highlighting multiline constructs. +@end menu + +@node Font Lock Basics +@subsection 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 @code{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. + +@defvar 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. If its value is @code{nil}, Font-Lock +mode does no highlighting, and you can use the @samp{Faces} menu +(under @samp{Edit} and then @samp{Text Properties} in the menu bar) to +assign faces explicitly to text in the buffer. + +If non-@code{nil}, the value should look like this: + +@example +(@var{keywords} [@var{keywords-only} [@var{case-fold} + [@var{syntax-alist} [@var{syntax-begin} @var{other-vars}@dots{}]]]]) +@end example + +The first element, @var{keywords}, indirectly specifies the value of +@code{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 @code{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. @xref{Levels of Font Lock}. + +The second element, @var{keywords-only}, specifies the value of the +variable @code{font-lock-keywords-only}. If this is omitted or +@code{nil}, syntactic fontification (of strings and comments) is also +performed. If this is non-@code{nil}, such fontification is not +performed. @xref{Syntactic Font Lock}. + +The third element, @var{case-fold}, specifies the value of +@code{font-lock-keywords-case-fold-search}. If it is non-@code{nil}, +Font Lock mode ignores case when searching as directed by +@code{font-lock-keywords}. + +If the fourth element, @var{syntax-alist}, is non-@code{nil}, it +should be a list of cons cells of the form @code{(@var{char-or-string} +. @var{string})}. These are used to set up a syntax table for +syntactic fontification (@pxref{Syntax Table Functions}). The +resulting syntax table is stored in @code{font-lock-syntax-table}. + +The fifth element, @var{syntax-begin}, specifies the value of +@code{font-lock-beginning-of-syntax-function}. We recommend setting +this variable to @code{nil} and using @code{syntax-begin-function} +instead. + +All the remaining elements (if any) are collectively called +@var{other-vars}. Each of these elements should have the form +@code{(@var{variable} . @var{value})}---which means, make +@var{variable} buffer-local and then set it to @var{value}. You can +use these @var{other-vars} to set other variables that affect +fontification, aside from those you can control with the first five +elements. @xref{Other Font Lock Variables}. +@end defvar + + If your mode fontifies text explicitly by adding +@code{font-lock-face} properties, it can specify @code{(nil t)} for +@code{font-lock-defaults} to turn off all automatic fontification. +However, this is not required; it is possible to fontify some things +using @code{font-lock-face} properties and set up automatic +fontification for other parts of the text. + +@node Search-based Fontification +@subsection Search-based Fontification + + The most important variable for customizing Font Lock mode is +@code{font-lock-keywords}. It specifies the search criteria for +search-based fontification. You should specify the value of this +variable with @var{keywords} in @code{font-lock-defaults}. + +@defvar 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! +@end defvar + + Each element of @code{font-lock-keywords} specifies how to find +certain cases of text, and how to highlight those cases. Font Lock mode +processes the elements of @code{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 @var{override} element of a @var{subexp-highlighter}. + + Each element of @code{font-lock-keywords} should have one of these +forms: + +@table @code +@item @var{regexp} +Highlight all matches for @var{regexp} using +@code{font-lock-keyword-face}. For example, + +@example +;; @r{Highlight occurrences of the word @samp{foo}} +;; @r{using @code{font-lock-keyword-face}.} +"\\<foo\\>" +@end example + +The function @code{regexp-opt} (@pxref{Regexp Functions}) is useful +for calculating optimal regular expressions to match a number of +different keywords. + +@item @var{function} +Find text by calling @var{function}, and highlight the matches +it finds using @code{font-lock-keyword-face}. + +When @var{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-@code{nil} if it succeeds, and set the +match data to describe the match that was found. Returning @code{nil} +indicates failure of the search. + +Fontification will call @var{function} repeatedly with the same limit, +and with point where the previous invocation left it, until +@var{function} fails. On failure, @var{function} need not reset point +in any particular way. + +@item (@var{matcher} . @var{subexp}) +In this kind of element, @var{matcher} is either a regular +expression or a function, as described above. The @sc{cdr}, +@var{subexp}, specifies which subexpression of @var{matcher} should be +highlighted (instead of the entire text that @var{matcher} matched). + +@example +;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},} +;; @r{using @code{font-lock-keyword-face}.} +("fu\\(bar\\)" . 1) +@end example + +If you use @code{regexp-opt} to produce the regular expression +@var{matcher}, you can use @code{regexp-opt-depth} (@pxref{Regexp +Functions}) to calculate the value for @var{subexp}. + +@item (@var{matcher} . @var{facespec}) +In this kind of element, @var{facespec} is an expression whose value +specifies the face to use for highlighting. In the simplest case, +@var{facespec} is a Lisp variable (a symbol) whose value is a face +name. + +@example +;; @r{Highlight occurrences of @samp{fubar},} +;; @r{using the face which is the value of @code{fubar-face}.} +("fubar" . fubar-face) +@end example + +However, @var{facespec} can also evaluate to a list of this form: + +@example +(face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{}) +@end example + +@noindent +to specify the face @var{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 +@code{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 @code{font-lock-unfontify-region-function} to +a function that clears these properties. @xref{Other Font Lock +Variables}. + +@item (@var{matcher} . @var{subexp-highlighter}) +In this kind of element, @var{subexp-highlighter} is a list +which specifies how to highlight matches found by @var{matcher}. +It has the form: + +@example +(@var{subexp} @var{facespec} [[@var{override} [@var{laxmatch}]]) +@end example + +The @sc{car}, @var{subexp}, is an integer specifying which subexpression +of the match to fontify (0 means the entire matching text). The second +subelement, @var{facespec}, is an expression whose value specifies the +face, as described above. + +The last two values in @var{subexp-highlighter}, @var{override} and +@var{laxmatch}, are optional flags. If @var{override} is @code{t}, +this element can override existing fontification made by previous +elements of @code{font-lock-keywords}. If it is @code{keep}, then +each character is fontified if it has not been fontified already by +some other element. If it is @code{prepend}, the face specified by +@var{facespec} is added to the beginning of the @code{font-lock-face} +property. If it is @code{append}, the face is added to the end of the +@code{font-lock-face} property. + +If @var{laxmatch} is non-@code{nil}, it means there should be no error +if there is no subexpression numbered @var{subexp} in @var{matcher}. +Obviously, fontification of the subexpression numbered @var{subexp} will +not occur. However, fontification of other subexpressions (and other +regexps) will continue. If @var{laxmatch} is @code{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: + +@smallexample +;; @r{Highlight occurrences of either @samp{foo} or @samp{bar}, using} +;; @r{@code{foo-bar-face}, even if they have already been highlighted.} +;; @r{@code{foo-bar-face} should be a variable whose value is a face.} +("foo\\|bar" 0 foo-bar-face t) + +;; @r{Highlight the first subexpression within each occurrence} +;; @r{that the function @code{fubar-match} finds,} +;; @r{using the face which is the value of @code{fubar-face}.} +(fubar-match 1 fubar-face) +@end smallexample + +@item (@var{matcher} . @var{anchored-highlighter}) +In this kind of element, @var{anchored-highlighter} specifies how to +highlight text that follows a match found by @var{matcher}. So a +match found by @var{matcher} acts as the anchor for further searches +specified by @var{anchored-highlighter}. @var{anchored-highlighter} +is a list of the following form: + +@example +(@var{anchored-matcher} @var{pre-form} @var{post-form} + @var{subexp-highlighters}@dots{}) +@end example + +Here, @var{anchored-matcher}, like @var{matcher}, is either a regular +expression or a function. After a match of @var{matcher} is found, +point is at the end of the match. Now, Font Lock evaluates the form +@var{pre-form}. Then it searches for matches of +@var{anchored-matcher} and uses @var{subexp-highlighters} to highlight +these. A @var{subexp-highlighter} is as described above. Finally, +Font Lock evaluates @var{post-form}. + +The forms @var{pre-form} and @var{post-form} can be used to initialize +before, and cleanup after, @var{anchored-matcher} is used. Typically, +@var{pre-form} is used to move point to some position relative to the +match of @var{matcher}, before starting with @var{anchored-matcher}. +@var{post-form} might be used to move back, before resuming with +@var{matcher}. + +After Font Lock evaluates @var{pre-form}, it does not search for +@var{anchored-matcher} beyond the end of the line. However, if +@var{pre-form} returns a buffer position that is greater than the +position of point after @var{pre-form} is evaluated, then the position +returned by @var{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 @var{anchored-matcher} search should +not span lines. + +For example, + +@smallexample +;; @r{Highlight occurrences of the word @samp{item} following} +;; @r{an occurrence of the word @samp{anchor} (on the same line)} +;; @r{in the value of @code{item-face}.} +("\\<anchor\\>" "\\<item\\>" nil nil (0 item-face)) +@end smallexample + +Here, @var{pre-form} and @var{post-form} are @code{nil}. Therefore +searching for @samp{item} starts at the end of the match of +@samp{anchor}, and searching for subsequent instances of @samp{anchor} +resumes from where searching for @samp{item} concluded. + +@item (@var{matcher} @var{highlighters}@dots{}) +This sort of element specifies several @var{highlighter} lists for a +single @var{matcher}. A @var{highlighter} list can be of the type +@var{subexp-highlighter} or @var{anchored-highlighter} as described +above. + +For example, + +@smallexample +;; @r{Highlight occurrences of the word @samp{anchor} in the value} +;; @r{of @code{anchor-face}, and subsequent occurrences of the word} +;; @r{@samp{item} (on the same line) in the value of @code{item-face}.} +("\\<anchor\\>" (0 anchor-face) + ("\\<item\\>" nil nil (0 item-face))) +@end smallexample + +@item (eval . @var{form}) +Here @var{form} is an expression to be evaluated the first time +this value of @code{font-lock-keywords} is used in a buffer. +Its value should have one of the forms described in this table. +@end table + +@strong{Warning:} Do not design an element of @code{font-lock-keywords} +to match text which spans lines; this does not work reliably. +For details, see @xref{Multiline Font Lock}. + +You can use @var{case-fold} in @code{font-lock-defaults} to specify +the value of @code{font-lock-keywords-case-fold-search} which says +whether search-based fontification should be case-insensitive. + +@defvar font-lock-keywords-case-fold-search +Non-@code{nil} means that regular expression matching for the sake of +@code{font-lock-keywords} should be case-insensitive. +@end defvar + +@node Customizing Keywords +@subsection Customizing Search-Based Fontification + + You can use @code{font-lock-add-keywords} to add additional +search-based fontification rules to a major mode, and +@code{font-lock-remove-keywords} to removes rules. + +@defun font-lock-add-keywords mode keywords &optional how +This function adds highlighting @var{keywords}, for the current buffer +or for major mode @var{mode}. The argument @var{keywords} should be a +list with the same format as the variable @code{font-lock-keywords}. + +If @var{mode} is a symbol which is a major mode command name, such as +@code{c-mode}, the effect is that enabling Font Lock mode in +@var{mode} will add @var{keywords} to @code{font-lock-keywords}. +Calling with a non-@code{nil} value of @var{mode} is correct only in +your @file{~/.emacs} file. + +If @var{mode} is @code{nil}, this function adds @var{keywords} to +@code{font-lock-keywords} in the current buffer. This way of calling +@code{font-lock-add-keywords} is usually used in mode hook functions. + +By default, @var{keywords} are added at the beginning of +@code{font-lock-keywords}. If the optional argument @var{how} is +@code{set}, they are used to replace the value of +@code{font-lock-keywords}. If @var{how} is any other non-@code{nil} +value, they are added at the end of @code{font-lock-keywords}. + +Some modes provide specialized support you can use in additional +highlighting patterns. See the variables +@code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types}, +and @code{java-font-lock-extra-types}, for example. + +@strong{Warning:} major mode functions must not call +@code{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 +@code{font-lock-keywords}. +@end defun + +@defun font-lock-remove-keywords mode keywords +This function removes @var{keywords} from @code{font-lock-keywords} +for the current buffer or for major mode @var{mode}. As in +@code{font-lock-add-keywords}, @var{mode} should be a major mode +command name or @code{nil}. All the caveats and requirements for +@code{font-lock-add-keywords} apply here too. +@end defun + + For example, this code + +@smallexample +(font-lock-add-keywords 'c-mode + '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend) + ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face))) +@end smallexample + +@noindent +adds two fontification patterns for C mode: one to fontify the word +@samp{FIXME}, even in comments, and another to fontify the words +@samp{and}, @samp{or} and @samp{not} as keywords. + +@noindent +That example affects only C mode proper. To add the same patterns to +C mode @emph{and} all modes derived from it, do this instead: + +@smallexample +(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))))) +@end smallexample + +@node Other Font Lock Variables +@subsection Other Font Lock Variables + + This section describes additional variables that a major mode can +set by means of @var{other-vars} in @code{font-lock-defaults} +(@pxref{Font Lock Basics}). + +@defvar font-lock-mark-block-function +If this variable is non-@code{nil}, it should be a function that is +called with no arguments, to choose an enclosing range of text for +refontification for the command @kbd{M-o M-o} +(@code{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 @code{mark-defun} for programming modes or @code{mark-paragraph} for +textual modes. +@end defvar + +@defvar font-lock-extra-managed-props +This variable specifies additional properties (other than +@code{font-lock-face}) that are being managed by Font Lock mode. It +is used by @code{font-lock-default-unfontify-region}, which normally +only manages the @code{font-lock-face} property. If you want Font +Lock to manage other properties as well, you must specify them in a +@var{facespec} in @code{font-lock-keywords} as well as add them to +this list. @xref{Search-based Fontification}. +@end defvar + +@defvar font-lock-fontify-buffer-function +Function to use for fontifying the buffer. The default value is +@code{font-lock-default-fontify-buffer}. +@end defvar + +@defvar 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 +@code{font-lock-default-unfontify-buffer}. +@end defvar + +@defvar 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 @var{verbose}. If @var{verbose} is non-@code{nil}, the +function should print status messages. The default value is +@code{font-lock-default-fontify-region}. +@end defvar + +@defvar 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 +@code{font-lock-default-unfontify-region}. +@end defvar + +@ignore +@defvar font-lock-inhibit-thing-lock +List of Font Lock mode related modes that should not be turned on. +Currently, valid mode names are @code{fast-lock-mode}, +@code{jit-lock-mode} and @code{lazy-lock-mode}. +@end defvar +@end ignore + +@node Levels of Font Lock +@subsection 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 @var{keywords} +in @code{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 +@code{font-lock-keywords}. + + Here are the conventions for how to define the levels of +fontification: + +@itemize @bullet +@item +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. + +@item +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. + +@item +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. +@end itemize + +@node Precalculated Fontification +@subsection Precalculated Fontification + + In addition to using @code{font-lock-defaults} for search-based +fontification, you may use the special character property +@code{font-lock-face} (@pxref{Special Properties}). This property +acts just like the explicit @code{face} property, but its activation +is toggled when the user calls @kbd{M-x font-lock-mode}. Using +@code{font-lock-face} is especially convenient for special modes +which construct their text programmatically, such as +@code{list-buffers} and @code{occur}. + +If your mode does not use any of the other machinery of Font Lock +(i.e. it only uses the @code{font-lock-face} property), it should not +set the variable @code{font-lock-defaults}. + +@node Faces for Font Lock +@subsection Faces for Font Lock +@cindex faces for font lock +@cindex font lock faces + + 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 @code{font-lock-comment-face} is +@code{font-lock-comment-face}. This means you can write +@code{font-lock-comment-face} in a context such as +@code{font-lock-keywords} where a face-name-valued expression is used. + +@table @code +@item font-lock-comment-face +@vindex font-lock-comment-face +Used (typically) for comments. + +@item font-lock-comment-delimiter-face +@vindex font-lock-comment-delimiter-face +Used (typically) for comments delimiters. + +@item font-lock-doc-face +@vindex font-lock-doc-face +Used (typically) for documentation strings in the code. + +@item font-lock-string-face +@vindex font-lock-string-face +Used (typically) for string constants. + +@item font-lock-keyword-face +@vindex font-lock-keyword-face +Used (typically) for keywords---names that have special syntactic +significance, like @code{for} and @code{if} in C. + +@item font-lock-builtin-face +@vindex font-lock-builtin-face +Used (typically) for built-in function names. + +@item font-lock-function-name-face +@vindex font-lock-function-name-face +Used (typically) for the name of a function being defined or declared, +in a function definition or declaration. + +@item font-lock-variable-name-face +@vindex font-lock-variable-name-face +Used (typically) for the name of a variable being defined or declared, +in a variable definition or declaration. + +@item font-lock-type-face +@vindex font-lock-type-face +Used (typically) for names of user-defined data types, +where they are defined and where they are used. + +@item font-lock-constant-face +@vindex font-lock-constant-face +Used (typically) for constant names. + +@item font-lock-preprocessor-face +@vindex font-lock-preprocessor-face +Used (typically) for preprocessor commands. + +@item font-lock-negation-char-face +@vindex font-lock-negation-char-face +Used (typically) for easily-overlooked negation characters. + +@item font-lock-warning-face +@vindex 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 +@samp{;;;###autoload} cookies in Emacs Lisp, and for @code{#error} +directives in C. +@end table + +@node Syntactic Font Lock +@subsection Syntactic Font Lock +@cindex syntactic font lock + +Syntactic fontification uses the syntax table to find comments and +string constants (@pxref{Syntax Tables}). It highlights them using +@code{font-lock-comment-face} and @code{font-lock-string-face} +(@pxref{Faces for Font Lock}), or whatever +@code{font-lock-syntactic-face-function} chooses. There are several +variables that affect syntactic fontification; you should set them by +means of @code{font-lock-defaults} (@pxref{Font Lock Basics}). + +@defvar font-lock-keywords-only +Non-@code{nil} means Font Lock should not do syntactic fontification; +it should only fontify based on @code{font-lock-keywords}. The normal +way for a mode to set this variable to @code{t} is with +@var{keywords-only} in @code{font-lock-defaults}. +@end defvar + +@defvar font-lock-syntax-table +This variable holds the syntax table to use for fontification of +comments and strings. Specify it using @var{syntax-alist} in +@code{font-lock-defaults}. If this is @code{nil}, fontification uses +the buffer's syntax table. +@end defvar + +@defvar font-lock-beginning-of-syntax-function +If this variable is non-@code{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 +@code{beginning-of-line} (used when the start of the line is known to +be outside a syntactic block), or @code{beginning-of-defun} for +programming modes, or @code{backward-paragraph} for textual modes. + +If the value is @code{nil}, Font Lock uses +@code{syntax-begin-function} to move back outside of any comment, +string, or sexp. This variable is semi-obsolete; we recommend setting +@code{syntax-begin-function} instead. + +Specify this variable using @var{syntax-begin} in +@code{font-lock-defaults}. +@end defvar + +@defvar 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 +@code{parse-partial-sexp}, and should return a face. The default +value returns @code{font-lock-comment-face} for comments and +@code{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 +@code{font-lock-syntactic-keywords} to highlight constructs that span +multiple lines, but this is too esoteric to document here. + +Specify this variable using @var{other-vars} in +@code{font-lock-defaults}. +@end defvar + +@node Setting Syntax Properties +@subsection Setting Syntax Properties + + Font Lock mode can be used to update @code{syntax-table} properties +automatically (@pxref{Syntax Properties}). This is useful in +languages for which a single syntax table by itself is not sufficient. + +@defvar font-lock-syntactic-keywords +This variable enables and controls updating @code{syntax-table} +properties by Font Lock. Its value should be a list of elements of +this form: + +@example +(@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch}) +@end example + +The parts of this element have the same meanings as in the corresponding +sort of element of @code{font-lock-keywords}, + +@example +(@var{matcher} @var{subexp} @var{facespec} @var{override} @var{laxmatch}) +@end example + +However, instead of specifying the value @var{facespec} to use for the +@code{face} property, it specifies the value @var{syntax} to use for +the @code{syntax-table} property. Here, @var{syntax} can be a string +(as taken by @code{modify-syntax-entry}), a syntax table, a cons cell +(as returned by @code{string-to-syntax}), or an expression whose value +is one of those two types. @var{override} cannot be @code{prepend} or +@code{append}. + +For example, an element of the form: + +@example +("\\$\\(#\\)" 1 ".") +@end example + +highlights syntactically a hash character when following a dollar +character, with a SYNTAX of @code{"."} (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: + +@example + ("\\('\\).\\('\\)" + (1 "\"") + (2 "\"")) +@end example + +highlights syntactically both single quotes which surround a single +character, with a SYNTAX of @code{"\""} (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 @samp{'@var{c}'} as strings syntactically. Other forms, such +as @samp{foo'bar} or @samp{'fubar'}, will not be highlighted as +strings. + +Major modes normally set this variable with @var{other-vars} in +@code{font-lock-defaults}. +@end defvar + +@node Multiline Font Lock +@subsection Multiline Font Lock Constructs +@cindex multiline font lock + + Normally, elements of @code{font-lock-keywords} should not match +across multiple lines; that doesn't work reliably, because Font Lock +usually scans just part of the buffer, and it can miss a multi-line +construct that crosses the line boundary where the scan starts. (The +scan normally starts at the beginning of a line.) + + Making elements that match multiline constructs work properly has +two aspects: correct @emph{identification} and correct +@emph{rehighlighting}. The first means that Font Lock finds all +multiline constructs. The second means that Font Lock will correctly +rehighlight all the relevant text when a multiline construct is +changed---for example, if some of the text that was previously part of +a multiline construct ceases to be part of it. The two aspects are +closely related, and often getting one of them to work will appear to +make the other also work. However, for reliable results you must +attend explicitly to both aspects. + + There are three ways to ensure correct identification of multiline +constructs: + +@itemize +@item +Add a function to @code{font-lock-extend-region-functions} that does +the @emph{identification} and extends the scan so that the scanned +text never starts or ends in the middle of a multiline construct. +@item +Use the @code{font-lock-fontify-region-function} hook similarly to +extend the scan so that the scanned text never starts or ends in the +middle of a multiline construct. +@item +Somehow identify the multiline construct right when it gets inserted +into the buffer (or at any point after that but before font-lock +tries to highlight it), and mark it with a @code{font-lock-multiline} +which will instruct font-lock not to start or end the scan in the +middle of the construct. +@end itemize + + There are three ways to do rehighlighting of multiline constructs: + +@itemize +@item +Place a @code{font-lock-multiline} property on the construct. This +will rehighlight the whole construct if any part of it is changed. In +some cases you can do this automatically by setting the +@code{font-lock-multiline} variable, which see. +@item +Make sure @code{jit-lock-contextually} is set and rely on it doing its +job. This will only rehighlight the part of the construct that +follows the actual change, and will do it after a short delay. +This only works if the highlighting of the various parts of your +multiline construct never depends on text in subsequent lines. +Since @code{jit-lock-contextually} is activated by default, this can +be an attractive solution. +@item +Place a @code{jit-lock-defer-multiline} property on the construct. +This works only if @code{jit-lock-contextually} is used, and with the +same delay before rehighlighting, but like @code{font-lock-multiline}, +it also handles the case where highlighting depends on +subsequent lines. +@end itemize + +@menu +* Font Lock Multiline:: Marking multiline chunks with a text property +* Region to Fontify:: Controlling which region gets refontified + after a buffer change. +@end menu + +@node Font Lock Multiline +@subsubsection Font Lock Multiline + + One way to ensure reliable rehighlighting of multiline Font Lock +constructs is to put on them the text property @code{font-lock-multiline}. +It should be present and non-@code{nil} for text that is part of a +multiline construct. + + When Font Lock is about to highlight a range of text, it first +extends the boundaries of the range as necessary so that they do not +fall within text marked with the @code{font-lock-multiline} property. +Then it removes any @code{font-lock-multiline} properties from the +range, and highlights it. The highlighting specification (mostly +@code{font-lock-keywords}) must reinstall this property each time, +whenever it is appropriate. + + @strong{Warning:} don't use the @code{font-lock-multiline} property +on large ranges of text, because that will make rehighlighting slow. + +@defvar font-lock-multiline +If the @code{font-lock-multiline} variable is set to @code{t}, Font +Lock will try to add the @code{font-lock-multiline} property +automatically on multiline constructs. This is not a universal +solution, however, since it slows down Font Lock somewhat. It can +miss some multiline constructs, or make the property larger or smaller +than necessary. + +For elements whose @var{matcher} is a function, the function should +ensure that submatch 0 covers the whole relevant multiline construct, +even if only a small subpart will be highlighted. It is often just as +easy to add the @code{font-lock-multiline} property by hand. +@end defvar + + The @code{font-lock-multiline} property is meant to ensure proper +refontification; it does not automatically identify new multiline +constructs. Identifying the requires that Font-Lock operate on large +enough chunks at a time. This will happen by accident on many cases, +which may give the impression that multiline constructs magically work. +If you set the @code{font-lock-multiline} variable non-@code{nil}, +this impression will be even stronger, since the highlighting of those +constructs which are found will be properly updated from then on. +But that does not work reliably. + + To find multiline constructs reliably, you must either manually +place the @code{font-lock-multiline} property on the text before +Font-Lock looks at it, or use +@code{font-lock-fontify-region-function}. + +@node Region to Fontify +@subsubsection 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 change alters the syntactic meaning of text on an +earlier line. + + You can enlarge (or even reduce) the region to fontify by setting +one the following variables: + +@defvar font-lock-extend-after-change-region-function +This buffer-local variable is either @code{nil} or a function for +Font-Lock to call to determine the region to scan and fontify. + +The function is given three parameters, the standard @var{beg}, +@var{end}, and @var{old-len} from after-change-functions +(@pxref{Change Hooks}). It should return either a cons of the +beginning and end buffer positions (in that order) of the region to +fontify, or @code{nil} (which means choose the region in the standard +way). 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. +@end defvar + +@node Desktop Save Mode +@section Desktop Save Mode +@cindex desktop save mode + +@dfn{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 (@pxref{Saving Emacs +Sessions,,, emacs, 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 @code{desktop-save-buffer} to +a non-@code{nil} value. + +@defvar desktop-save-buffer +If this buffer-local variable is non-@code{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 +@var{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 + +@example +(desktop-file-name @var{file-name} @var{desktop-dirname}) +@end example + +@end defvar + +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 @code{desktop-buffer-mode-handlers}. + +@defvar desktop-buffer-mode-handlers +Alist with elements + +@example +(@var{major-mode} . @var{restore-buffer-function}) +@end example + +The function @var{restore-buffer-function} will be called with +argument list + +@example +(@var{buffer-file-name} @var{buffer-name} @var{desktop-buffer-misc}) +@end example + +and it should return the restored buffer. +Here @var{desktop-buffer-misc} is the value returned by the function +optionally bound to @code{desktop-save-buffer}. +@end defvar + +@ignore + arch-tag: 4c7bff41-36e6-4da6-9e7f-9b9289e27c8e +@end ignore