From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#34708: alist-get has unclear documentation Date: Tue, 5 Mar 2019 16:16:19 -0800 (PST) Message-ID: <60367f47-c0b0-45b4-8ccf-169044400a75@default> References: <87wolhr5k6.fsf@web.de> <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> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="138574"; mail-complaints-to="usenet@blaine.gmane.org" To: Eric Abrahamsen , 34708@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Wed Mar 06 01:17:17 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 1h1KFF-000ZuM-IM for geb-bug-gnu-emacs@m.gmane.org; Wed, 06 Mar 2019 01:17:13 +0100 Original-Received: from localhost ([127.0.0.1]:51459 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h1KFE-00034o-He for geb-bug-gnu-emacs@m.gmane.org; Tue, 05 Mar 2019 19:17:12 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:47627) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h1KF5-00034W-Mb for bug-gnu-emacs@gnu.org; Tue, 05 Mar 2019 19:17:04 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1h1KF4-0005DL-Tf for bug-gnu-emacs@gnu.org; Tue, 05 Mar 2019 19:17:03 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:48307) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1h1KF4-0005C7-Ne for bug-gnu-emacs@gnu.org; Tue, 05 Mar 2019 19:17:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1h1KF4-0006jq-Dw for bug-gnu-emacs@gnu.org; Tue, 05 Mar 2019 19:17:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 06 Mar 2019 00:17:02 +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.155183139525866 (code B ref 34708); Wed, 06 Mar 2019 00:17:02 +0000 Original-Received: (at 34708) by debbugs.gnu.org; 6 Mar 2019 00:16:35 +0000 Original-Received: from localhost ([127.0.0.1]:33618 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1h1KEd-0006j7-EE for submit@debbugs.gnu.org; Tue, 05 Mar 2019 19:16:35 -0500 Original-Received: from userp2120.oracle.com ([156.151.31.85]:50908) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1h1KEa-0006ip-Ix for 34708@debbugs.gnu.org; Tue, 05 Mar 2019 19:16:33 -0500 Original-Received: from pps.filterd (userp2120.oracle.com [127.0.0.1]) by userp2120.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x2603ZR2138846; Wed, 6 Mar 2019 00:16:25 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2018-07-02; bh=A+SlZ38q9YEc3rEuoySfNW8pddfWqWJn6NfO3J8LTB4=; b=5b9Y27fp0szP/h2mBWTVOoCYUGH/Y1BBNAfcPMUCl3KBvCQ1fzLnfbS/szdGMqHugs1C aX+c+Stqo8q3konuBU4CZI4HfL+2LmZzIeXn94oH7GzX74MPFvY4PoUCZBBro9RWKpzI s66YGIKxZN/RjofCbT83v+TA01Cx9YOfxKc6Z6zSjklcvPPvNj1/w0OeqAh07EF7Oks0 0SGDHS7+MH85VyAs3I9FON5zg2MIHSe0OwB3ue8hIleJquK7o+vK7IPVJlIux2pZd3FZ J5u+Ev9iRqficG2jYYrv8qe/+cQorwXQrA5mur7KH2+sWaynsOseRMwdJO6kBMMkJcVK dg== Original-Received: from aserv0021.oracle.com (aserv0021.oracle.com [141.146.126.233]) by userp2120.oracle.com with ESMTP id 2qyjfrgp60-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Wed, 06 Mar 2019 00:16:25 +0000 Original-Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by aserv0021.oracle.com (8.14.4/8.14.4) with ESMTP id x260GNQW020594 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Wed, 6 Mar 2019 00:16:24 GMT Original-Received: from abhmp0001.oracle.com (abhmp0001.oracle.com [141.146.116.7]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id x260GKY3011258; Wed, 6 Mar 2019 00:16:21 GMT In-Reply-To: <87h8chey12.fsf@ericabrahamsen.net> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4810.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=5900 definitions=9186 signatures=668685 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=908 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1903050155 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:156081 Archived-At: Getting from an alist the value for a given key is straightforward, obvious. So presumably, wrt getting, `alist-get' doesn't have to say more than that's what it does. But _setting_ a value for a given key in an alist is NOT straightforward. (An alist is not a hash table.) Often (typically) it means just consing a new alist entry on the front of the alist. (That's pretty much the main reason to use an alist.) But you could alternatively first remove one or more existing entry for that key from the alist and then add the requested key+value entry. And if you remove _all_ such entries first then you don't necessarily need to add the new entry to the beginning (though you almost always would, other things being equal). The ambiguity wrt setting means that the part of the `alist-get' doc that talks about using it with `setf', to set the value of the key, needs to be very clear and correct wrt the implementation. If the implementation just tacks on a new entry at the list beginning, then say so. If it does something else then say what that is. It's not admissible to just say that it sets the key to the given value. Why? Because of how alists are used. Code can very easily make use of an alist if it knows how it is being maintained. `alist-get' is a general function, and its doc needs to say something about how `setf' sets the value (what the result is). Similarly wrt removing an alist entry for a given key. Does it actually remove all such entries, or does it just tack on a new entry with value nil at the beginning of the list? These things need to be specified in the doc. Alists can be handled in more than one way when setting and deleting keys. The doc needs to tell us what `setf' with `alist-get' does to realize these things. A user doesn't necessarily care about the "how" details, but s?he deserves to know the "what": What is the result of setting the value of a key or removing a key?