Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

> branch: emacs-25
> commit 2460cfac091c6a5b095816bef9e639f9da88f432
> Author: Eli Zaretskii <eliz@gnu.org>
> Commit: Eli Zaretskii <eliz@gnu.org>
>
>     * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.
> ---
>  doc/lispref/lists.texi |    8 ++++++++
>  etc/NEWS               |    1 +
>  2 files changed, 9 insertions(+), 0 deletions(-)
>
> diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
> index d961caf..c18c408 100644
> --- a/doc/lispref/lists.texi
> +++ b/doc/lispref/lists.texi
> @@ -1556,6 +1556,14 @@ keys may not be symbols:
>  @end smallexample
>  @end defun
>  
> +@defun alist-get key value &optional default
> +This function is like @code{assq}, but instead of returning the entire
> +association for @var{key}, @code{(@var{key} . @var{value})}, it
> +returns just the @var{value}.  It returns @var{default} if @var{key}
> +is not found in @var{alist}, defaulting to @code{nil} if @var{default}
> +is omitted.
> +@end defun
> +

Should we add that it is also a valid place expression ("setf'able")?  Or
to the docstring?  That fact doesn't seem to be discoverable at all now.


Thanks,

Michael.

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: Eli Zaretskii <eliz@gnu.org>
> Date: Tue, 19 Jan 2016 10:53:09 +0100
> 
> > +@defun alist-get key value &optional default
> > +This function is like @code{assq}, but instead of returning the entire
> > +association for @var{key}, @code{(@var{key} . @var{value})}, it
> > +returns just the @var{value}.  It returns @var{default} if @var{key}
> > +is not found in @var{alist}, defaulting to @code{nil} if @var{default}
> > +is omitted.
> > +@end defun
> 
> Should we add that it is also a valid place expression ("setf'able")?  Or
> to the docstring?  That fact doesn't seem to be discoverable at all now.

I don't know -- should we?  I didn't find any other function for which
we say something like that, so saw no reason to single this one out.
Did I miss something?

In any case, if it's so important to mention that, why doesn't the
function's doc string make a point of doing so?  Or maybe I didn't
understand the doc string (do you?).

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[John Wiegley]

>>>>> Eli Zaretskii <eliz@gnu.org> writes:

>> > +@defun alist-get key value &optional default
>> 
>> Should we add that it is also a valid place expression ("setf'able")?  Or
>> to the docstring?  That fact doesn't seem to be discoverable at all now.

> I don't know -- should we? I didn't find any other function for which we say
> something like that, so saw no reason to single this one out. Did I miss
> something?

> In any case, if it's so important to mention that, why doesn't the
> function's doc string make a point of doing so? Or maybe I didn't understand
> the doc string (do you?).

alist-get is extremely welcome, I'm quite tired of writing (cdr (assq ...)).
The fact that it is a setf "place" is also quite wonderful.

But where to document that fact so people find it... `setf' is applicable in
many scenarios, which people familiar with setf mainly know -- since I imagine
not many people use setf who are not from the CL world.

We could start adding something like this at the bottom of such functions:

  Invocations of this function may be used as a place expression to `setf'.

That is, if we wish to encourage `setf' use. The other possibility is to add
documentation to the Elisp manual where it describes `setf', and list all the
functions that may be used by it. I have a feeling that would reach your
intended audience better than extending the docstring for `alist-get'.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Yuri Khan]

On Tue, Jan 19, 2016 at 11:59 PM, John Wiegley <jwiegley@gmail.com> wrote:

> We could start adding something like this at the bottom of such functions:
>
>   Invocations of this function may be used as a place expression to `setf'.
>
> That is, if we wish to encourage `setf' use. The other possibility is to add
> documentation to the Elisp manual where it describes `setf', and list all the
> functions that may be used by it. I have a feeling that would reach your
> intended audience better than extending the docstring for `alist-get'.

Good documentation advertises relationships between separately
documented entities at both ends.

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[John Wiegley]

>>>>> Yuri Khan <yuri.v.khan@gmail.com> writes:

> Good documentation advertises relationships between separately
> documented entities at both ends.

No doubt, except when there are many, many-to-many relationships. Too much
information can, at times, obscure the main point.

The use of `setf' is mainly orthogonal to the purpose of `alist-get'. Yes, you
can use them in combination, but so can a lot of other functions with either
of those. We're not going to add all those possibilities to both docstrings.

