Previous: Font Lock Mode, Up: Modes
A hook is a variable where you can store a function or functions to be called on a particular occasion by an existing program. Emacs provides hooks for the sake of customization. Most often, hooks are set up in the init file (see Init File), but Lisp programs can set them also. See Standard Hooks, for a list of standard hook variables.
Most of the hooks in Emacs are normal hooks. These variables contain lists of functions to be called with no arguments. When the hook name ends in ‘-hook’, that tells you it is normal. We try to make all hooks normal, as much as possible, so that you can use them in a uniform way.
Every major mode function is supposed to run a normal hook called the
mode hook as the last step of initialization. This makes it easy
for a user to customize the behavior of the mode, by overriding the
buffer-local variable assignments already made by the mode. But hooks
are used in other contexts too. For example, the hook
suspend-hook
runs just before Emacs suspends itself
(see Suspending Emacs).
The recommended way to add a hook function to a normal hook is by
calling add-hook
(see below). The hook functions may be any of
the valid kinds of functions that funcall
accepts (see What Is a Function). Most normal hook variables are initially void;
add-hook
knows how to deal with this.
If the hook variable's name does not end with ‘-hook’, that indicates it is probably an abnormal hook. Then you should look at its documentation to see how to use the hook properly.
If the variable's name ends in ‘-functions’ or ‘-hooks’,
then the value is a list of functions, but it is abnormal in that either
these functions are called with arguments or their values are used in
some way. You can use add-hook
to add a function to the list,
but you must take care in writing the function. (A few of these
variables are actually normal hooks which were named before we
established the convention of using ‘-hook’ for them.)
If the variable's name ends in ‘-function’, then its value is just a single function, not a list of functions.
Here's an example that uses a mode hook to turn on Auto Fill mode when in Lisp Interaction mode:
(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
At the appropriate time, Emacs uses the run-hooks
function to
run particular hooks. This function calls the hook functions that have
been added with add-hook
.
This function takes one or more hook variable names as arguments, and runs each hook in turn. Each argument should be a symbol that is a hook variable. These arguments are processed in the order specified.
If a hook variable has a non-
nil
value, that value may be a function or a list of functions. If the value is a function (either a lambda expression or a symbol with a function definition), it is called. If it is a list, the elements are called, in order. The hook functions are called with no arguments. Nowadays, storing a single function in the hook variable is semi-obsolete; you should always use a list of functions.For example, here's how
emacs-lisp-mode
runs its mode hook:(run-hooks 'emacs-lisp-mode-hook)
This function is the way to run an abnormal hook which passes arguments to the hook functions. It calls each of the hook functions, passing each of them the arguments args.
This function is the way to run an abnormal hook which passes arguments to the hook functions, and stops as soon as any hook function fails. It calls each of the hook functions, passing each of them the arguments args, until some hook function returns
nil
. Then it stops, and returnsnil
if some hook function returnednil
. Otherwise it returns a non-nil
value.
This function is the way to run an abnormal hook which passes arguments to the hook functions, and stops as soon as any hook function succeeds. It calls each of the hook functions, passing each of them the arguments args, until some hook function returns non-
nil
. Then it stops, and returns whatever was returned by the last hook function that was called.
This function is the handy way to add function function to hook variable hook. The argument function may be any valid Lisp function with the proper number of arguments. For example,
(add-hook 'text-mode-hook 'my-text-hook-function)adds
my-text-hook-function
to the hook calledtext-mode-hook
.You can use
add-hook
for abnormal hooks as well as for normal hooks.It is best to design your hook functions so that the order in which they are executed does not matter. Any dependence on the order is “asking for trouble.” However, the order is predictable: normally, function goes at the front of the hook list, so it will be executed first (barring another
add-hook
call). If the optional argument append is non-nil
, the new hook function goes at the end of the hook list and will be executed last.If local is non-
nil
, that says to make the new hook function buffer-local in the current buffer and automatically callsmake-local-hook
to make the hook itself buffer-local.
This function removes function from the hook variable hook.
If local is non-
nil
, that says to remove 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 local makes no difference.
This function makes the hook variable
hook
buffer-local in the current buffer. When a hook variable is buffer-local, it can have buffer-local and global hook functions, andrun-hooks
runs all of them.This function works by adding
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. Sincerun-hooks
understands this flag,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 oft
.Do not use
make-local-variable
directly for hook variables; it is not sufficient.