From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Eric Abrahamsen Newsgroups: gmane.emacs.bugs Subject: bug#34708: alist-get has unclear documentation Date: Fri, 15 Mar 2019 11:48:31 -0700 Message-ID: <87wol09dog.fsf@ericabrahamsen.net> References: <87y35xdu4w.fsf@web.de> <87mumcdu7f.fsf@web.de> <875zsyhakx.fsf@ericabrahamsen.net> <87fts2h9we.fsf@web.de> <871s3mh85d.fsf@ericabrahamsen.net> <874l8iebyz.fsf@web.de> <878sxui7bo.fsf@ericabrahamsen.net> <87va0xcxco.fsf@web.de> <87h8chey12.fsf@ericabrahamsen.net> <60367f47-c0b0-45b4-8ccf-169044400a75@default> <8736ntmsy3.fsf@web.de> <3af3b645-84e0-4208-be48-810e8cd2cfa8@default> <87a7i01bk0.fsf@web.de> <871s3c14s9.fsf@web.de> <5fac8365-68d2-4cc5-b5c3-d2658350ea28@default> <87imwoyo2b.fsf@web.de> <87a7hwqgj8.fsf@web.de> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="149120"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) Cc: 34708@debbugs.gnu.org To: Michael Heerdegen Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Mar 15 19:50:15 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1h4ruI-000cgP-OF for geb-bug-gnu-emacs@m.gmane.org; Fri, 15 Mar 2019 19:50:14 +0100 Original-Received: from localhost ([127.0.0.1]:59954 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h4ruH-0000vw-R9 for geb-bug-gnu-emacs@m.gmane.org; Fri, 15 Mar 2019 14:50:13 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:34565) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h4rt9-0000KU-Nl for bug-gnu-emacs@gnu.org; Fri, 15 Mar 2019 14:49:05 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1h4rt8-0000k9-K1 for bug-gnu-emacs@gnu.org; Fri, 15 Mar 2019 14:49:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:60199) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1h4rt8-0000jo-36 for bug-gnu-emacs@gnu.org; Fri, 15 Mar 2019 14:49:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1h4rt7-000804-KP for bug-gnu-emacs@gnu.org; Fri, 15 Mar 2019 14:49:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eric Abrahamsen Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 15 Mar 2019 18:49:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 34708 X-GNU-PR-Package: emacs Original-Received: via spool by 34708-submit@debbugs.gnu.org id=B34708.155267572130722 (code B ref 34708); Fri, 15 Mar 2019 18:49:01 +0000 Original-Received: (at 34708) by debbugs.gnu.org; 15 Mar 2019 18:48:41 +0000 Original-Received: from localhost ([127.0.0.1]:45510 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1h4rsn-0007zQ-1B for submit@debbugs.gnu.org; Fri, 15 Mar 2019 14:48:41 -0400 Original-Received: from ericabrahamsen.net ([52.70.2.18]:45334 helo=mail.ericabrahamsen.net) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1h4rsk-0007zC-VL for 34708@debbugs.gnu.org; Fri, 15 Mar 2019 14:48:39 -0400 Original-Received: from localhost (75-172-122-141.tukw.qwest.net [75.172.122.141]) (Authenticated sender: eric@ericabrahamsen.net) by mail.ericabrahamsen.net (Postfix) with ESMTPSA id 9C649FA17F; Fri, 15 Mar 2019 18:48:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ericabrahamsen.net; s=mail; t=1552675713; bh=jkOmbHcREOSlkCesSbpcQluofWxhCnfIJZjNd7eJYjc=; h=From:To:Cc:Subject:References:Date:In-Reply-To:From; b=vfS9OaWzkM7rB31vaL/iehQgrWwXOjjW0zxnrhV/t+DSbn+TrUoaDJQcXnFvvH1N6 oVPWhbBJk5yO/Gvee5NWtq4VsU3AIQMjzpEVAdbsuPOn9AmcHgK0jxFwWG9vCj+DWr 0xtRlObYyz9NvAWq/cMto6yvK3hsEVFiofte4rDI= In-Reply-To: <87a7hwqgj8.fsf@web.de> (Michael Heerdegen's message of "Fri, 15 Mar 2019 16:54:51 +0100") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:156396 Archived-At: Michael Heerdegen writes: > Michael Heerdegen writes: > >> Actually, it's not even trivial at all. Setting alist-get as place >> could also build a new alist, leaving the one stored in the ALIST place >> intact, and set place ALIST to the new list. But it potentially >> modifies the list stored in place ALIST. That's not inevitable, so it >> could be worth telling that. > > I tried that - see the draft at the end of the message. And I tried to > cover everything that has been noted here to some degree while still > keeping the docstring fluent and at an acceptable length. > > I did not touch the manual, maybe someone else wants to give that a try? > > From 3b8ef1ee9d9a5001e2de930ec34e3bdd3d4f87ad Mon Sep 17 00:00:00 2001 > From: Michael Heerdegen > Date: Tue, 12 Mar 2019 15:13:55 +0100 > Subject: [PATCH] WIP: Improve documentation of alist-get > > (Bug#34708)... > --- > lisp/subr.el | 26 ++++++++++++++++++++++++-- > 1 file changed, 24 insertions(+), 2 deletions(-) > > diff --git a/lisp/subr.el b/lisp/subr.el > index 4024c68e68..8ea8fb602c 100644 > --- a/lisp/subr.el > +++ b/lisp/subr.el > @@ -756,9 +756,31 @@ alist-get > If KEY is not found in ALIST, return DEFAULT. > Use TESTFN to lookup in the alist if non-nil. Otherwise, use `assq'. > > -This is a generalized variable suitable for use with `setf'. > +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. > + > +Example: > + > + (setq foo '((a . 0))) > + (setf (alist-get 'a foo) 1 > + (alist-get 'b foo) 2) > + > + foo ==> ((b . 2) (a . 1)) > + > + > When using it to set a value, optional argument REMOVE non-nil > -means to remove KEY from ALIST if the new value is `eql' to DEFAULT." > +means to remove KEY from ALIST if the new value is `eql' to > +DEFAULT (more precisely the first found association will be > +deleted from the alist). > + > +Example: > + > + (setq foo '((a . 1) (b . 2))) > + (setf (alist-get 'b foo nil 'remove) nil) > + > + foo ==> ((a . 1))" > (ignore remove) ;;Silence byte-compiler. > (let ((x (if (not testfn) > (assq key alist) I like it! Thanks for your work on this.