If setf+alist-get were a primary use case for alist-get, I'd be more
convinced; but it's just one possible combination.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Eli Zaretskii]

> From: Yuri Khan <yuri.v.khan@gmail.com>
> Date: Wed, 20 Jan 2016 13:31:08 +0600
> 
> Good documentation advertises relationships between separately
> documented entities at both ends.

Please feel free to submit documentation patches to that effect.

TIA

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

> > From: Michael Heerdegen <michael_heerdegen@web.de>
> > Cc: Eli Zaretskii <eliz@gnu.org>
> > Date: Tue, 19 Jan 2016 10:53:09 +0100
> > 
> > > +@defun alist-get key value &optional default
> > > +This function is like @code{assq}, but instead of returning the
> > > entire
> > > +association for @var{key}, @code{(@var{key} . @var{value})}, it
> > > +returns just the @var{value}.  It returns @var{default} if @var{key}
> > > +is not found in @var{alist}, defaulting to @code{nil} if
> > > @var{default}
> > > +is omitted.
> > > +@end defun
> > 
> > Should we add that it is also a valid place expression
> > ("setf'able")?  Or
> > to the docstring?  That fact doesn't seem to be discoverable at all now.

CC'ing Stefan, I think he can clarify.

> I don't know -- should we?  I didn't find any other function for which
> we say something like that, so saw no reason to single this one out.

I think setf'ing alist-get is the preferred way now to change the value
associated to a key.  If it is, it should be discoverable in some way,
because it is an important functionality.  Unlike other functions that
are setf'able, in this case we have no equivalent setter function
defined, i think.

> In any case, if it's so important to mention that, why doesn't the
> function's doc string make a point of doing so?  Or maybe I didn't
> understand the doc string (do you?).

I think the docstring should be improved.  AFAICT the REMOVE arg makes
only sense when using the function with a gv setter.


Michael.

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: emacs-devel@gnu.org, Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Tue, 19 Jan 2016 19:01:30 +0100
> 
> > I don't know -- should we?  I didn't find any other function for which
> > we say something like that, so saw no reason to single this one out.
> 
> I think setf'ing alist-get is the preferred way now to change the value
> associated to a key.  If it is, it should be discoverable in some way,
> because it is an important functionality.  Unlike other functions that
> are setf'able, in this case we have no equivalent setter function
> defined, i think.

Isn't 'cdr' also in that class?  As well as at least a few others?

AFAIU, this function just saves you from the need to repeatedly test
the value returned by assq before using it, that's all.  I don't see
what's so exciting about that.  We have similar tricks, some of them
gems, all over the place, and there's no practical way we could make
them stand out enough, not when we have almost 2000 functions, macros,
and special forms documented in the manual (and many more not
documented).  The only way is for people to read well-written code and
learn.  No manual can ever replace that.

> I think the docstring should be improved.  AFAICT the REMOVE arg makes
> only sense when using the function with a gv setter.

For the record, that doc string almost made me weep in frustration --
about my own stupidity, no doubt, since I couldn't make heads or tails
out of it, when I compared it with the actual code (including studying
the _only_ use of it in the context of a gv setter, AFAICT).

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[John Wiegley]

>>>>> Eli Zaretskii <eliz@gnu.org> writes:

> Isn't 'cdr' also in that class? As well as at least a few others?

We have setcdr.

> AFAIU, this function just saves you from the need to repeatedly test the
> value returned by assq before using it, that's all.

The old way:

    GET: (cdr (assq key my-alist))
    SET: (setcdr (assq key my-alist) new-value)

