Function: track-changes-register

track-changes-register is a byte-compiled function defined in track-changes.el.gz.

Signature

(track-changes-register SIGNAL &key NOBEFORE DISJOINT IMMEDIATE)

Documentation

Register a new tracker whose change-tracking function is SIGNAL.

Return the ID of the new tracker.

SIGNAL is a function that will be called with one argument (the tracker ID) after the current buffer is modified, so that it can react to the change. Once called, SIGNAL is not called again until track-changes-fetch is called with the corresponding tracker ID.

If optional argument NOBEFORE is non-nil, it means that this tracker does not need the BEFORE strings (it will receive their size instead).

If optional argument DISJOINT is non-nil, SIGNAL is called every time just before combining changes from "distant" parts of the buffer. This is needed when combining disjoint changes into one bigger change is unacceptable, typically for performance reasons. These calls are distinguished from normal calls by calling SIGNAL with a second argument which is the distance between the upcoming change and the previous changes. BEWARE: In that case SIGNAL is called directly from before-change-functions and should thus be extra careful: don't modify the buffer, don't call a function that may block, ... In order to prevent the upcoming change from being combined with the previous changes, SIGNAL needs to call track-changes-fetch before it returns.

By default SIGNAL is called after a change via a 0 seconds timer. If optional argument IMMEDIATE is non-nil it means SIGNAL should be called as soon as a change is detected, BEWARE: In that case SIGNAL is called directly from after-change-functions and should thus be extra careful: don't modify the buffer, don't call a function that may block, do as little work as possible, ... When IMMEDIATE is non-nil, the SIGNAL should probably not always call track-changes-fetch, since that would defeat the purpose of this library.

View in manual

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/track-changes.el.gz
(cl-defun track-changes-register ( signal &key nobefore disjoint immediate)
  "Register a new tracker whose change-tracking function is SIGNAL.
Return the ID of the new tracker.

SIGNAL is a function that will be called with one argument (the tracker ID)
after the current buffer is modified, so that it can react to the change.
Once called, SIGNAL is not called again until `track-changes-fetch'
is called with the corresponding tracker ID.

If optional argument NOBEFORE is non-nil, it means that this tracker does
not need the BEFORE strings (it will receive their size instead).

If optional argument DISJOINT is non-nil, SIGNAL is called every time just
before combining changes from \"distant\" parts of the buffer.
This is needed when combining disjoint changes into one bigger change
is unacceptable, typically for performance reasons.
These calls are distinguished from normal calls by calling SIGNAL with
a second argument which is the distance between the upcoming change and
the previous changes.
BEWARE: In that case SIGNAL is called directly from `before-change-functions'
and should thus be extra careful: don't modify the buffer, don't call a function
that may block, ...
In order to prevent the upcoming change from being combined with the previous
changes, SIGNAL needs to call `track-changes-fetch' before it returns.

By default SIGNAL is called after a change via a 0 seconds timer.
If optional argument IMMEDIATE is non-nil it means SIGNAL should be called
as soon as a change is detected,
BEWARE: In that case SIGNAL is called directly from `after-change-functions'
and should thus be extra careful: don't modify the buffer, don't call a function
that may block, do as little work as possible, ...
When IMMEDIATE is non-nil, the SIGNAL should probably not always call
`track-changes-fetch', since that would defeat the purpose of this library."
  (track-changes--trace)
  (when (and nobefore disjoint)
    ;; FIXME: Without `before-change-functions', we can discover
    ;; a disjoint change only after the fact, which is not good enough.
    ;; But we could use a stripped down before-change-function,
    (error "`disjoint' not supported for `nobefore' trackers"))
  (track-changes--clean-state)
  (unless nobefore
    (setq track-changes--before-no nil)
    (add-hook 'before-change-functions #'track-changes--before nil t))
  (add-hook 'after-change-functions  #'track-changes--after  nil t)
  (let ((tracker (track-changes--tracker signal track-changes--state
                                         nobefore immediate)))
    (push tracker track-changes--trackers)
    (push tracker track-changes--clean-trackers)
    (when disjoint
      (push tracker track-changes--disjoint-trackers))
    tracker))