Subject: bug#75170: add-to-alist: new function

From: Roland Winkler <[email-masked]>
Date: Sun, 19 Jan 2025 00:17:01 -0600

On Sun, Jan 19 2025, Michael Heerdegen wrote:
>> Is there a simple way to accomplish this in other ways (a way that we
>> recommend for users in their init file if they do not want to use
>> customize like me)?
>
> We indeed recommend using (setf (alist-get ...)), IIUC this is _exactly_
> what you were looking for.  Your patch contains an implementation of the
> setter of `alist-get', and we would add a duplication.
>
> If you did not find this thing, maybe we need to add a hint to some
> chapter of the manual?

Great! -- It seems, indeed, the code I am looking for does (mostly, see
below) exist.  But the "We indeed recommend using..." can be improved.
It should appear at a spot where not only advanced elisp hackers may
have a chance of finding it.  But more average users should be able to
find it, too (say, as a strategy for modifying alists in the emacs init
file).

I just noticed: the docstring of alist-get is much more verbose
regarding how this function can be combined with setf than the elisp
manual.  So extending the documentation of alist-get in the elisp manual
can already make a big difference!  Personally, I always find typical
usage examples in the elisp manual most helpful.

Actually, I just read the docstring from alist-get a couple of times.
And the meaning of the optional arg REMOVE is not clear to me: what is
the "new value" of an association if the key is removed from the alist?

Also, it seems to me there is a difference between add-to-alist and
(setf (alist-get ...)).  It was already Stephen Gildea's original
proposal from long time ago to give this function an optional arg
NO-REPLACE, and his proposal included a nice example for when this can
be useful (copied in my first posting).  It seems to me that
(setf (alist-get ...)) has no equivalent of NO-REPLACE.  Personally,
I have not run in a situation when I had needed this arg; but I can
imagine that it would help others.

Roland