bug#34708: alist-get has unclear documentation

[Drew Adams <drew.adams@oracle.com>]

> > If so, is `eql' really appropriate for most such cases (which are
> > quite common)?
> >
> > And even for `(a . (1 2))', aka `(a 1 2)', is `eql' appropriate?
> > Since the cdr of a list is more typically a list, why would we choose
> > `eql' as the default value-comparison predicate?  To compare lists the
> > default predicate should be `equal' (or possibly but not likely `eq'),
> > no?
> 
> Yes, in these cases eql is not useful.

But they are the more common cases, I expect.
The cdr of a list is typically a list, not an
atom.

And even for the elements of an alist I expect
that is more typical: a list of values (as VALUE
of a KEY) is more general and typically more
useful than a single, atomic value.

If this is the case then it's an argument for
the default being set to `equal', not `eql'.

> > > > > (2) The remove feature has a strange corner case.  Normally the
> > > > > first found association is removed,
> > > >
> > > > So "normally" it's really "remove one".
> > > >
> > > > Why is this?  What's the point of REMOVE - why is
> > > > it needed (added to the design) at all?  Is it to
> > > > provide a way to remove all entries with a given
> > > > key or only the first such?
> > >
> > > The first.
> >
> > Then why did (does?) the doc say "if the new value
> > is `eql' to DEFAULT"?  It sounds like it removes
> > only the entries with a given key AND a given value.
> 
> It removes the first entry with given KEY and value eql DEFAULT.

[FYI: "The first such", above, meant the first
entry with a given key - "such" refers to
"entries with a given key".  It doesn't mean the
first entry with a given key and value.  I guess
I should have made that more explicit.]

My question in that case is why REMOVE is made
to work this way?  Normally, alist element
lookup/identification is by key only (or value
only).  To look up both key and value it's
`member', not `assoc' (or `rassoc').

That's an operation on general list elements;
it's not so much an alist operation.  Why is
removing an association different in this
regard from adding or changing an association?
Why does it need both key and value?

I'm still having trouble grasping the point of
having REMOVE in this construct.  Seems like a
ball of confusion and behavior not specifically
related to alists.

> > Anyway, if that's all REMOVE does (removes all
> > occurrences), and if it can be a predicate, then it
> > sounds like it just does `cl-delete-if'.
> >
> > If so, what's an example of why/when someone would
> > want to use `setf' and `alist-get' to remove entries,
> > as opposed to just using `cl-delete-if'?
> 
> You can also cl-delete-if, yes, there semantics overlap.  OTOH
> cl-delete-if doesn't support generalized variables.

At any rate, that example was predicated on my wrong
guess that REMOVE removes all, not just the first,
identified instance, which you've now clarified
is not the case.

> > Then isn't it a bit misleading for the function name
> > and doc to suggest that this is a general way of using
> > alists?
> 
> I don't get that impression from the doc.  For the name: what else would
> you suggest?  This _is_ the general way of getting associations from an
> alist.  You can also use it in place expressions where it is convenient,
> you don't have to, of course.  It's in the nature of place expressions
> that there use is a bit limited compared to what you could do with
> general lisp.  I see no problem here.

I find it misleading, but people can see things
differently.

Getting an association by both key and value
is _not_ the general way of getting an alist
association.  Getting it by key only is the
usual way.  Getting it by value only is another,
less common way.

`alist-get' by itself seems to act normally wrt
alists.  But its use with `setf' and REMOVE
doesn't seem, to me, to reflect the usual alist
manipulation.
 
> > So far, I guess I don't see the use case for making it a generalized
> > variable.  It's easy enough to set alist values, and doing so with
> > `setf' and `alist-get' sounds more complicated, not less.
> >
> > For getting, I think I get it: folks apparently don't want to get the
> > full element and then dig out the value (cdr) from it.  (Is there more
> > to it than that?)  For setting and removing, I don't get the
> > advantage, so far.
> 
> You only seem to think of one case: I have a variable x which holds an
> alist which I want to manipulate.  There are more cases: the alist place
> could be a real nontrivial place.

How is that a different case?  But maybe I
don't have understand what you have in mind
by a real nontrivial place.  Presumably
you're talking about an alist with complex
elements?  How does that change things? Could
you give an example that shows what you mean?

> And you can not only use setf on
> alist-get places, but all macros that handle places, e.g. incf or callf
> or letf or ...  There are surely cases where using alist-get in a place
> expression can be handy.  Nowhere is said that you should use alist-get
> only and always when dealing with alists, especially for manipulation.

OK.  An example would still help.  The `setf'
examples we've seen so far don't seem very
helpful, to me.  But maybe an example with
some other `*f' place-manipulation functions
would help understanding.

I think it's mostly REMOVE that bothers me.
I expect an alist "place" operation to set
(create or update) an alist entry, not to
remove an entry, and especially not by
specifying that entry by both key and value.

> > > One thing I don't find consistent is the case where the alist already
> > > has multiple occurrences of a key.  E.g.
> > >
> > > (setq my-alist '((a . 1) (b . 2) (a . -1)))
> > > (setf (alist-get 'a my-alist 1 'remove) 1)
> > > my-alist ==> ((b . 2) (a . -1))
> > >
> > > (alist-get 'a my-alist 1)
> > >   ==> -1    (!)
> > >
> > > One would expect 1, of course.
> >
> > Why?  The doc says that it returns DEFAULT only
> > if KEY is not found in ALIST.  But entry (a . -1)
> > finds `a' associated with -1.  What am I missing?
> 
> Think from the viewpoint of places: I have set the place to 1.  Then I
> expect that I get 1 when evaluating the place expression afterwards.

You have _not_ set the place to 1, have you?
The second 1, combined with REMOVE, doesn't
set the place at all, does it?  Doesn't REMOVE
just remove the place altogether?

I think that the REMOVE "feature" gets in the
way of understanding here.  I think you're
agreeing, in a sense, by saying that the sexp
gives the _impression_ that it sets the place
to 1 without actually doing so.  No?

> > `alist-get' specifies an alist entry (a single one, BTW).  `setf' of
> > `alist-get' should set/create an alist entry (a single one, BTW).
> > Otherwise, we're abusing the intention of one or both of these
> > "functions".  No?
> 
> I indeed see that point different, yes.  The remove syntax when using it
> as a place is not super sexy (no one says you have to use it for that
> btw), but I don't see what you write as a requirement.  When not using
> REMOVE it's all very straightforward in my opinion.

Let's consider just REMOVE then.