bug-gnu-emacs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

bug#23548: 25.0.93; lists.texi (alist-get): Document optional arg 'remov


From: Tino Calancha
Subject: bug#23548: 25.0.93; lists.texi (alist-get): Document optional arg 'remove'.
Date: Tue, 17 May 2016 02:07:21 +0900 (JST)
User-agent: Alpine 2.20 (LRH 67 2015-01-07)



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 <address@hidden>
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

address@hidden alist-get key value &optional default
address@hidden 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 address@hidden and @var{default} is @code{eql}
+to @var{new-val}, then the entry at @var{key} is deleted.
+
+For example:
+
address@hidden
+(let ((myalist '((a . 1) (b . 2) (c . 3))))
+  (setf (alist-get 'a myalist 1 'remove) 1)
+  myalist)
address@hidden ((b . 2) (c . 3))
address@hidden smallexample
 @end defun

 @defun rassq value alist
--
2.8.1






reply via email to

[Prev in Thread] Current Thread [Next in Thread]