[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#34708: alist-get has unclear documentation
From: |
Drew Adams |
Subject: |
bug#34708: alist-get has unclear documentation |
Date: |
Sun, 3 Mar 2019 07:51:51 -0800 (PST) |
> > I think the sentence below is a good and short explanation for the
> > doc-string.
> >
> > The return value can be conveniently used as a generalized variable
Lose "conveniently", please.
> > (a place) to set the value associated with KEY in ALIST, like in the
> > example (setf (alist-get key alist) new-value)
>
> Thanks for the idea. I don't think we should explain it like this
> however, because when evaluating
>
> (setf (alist-get key alist) new-value)
>
> the function `alist-get' is never called, so there is no return value.
Yes. (But that text didn't say it was called, and
it didn't mention a return value.)
`setf' is a macro. Its PLACE arg serves as a
_specification_ of a place (a "generalized
variable") whose value is to be set. And "set"
means create or update.
It's not really about `alist-get' here; it's
about `setf'. `alist-get' itself has nothing
to do with using a generalized variable.
> Of course what is sexy about place expressions is that it looks like
> you would directly set the result of a function call, but what happens is
> that setf doesn't evaluate the call but analyses it and builds and
> evaluates code that leads to this result.
Yes. But that's "just" plumbing. It's not
important to explain that here, I think.
In terms of describing the role of `alist-get'
as a `setf' place it's not relevant, at a first
approximation.
That `setf' doesn't call `alist-get' but instead
analyses the spec and builds code that does the
right thing is not necessary for getting the main
point that `alist-get' can be used with `setf' to
specify an alist element to create or update.
> Eric suggested to say "this form is a setf-able place" but this also
> doesn't answer the question what this (form) is. `alist-get' is not a
> form, it's the name of a function. In my opinion it would be cleaner
> to say something like "the name of this function can be used to build
> place expressions" or "can be used in place expressions" or so.
> Better ideas welcome.
Yes wrt the substance (content). But an active
phrasing is often better than the passive "__ can
be used". Say what this does by saying what you
can do with it.
You can use function `alist-get' in a PLACE-expression
argument to `setf'. In this role it specifies an
alist element whose value `setf' sets:
(setf (alist-get KEY ALIST) NEW-VALUE)
Here, `setf' sets the value part of an element
of ALIST whose key is KEY to NEW-VALUE.
It's important to not give the impression that
there must be an _existing_ element with KEY.
Showing an example can help dispel that mistake.
(setq foo ())
(setf (alist-get 'a foo) 1
(alist-get 'b foo) 2)
C-h v foo ; ==> ((b . 2) (a . 1))
- bug#34708: alist-get has unclear documentation, (continued)
- bug#34708: alist-get has unclear documentation, Miguel V. S. Frasson, 2019/03/02
- bug#34708: alist-get has unclear documentation, Michael Heerdegen, 2019/03/02
- bug#34708: alist-get has unclear documentation, Eric Abrahamsen, 2019/03/02
- bug#34708: alist-get has unclear documentation, Phil Sainty, 2019/03/02
- bug#34708: alist-get has unclear documentation, Michael Heerdegen, 2019/03/03
- bug#34708: alist-get has unclear documentation, Michael Heerdegen, 2019/03/18
- bug#34708: alist-get has unclear documentation, Miguel V. S. Frasson, 2019/03/02
- bug#34708: alist-get has unclear documentation, Eric Abrahamsen, 2019/03/02
- bug#34708: alist-get has unclear documentation, Miguel V. S. Frasson, 2019/03/03
- bug#34708: alist-get has unclear documentation, Michael Heerdegen, 2019/03/03
- bug#34708: alist-get has unclear documentation,
Drew Adams <=
- bug#34708: alist-get has unclear documentation, Eric Abrahamsen, 2019/03/03
- bug#34708: alist-get has unclear documentation, Eric Abrahamsen, 2019/03/04
- bug#34708: alist-get has unclear documentation, Michael Heerdegen, 2019/03/04
- bug#34708: alist-get has unclear documentation, Eric Abrahamsen, 2019/03/04
- bug#34708: alist-get has unclear documentation, Michael Heerdegen, 2019/03/04
- bug#34708: alist-get has unclear documentation, Eric Abrahamsen, 2019/03/04
- bug#34708: alist-get has unclear documentation, Michael Heerdegen, 2019/03/05
- bug#34708: alist-get has unclear documentation, Eric Abrahamsen, 2019/03/05
- bug#34708: alist-get has unclear documentation, Drew Adams, 2019/03/05
- bug#34708: alist-get has unclear documentation, Michael Heerdegen, 2019/03/11