From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Nicolas Richard Newsgroups: gmane.emacs.bugs Subject: bug#22192: Doc string of macroexp-let2 is obscure. Date: Thu, 17 Dec 2015 13:29:36 +0100 Message-ID: <87r3il45sf.fsf@ulb.ac.be> References: <20151217100936.GA2988@acm.fritz.box> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1450355750 1749 80.91.229.3 (17 Dec 2015 12:35:50 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 17 Dec 2015 12:35:50 +0000 (UTC) Cc: 22192@debbugs.gnu.org To: Alan Mackenzie Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Dec 17 13:35:38 2015 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1a9XmK-0006vc-KD for geb-bug-gnu-emacs@m.gmane.org; Thu, 17 Dec 2015 13:35:29 +0100 Original-Received: from localhost ([::1]:53106 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9XmJ-0000Eq-Vl for geb-bug-gnu-emacs@m.gmane.org; Thu, 17 Dec 2015 07:35:28 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:44404) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9Xh9-0000id-7u for bug-gnu-emacs@gnu.org; Thu, 17 Dec 2015 07:30:08 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1a9Xh5-0006UA-4g for bug-gnu-emacs@gnu.org; Thu, 17 Dec 2015 07:30:07 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:46645) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9Xh5-0006U3-14 for bug-gnu-emacs@gnu.org; Thu, 17 Dec 2015 07:30:03 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84) (envelope-from ) id 1a9Xh4-0004Pg-Pn for bug-gnu-emacs@gnu.org; Thu, 17 Dec 2015 07:30:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Nicolas Richard Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 17 Dec 2015 12:30:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 22192 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 22192-submit@debbugs.gnu.org id=B22192.145035534416872 (code B ref 22192); Thu, 17 Dec 2015 12:30:02 +0000 Original-Received: (at 22192) by debbugs.gnu.org; 17 Dec 2015 12:29:04 +0000 Original-Received: from localhost ([127.0.0.1]:54247 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1a9Xg7-0004O4-Jv for submit@debbugs.gnu.org; Thu, 17 Dec 2015 07:29:03 -0500 Original-Received: from mxin.ulb.ac.be ([164.15.128.112]:57704) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1a9Xg4-0004Nd-24 for 22192@debbugs.gnu.org; Thu, 17 Dec 2015 07:29:01 -0500 X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AmAFAN6pclakD4Xx/2dsb2JhbABegmmCEIJivHaGDQKCBAEBAQEBAYELhDUBAQQjVhAIAw4MAgUhAgIPAQRJE4gvqyGOH4NiAQsBIIEBhVWEfYRZgx6BSQWNNYlHll6UBmSEBT00hHwBAQE Original-Received: from mathsrv4.ulb.ac.be (HELO localhost) ([164.15.133.241]) by smtp.ulb.ac.be with ESMTP; 17 Dec 2015 13:28:58 +0100 In-Reply-To: <20151217100936.GA2988@acm.fritz.box> (Alan Mackenzie's message of "Thu, 17 Dec 2015 10:09:36 +0000") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.0.50 (gnu/linux) 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-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:110078 Archived-At: Alan Mackenzie writes: > "Bind VAR to a copyable expression that returns the value of EXP. > This is like `(let ((v ,EXP)) ,EXPS) except that `v' is a new generat= ed > symbol which EXPS can find in VAR. > TEST should be the name of a predicate on EXP checking whether the `l= et' can > be skipped; if nil, as is usual, `macroexp-const-p' is used." > > This macro is widely used (over 50 times) in Emacs, and is not > documented in the Elisp manual. The doc string is difficult to > understand. I agree that the docstring was pretty obscure, but it was modified in commit 5e3fde03b45877d3e30f859a14c10043e637aa63=20 It now is : Evaluate BODY with SYM bound to an expression for EXP=E2=80=99s value. The intended usage is that BODY generates an expression that will refer to EXP=E2=80=99s value multiple times, but will evaluate EXP only once. As BODY generates that expression, it should use SYM to stand for the value of EXP. If EXP is a simple, safe expression, then SYM=E2=80=99s value is EXP it= self. Otherwise, SYM=E2=80=99s value is a symbol which holds the value produc= ed by evaluating EXP. The return value incorporates the value of BODY, plus additional code to evaluate EXP once and save the result so SYM can refer to it. If BODY consists of multiple forms, they are all evaluated but only the last one=E2=80=99s value matters. TEST is a predicate to determine whether EXP qualifies as simple and safe; if TEST is nil, only constant expressions qualify. Example: (macroexp-let2 nil foo EXP `(* ,foo ,foo)) generates an expression that evaluates EXP once, then returns the square of that value. You could do this with (let ((foovar EXP)) (* foovar foovar)) but using =E2=80=98macroexp-let2=E2=80=99 produces more efficient code = in cases where EXP is a constant. --=20 Nicolas