Previous: Auto-Overlay Hooks, Up: Extending the Auto-Overlays Package


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


Footnotes

[1] Or at least undocumented, and therefore unreliable.