File: track-changes.el.html
This library is a layer of abstraction above before-change-functions
and after-change-functions which takes care of accumulating changes
until a time when its client finds it convenient to react to them.
It provides an API that is easier to use correctly than our
*-change-functions hooks. Problems that it claims to solve:
- Before and after calls are not necessarily paired.
- The beg/end values don't always match.
- There's usually only one call to the hooks per command but
there can be thousands of calls from within a single command,
so naive users will tend to write code that performs poorly
in those rare cases.
- The hooks are run at a fairly low-level so there are things they
really shouldn't do, such as modify the buffer or wait.
- The after call doesn't get enough info to rebuild the before-change state,
so some callers need to use both before-c-f and after-c-f (and then
deal with the first two points above).
The new API is almost like after-change-functions except that:
- It provides the "before string" (i.e. the previous content of
the changed area) rather than only its length.
- It can combine several changes into larger ones.
- Clients do not have to process changes right away, instead they
can let changes accumulate (by combining them into a larger change)
until it is convenient for them to process them.
- By default, changes are signaled at most once per command.
The API consists in the following functions:
(track-changes-register SIGNAL &key NOBEFORE DISJOINT IMMEDIATE)
(track-changes-fetch ID FUNC)
(track-changes-unregister ID)
A typical use case might look like:
(defvar my-foo--change-tracker nil) (define-minor-mode my-foo-mode "Fooing like there's no tomorrow." (if (null my-foo-mode) (when my-foo--change-tracker (track-changes-unregister my-foo--change-tracker) (setq my-foo--change-tracker nil)) (unless my-foo--change-tracker (setq my-foo--change-tracker (track-changes-register (lambda (id) (track-changes-fetch id (lambda (beg end before) ..DO THE THING..))))))))
Defined variables (13)
track-changes--before-beg | Beginning position of the remembered "before string". |
track-changes--before-clean | Status of ‘track-changes--before-*’ vars. |
track-changes--before-end | End position of the text replacing the "before string". |
track-changes--before-no | If non-nil, all the trackers are ‘nobefore’. |
track-changes--before-string | String holding some contents of the buffer before the current change. |
track-changes--buffer-size | Current size of the buffer, as far as this library knows. |
track-changes--clean-trackers | List of trackers that are clean. |
track-changes--disjoint-trackers | List of trackers that want to react to disjoint changes. |
track-changes--error-log | List of errors encountered. |
track-changes--trace | Ring holding a trace of recent calls to the API. |
track-changes--trackers | List of trackers currently registered in the buffer. |
track-changes-record-errors | If non-nil, keep track of errors in ‘before/after-change-functions’ calls. |
track-changes-undo-only | Bound to non-nil by ‘track-changes-fetch’ if the change was an undo. |