GNU Info

Info Node: (elisp)Hooks

(elisp)Hooks


Prev: Font Lock Mode Up: Modes
Enter node , (file) or (file)node

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.  Emacs
provides hooks for the sake of customization.  Most often, hooks are set
up in the init file (Note: Init File), but Lisp programs can set them
also.  Note: 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 (Note: 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 (Note: 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'.

 - Function: run-hooks &rest hookvars
     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)

 - Function: run-hook-with-args hook &rest args
     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.

 - Function: run-hook-with-args-until-failure hook &rest 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 returns `nil' if some hook function
     returned `nil'.  Otherwise it returns a non-`nil' value.

 - Function: run-hook-with-args-until-success hook &rest 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 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.

 - 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
     buffer-local in the current buffer and automatically calls
     `make-local-hook' to make the hook itself buffer-local.

 - 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
     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.

 - Function: make-local-hook hook
     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, and `run-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.  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.


automatically generated by info2www version 1.2.2.9