The new hotness:

    GET: (alist-get key my-alist)
    SET: (setf (alist-get key my-alist) new-value)

So... not actually a whole lot of difference. I'm not sure if this is exciting
enough to need advertisement in a docstring. But in the elisp manual, sure.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Eli Zaretskii]

> From: John Wiegley <jwiegley@gmail.com>
> Cc: Michael Heerdegen <michael_heerdegen@web.de>,  monnier@iro.umontreal.ca,  emacs-devel@gnu.org
> Date: Tue, 19 Jan 2016 10:42:57 -0800
> 
> So... not actually a whole lot of difference. I'm not sure if this is exciting
> enough to need advertisement in a docstring. But in the elisp manual, sure.

Done.

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Michael Heerdegen]

John Wiegley <jwiegley@gmail.com> writes:


> The old way:
>
>     GET: (cdr (assq key my-alist))
>     SET: (setcdr (assq key my-alist) new-value)
>
> The new hotness:
>
>     GET: (alist-get key my-alist)
>     SET: (setf (alist-get key my-alist) new-value)

That's only one half of the truth: Your two SETs are different if KEY is
not yet present in MY-ALIST.  "The old way" doesn't work in that case,
the new one does.  It replaces a complete

  (if (assq ...)
    (setcdr ... ...)
   (push ... ...))


Michael.

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Stefan Monnier]

>     SET: (setcdr (assq key my-alist) new-value)

This fails if (assq key my-alist) returns nil.


        Stefan

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

> > I think setf'ing alist-get is the preferred way now to change the value
> > associated to a key.  If it is, it should be discoverable in some way,
> > because it is an important functionality.  Unlike other functions that
> > are setf'able, in this case we have no equivalent setter function
> > defined, i think.
>
> Isn't 'cdr' also in that class?

No, we have setcdr.

>  As well as at least a few others?

Dunno.  Which ones?

> For the record, that doc string almost made me weep in frustration --
> about my own stupidity, no doubt, since I couldn't make heads or tails
> out of it, when I compared it with the actual code (including studying
> the _only_ use of it in the context of a gv setter, AFAICT).

Maybe _only_ because few people know about it.

The problem I want to solve is: Now that assoc.el is obsolete, there is
no replacement for `aput' besides setf'ing alist-get.

Manipulating alists is a thing sometimes necessary for customizing
Emacs, it is useful for end users.  They should not need to study source
code.


Michael.

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Date: Tue, 19 Jan 2016 19:52:18 +0100
> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
> 
> > For the record, that doc string almost made me weep in frustration --
> > about my own stupidity, no doubt, since I couldn't make heads or tails
> > out of it, when I compared it with the actual code (including studying
> > the _only_ use of it in the context of a gv setter, AFAICT).
> 
> Maybe _only_ because few people know about it.

The function was added recently, so we should expect it to be
relatively unfamiliar.

> The problem I want to solve is: Now that assoc.el is obsolete, there is
> no replacement for `aput' besides setf'ing alist-get.
> 
> Manipulating alists is a thing sometimes necessary for customizing
> Emacs, it is useful for end users.  They should not need to study source
> code.

I added it now to the list in the section that discusses 'setf', which
is where we name functions with this property.  I very much doubt that
this will help advertising this property in any significant way, but
at least now we can stop arguing about it, I hope.

As an aside, people who are interested in better documentation are
welcome to commit changes to the manuals.  I only did that humongous
job because no one else would, but it's not like I'm the only one who
can (or should) do it, you know.  IOW, instead of questioning my
judgment, by all means simply make the improvements you think are due.

Thanks.

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

> As an aside, people who are interested in better documentation are
> welcome to commit changes to the manuals.  I only did that humongous
> job because no one else would, but it's not like I'm the only one who
> can (or should) do it, you know.  IOW, instead of questioning my
> judgment, by all means simply make the improvements you think are due.

No, I really wanted to discuss it, not that you just make some change.

