@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 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/modes
@node Modes, Documentation, Keymaps, Top
@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:
+@menu
+* Running Hooks:: How to run a hook.
+* Setting Hooks:: How to put functions on a hook, or remove them.
+@end menu
-@example
-(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
-@end example
+@node Running Hooks
+@subsection Running Hooks
- At the appropriate time, Emacs uses the @code{run-hooks} function to
-run particular hooks.
+ At the appropriate times, Emacs uses the @code{run-hooks} function
+and the other functions below to run particular hooks.
@defun run-hooks &rest hookvars
This function takes one or more normal hook variable names as
@code{nil}, it returns @code{nil} as well.
@end defun
+@node Setting Hooks
+@subsection Setting Hooks
+
+ 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
+
@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
If @var{function} is already present in @var{hook} (comparing using
@code{equal}), then @code{add-hook} does not add it a second time.
+If @var{function} has a non-@code{nil} property
+@code{permanent-local-hook}, then @code{kill-all-local-variables} (or
+changing major modes) won't delete it from the hook variable's local
+value.
+
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,
@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.
+``pretty'' name of the mode, usually a string (but see @ref{Mode Line
+Data}, for other possible forms). The name of the mode appears
+in the mode line.
@item
@cindex functions in modes
letters and other printing characters as special commands.
@item
-Major modes modes for editing text should not define @key{RET} to do
+Major 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
;; @r{File name (within directory) starts with a dot.}
'(("/\\.[^/]*\\'" . 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))
@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.
+buffer's major mode. Each major mode should set this variable so that
+the mode name will appear in the mode line. The value does not have
+to be a string, but can use any of the data types valid in a mode-line
+construct (@pxref{Mode Line Data}). To compute the string that will
+identify the mode name in the mode line, use @code{format-mode-line}
+(@pxref{Emulating Mode Line}).
@end defvar
@defvar mode-line-process
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 first symbol specifies the @samp{mode default} level of
+fontification, the next symbol level 1 fontification, the next level 2,
+and so on. The @samp{mode default} level is normally the same as level
+1. It is used when @code{font-lock-maximum-decoration} has a @code{nil}
+value. @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
It has the form:
@example
-(@var{subexp} @var{facespec} [[@var{override} [@var{laxmatch}]])
+(@var{subexp} @var{facespec} [@var{override} [@var{laxmatch}]])
@end example
The @sc{car}, @var{subexp}, is an integer specifying which subexpression
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.
+@code{font-lock-remove-keywords} to remove rules.
@defun font-lock-add-keywords mode keywords &optional how
This function adds highlighting @var{keywords}, for the current buffer
@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
+@defun jit-lock-register function &optional contextual
+This function tells Font Lock mode to run the Lisp function
+@var{function} any time it has to fontify or refontify part of the
+current buffer. It calls @var{function} before calling the default
+fontification functions, and gives it two arguments, @var{start} and
+@var{end}, which specify the region to be fontified or refontified.
+
+The optional argument @var{contextual}, if non-@code{nil}, forces Font
+Lock mode to always refontify a syntactically relevant part of the
+buffer, and not just the modified lines. This argument can usually be
+omitted.
+@end defun
+
+@defun jit-lock-unregister function
+If @var{function} was previously registered as a fontification
+function using @code{jit-lock-register}, this function unregisters it.
+@end defun
@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}.
+fontification; it is up to the user to choose one of these levels,
+normally by setting @code{font-lock-maximum-decoration} (@pxref{Font
+Lock,,, emacs, the GNU Emacs Manual}). 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: