Hooks
=====
A "hook" is a variable where you can store a function or functions
to be called on a particular occasion by an existing program. XEmacs
provides hooks for the sake of customization. Most often, hooks are set
up in the `.emacs' file, but Lisp programs can set them also. *Note
Standard Hooks::, for a list of standard hook variables.
Most of the hooks in XEmacs are "normal hooks". These variables
contain lists of functions to be called with no arguments. The reason
most hooks are normal hooks is so that you can use them in a uniform
way. You can usually tell when a hook is a normal hook, because its
name ends in `-hook'.
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 (*note What Is a
Function::). Most normal hook variables are initially void; `add-hook'
knows how to deal with this.
As for abnormal hooks, those whose names end in `-function' have a
value that is a single function. Those whose names end in `-hooks'
have a value that is a list of functions. Any hook that is abnormal is
abnormal because a normal hook won't do the job; either the functions
are called with arguments, or their values are meaningful. The name
shows you that the hook is abnormal and that you should look at its
documentation string to see how to use it properly.
Major mode functions are supposed to run a 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 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
XEmacs suspends itself (see Suspending XEmacs).
Here's an expression 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)
The next example shows how to use a hook to customize the way XEmacs
formats C code. (People often have strong personal preferences for one
format or another.) Here the hook function is an anonymous lambda
expression.
(add-hook 'c-mode-hook
(function (lambda ()
(setq c-indent-level 4
c-argdecl-indent 0
c-label-offset -4
c-continued-statement-indent 0
c-brace-offset 0
comment-column 40))))
(setq c++-mode-hook c-mode-hook)
The final example shows how the appearance of the modeline can be
modified for a particular class of buffers only.
(add-hook 'text-mode-hook
(function (lambda ()
(setq modeline-format
'(modeline-modified
"Emacs: %14b"
" "
default-directory
" "
global-mode-string
"%[("
mode-name
minor-mode-alist
"%n"
modeline-process
") %]---"
(-3 . "%p")
"-%-")))))
At the appropriate time, XEmacs uses the `run-hooks' function to run
particular hooks. This function calls the hook functions you have
added with `add-hooks'.
- Function: run-hooks &rest hookvar
This function takes one or more hook variable names as arguments,
and runs each hook in turn. Each HOOKVAR 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.
For example, here's how `emacs-lisp-mode' runs its mode hook:
(run-hooks 'emacs-lisp-mode-hook)
- Function: add-hook hook function &optional append local
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 called `text-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
local to the current buffer. Before you can do this, you must
make the hook itself buffer-local by calling `make-local-hook'
(*not* `make-local-variable'). If the hook itself is not
buffer-local, then the value of LOCAL makes no difference--the
hook function is always global.
- Function: remove-hook hook function &optional local
This function removes FUNCTION from the hook variable HOOK.
If LOCAL is non-`nil', that says to remove FUNCTION from the local
hook list instead of from the global hook list. If the hook
itself is not buffer-local, then the value of LOCAL makes no
difference.
- Function: make-local-hook hook
This function makes the hook variable `hook' local to the current
buffer. When a hook variable is local, it can have local and
global hook functions, and `run-hooks' runs all of them.
This function works by making `t' an element of the buffer-local
value. That serves as a flag to use the hook functions in the
default value of the hook variable as well as those in the local
value. Since `run-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 of `t'.
Do not use `make-local-variable' directly for hook variables; it is
not sufficient.