I still think the typical Emacs user will ask himself: "Where is
alist-put?".  Don't you think (info "(elisp) Association Lists") should
answer this question?


Michael.

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: monnier@iro.umontreal.ca,  emacs-devel@gnu.org
> Date: Tue, 19 Jan 2016 20:34:33 +0100
> 
> I really wanted to discuss it, not that you just make some change.

(I made the change because John asked for it.)

If you want to discuss this, then I'm not sure I'm the one you should
discuss this with.  I never use alist-get in any of my code; the only
reason I know about its existence is because it was marked
undocumented in NEWS, and I went through NEWS as part of finishing the
documentation for v25.1.

If you ask my opinion as someone who writes documentation quite a lot,
then I don't think we can do _anything_ in the manual to make this
feature of this particular function more discoverable.  With the size
of the manual we have, you have to _know_ what you are looking for to
find it quickly.

> I still think the typical Emacs user will ask himself: "Where is
> alist-put?".  Don't you think (info "(elisp) Association Lists") should
> answer this question?

IME, the best way to answer such questions is to add alist-put.

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[John Wiegley]

>>>>> Eli Zaretskii <eliz@gnu.org> writes:

> IME, the best way to answer such questions is to add alist-put.

Yeah, let's add alist-put. Even if setf can do the job, then let's use in the
implementation of alist-put.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Michael Heerdegen]

John Wiegley <jwiegley@gmail.com> writes:

> > IME, the best way to answer such questions is to add alist-put.
>
> Yeah, let's add alist-put. Even if setf can do the job, then let's use
> in the implementation of alist-put.

I would prefer the other way round: just factor out the setter and name
it.

@Stefan: can you enlighten us why you didn't initially do this?


Regards,

Michael

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Stefan Monnier]

> I would prefer the other way round: just factor out the setter and
> name it.
> @Stefan: can you enlighten us why you didn't initially do this?

'Cause I don't know how.


        Stefan

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Michael Heerdegen]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

> > @Stefan: can you enlighten us why you didn't initially do this?
>
> 'Cause I don't know how.

I don't understand...what don't you know?


Michael.

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Stefan Monnier]

>> > @Stefan: can you enlighten us why you didn't initially do this?
>> 'Cause I don't know how.
> I don't understand...what don't you know?

How to provide a function that does the core work of (setf (alist-get
..) ...), such that it can be used in the expanded code and ideally
even independently.


        Stefan

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Michael Heerdegen]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

> >> > @Stefan: can you enlighten us why you didn't initially do this?
> >> 'Cause I don't know how.
> > I don't understand...what don't you know?
>
> How to provide a function that does the core work of (setf (alist-get
> ..) ...), such that it can be used in the expanded code and ideally
> even independently.

I see.

I think if we add an `alist-put', it should ideally be a macro (in
analogy to `push' that adds to a plain list), and the signature should
be analogous to `alist-get' OTOH.  So we would end up with something
like

--8<---------------cut here---------------start------------->8---
(defmacro alist-put (key value place &optional default remove)
  (gv-letplace (_ setter) `(alist-get ,key ,place ,default ,remove)
    (funcall setter value)))
--8<---------------cut here---------------end--------------->8---

Would it make sense to add something like this?


Michael.

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Date: Thu, 21 Jan 2016 18:44:25 +0100
> 
> --8<---------------cut here---------------start------------->8---
> (defmacro alist-put (key value place &optional default remove)
>   (gv-letplace (_ setter) `(alist-get ,key ,place ,default ,remove)
>     (funcall setter value)))
> --8<---------------cut here---------------end--------------->8---
> 
> Would it make sense to add something like this?

Not without a decent doc string.

Thanks.

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Eli Zaretskii]

> Date: Thu, 21 Jan 2016 20:00:06 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: emacs-devel@gnu.org
> 
> > From: Michael Heerdegen <michael_heerdegen@web.de>
> > Date: Thu, 21 Jan 2016 18:44:25 +0100
> > 
> > --8<---------------cut here---------------start------------->8---
> > (defmacro alist-put (key value place &optional default remove)
> >   (gv-letplace (_ setter) `(alist-get ,key ,place ,default ,remove)
> >     (funcall setter value)))
> > --8<---------------cut here---------------end--------------->8---
> > 
> > Would it make sense to add something like this?
> 
> Not without a decent doc string.

