GNU bug report logs - #23548
25.0.93; lists.texi (alist-get): Document optional arg 'remove'.

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 23548 in the body.
You can then email your comments to 23548 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: Tino Calancha <f92capac <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 25.0.93; lists.texi (alist-get): Document optional arg 'remove'.
Date: Mon, 16 May 2016 23:13:35 +0900 (JST)

* doc/lispref/lists.texi (alist-get): Document optional arg. 'remove'.
Rename second argument to 'alist'.


In GNU Emacs 25.0.93.3 (x86_64-pc-linux-gnu, GTK+ Version 2.24.30)
Repository revision: 6de0715f5467d4b925e2dfe082174529ace3b174


From 23f7df037e23c867cfa0090936c9f974e6e83175 Mon Sep 17 00:00:00 2001
From: Tino Calancha <f92capac <at> gmail.com>
Date: Mon, 16 May 2016 23:01:14 +0900
Subject: [PATCH] ; * lists.texi (alist-get): Document optional arg 'remove'.

---
 doc/lispref/lists.texi | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index c18c408..7d411af 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -1556,12 +1556,17 @@ Association Lists
 @end smallexample
 @end defun

-@defun alist-get key value &optional default
+@defun alist-get key alist &optional default remove
 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.
+
+When using this function to set the value at @var{key}
+to @var{new-val}, if @var{remove} evaluates non-@code{nil} and
+@var{default} is @code{eql} to @var{new-val}, then the entry at
+@var{key} is deleted.
 @end defun

 @defun rassq value alist
-- 
2.8.1

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Tino Calancha <f92capac <at> gmail.com>
Cc: 23548 <at> debbugs.gnu.org
Subject: Re: bug#23548: 25.0.93;
 lists.texi (alist-get): Document optional arg 'remove'.
Date: Mon, 16 May 2016 19:20:06 +0300

> Date: Mon, 16 May 2016 23:13:35 +0900 (JST)
> From: Tino Calancha <f92capac <at> gmail.com>
> 
> * doc/lispref/lists.texi (alist-get): Document optional arg. 'remove'.
> Rename second argument to 'alist'.

You renamed it only in the @defun line.  The description still uses
'value', so there's now a disconnect.

> +@defun alist-get key alist &optional default remove
>   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.
> +
> +When using this function to set the value at @var{key}
> +to @var{new-val}, if @var{remove} evaluates non-@code{nil} and
> +@var{default} is @code{eql} to @var{new-val}, then the entry at
> +@var{key} is deleted.

More importantly, I'm sorry to say that this additional text makes no
sense to me.  It just repeats what the doc string says (which also
makes no sense).  You cannot talk about using this function "to set
the value at KEY", without some explaining, because 'alist-get'
doesn't itself set anything, it _gets_ a value of KEY.  Right?

I believe this text needs a much longer and more detailed explanation,
and most probably also an example, to make sense.  (The doc string
could use some more explanations as well.)

Thanks.

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

From: Tino Calancha <f92capac <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Tino Calancha <f92capac <at> gmail.com>, 23548 <at> debbugs.gnu.org
Subject: Re: bug#23548: 25.0.93; lists.texi (alist-get): Document optional
 arg 'remove'.
Date: Tue, 17 May 2016 02:07:21 +0900 (JST)

> You renamed it only in the @defun line.  The description still uses
> 'value', so there's now a disconnect.

> More importantly, I'm sorry to say that this additional text makes no
> sense to me.  It just repeats what the doc string says (which also
> makes no sense).
For me either.  I was following the 'authority principle': someone 
wrote that doc. string because she thought is was clear enough.

You cannot talk about using this function "to set
> the value at KEY", without some explaining, because 'alist-get'
> doesn't itself set anything, it _gets_ a value of KEY.  Right?
Right.  I miss they mention something like: using this function as
PLACE in `setf'.

> I believe this text needs a much longer and more detailed explanation,
> and most probably also an example, to make sense.  (The doc string
> could use some more explanations as well.)
I modified previous patch and added one example.  It may be an start for
getting it more comprehensible.


From 78fa526404c6ea57e42c44423d1bfecef5b45eea Mon Sep 17 00:00:00 2001
From: Tino Calancha <f92capac <at> gmail.com>
Date: Tue, 17 May 2016 01:56:15 +0900
Subject: [PATCH] * lists.texi (alist-get): Document optional arg 'remove'

---
 doc/lispref/lists.texi | 23 ++++++++++++++++++-----
 1 file changed, 18 insertions(+), 5 deletions(-)

diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index c18c408..d9f3d17 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -1556,12 +1556,25 @@ Association Lists
 @end smallexample
 @end defun

-@defun alist-get key value &optional default
+@defun alist-get key alist &optional default remove
 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.
+association for @var{key}, it returns the @sc{cdr}.
+It returns @var{default} if @var{key} is not found in @var{alist},
+defaulting to @code{nil} if @var{default} is omitted.
+
+When using this function in conjunction with @code{setf}
+to set the value of @var{alist} at @var{key} to @var{new-val},
+if @var{remove} evaluates non-@code{nil} and @var{default} is @code{eql}
+to @var{new-val}, then the entry at @var{key} is deleted.
+
+For example:
+
+@smallexample
+(let ((myalist '((a . 1) (b . 2) (c . 3))))
+  (setf (alist-get 'a myalist 1 'remove) 1)
+  myalist)
+@result{} ((b . 2) (c . 3))
+@end smallexample
 @end defun

 @defun rassq value alist
-- 
2.8.1

Message #16 received at 23548-done <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: 23548-done <at> debbugs.gnu.org
Subject: Re: bug#23548: 25.0.93;
 lists.texi (alist-get): Document optional arg 'remove'.
Date: Tue, 07 Jun 2016 20:00:27 -0400

Version: 25.1

Thanks; I tweaked the docs.

Previous Next

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