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, 12 Mar 2019 09:18:27 -0700 (PDT) Message-ID: <5fac8365-68d2-4cc5-b5c3-d2658350ea28@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> <60367f47-c0b0-45b4-8ccf-169044400a75@default> <8736ntmsy3.fsf@web.de> <3af3b645-84e0-4208-be48-810e8cd2cfa8@default> <87a7i01bk0.fsf@web.de> <871s3c14s9.fsf@web.de> 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="182525"; mail-complaints-to="usenet@blaine.gmane.org" Cc: Eric Abrahamsen , 34708@debbugs.gnu.org To: Michael Heerdegen Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Mar 12 17:37: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 1h3kOy-000lOP-Ie for geb-bug-gnu-emacs@m.gmane.org; Tue, 12 Mar 2019 17:37:16 +0100 Original-Received: from localhost ([127.0.0.1]:55508 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h3kOx-0003vn-Fu for geb-bug-gnu-emacs@m.gmane.org; Tue, 12 Mar 2019 12:37:15 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:36587) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h3k7M-0005jb-La for bug-gnu-emacs@gnu.org; Tue, 12 Mar 2019 12:19:05 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1h3k7L-0003lD-Me for bug-gnu-emacs@gnu.org; Tue, 12 Mar 2019 12:19:04 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:55183) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1h3k7J-0003kG-Ur for bug-gnu-emacs@gnu.org; Tue, 12 Mar 2019 12:19:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1h3k7J-0004Dy-MP for bug-gnu-emacs@gnu.org; Tue, 12 Mar 2019 12:19:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 12 Mar 2019 16:19: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.155240751916205 (code B ref 34708); Tue, 12 Mar 2019 16:19:01 +0000 Original-Received: (at 34708) by debbugs.gnu.org; 12 Mar 2019 16:18:39 +0000 Original-Received: from localhost ([127.0.0.1]:40494 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1h3k6w-0004DJ-NR for submit@debbugs.gnu.org; Tue, 12 Mar 2019 12:18:38 -0400 Original-Received: from aserp2130.oracle.com ([141.146.126.79]:44082) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1h3k6u-0004D6-Ng for 34708@debbugs.gnu.org; Tue, 12 Mar 2019 12:18:37 -0400 Original-Received: from pps.filterd (aserp2130.oracle.com [127.0.0.1]) by aserp2130.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x2CGDfOS102389; Tue, 12 Mar 2019 16:18:30 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : cc : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2018-07-02; bh=N6Cv3IN1cGwtLDFKct+X8ItrlRj03Re4Ic8BXSwDtdo=; b=NhdiTma/M57M7pIa1yCg/6wsKFOjt8p3dyNNWJIqA/fHsACDu0Ar1psQ3JHO8qAoE4Ha 9gh0H73OXyeQ9Q422SrItjyGEFgmGVN4CpbYVxEc9VBoJOZI3fg6LPdjLIgpyai1H+W8 1eAlGlltb4v7rfIBsOZkoQqkeCkkxb9/Ku/5BM4KWNZDelDhPAnp0xKMRIhkFyZdFV5q wEF84oxvtWt25eVcWF/buhfChWH7rwfbxr4utHnWTEt4DsboRoRy+EtzG9ioh8x4eps9 q17pTJ8qwFB/uMecNyh9pLG1jyGLBo7hC6S3N9KueS8iZmSMPK3FE4iXQdfwTI+CMYq4 2w== Original-Received: from userv0021.oracle.com (userv0021.oracle.com [156.151.31.71]) by aserp2130.oracle.com with ESMTP id 2r430ep8f2-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 12 Mar 2019 16:18:30 +0000 Original-Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75]) by userv0021.oracle.com (8.14.4/8.14.4) with ESMTP id x2CGITTp027853 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 12 Mar 2019 16:18:29 GMT Original-Received: from abhmp0020.oracle.com (abhmp0020.oracle.com [141.146.116.26]) by userv0122.oracle.com (8.14.4/8.14.4) with ESMTP id x2CGISqc021726; Tue, 12 Mar 2019 16:18:28 GMT In-Reply-To: <871s3c14s9.fsf@web.de> 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=9193 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=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1903120113 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:156268 Archived-At: > > OK. Put it differently: it's worth documenting that updating an alist > > entry with `setf' is a "destructive" operation: it can change list > > structure. Dunno whether that is already said somewhere, but even if > > it is, a reminder wouldn't hurt. >=20 > But isn't that trivial? How else could we add associations? Yes, it's true of `setf' in general. It's still worth repeating, I think (just one opinion). One person's "trivial" is another's "gotcha". But apparently we don't even point this out in the Elisp manual doc for `setf', alas. And even for `setcdr' etc., the manual doesn't repeat it. It mentions it only in the parent node, `Modifying Existing List Structure'. `setf' is not mentioned in that node, BTW. Perhaps some mention would make sense, saying that when the place to be modified is a list the list structure can be modified - it is a so-called "destructive" operation. "Destructive" is mentioned in node `Rearrangement', however. Why it's not mentioned in nodes `Setcar' and `Setcdr' I don't know. (Sure, those nodes do make clear that list structure can be modified. But they don't specifically call them "destructive" operations.) I suggest we document explicitly for `alist-get' that using it as a generalized variable is a "destructive" operation - in both the doc string and node `Association Lists'. Whenever we say of some function that it "is a generalized variable suitable for use with `setf'", I think we should add that using it to modify a list is a "destructive" operation, i.e., it can change list structure. We should be a bit more consistent. We say `delq' is a "destructive" operation, but we don't say that explicitly about `delete' with a list (node `Sets and Lists'). (We do say it indirectly.) I'm not crazy about the term "destructive" for changes to list structure, BTW. But that's the term Emacs Lisp doc has chosen to use. As such, we should call it out everywhere it's applicable - or nowhere. It is not the case, for example, that `setcdr' is more "destructive" than `setf' + `alist-get'. Some get so excited about such "destruction" that they make a big deal about strongly discouraging users from using such functions. I don't. But I do think it's worth explicitly making users aware of which functions can change list structure (as well as what that means - the consequences).