procyberian/emacs
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Describe the precise interaction of complex primitives with the change hooks

Browse source 
* doc/lispref/text.texi (Change Hooks): Document that most buffer changing
primitives call before- and after-change-functions in balanced pairs, but that
some complex primitives call b-c-f once, and a-c-f zero, one, or several
times.
This commit is contained in:
Alan Mackenzie 2018-01-06 18:55:08 +00:00
parent 3a22097cf6
commit e876f5f9fb
1 changed files with 15 additions and 8 deletions

23
doc/lispref/text.texi
View file

@ -5023,14 +5023,21 @@ these functions, and neither do certain internal buffer changes, such
as changes in buffers created by Emacs internally for certain jobs,
that should not be visible to Lisp programs.
Do @emph{not} expect the before-change hooks and the after-change
hooks be called in balanced pairs around each buffer change. Also
don't expect the before-change hooks to be called for every chunk of
text Emacs is about to delete. These hooks are provided on the
assumption that Lisp programs will use either before- or the
after-change hooks, but not both, and the boundaries of the region
where the changes happen might include more than just the actual
changed text, or even lump together several changes done piecemeal.
The vast bulk of buffer changing primitives will call
@code{before-change-functions} and @code{after-change-functions} in
balanced pairs, once for each change, where the arguments to these
hooks exactly delimit the change being made. Yet, hook functions
should not rely on this always being the case:
Other, complex primitives call @code{before-change-functions} once
before making changes, and then call @code{after-change-functions}
zero, one, or several times, depending on how many individual changes
the primitive is making. The arguments to
@code{before-change-functions} will enclose a region in which the
individual changes are made, but won't necessarily be the minimal such
region. The arguments to each successive call of
@code{after-change-functions} will then delimit the current part of
the change exactly.
@defmac combine-after-change-calls body@dots{}
The macro executes @var{body} normally, but arranges to call the