From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.devel Subject: RE: Lispref add-to-list - doc is unnecessary convoluted Date: Fri, 4 Dec 2020 10:02:08 -0800 (PST) Message-ID: <711d2a3c-49cd-4d7e-8d4e-720ad4b580cd@default> References: <83zh2udle7.fsf@gnu.org> > < Mime-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="24658"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: arthur miller , Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Dec 04 21:34:17 2020 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1klHmS-0006Ha-97 for ged-emacs-devel@m.gmane-mx.org; Fri, 04 Dec 2020 21:34:16 +0100 Original-Received: from localhost ([::1]:56152 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1klHmR-0001oR-9l for ged-emacs-devel@m.gmane-mx.org; Fri, 04 Dec 2020 15:34:15 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:56418) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1klFRi-0005UZ-8y for emacs-devel@gnu.org; Fri, 04 Dec 2020 13:04:42 -0500 Original-Received: from aserp2120.oracle.com ([141.146.126.78]:58132) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1klFRK-0008Pz-Qw; Fri, 04 Dec 2020 13:04:29 -0500 Original-Received: from pps.filterd (aserp2120.oracle.com [127.0.0.1]) by aserp2120.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 0B4HxIq3194930; Fri, 4 Dec 2020 18:04:10 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-2020-01-29; bh=IyOEcykWimBK73bzkDirJvhKuDL5IjUKDujzDzqTiY4=; b=S+iCvs381+xvb/znm6P9cyJF89D/uGkH63xTQkLac0scFt8vZmX0Hgh0RQ5qPH7aMyg8 SvZ1rdQnJQFWMhKnsJVd9uf58Fki+r9jn9Im8QmIwUE6WHr5QFoLEmtn8BIiieiMNDa7 Tl3N+oT0ymoSWvCa6j1dVgowJRIBIpGbPHrRuRNoSRrhDUUMUp7YR5bufHnS5vWPMqZm G0QO5eQXnrhUWp/SGYZn+w2mUPaUaDvGJDo4S5VKLZmK1TG7z+YgZS88u8Psxgj02tTq 6doiTdlqdRsvRGMPFbsimud94zXg/BCSK/7+9+eNUrUHNcYa/lcwZyxtNZy30CFzopdi Kw== Original-Received: from aserp3020.oracle.com (aserp3020.oracle.com [141.146.126.70]) by aserp2120.oracle.com with ESMTP id 353egm4e72-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Fri, 04 Dec 2020 18:04:10 +0000 Original-Received: from pps.filterd (aserp3020.oracle.com [127.0.0.1]) by aserp3020.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 0B4I0IoQ142555; Fri, 4 Dec 2020 18:02:10 GMT Original-Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by aserp3020.oracle.com with ESMTP id 3540f3n40q-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 04 Dec 2020 18:02:10 +0000 Original-Received: from abhmp0013.oracle.com (abhmp0013.oracle.com [141.146.116.19]) by aserv0121.oracle.com (8.14.4/8.13.8) with ESMTP id 0B4I29X0030980; Fri, 4 Dec 2020 18:02:09 GMT In-Reply-To: X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.5071.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9825 signatures=668682 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 mlxscore=0 malwarescore=0 phishscore=0 suspectscore=0 bulkscore=0 spamscore=0 adultscore=0 mlxlogscore=999 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2009150000 definitions=main-2012040103 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9825 signatures=668682 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 mlxscore=0 bulkscore=0 suspectscore=0 phishscore=0 mlxlogscore=999 lowpriorityscore=0 malwarescore=0 priorityscore=1501 spamscore=0 impostorscore=0 clxscore=1015 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2009150000 definitions=main-2012040103 Received-SPF: pass client-ip=141.146.126.78; envelope-from=drew.adams@oracle.com; helo=aserp2120.oracle.com X-Spam_score_int: -58 X-Spam_score: -5.9 X-Spam_bar: ----- X-Spam_report: (-5.9 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-1.496, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:260315 Archived-At: > > > why doesn't add-to-list take a list value, why symbol? > > > > That's its specific purpose: update the value > > of a (list-valued) _variable_.=A0 It's all about > > a variable - updating its value. > > > > The doc is very clear: > > https://www.gnu.org/software/emacs/manual/html_node/elisp/List-Variable= s.html > > > > Please read the entire topic (node). > > I understand the obvious I'm not sure you do. Or maybe it's not so obvious. I suggest you read that manual node again. I'm not talking about the doc string. It's important to read about all of what's in that node, as the things presented are related - you can compare and contrast them to better understand what each is for (what it does). > Was it necessary for some reason that I don't > understand to design this function this way? > Or could have just taken a list from the very beginning? It's not about modifying a list. And it's not about consing an element onto a list. It's about consing an element onto a list that is the value of a _variable_ and reassigning that variable to the result. A function that takes only a list as arg has no way of assigning any value to a _variable_. This function (and it is a function, unlike, say, `setq') takes a _symbol_ as arg - a symbol whose value as a _variable_ is a list. And it returns the same symbol, after changing its value to be a list that has the argument value as car and the original value (list) as cdr. That's all. You can compare it with the macro `push', if you like. That macro has, as its second arg, a _place_, which can be, for example, a variable. It adds a value to the list that's stored in the place. If the place is a variable then that list is the value of the variable. For a variable, `push' thus updates the value of a list-valued variable to be a list whose car is the argument value and whose cdr is the original value (list). The essential difference between `add-to-list' and `push' (in the case of pushing to a variable place) is that the former is a function and the latter is a macro. You can pass a sexp as first arg to `add-to-list', and it gets _evaluated_ to provide the variable to use.