@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/modes
@node Modes, Documentation, Keymaps, Top
@cindex Fundamental mode
Major modes specialize Emacs for editing particular kinds of text.
-Each buffer has only one major mode at a time.
+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.
The least specialized major mode is called @dfn{Fundamental mode}.
This mode has no mode-specific definitions or variable settings, so each
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.
+
+@findex define-generic-mode
+ For a very simple programming language major mode that handles
+comments and fontification, you can use @code{define-generic-mode}
+in @file{generic.el}.
+
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
* Example Major Modes:: Text mode and Lisp modes.
* 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
+* Derived Modes:: Defining a new major mode based on another major
mode.
@end menu
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:
+define a new major mode.
+
+ This list of conventions is only partial, because each major mode
+should aim for consistency in general with other Emacs major modes.
+This makes Emacs as a whole more coherent. It is impossible to list
+here all the possible points where this issue might come up; if the
+Emacs developers point out an area where your major mode deviates from
+the usual conventions, please make it compatible.
@itemize @bullet
@item
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
text can reasonably redefine letters and other printing characters as
editing commands. Dired and Rmail both do this.
+@item
+Major modes must not define @key{RET} to do anything other than insert
+a newline. The command to insert a newline and then indent is
+@kbd{C-j}. Please keep this distinction uniform for all major modes.
+
+@item
+Major modes should not alter options that are primary 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
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 use
+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.
@smallexample
@group
;; @r{Create mode-specific tables.}
-(defvar text-mode-syntax-table nil
+(defvar text-mode-syntax-table nil
"Syntax table used while in text mode.")
@end group
@smallexample
@group
;; @r{Create mode-specific table variables.}
-(defvar lisp-mode-syntax-table nil "")
+(defvar lisp-mode-syntax-table nil "")
(defvar emacs-lisp-mode-syntax-table nil "")
(defvar lisp-mode-abbrev-table nil "")
@end group
;; @r{Set syntax of chars up to 0 to class of chars that are}
;; @r{part of symbol names but not words.}
;; @r{(The number 0 is @code{48} in the @sc{ascii} character set.)}
- (while (< i ?0)
+ (while (< i ?0)
(modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table)
(setq i (1+ i)))
@dots{}
@end smallexample
Finally, here is the complete major mode function definition for
-Lisp mode.
+Lisp mode.
@smallexample
@group
mode specification error}, followed by the original error message.
@end deffn
-@defopt enable-local-variables
-This variable controls processing of local variables lists in files
-being visited. A value of @code{t} means process the local variables
-lists unconditionally; @code{nil} means ignore them; anything else means
-ask the user what to do for each file. The default value is @code{t}.
-@end defopt
-
-@defvar ignored-local-variables
-This variable holds a list of variables that should not be
-set by a file's local variables list. Any value specified
-for one of these variables is ignored.
-@end defvar
-
-In addition to this list, any variable whose name has a non-@code{nil}
-@code{risky-local-variable} property is also ignored.
-
-@defopt enable-local-eval
-This variable controls processing of @samp{Eval:} in local variables
-lists in files being visited. A value of @code{t} means process them
-unconditionally; @code{nil} means ignore them; anything else means ask
-the user what to do for each file. The default value is @code{maybe}.
-@end defopt
-
@defun set-auto-mode
@cindex visited file mode
This function selects the major mode that is appropriate for the
How Major Modes are Chosen, emacs, The GNU Emacs Manual}.
@end defun
-@defopt default-major-mode
+@defopt default-major-mode
This variable holds the default major mode for new buffers. The
standard value is @code{fundamental-mode}.
@end group
@group
("\\.el\\'" . emacs-lisp-mode)
- ("\\.c\\'" . c-mode)
+ ("\\.c\\'" . c-mode)
("\\.h\\'" . c-mode)
@dots{})
@end group
@smallexample
@group
(setq auto-mode-alist
- (append
+ (append
;; @r{File name (within directory) starts with a dot.}
- '(("/\\.[^/]*\\'" . fundamental-mode)
+ '(("/\\.[^/]*\\'" . fundamental-mode)
;; @r{File name has no dot.}
- ("[^\\./]*\\'" . fundamental-mode)
+ ("[^\\./]*\\'" . fundamental-mode)
;; @r{File name ends in @samp{.C}.}
("\\.C\\'" . c++-mode))
auto-mode-alist))
not indicate which major mode to use.
@end defvar
-@defun hack-local-variables &optional force
-This function parses, and binds or evaluates as appropriate, any local
-variables specified by the contents of the current buffer.
-
-The handling of @code{enable-local-variables} documented for
-@code{normal-mode} actually takes place here. The argument @var{force}
-usually comes from the argument @var{find-file} given to
-@code{normal-mode}.
-@end defun
-
@node Mode Help
@subsection Getting Help about a Major Mode
@cindex mode help
The new command @var{variant} is defined to call the function
@var{parent}, then override certain aspects of that parent mode:
-@itemize @bullet
+@itemize @bullet
@item
The new mode has its own keymap, named @code{@var{variant}-map}.
@code{define-derived-mode} initializes this map to inherit from
@item
The new mode has its own syntax table, kept in the variable
@code{@var{variant}-syntax-table}.
-@code{define-derived-mode} initializes this variable by copying
+@code{define-derived-mode} initializes this variable by copying
@code{@var{parent}-syntax-table}, if it is not already set.
@item
The new mode has its own abbrev table, kept in the variable
@code{@var{variant}-abbrev-table}.
-@code{define-derived-mode} initializes this variable by copying
+@code{define-derived-mode} initializes this variable by copying
@code{@var{parent}-abbrev-table}, if it is not already set.
@item
The new mode has its own mode hook, @code{@var{variant}-hook},
which it runs in standard fashion as the very last thing that it does.
-(The new mode also runs the mode hook of @var{parent} as part
+(The new mode also runs the mode hook of @var{parent} as part
of calling @var{parent}.)
@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
+evaluates the forms in @var{body} after setting up all its usual
overrides, just before running @code{@var{variant}-hook}.
The argument @var{docstring} specifies the documentation string for the
(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 Minor Modes
@menu
* Minor Mode Conventions:: Tips for writing a minor mode.
* Keymaps and Minor Modes:: How a minor mode can have its own keymap.
-* Easy-Mmode:: A convenient facility for defining minor modes.
+* Defining Minor Modes:: A convenient facility for defining minor modes.
@end menu
@node Minor Mode Conventions
@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:}, and @kbd{;}. (Those few punctuation
characters are reserved for major modes.)
-@node Easy-Mmode
-@subsection Easy-Mmode
+@node Defining Minor Modes
+@subsection Defining Minor Modes
- The easy-mmode package provides a convenient way of implementing a
-mode in one self-contained definition. It currently supports only
+ The macro @code{define-minor-mode} offers a convenient way of
+implementing a mode in one self-contained definition. It supports only
buffer-local minor modes, not global ones.
-@defmac easy-mmode-define-minor-mode mode doc &optional init-value mode-indicator keymap
-@tindex easy-mmode-define-minor-mode
+@defmac define-minor-mode mode doc &optional init-value mode-indicator keymap body...
+@tindex define-minor-mode
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}.
-This macro defines a command named @var{mode} which toggles the minor
-mode, and has @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}.
+The command named @var{mode} finishes by executing the @var{body} forms,
+if any, after it has performed the standard actions such as setting
+the variable named @var{mode}.
The string @var{mode-indicator} says what to display in the mode line
when the mode is enabled; if it is @code{nil}, the mode is not displayed
@end example
@end defmac
- Here is an example of using @code{easy-mmode-define-minor-mode}:
+ Here is an example of using @code{define-minor-mode}:
@smallexample
-(easy-mmode-define-minor-mode hungry-mode
+(define-minor-mode hungry-mode
"Toggle Hungry mode.
-With no argument, this command toggles the mode.
+With no argument, this command toggles the mode.
Non-null prefix argument turns on the mode.
Null prefix argument turns off the mode.
;; The minor mode bindings.
'(("\C-\^?" . hungry-electric-delete)
("\C-\M-\^?"
- . (lambda ()
+ . (lambda ()
(interactive)
(hungry-electric-delete t)))))
@end smallexample
mode is enabled. It initializes the keymap with key bindings for
@kbd{C-@key{DEL}} and @kbd{C-M-@key{DEL}}.
+
+@findex easy-mmode-define-minor-mode
+ The name @code{easy-mmode-define-minor-mode} is an alias
+for this macro.
+
@node Mode Line Format
@section Mode Line Format
@cindex mode line
window is scrolled. @code{header-line-format} is used likewise for
header lines.
- The mode line and header line of a window are normally updated
-whenever a different buffer is shown in the window, or when the buffer's
-modified-status changes from @code{nil} to @code{t} or vice-versa. 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.
+ For efficiency, Emacs does not recompute the mode line and header
+line of a window in every redisplay. It does so when circumstances
+appear to call for it---for instance, if you change the window
+configuration, switch buffers, narrow or widen the buffer, scroll, or
+change the buffer's modification status. If you modify any of the
+variables referenced by @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.
@c Emacs 19 feature
@defun force-mode-line-update
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.
+
+This function also forces recomputation of the menu bar menus
+and the frame title.
@end defun
The mode line is usually displayed in inverse video; see
@code{mode-line-inverse-video} in @ref{Inverse Video}.
+ A window that is just one line tall does not display either a mode
+line or a header line, even if the variables call for one. A window
+that is two lines tall cannot display both a mode line and a header
+line at once; if the variables call for both, only the mode line
+actually appears.
+
@menu
* Mode Line Data:: The data structure that controls the mode line.
* Mode Line Variables:: Variables used in that data structure.
'mode-line-mule-info
'mode-line-modified
'mode-line-frame-identification
- "%b--"
+ "%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"
+ 'mode-line-process
+ 'minor-mode-alist
+ "%n"
")%]--"
@group
'(which-func-mode ("" which-func-format "--"))
@code{mode-line-format} were changed to use them.
@defvar mode-line-mule-info
-@tindex 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-frame-identification
-@tindex 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
@group
minor-mode-alist
@result{} ((vc-mode vc-mode)
- (abbrev-mode " Abbrev")
- (overwrite-mode overwrite-mode)
- (auto-fill-function " Fill")
+ (abbrev-mode " Abbrev")
+ (overwrite-mode overwrite-mode)
+ (auto-fill-function " Fill")
(defining-kbd-macro " Def")
(isearch-mode isearch-mode))
@end group
@group
" %[("
;; @r{@code{mode-line-mode-name} is a function}
- ;; @r{that copies the mode name and adds text
+ ;; @r{that copies the mode name and adds text}
;; @r{properties to make it mouse-sensitive.}
(:eval (mode-line-mode-name))
mode-line-process
- minor-mode-alist
- "%n"
+ minor-mode-alist
+ "%n"
")%]--"
@end group
@group
@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} (@xref{Mode Line Data}).
+is the same as for @code{mode-line-format} (@pxref{Mode Line Data}).
@end defvar
@tindex default-header-line-format
@code{imenu-extract-index-name-function}:
@defvar imenu-prev-index-position-function
-If this variable is non-@code{nil}, its value should be a funtion that
+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 shuould
+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.
* Search-based Fontification::
* Other Font Lock Variables::
* Levels of Font Lock::
+* Precalculated Fontification::
* Faces for Font Lock::
* Syntactic Font Lock::
@end menu
it finds using @code{font-lock-keyword-face}.
When @var{function} is called, it receives one argument, the limit of
-the search. It should return non-@code{nil} if it succeeds, and set the
-match data to describe the match that was found.
+the search; it should 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{match})
In this kind of element, @var{matcher} is either a regular
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 signalled which
+terminates search-based fontification.
Here are some examples of elements of this kind, and what they do:
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 conveninent 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), you can tell
+Emacs not to load all of font-lock.el (unless it's already loaded), by
+setting the variable @code{font-lock-core-only} to non-nil as part of
+the @code{font-lock-defaults} settings. Here is the canonical way to
+do this:
+
+@example
+(set (make-local-variable 'font-lock-defaults)
+ '(nil t nil nil nil (font-lock-core-only . t)))
+@end example
+
@node Faces for Font Lock
@subsection Faces for Font Lock
@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.
+in a function definition or declaration.
@item font-lock-variable-name-face
@vindex font-lock-variable-name-face
these functions are called with arguments or their values are used in
some way. You can use @code{add-hook} to add a function to the list,
but you must take care in writing the function. (A few of these
-variables are actually normal hooks which were named before we
-established the convention of using @samp{-hook} for them.)
+variables, notably those ending in @samp{-hooks}, are actually
+normal hooks which were named before we established the convention of
+using @samp{-hook} for them.)
If the variable's name ends in @samp{-function}, then its value
is just a single function, not a list of functions.
argument @var{append} is non-@code{nil}, the new hook function goes at
the end of the hook list and will be executed last.
-If @var{local} is non-@code{nil}, that says to make the new hook
-function buffer-local in the current buffer. Before you can do this, you must
-make the hook itself buffer-local by calling @code{make-local-hook}
-(@strong{not} @code{make-local-variable}). If the hook itself is not
-buffer-local, then the value of @var{local} makes no difference---the
-hook function is always global.
+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.
@end defun
@defun remove-hook hook function &optional local
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.
-If the hook variable itself is not buffer-local, then the value of
-@var{local} makes no difference.
-@end defun
-
-@defun make-local-hook hook
-This function makes the hook variable @code{hook} buffer-local in the
-current buffer. When a hook variable is buffer-local, it can have
-buffer-local and global hook functions, and @code{run-hooks} runs all of
-them.
-
-This function works by adding @code{t} as an element of the buffer-local
-value. That serves as a flag to use the hook functions listed in the default
-value of the hook variable, as well as those listed in the buffer-local value.
-Since @code{run-hooks} understands this flag, @code{make-local-hook}
-works with all normal hooks. It works for only some non-normal
-hooks---those whose callers have been updated to understand this meaning
-of @code{t}.
-
-Do not use @code{make-local-variable} directly for hook variables; it is
-not sufficient.
@end defun