Sorry, that was probably uncalled-for.

In my defense, I just came up from a few days of fixing bad or
non-existent documentation for code like the above, which just pushed
me off the edge.  And it's not over yet.  I hope we will never again
admit such code into Emacs.

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

> In my defense, I just came up from a few days of fixing bad or
> non-existent documentation for code like the above, which just pushed
> me off the edge.  And it's not over yet.  I hope we will never again
> admit such code into Emacs.

I hope that too.  Thanks for all your work.


Michael.

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[John Wiegley]

>>>>> Eli Zaretskii <eliz@gnu.org> writes:

>> > (defmacro alist-put (key value place &optional default remove)
>> >   (gv-letplace (_ setter) `(alist-get ,key ,place ,default ,remove)
>> >     (funcall setter value)))
>> 
>> Not without a decent doc string.

I hear you.  For that code above, the comment would be:

    Given an expression -- in this case, `alist-get' applied to the arguments
    passed to this macro -- find the `setter' that can "modify in place" the
    object returned by that expression, and immediately use it to replace that
    object with the value passed by the caller.

Syntactical it's unfortunate, given what it's trying to do. `gv-letplace'
could use another name...

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Eli Zaretskii]

> From: John Wiegley <jwiegley@gmail.com>
> Cc: michael_heerdegen@web.de,  emacs-devel@gnu.org
> Date: Thu, 21 Jan 2016 16:56:06 -0800
> 
> >>>>> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> > (defmacro alist-put (key value place &optional default remove)
> >> >   (gv-letplace (_ setter) `(alist-get ,key ,place ,default ,remove)
> >> >     (funcall setter value)))
> >> 
> >> Not without a decent doc string.
> 
> I hear you.  For that code above, the comment would be:
> 
>     Given an expression -- in this case, `alist-get' applied to the arguments
>     passed to this macro -- find the `setter' that can "modify in place" the
>     object returned by that expression, and immediately use it to replace that
>     object with the value passed by the caller.

The doc string should explain the arguments, so that should be added
to the text you propose.

Thanks.

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[John Wiegley]

>>>>> Eli Zaretskii <eliz@gnu.org> writes:

>> Given an expression -- in this case, `alist-get' applied to the arguments
>> passed to this macro -- find the `setter' that can "modify in place" the
>> object returned by that expression, and immediately use it to replace that
>> object with the value passed by the caller.

> The doc string should explain the arguments, so that should be added to the
> text you propose.

What I wrote should really be a comment above the code, to explain what it
does to human beings. The actual docstring should be along the lines of "Get a
value from an alist"...

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Michael Heerdegen]

John Wiegley <jwiegley@gmail.com> writes:

> What I wrote should really be a comment above the code, to explain
> what it does to human beings.

Do you really think we should add a comment like that to the code?  To
understand the definition, it's better to have a look at gv.el.  After
having had a look, such a comment is not necessary anymore, since we
have a more or less trivial usage of `gv-letplace'.


Michael.

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[John Wiegley]

>>>>> Michael Heerdegen <michael_heerdegen@web.de> writes:

> Do you really think we should add a comment like that to the code? To
> understand the definition, it's better to have a look at gv.el. After having
> had a look, such a comment is not necessary anymore, since we have a more or
> less trivial usage of `gv-letplace'.

Well, some comment would have been nice; compare Eli's reaction, knowing he's
a well seasoned Elisp developer. At the very least, a docstring that makes it
obvious what the code is intending to accomplish. And `gv-letplace' is still a
name that should be changed. Maybe `let-getf-setf'?

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Michael Heerdegen]

John Wiegley <jwiegley@gmail.com> writes:


> Well, some comment would have been nice; compare Eli's reaction,
> knowing he's a well seasoned Elisp developer. At the very least, a
> docstring that makes it obvious what the code is intending to
> accomplish.

Of course, I just wanted to wait with the docstring until I'm sure all
agree with the semantic.

> And `gv-letplace' is still a name that should be changed.

Ok.

> Maybe `let-getf-setf'?

Mmh. `getf' is also the name of a property list thing.  `setf' also
doesn't fit so well...

How about `gv-let-accessors'?


Michael.

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Michael Heerdegen]

Michael Heerdegen <michael_heerdegen@web.de> writes:

> How about `gv-let-accessors'?

Though, if we want to name the macro according to the type of input
object (like `let-alist'), "letplace" is a quite canonical name.


Michael.

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[John Wiegley]

>>>>> Michael Heerdegen <michael_heerdegen@web.de> writes:

> Though, if we want to name the macro according to the type of input object
> (like `let-alist'), "letplace" is a quite canonical name.

Ok, then maybe 2 of us understand it now. :)

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[John Wiegley]

[-- Attachment #1: Type: text/plain, Size: 638 bytes --]

>>>>> John Wiegley <johnw@gnu.org> writes:

> Well, some comment would have been nice; compare Eli's reaction, knowing
> he's a well seasoned Elisp developer. At the very least, a docstring that
> makes it obvious what the code is intending to accomplish. And `gv-letplace'
> is still a name that should be changed. Maybe `let-getf-setf'?

It finally occurred to me that gv.el should really be called place.el, and
gv-letplace should just be `place-let'. What do you think?

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 629 bytes --]

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Stefan Monnier]

> It finally occurred to me that gv.el should really be called place.el, and
> gv-letplace should just be `place-let'. What do you think?

I haven't looked at the ramifications of such a change, but it sounds
good to me (too bad you didn't come up with it earlier, so as to avoid
the pain of renaming a feature introduced several versions ago).


        Stefan

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[John Wiegley]

>>>>> Stefan Monnier <monnier@iro.umontreal.ca> writes:

> I haven't looked at the ramifications of such a change, but it sounds good
> to me (too bad you didn't come up with it earlier, so as to avoid the pain
> of renaming a feature introduced several versions ago).

Yes, it had to wait until a discussion on the joy of places at the recent
Emacs Hackathon. I'll put it on my list to make this change on master toward
26.x.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Do you really think we should add a comment like that to the code?  To
  > understand the definition, it's better to have a look at gv.el.  After
  > having had a look, such a comment is not necessary anymore, since we
  > have a more or less trivial usage of `gv-letplace'.

Then maybe the comment should say that.

Anything that will help a fair fraction of readers understand the code
is a useful comment.  One might discuss just what is the best thing for
a comment to say, but uncertainty about that point does not mean it
is better not to have a comment.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

Re: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Michael Heerdegen]

John Wiegley <jwiegley@gmail.com> writes:

> >> > (defmacro alist-put (key value place &optional default remove)
> >> >   (gv-letplace (_ setter) `(alist-get ,key ,place ,default ,remove)
> >> >     (funcall setter value)))

> I hear you.  For that code above, the comment would be:
>
>     Given an expression -- in this case, `alist-get' applied to the
>     arguments passed to this macro -- find the `setter' that can
>     "modify in place" the object returned by that expression, and
>     immediately use it to replace that object with the value passed by
>     the caller.

Not quite, or at least imprecise: SETTER is a function that is called
with an expression, and returns the code that does what you describe.

Note that there is no backquote used in the above definition of
`alist-put'.

So, strictly speaking, the name "setter" is not 100% correct.


Michael.

RE: emacs-25 2460cfa: * doc/lispref/lists.texi (Association Lists): Document 'alist-get'.

[Drew Adams]

> I still think the typical Emacs user will ask himself: "Where is
> alist-put?".  Don't you think (info "(elisp) Association Lists") should
> answer this question?

Maybe create an `alist-put' that is an appropriate alias?