From debbugs-submit-bounces@debbugs.gnu.org Mon May 16 10:10:34 2016 Received: (at submit) by debbugs.gnu.org; 16 May 2016 14:10:34 +0000 Received: from localhost ([127.0.0.1]:53848 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1b2JE9-0005UE-Sn for submit@debbugs.gnu.org; Mon, 16 May 2016 10:10:34 -0400 Received: from eggs.gnu.org ([208.118.235.92]:47669) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1b2JE9-0005U3-0x for submit@debbugs.gnu.org; Mon, 16 May 2016 10:10:33 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1b2JDz-0004pO-SS for submit@debbugs.gnu.org; Mon, 16 May 2016 10:10:27 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00,FREEMAIL_FROM autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:43874) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1b2JDz-0004pE-Ou for submit@debbugs.gnu.org; Mon, 16 May 2016 10:10:23 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:38604) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1b2JDx-0004ZY-Pa for bug-gnu-emacs@gnu.org; Mon, 16 May 2016 10:10:22 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1b2JDt-0004nh-FZ for bug-gnu-emacs@gnu.org; Mon, 16 May 2016 10:10:20 -0400 Received: from calancha-ilc.kek.jp ([130.87.234.234]:60076) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1b2JDt-0004nE-5Q for bug-gnu-emacs@gnu.org; Mon, 16 May 2016 10:10:17 -0400 Received: by calancha-ilc.kek.jp (Postfix, from userid 500) id 2A1F55942; Mon, 16 May 2016 23:13:35 +0900 (JST) Received: from localhost (localhost [127.0.0.1]) by calancha-ilc.kek.jp (Postfix) with ESMTP id 110815530 for ; Mon, 16 May 2016 23:13:35 +0900 (JST) Date: Mon, 16 May 2016 23:13:35 +0900 (JST) From: Tino Calancha X-X-Sender: calancha@calancha-ilc.kek.jp To: bug-gnu-emacs@gnu.org Subject: 25.0.93; lists.texi (alist-get): Document optional arg 'remove'. Message-ID: User-Agent: Alpine 2.20 (LRH 67 2015-01-07) MIME-Version: 1.0 Content-Type: text/plain; format=flowed; charset=US-ASCII X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -4.0 (----) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -4.0 (----) * 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 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 From debbugs-submit-bounces@debbugs.gnu.org Mon May 16 12:20:27 2016 Received: (at 23548) by debbugs.gnu.org; 16 May 2016 16:20:27 +0000 Received: from localhost ([127.0.0.1]:54000 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1b2LFq-0002AU-WF for submit@debbugs.gnu.org; Mon, 16 May 2016 12:20:27 -0400 Received: from eggs.gnu.org ([208.118.235.92]:49183) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1b2LFp-0002AG-Kd for 23548@debbugs.gnu.org; Mon, 16 May 2016 12:20:25 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1b2LFf-0000Um-Fs for 23548@debbugs.gnu.org; Mon, 16 May 2016 12:20:20 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-1.4 required=5.0 tests=BAYES_20,RP_MATCHES_RCVD autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:59592) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1b2LFf-0000UX-D6; Mon, 16 May 2016 12:20:15 -0400 Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:2348 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1b2LFX-0007xg-LZ; Mon, 16 May 2016 12:20:14 -0400 Date: Mon, 16 May 2016 19:20:06 +0300 Message-Id: <8337pi5615.fsf@gnu.org> From: Eli Zaretskii To: Tino Calancha In-reply-to: (message from Tino Calancha on Mon, 16 May 2016 23:13:35 +0900 (JST)) Subject: Re: bug#23548: 25.0.93; lists.texi (alist-get): Document optional arg 'remove'. References: X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -6.4 (------) X-Debbugs-Envelope-To: 23548 Cc: 23548@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Eli Zaretskii Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -6.4 (------) > Date: Mon, 16 May 2016 23:13:35 +0900 (JST) > From: Tino Calancha > > * 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. From debbugs-submit-bounces@debbugs.gnu.org Mon May 16 13:04:12 2016 Received: (at 23548) by debbugs.gnu.org; 16 May 2016 17:04:12 +0000 Received: from localhost ([127.0.0.1]:54050 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1b2LwC-0003FG-H7 for submit@debbugs.gnu.org; Mon, 16 May 2016 13:04:12 -0400 Received: from calancha-ilc.kek.jp ([130.87.234.234]:45233) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1b2LwA-0003F2-9U for 23548@debbugs.gnu.org; Mon, 16 May 2016 13:04:11 -0400 Received: by calancha-ilc.kek.jp (Postfix, from userid 500) id 98B83606E; Tue, 17 May 2016 02:07:21 +0900 (JST) Received: from localhost (localhost [127.0.0.1]) by calancha-ilc.kek.jp (Postfix) with ESMTP id 8049E54B3; Tue, 17 May 2016 02:07:21 +0900 (JST) Date: Tue, 17 May 2016 02:07:21 +0900 (JST) From: Tino Calancha X-X-Sender: calancha@calancha-ilc.kek.jp To: Eli Zaretskii Subject: Re: bug#23548: 25.0.93; lists.texi (alist-get): Document optional arg 'remove'. In-Reply-To: <8337pi5615.fsf@gnu.org> Message-ID: References: <8337pi5615.fsf@gnu.org> User-Agent: Alpine 2.20 (LRH 67 2015-01-07) MIME-Version: 1.0 Content-Type: text/plain; format=flowed; charset=US-ASCII X-Spam-Score: 1.0 (+) X-Debbugs-Envelope-To: 23548 Cc: Tino Calancha , 23548@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 1.0 (+) > 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 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 From debbugs-submit-bounces@debbugs.gnu.org Tue Jun 07 20:00:37 2016 Received: (at 23548-done) by debbugs.gnu.org; 8 Jun 2016 00:00:37 +0000 Received: from localhost ([127.0.0.1]:59267 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bAQvF-0005Go-Gi for submit@debbugs.gnu.org; Tue, 07 Jun 2016 20:00:37 -0400 Received: from eggs.gnu.org ([208.118.235.92]:37766) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bAQvD-0005Gb-Pd for 23548-done@debbugs.gnu.org; Tue, 07 Jun 2016 20:00:36 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bAQv7-0002TR-Vj for 23548-done@debbugs.gnu.org; Tue, 07 Jun 2016 20:00:30 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-3.3 required=5.0 tests=BAYES_00,RP_MATCHES_RCVD autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:59528) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bAQv7-0002TA-Rz for 23548-done@debbugs.gnu.org; Tue, 07 Jun 2016 20:00:29 -0400 Received: from rgm by fencepost.gnu.org with local (Exim 4.82) (envelope-from ) id 1bAQv5-0000h9-MM; Tue, 07 Jun 2016 20:00:27 -0400 From: Glenn Morris To: 23548-done@debbugs.gnu.org Subject: Re: bug#23548: 25.0.93; lists.texi (alist-get): Document optional arg 'remove'. References: X-Spook: airframe AQIM al-Qaida Ammonium nitrate National X-Ran: d=D>[^\Bs/^!!bm5yB`0ZRZLmw!e((DtuB<%HpboxGA]J.[Z?T]|D=u0by.*BlZD'cGPT= X-Hue: white X-Attribution: GM Date: Tue, 07 Jun 2016 20:00:27 -0400 In-Reply-To: (Tino Calancha's message of "Mon, 16 May 2016 23:13:35 +0900 (JST)") Message-ID: User-Agent: Gnus (www.gnus.org), GNU Emacs (www.gnu.org/software/emacs/) MIME-Version: 1.0 Content-Type: text/plain X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -6.4 (------) X-Debbugs-Envelope-To: 23548-done X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -6.4 (------) Version: 25.1 Thanks; I tweaked the docs. From unknown Sun Aug 10 16:48:32 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Wed, 06 Jul 2016 11:24:04 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator