GNU Info

(elisp)Change Hooks

---

Prev: MD5 Checksum Up: Text

---

Enter node , (file) or (file)node

Change Hooks
============

   These hook variables let you arrange to take notice of all changes in
all buffers (or in a particular buffer, if you make them buffer-local).
See also Note: Special Properties, for how to detect changes to
specific parts of the text.

   The functions you use in these hooks should save and restore the
match data if they do anything that uses regular expressions;
otherwise, they will interfere in bizarre ways with the editing
operations that call them.

 - Variable: before-change-functions
     This variable holds a list of functions to call before any buffer
     modification.  Each function gets two arguments, the beginning and
     end of the region that is about to change, represented as
     integers.  The buffer that is about to change is always the
     current buffer.

 - Variable: after-change-functions
     This variable holds a list of functions to call after any buffer
     modification.  Each function receives three arguments: the
     beginning and end of the region just changed, and the length of
     the text that existed before the change.  All three arguments are
     integers.  The buffer that's about to change is always the current
     buffer.

     The length of the old text is the difference between the buffer
     positions before and after that text as it was before the change.
     As for the changed text, its length is simply the difference
     between the first two arguments.

 - Macro: combine-after-change-calls body...
     The macro executes BODY normally, but arranges to call the
     after-change functions just once for a series of several
     changes--if that seems safe.

     If a program makes several text changes in the same area of the
     buffer, using the macro `combine-after-change-calls' around that
     part of the program can make it run considerably faster when
     after-change hooks are in use.  When the after-change hooks are
     ultimately called, the arguments specify a portion of the buffer
     including all of the changes made within the
     `combine-after-change-calls' body.

     *Warning:* You must not alter the values of
     `after-change-functions' within the body of a
     `combine-after-change-calls' form.

     *Note:* If the changes you combine occur in widely scattered parts
     of the buffer, this will still work, but it is not advisable,
     because it may lead to inefficient behavior for some change hook
     functions.

   The two variables above are temporarily bound to `nil' during the
time that any of these functions is running.  This means that if one of
these functions changes the buffer, that change won't run these
functions.  If you do want a hook function to make changes that run
these functions, make it bind these variables back to their usual
values.

   One inconvenient result of this protective feature is that you cannot
have a function in `after-change-functions' or
`before-change-functions' which changes the value of that variable.
But that's not a real limitation.  If you want those functions to change
the list of functions to run, simply add one fixed function to the hook,
and code that function to look in another variable for other functions
to call.  Here is an example:

     (setq my-own-after-change-functions nil)
     (defun indirect-after-change-function (beg end len)
       (let ((list my-own-after-change-functions))
         (while list
           (funcall (car list) beg end len)
           (setq list (cdr list)))))
     
     (add-hooks 'after-change-functions
                'indirect-after-change-function)

 - Variable: first-change-hook
     This variable is a normal hook that is run whenever a buffer is
     changed that was previously in the unmodified state.

 - Variable: inhibit-modification-hooks
     If this variable is non-`nil', all of the change hooks are
     disabled; none of them run.  This affects all the hook variables
     described above in this section, as well as the hooks attached to
     certain special text properties (Note: Special Properties) and
     overlay properties (Note: Overlay Properties).

     This variable is available starting in Emacs 21.