4.5 Auto-Overlay Modification Pseudo-Hooks

The auto-overlays package adds functions to buffer and overlay modification hooks in order to update the overlays as the buffer text is modified (see Modification Hooks). The order in which all these modification hooks are called is undefined in Emacs¹. Therefore, the auto-overlays package provides a mechanism to schedule functions to run at particular points during the overlay update process.

There are two stages to the overlay update process: first, any match overlay suicide functions are called, then modified buffer lines are scanned for new regexp matches. Three pseudo-hooks are defined that are called before, after and in between these stages. Their values are lists containing elements of the form:

     (function arg1 arg2 ...)

where function is the function to be called by the hook, and the arg's are the arguments to be passed to that function. The list elements are evaluated in order. The pseudo-hooks are cleared each time after they have been called.

auto-o-pending-pre-suicide

Pseudo-hook called before any suicide functions.

auto-o-pending-post-suicide

Pseudo-hook called after any suicide functions but before scanning for regexp matches.

auto-o-pending-post-update

Pseudo-hook called after scanning for regexp matches.

These pseudo-hooks can be used to ensure that a function that would normally be added to a modification hook will be called at a particular point in the auto-overlay update process. To achieve this, a helper function must be added to the modification hook instead. The helper function should add the function itself to the appropriate pseudo-hook by adding a list element with the form described above. The push and add-to-list Elisp functions are the most useful ways to add elements to the list.