GNU bug report logs - #43836
27.1; Doc string of `alist-get'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 43836 in the body.
You can then email your comments to 43836 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 27.1; Doc string of `alist-get'
Date: Tue, 6 Oct 2020 12:26:40 -0700 (PDT)

The doc string is less clear in 27.1 than it was in 26.3.

Instead of saying that a generalized variable is involved, it says:

  You can use `alist-get' in PLACE expressions.  This will modify
  an existing association (more precisely, the first one if
  multiple exist), or add a new element to the beginning of ALIST,
  destructively modifying the list stored in ALIST.

A user can a least look up "generalized variable" in Emacs 26.  The
Emacs 27 version just refers to "PLACE expressions", which is unclear
and can't be looked up easily.  And why is PLACE uppercase, which
indicates that it's something in the calling sequence or is otherwise
defined in the doc string somehow?

It's also not clear how _adding_ a new element to the beginning of ALIST
destructively modifies it.  Does it really mean setting the car of ALIST
to a different element, not adding an element?

Message #8 received at 43836 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 43836 <at> debbugs.gnu.org
Subject: Re: bug#43836: 27.1; Doc string of `alist-get'
Date: Wed, 07 Oct 2020 04:51:40 +0200

Drew Adams <drew.adams <at> oracle.com> writes:

> The doc string is less clear in 27.1 than it was in 26.3.
>
> Instead of saying that a generalized variable is involved, it says:
>
>   You can use `alist-get' in PLACE expressions.  This will modify
>   an existing association (more precisely, the first one if
>   multiple exist), or add a new element to the beginning of ALIST,
>   destructively modifying the list stored in ALIST.
>
> A user can a least look up "generalized variable" in Emacs 26.  The
> Emacs 27 version just refers to "PLACE expressions", which is unclear
> and can't be looked up easily.  And why is PLACE uppercase, which
> indicates that it's something in the calling sequence or is otherwise
> defined in the doc string somehow?

I've now reintroduced "generalized variable" and downcased PLACE in
Emacs 28.

> It's also not clear how _adding_ a new element to the beginning of ALIST
> destructively modifies it.  Does it really mean setting the car of ALIST
> to a different element, not adding an element?

The example that follows on clarifies what's meant here.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #15 received at 43836 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 43836 <at> debbugs.gnu.org
Subject: RE: bug#43836: 27.1; Doc string of `alist-get'
Date: Tue, 6 Oct 2020 21:29:17 -0700 (PDT)

> > It's also not clear how _adding_ a new element to the beginning of ALIST
> > destructively modifies it.  Does it really mean setting the car of ALIST
> > to a different element, not adding an element?
> 
> The example that follows on clarifies what's meant here.

Not really.  Not clear to me what's meant.

The first example adds (b . 2) to the front of the
alist.  OK.  But does it destructively modify the
list?  Or does `foo' just point to a new list (new
cons) whose cdr is the old list?

(I'm sure that some operations with `alist-get' do
modify list structure.  But I don't see how adding
an element to the front of the list does that.)

And how do you add an element (b . 3) to the front
of an alist that has an element (b . 2)?  An alist
can have multiple elements with the same key.

Sorry, but just what the behavior is for a place
expression that uses `alist-get' isn't clear to me
from that doc string, at all.

I have the same questions for the description at
(elisp) `Association Lists'.

This is apparently a useful function, and a bit
complex.  I suspect the doc isn't doing it justice,
but not understanding the actual behavior I can
only wonder.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.