From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Michael Heerdegen Newsgroups: gmane.emacs.bugs Subject: bug#34708: alist-get has unclear documentation Date: Fri, 15 Mar 2019 16:54:51 +0100 Message-ID: <87a7hwqgj8.fsf@web.de> 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> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="211709"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) Cc: Eric Abrahamsen , 34708@debbugs.gnu.org To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Mar 15 17:05:09 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 1h4pKW-000svc-Jj for geb-bug-gnu-emacs@m.gmane.org; Fri, 15 Mar 2019 17:05:08 +0100 Original-Received: from localhost ([127.0.0.1]:57984 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h4pKV-0001gE-G8 for geb-bug-gnu-emacs@m.gmane.org; Fri, 15 Mar 2019 12:05:07 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:35440) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h4pGJ-0006Qk-TS for bug-gnu-emacs@gnu.org; Fri, 15 Mar 2019 12:00:50 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1h4pBj-0006mW-0n for bug-gnu-emacs@gnu.org; Fri, 15 Mar 2019 11:56:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:60077) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1h4pBi-0006l5-Ao for bug-gnu-emacs@gnu.org; Fri, 15 Mar 2019 11:56:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1h4pBh-0006rm-Tx for bug-gnu-emacs@gnu.org; Fri, 15 Mar 2019 11:56:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Michael Heerdegen Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 15 Mar 2019 15:56: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.155266531226326 (code B ref 34708); Fri, 15 Mar 2019 15:56:01 +0000 Original-Received: (at 34708) by debbugs.gnu.org; 15 Mar 2019 15:55:12 +0000 Original-Received: from localhost ([127.0.0.1]:45388 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1h4pAu-0006qX-9P for submit@debbugs.gnu.org; Fri, 15 Mar 2019 11:55:12 -0400 Original-Received: from mout.web.de ([212.227.15.4]:50259) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1h4pAs-0006qF-GG for 34708@debbugs.gnu.org; Fri, 15 Mar 2019 11:55:11 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=web.de; s=dbaedf251592; t=1552665292; bh=cCbssR1X9BPW8GOl4XAIORrUZtfNlYZrtimAM8G/rq4=; h=X-UI-Sender-Class:From:To:Cc:Subject:References:Date:In-Reply-To; b=TBHMvnMKRWFlDdh3rJZWq6EMzpBtSZyXJNL0JbkA+DWGYFqQ1+rq80h9YRWVuycB1 xHC9DEQZONrRcsRzPT2W+sWu3af0M/JQglRlLK7rb36FEP0pNjlniCk3dmF4CQhQMF QzLk62pVvOJDn6fNv3HwAul51DPiMyY0DOdLS8xw= X-UI-Sender-Class: c548c8c5-30a9-4db5-a2e7-cb6cb037b8f9 Original-Received: from drachen.dragon ([88.67.111.211]) by smtp.web.de (mrweb001 [213.165.67.108]) with ESMTPSA (Nemesis) id 0Lcgp5-1gebIy3HQl-00k4n6; Fri, 15 Mar 2019 16:54:51 +0100 In-Reply-To: <87imwoyo2b.fsf@web.de> (Michael Heerdegen's message of "Tue, 12 Mar 2019 18:55:56 +0100") X-Provags-ID: V03:K1:eWk6V79O8K1gvVFEXtvRnyNgBlKZSsamFU/IF/HWfxBM8o8eQ4I HeSNE+zJxt0xb/leEZMpXrz2jWT5rihpVsNlpCG/XTF4zebHNc7LyNvpHFQw+2s5DAS7z3I w8eCYhKalKMNTEYdr6kaeEdnZZp9a9VByaZtJ5gHZGP0JwXKQFBWkQSFgxjJuTVJzAlI1wp qF8kNsxKD7dzb+7m+Kqqw== X-UI-Out-Filterresults: notjunk:1;V03:K0:lwuxjejYFFg=:PHlpPtGyyg4GbxqbKPzvki oiIsH2OowEamCWvodvGOGS/dolhOODCQJa31Yf0eVql0U8SeYQQWUhIae8kutnpXY20/QrJgv mFaSJQMEeVrhY120mDmkBykkejndywWbQuOdcOIIv8gKhCPmEfRdwZFYAtkxlBNira052TCpF Bfef/baFnq3t1IOEfTsXX4hN4wpYOFzsJPavbQZQcVLZTE4lugUo9zqsOZJAir3AJwKl8FH1J DOb8V3q5f0jwbeiNvP1+NkfKTJEebROVUI5Jonc7OszaCkKXxfRRqNO6RHnO55BjuBpRQdhBy 8/ZGzpYEv4cu9qz5kg5j7T00h4NHfdhITDH+5YvqR0icHJB7Szennqns8kqerY4zKsviGfxX4 cBSYGFgx6tnm2iX+alClNrIBnNLpio+I+GeI2XIMz9pft5GKwCoI4Au6Ig8duoBTKrnEgY5ro bhn/Kf7ftIAu3DkkG/qEE3HOxZG9sBEcTQRdaFdQqipL0UpQBfSExKSODYt03QireiuNZXtuD yXMlEPDUUHdPyRbAfoZ71RfwNaD6wbDTZK1cI/28S24+rSBazWLdP/97Bg+upp3bQY5ildOpZ dlO+YpMl3B11eQwuuVm78MsKNh2qjUuBms76vysGfb1m+Rkz15dXSj4bZ+WQVb/0D35c60hId dXVDxVUut9sdYex0r5YIPrX+BF2iQnKKe6ZZb/ziRt3Z/VU9W6ld5AVZ1jrVCoPFI/LFSdlMI g7u51s0Wg0DZU+rki2OtDOR97842PfKSRlWPAvuZZcoGaUwDhl1UwcaRqA8BIrQu7bTguPRq 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:156389 Archived-At: --=-=-= Content-Type: text/plain 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? --=-=-= Content-Type: text/x-diff Content-Disposition: inline; filename=0001-WIP-Improve-documentation-of-alist-get.patch Content-Transfer-Encoding: quoted-printable =46rom 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)... =2D-- 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 =2D-- 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 =3D=3D> ((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 =3D=3D> ((a . 1))" (ignore remove) ;;Silence byte-compiler. (let ((x (if (not testfn) (assq key alist) =2D- 2.20.1 --=-=-= Content-Type: text/plain Michael. --=-=-=--