Subject: Re: bug#70077: An easier way to track buffer changes

From: Eli Zaretskii <[email-masked]>
Date: Fri, 29 Mar 2024 21:12:54 +0300

> Cc: Nicolas Goaziou <[email-masked]>,
>  Ihor Radchenko <[email-masked]>, Alan Mackenzie <[email-masked]>,
>  João Távora <[email-masked]>,
>  Alan Zimmerman <[email-masked]>,
>  Frédéric Bour <[email-masked]>,
>  Phillip Lord <[email-masked]>,
>  Stephen Leake <[email-masked]>, Yuan Fu <[email-masked]>,
>  Qiantan Hong <[email-masked]>, [email-masked]
> Date: Fri, 29 Mar 2024 12:15:53 -0400
> From:  Stefan Monnier via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <[email-masked]>
> 
>     (defun track-changes-register ( signal)
>       "Register a new tracker and return a new tracker ID.
>     SIGNAL is a function that will be called with no argument when
>     the current buffer is modified, so that we can react to the change.
>     Once called, SIGNAL is not called again until `track-changes-fetch'
>     is called with the corresponding tracker ID."
>     
>     (defun track-changes-unregister (id)
>       "Remove the tracker denoted by ID.
>     Trackers can consume resources (especially if `track-changes-fetch' is
>     not called), so it is good practice to unregister them when you don't
>     need them any more."
>     
>     (defun track-changes-fetch (id func)
>       "Fetch the pending changes.
>     ID is the tracker ID returned by a previous `track-changes-register'.
>     FUNC is a function.  It is called with 3 arguments (BEGIN END BEFORE)
>     where BEGIN..END delimit the region that was changed since the last
>     time `track-changes-fetch' was called and BEFORE is a string containing
>     the previous content of that region.
>     
>     If no changes occurred since the last time, FUNC is not called and
>     we return nil, otherwise we return the value returned by FUNC,
>     and re-enable the TRACKER corresponding to ID."

I cannot imagine how applications would use these APIs.  I'm probably
missing something, org the above documentation does.  Can you show
some real-life examples?