From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#27584: 26.0.50; alist-get: Add optional arg TESTFN Date: Fri, 07 Jul 2017 10:46:55 +0300 Message-ID: <838tk0n0y8.fsf@gnu.org> References: <87tw2rva7v.fsf@calancha-pc> <87mv8j6y1z.fsf@petton.fr> <87y3s2m76v.fsf@calancha-pc> <8737a83fq6.fsf@calancha-pc> Reply-To: Eli Zaretskii NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1499413731 31100 195.159.176.226 (7 Jul 2017 07:48:51 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Fri, 7 Jul 2017 07:48:51 +0000 (UTC) Cc: nicolas@petton.fr, 27584@debbugs.gnu.org, monnier@IRO.UMontreal.CA To: Tino Calancha Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Jul 07 09:48:42 2017 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dTO0E-0007NR-Pc for geb-bug-gnu-emacs@m.gmane.org; Fri, 07 Jul 2017 09:48:38 +0200 Original-Received: from localhost ([::1]:55025 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dTO0H-00032S-3i for geb-bug-gnu-emacs@m.gmane.org; Fri, 07 Jul 2017 03:48:41 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:34336) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dTNzi-0002kJ-15 for bug-gnu-emacs@gnu.org; Fri, 07 Jul 2017 03:48:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dTNze-0002UU-SI for bug-gnu-emacs@gnu.org; Fri, 07 Jul 2017 03:48:06 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:53031) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dTNze-0002UK-OS for bug-gnu-emacs@gnu.org; Fri, 07 Jul 2017 03:48:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1dTNze-0007Ki-GP for bug-gnu-emacs@gnu.org; Fri, 07 Jul 2017 03:48:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 07 Jul 2017 07:48:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 27584 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 27584-submit@debbugs.gnu.org id=B27584.149941365028152 (code B ref 27584); Fri, 07 Jul 2017 07:48:02 +0000 Original-Received: (at 27584) by debbugs.gnu.org; 7 Jul 2017 07:47:30 +0000 Original-Received: from localhost ([127.0.0.1]:55708 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dTNz8-0007Jz-8p for submit@debbugs.gnu.org; Fri, 07 Jul 2017 03:47:30 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:43177) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dTNz6-0007Jm-A2 for 27584@debbugs.gnu.org; Fri, 07 Jul 2017 03:47:28 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dTNyx-0002By-VO for 27584@debbugs.gnu.org; Fri, 07 Jul 2017 03:47:23 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:36790) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dTNyo-00029J-Ay; Fri, 07 Jul 2017 03:47:10 -0400 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:4076 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1dTNym-0004m2-8Z; Fri, 07 Jul 2017 03:47:09 -0400 In-reply-to: <8737a83fq6.fsf@calancha-pc> (message from Tino Calancha on Fri, 07 Jul 2017 15:48:01 +0900) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] 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: 208.118.235.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:134293 Archived-At: > From: Tino Calancha > Date: Fri, 07 Jul 2017 15:48:01 +0900 > Cc: Nicolas Petton , > Stefan Monnier Thanks. A few comments about the documentation parts: > -@defun alist-get key alist &optional default remove > -This function is like @code{assq}, but instead of returning the entire > +@defun alist-get key alist &optional default remove testfn > +This function is like @code{assq} when @var{testfn} is @code{nil}, > +but instead of returning the entire > association for @var{key} in @var{alist}, > @w{@code{(@var{key} . @var{value})}}, it returns just the @var{value}. > +When @var{testfn} is non-@code{nil}, it returns @var{value} if @var{key} > +is equal to the car of an element of @var{alist}. The equality is > +tested with @var{testfn}. > If @var{key} is not found in @var{alist}, it returns @var{default}. Sometimes, trying to make small changes to existing documentation makes the documentation less readable and even confusing. This is one of those cases: where previously alist-get was only a minor deviation from assq, and thus just mentioning those deviations would do, now the deviations are much more significant, and the reference to assq gets in the way instead of helping. So I would rewrite the documentation like this: @defun alist-get key alist &optional default remove testfn This function is similar to @code{assq}. It finds the first association @w{@code{(@var{key} . @var{value})}} by comparing @var{key} with @var{alist} elements, and, if found, returns the @var{value} of that association. If no association is found, the function returns @var{default}. Comparison of @var{key} against @var{alist} elements uses the function specified by @var{testfn}, defaulting to @code{eq}. The return value is a generalized variable (@pxref{Generalized Variables}) that can be used to change a value with @code{setf}. When using it to set a value, optional argument @var{remove} non-@code{nil} means to remove @var{key}'s association from @var{alist} if the new value is @code{eql} to @var{default}. @end defun > -@defun assoc-default key alist &optional test default > +@defun assoc-default key alist &optional test default full > This function searches @var{alist} for a match for @var{key}. For each > element of @var{alist}, it compares the element (if it is an atom) or > the element's @sc{car} (if it is a cons) against @var{key}, by calling > @@ -1652,7 +1656,8 @@ Association Lists > > If an alist element matches @var{key} by this criterion, > then @code{assoc-default} returns a value based on this element. > -If the element is a cons, then the value is the element's @sc{cdr}. > +If the element is a cons, then the value is the element if @var{full} > +is non-@code{nil}, or the element's @sc{cdr} if @var{full} is @code{nil}. Suggest to simplify: If the element is a cons, then the value is the element's @sc{cdr} if @var{full} is @code{nil} or omitted, or the entire element otherwise. > -(defun map-elt (map key &optional default) > +(defun map-elt (map key &optional default testfn) > "Lookup KEY in MAP and return its associated value. > If KEY is not found, return DEFAULT which defaults to nil. > > -If MAP is a list, `eql' is used to lookup KEY. > +If MAP is a list, TESTFN is used to lookup KEY if non-nil or `eql' if nil. Since the sentence references more than one argument, the "or `eql' if nil" part is ambiguous. Suggest to disambiguate: If MAP is a list, `eql' is used to lookup KEY. Optional argument TESTFN, if non-nil, means use its function definition instead of `eql'. > -(defmacro map-put (map key value) > +(defmacro map-put (map key value &optional testfn) > "Associate KEY with VALUE in MAP and return VALUE. > If KEY is already present in MAP, replace the associated value > with VALUE. > +When MAP is a list, test equality with TESTFN if non-nil, otherwise use `eql'. Likewise here. > -(defun assoc-default (key alist &optional test default) > +(defun assoc-default (key alist &optional test default full) > "Find object KEY in a pseudo-alist ALIST. > ALIST is a list of conses or objects. Each element > (or the element's car, if it is a cons) is compared with KEY by > calling TEST, with two arguments: (i) the element or its car, > and (ii) KEY. > If that is non-nil, the element matches; then `assoc-default' > - returns the element's cdr, if it is a cons, or DEFAULT if the > - element is not a cons. > + returns the element, if it is a cons and FULL is non-nil, > + or the element's cdr, if it is a cons and FULL is nil, ^^ That "it" is ambiguous: does it refer to "element" or to "cdr"? > -(defun alist-get (key alist &optional default remove) > - "Return the value associated with KEY in ALIST, using `assq'. > +(defun alist-get (key alist &optional default remove testfn) > + "Return the value associated with KEY in ALIST. > If KEY is not found in ALIST, return DEFAULT. > +Use TESTFN to lookup in the alist if non-nil. Otherwise, use `assq'. Again, "if non-nil" is ambiguous: it could refer to TESTFN or to alist. > +@defun assoc-predicate key alist &optional pred > +This function is like @code{assoc} in that it returns the first > +association for @var{key} in @var{alist}, but if @code{pred} is > +non-@code{nil}, then it makes the comparison using @code{pred} > +instead of @code{equal}. @code{assoc-predicate} returns @code{nil} > +if no association in @var{alist} has a @sc{car}, @var{x}, satisfying > +@code{(funcall pred x key)}. ^^^^^^^^^^^^^^^^^^ "pred", "x", and "key" should be in @var here. I'd also include the entire @code snippet in @w{..}, so that it won't be split between two lines. > ++++ > +** New defun 'assoc-predicate', like 'assoc' with an optional argument > +PRED, a predicate to compare the elements in the alist. Please use "function" in NEWS, not "defun". > +(defun assoc-predicate (key alist &optional pred) > + "Like `assoc' but compare keys with TEST." ^^^^ PRED, not TEST. Thanks.