Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Sean Whitton]

Hello,

On Tue 12 Apr 2022 at 02:02AM -04, Sean Whitton wrote:

> branch: master
> commit 2e9111813b1dfdda1bf56c2b70a4220dbd8abce1
> Author: Sean Whitton <spwhitton@spwhitton.name>
> Commit: Sean Whitton <spwhitton@spwhitton.name>
>
>     Add two classic Common Lisp macro-writing macros
>
>     * lisp/emacs-lisp/cl-macs.el (cl-with-gensyms, cl-once-only): New macros.
> ---
>  lisp/emacs-lisp/cl-macs.el | 51 ++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 51 insertions(+)

This seems to have introduced compilation warnings like this into
bootstrap builds only:

    Warning: Eager macro-expansion skipped due to cycle:
      … => (load "cl-macs.el") => (macroexpand-all …) => (macroexpand (cl-psetq …)) => (load "cl-macs.el")

I rebuilt before pushing, but not a bootstrap build.

Do I need to regenerate something somewhere?  Sorry for the noise.

-- 
Sean Whitton

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Po Lu]

Sean Whitton <spwhitton@spwhitton.name> writes:

> branch: master
> commit 2e9111813b1dfdda1bf56c2b70a4220dbd8abce1
> Author: Sean Whitton <spwhitton@spwhitton.name>
> Commit: Sean Whitton <spwhitton@spwhitton.name>
>
>     Add two classic Common Lisp macro-writing macros
>     
>     * lisp/emacs-lisp/cl-macs.el (cl-with-gensyms, cl-once-only): New macros.

Doesn't this need documentation and an entry in NEWS?

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Stefan Monnier]

> This seems to have introduced compilation warnings like this into
> bootstrap builds only:
>
>     Warning: Eager macro-expansion skipped due to cycle:
>       … => (load "cl-macs.el") => (macroexpand-all …) => (macroexpand (cl-psetq …)) => (load "cl-macs.el")
>
> I rebuilt before pushing, but not a bootstrap build.
>
> Do I need to regenerate something somewhere?  Sorry for the noise.

You need to fix the code to avoid those cycles (e.g. by refraining from
using `cl-psetq`, or by moving the macros that use `cl-psetq` after the
`cl-psetq` macro).

Po Lu [2022-04-12 14:42:19] wrote:
> Doesn't this need documentation and an entry in NEWS?

Indeed.  You might like to change the `macroexp-let2` uses in `cl.texi`
while at it.


        Stefan

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Lars Ingebrigtsen]

Sean Whitton <spwhitton@spwhitton.name> writes:

>     Add two classic Common Lisp macro-writing macros
>
>     * lisp/emacs-lisp/cl-macs.el (cl-with-gensyms, cl-once-only): New macros.

Emacs now gives a lot of the following warnings when compiling -- I
haven't checked that it's due to the commit above, but I guess it's
either that or 6a480c830b.

Warning: Eager macro-expansion skipped due to cycle:
  … => (load "cl-macs.el") => (macroexpand-all …) => (macroexpand (cl-psetq …)) => (load "cl-macs.el")
Warning: Eager macro-expansion skipped due to cycle:
  … => (load "cl-macs.el") => (macroexpand-all …) => (macroexpand (cl-psetq …)) => (load "cl-macs.el")
  ELC      calendar/diary-lib.elc
  ELC      calendar/holidays.elc
Warning: Eager macro-expansion skipped due to cycle:


-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Sean Whitton]

[-- Attachment #1: Type: text/plain, Size: 1059 bytes --]

Hello,

On Tue 12 Apr 2022 at 10:46am +02, Lars Ingebrigtsen wrote:

> Sean Whitton <spwhitton@spwhitton.name> writes:
>
>>     Add two classic Common Lisp macro-writing macros
>>
>>     * lisp/emacs-lisp/cl-macs.el (cl-with-gensyms, cl-once-only): New macros.
>
> Emacs now gives a lot of the following warnings when compiling -- I
> haven't checked that it's due to the commit above, but I guess it's
> either that or 6a480c830b.
>
> Warning: Eager macro-expansion skipped due to cycle:
>   … => (load "cl-macs.el") => (macroexpand-all …) => (macroexpand (cl-psetq …)) => (load "cl-macs.el")
> Warning: Eager macro-expansion skipped due to cycle:
>   … => (load "cl-macs.el") => (macroexpand-all …) => (macroexpand (cl-psetq …)) => (load "cl-macs.el")
>   ELC      calendar/diary-lib.elc
>   ELC      calendar/holidays.elc
> Warning: Eager macro-expansion skipped due to cycle:

Here is the fix.  I'll be at a machine where I can install it later
today, or someone else can sooner.  Apologies again!

-- 
Sean Whitton

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Fix-eager-macroexpansion-cycle-in-cl-once-only.patch --]
[-- Type: text/x-diff, Size: 1416 bytes --]

From f467478832a9041017653a07619acfdb9406ad99 Mon Sep 17 00:00:00 2001
From: Sean Whitton <spwhitton@spwhitton.name>
Date: Tue, 12 Apr 2022 08:48:18 -0700
Subject: [PATCH] Fix eager macroexpansion cycle in cl-once-only

* lisp/emacs-lisp/cl-macs.el (cl-once-only): Use different cl-loop
syntax, with no functional change, but such that the loop does not
expand into cl-psetq.
---
 lisp/emacs-lisp/cl-macs.el | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lisp/emacs-lisp/cl-macs.el b/lisp/emacs-lisp/cl-macs.el
index af8855516c..364b5120a0 100644
--- a/lisp/emacs-lisp/cl-macs.el
+++ b/lisp/emacs-lisp/cl-macs.el
@@ -2473,11 +2473,11 @@ cl-once-only
        ;; We require this explicit call to `list' rather than using
        ;; (,,@(cl-loop ...)) due to a limitation of Elisp's backquote.
        `(let ,(list
-               ,@(cl-loop for name in names and gensym in our-gensyms
+               ,@(cl-loop for name in names for gensym in our-gensyms
                           for to-eval = (or (cadr name) (car name))
                           collect ``(,,gensym ,,to-eval)))
           ;; During macroexpansion, bind each NAME to its gensym.
-          ,(let ,(cl-loop for name in names and gensym in our-gensyms
+          ,(let ,(cl-loop for name in names for gensym in our-gensyms
                           collect `(,(car name) ,gensym))
              ,@body)))))
 
-- 
2.30.2

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Sean Whitton]

Hello,

On Tue 12 Apr 2022 at 03:14am -04, Stefan Monnier wrote:

>> Doesn't this need documentation and an entry in NEWS?
>
> Indeed.  You might like to change the `macroexp-let2` uses in `cl.texi`
> while at it.

Ah, I didn't know about cl.texi, I will edit that.

Were you thinking those uses of macroexp-let2 should become cl-once-only
or just take advantage of how the first argument of the former can now
be omitted?

-- 
Sean Whitton

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Lars Ingebrigtsen]

Sean Whitton <spwhitton@spwhitton.name> writes:

> Here is the fix.  I'll be at a machine where I can install it later
> today, or someone else can sooner.  Apologies again!

No problem; pushed now.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Stefan Monnier]

> Were you thinking those uses of macroexp-let2 should become cl-once-only

Yes, that.


        Stefan

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Sean Whitton]

[-- Attachment #1: Type: text/plain, Size: 549 bytes --]

Hello,

On Tue 12 Apr 2022 at 02:42PM +08, Po Lu wrote:

> Sean Whitton <spwhitton@spwhitton.name> writes:
>
>> branch: master
>> commit 2e9111813b1dfdda1bf56c2b70a4220dbd8abce1
>> Author: Sean Whitton <spwhitton@spwhitton.name>
>> Commit: Sean Whitton <spwhitton@spwhitton.name>
>>
>>     Add two classic Common Lisp macro-writing macros
>>
>>     * lisp/emacs-lisp/cl-macs.el (cl-with-gensyms, cl-once-only): New macros.
>
> Doesn't this need documentation and an entry in NEWS?

Here's my docs patch if anyone has any comments.

-- 
Sean Whitton

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Document-additions-of-cl-with-gensyms-and-cl-once-on.patch --]
[-- Type: text/x-patch, Size: 5351 bytes --]

From 99c8d1a12bbc4c471d8b3049c3724dae227cee7f Mon Sep 17 00:00:00 2001
From: Sean Whitton <spwhitton@spwhitton.name>
Date: Tue, 12 Apr 2022 11:38:32 -0700
Subject: [PATCH] Document additions of cl-with-gensyms and cl-once-only

* NEWS: Document additions of cl-with-gensyms and cl-once-only.
* doc/misc/cl.texi (Macro-Writing Macros): New section.
(Obsolete Setf Customization): Use cl-once-only rather than
macroexp-let2, and fix a quotation bug in one example.
---
 doc/misc/cl.texi | 84 ++++++++++++++++++++++++++++++++++++++++++++++--
 etc/NEWS         |  3 ++
 2 files changed, 85 insertions(+), 2 deletions(-)

diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index a6fe29e102..23c0c53c20 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -843,6 +843,7 @@ Control Structure
 * Iteration::              @code{cl-do}, @code{cl-dotimes}, @code{cl-dolist}, @code{cl-do-symbols}.
 * Loop Facility::          The Common Lisp @code{loop} macro.
 * Multiple Values::        @code{cl-values}, @code{cl-multiple-value-bind}, etc.
+* Macro-Writing Macros::   @code{cl-with-gensyms}, @code{cl-once-only}.
 @end menu
 
 @node Assignment
@@ -2513,6 +2514,85 @@ Multiple Values
 Since a perfect emulation is not feasible in Emacs Lisp, this
 package opts to keep it as simple and predictable as possible.
 
+@node Macro-Writing Macros
+@section Macro-Writing Macros
+
+@noindent
+This package includes two classic Common Lisp macro-writing macros to
+help render complex macrology easier to read.
+
+@defmac cl-with-gensyms names body@dots{}
+This macro expands to code that executes @var{body} with each of the
+variables in @var{names} bound to a fresh uninterned symbol or
+``gensym''.  @xref{Creating Symbols}.  For macros requiring more than
+one gensym, use of @code{cl-with-gensyms} shortens the code and
+renders one's intentions clearer.  Compare:
+
+@example
+(defmacro my-macro (foo)
+  (let ((bar (gensym "bar"))
+        (baz (gensym "baz"))
+        (quux (gensym "quux")))
+    `(let ((,bar (+ @dots{})))
+       @dots{})))
+
+(defmacro my-macro (foo)
+  (cl-with-gensyms (bar baz quux)
+    `(let ((,bar (+ @dots{})))
+       @dots{})))
+@end example
+@end defmac
+
+@defmac cl-once-only ((name form)@dots{}) body@dots{}
+This macro is primarily to help the macro programmer ensure that forms
+supplied by the user of the macro are evaluated just once by its
+expansion even though the result of evaluating the form is to occur
+more than once.  Less often, this macro is used to ensure that forms
+supplied by the macro programmer are evaluated just once.
+
+Each @var{name} is a variable which can be used to refer to the result
+of evaluating @var{form} in @var{body}.  @code{cl-once-only} binds
+each @var{name} to a fresh uninterned symbol during the evaluation of
+@var{body}.  Then, @code{cl-once-only} wraps the final expansion in
+code to evaluate each @var{form} and bind it to the corresponding
+uninterned symbol.  Thus, when the macro writer substitutes the value
+for @var{name} into the expansion they are effectively referring to
+the result of evaluating @var{form}, rather than @var{form} itself.
+Another way to put this is that each @var{name} is bound to an
+expression for the (singular) result of evaluating @var{form}.
+
+The most common case is where @var{name} is one of the arguments to
+the macro being written, so @code{(name name)} may be abbreviated to
+just @code{name}.
+
+For example, consider this macro:
+
+@example
+(defmacro my-list (x y &rest forms)
+  (let ((x-result (gensym))
+        (y-result (gensym)))
+    `(let ((,x-result ,x)
+           (,y-result ,y))
+       (list ,x-result ,y-result ,x-result ,y-result
+             (progn ,@@forms))))
+@end example
+
+In a call like @code{(my-list (pop foo) ...)} the intermediate binding
+to @code{x-result} ensures that the @code{pop} is not done twice.  But
+as a result the code is rather complex: the reader must keep track of
+how @code{x-result} really just means the first parameter of the call
+to the macro, and the required use of multiple gensyms to avoid
+variable capture by @code{(progn ,@@forms)} obscures things further.
+@code{cl-once-only} takes care of these details:
+
+@example
+(defmacro my-list (x &rest forms)
+  (cl-once-only (x y)
+    `(list ,x ,y ,x ,y
+           (progn ,@@forms))))
+@end example
+@end defmac
+
 @node Macros
 @chapter Macros
 
@@ -5028,13 +5108,13 @@ Obsolete Setf Customization
 @example
 (defmacro incf (place &optional n)
   (gv-letplace (getter setter) place
-    (macroexp-let2 nil v (or n 1)
+    (cl-once-only ((v (or n 1)))
       (funcall setter `(+ ,v ,getter)))))
 @end example
 @ignore
 (defmacro concatf (place &rest args)
   (gv-letplace (getter setter) place
-    (macroexp-let2 nil v (mapconcat 'identity args)
+    (cl-once-only ((v `(mapconcat 'identity ',args)))
       (funcall setter `(concat ,getter ,v)))))
 @end ignore
 @end defmac
diff --git a/etc/NEWS b/etc/NEWS
index 79c27da549..196f7ef999 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1363,6 +1363,9 @@ functions.
 +++
 ** 'macroexp-let2*' can omit 'test' arg and use single-var bindings.
 
++++
+** New macro-writing macros, 'cl-with-gensyms' and 'cl-once-only'.
+
 +++
 ** New variable 'last-event-device' and new function 'device-class'.
 On X Windows, 'last-event-device' specifies the input extension device
-- 
2.30.2

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Eli Zaretskii]

> From: Sean Whitton <spwhitton@spwhitton.name>
> Date: Tue, 12 Apr 2022 11:43:30 -0700
> 
> Here's my docs patch if anyone has any comments.

Thanks for writing the documentation.

> +@defmac cl-with-gensyms names body@dots{}

Shouldn't @dots{} follow NAMES?  There's just one BODY, but any
number of NAMES, right?

> +This macro expands to code that executes @var{body} with each of the
> +variables in @var{names} bound to a fresh uninterned symbol or
> +``gensym''.

Instead of "or" I suggest to say "a.k.a.@: @dfn{gensym}" (and add a
@cindex entry for "gensym", as usual with any term in @dfn).

> +@defmac cl-once-only ((name form)@dots{}) body@dots{}
> +This macro is primarily to help the macro programmer ensure that forms
> +supplied by the user of the macro are evaluated just once by its
> +expansion even though the result of evaluating the form is to occur
> +more than once.  Less often, this macro is used to ensure that forms
> +supplied by the macro programmer are evaluated just once.
> +
> +Each @var{name} is a variable which can be used to refer to the result
> +of evaluating @var{form} in @var{body}.  @code{cl-once-only} binds
> +each @var{name} to a fresh uninterned symbol during the evaluation of
> +@var{body}.

My recommendation is always to try to name parameters after their
roles.  In this case, I'd use VAR or VARIABLE instead of the less
specific NAME.  Then you could make the text shorter and thus clearer:

  Each @var{variable} can be used to refer to the result of evaluating
  @var{form} in @var{body}.  @code{cl-once-only} binds each
  @var{variable} to a fresh uninterned symbol...

(And why not use "gensym" instead of the wordier "uninterned symbol"?
that's why you introduced that terminology, right?)

>            Then, @code{cl-once-only} wraps the final expansion in
> +code to evaluate each @var{form} and bind it to the corresponding
> +uninterned symbol.

How can a form be bound to a symbol?

> +In a call like @code{(my-list (pop foo) ...)} the intermediate binding
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Long stretches of @code which have embedded whitespace, like that one
above, should be  wrapped in @w{..}, to prevent them from being broken
between two lines.

Also, why a literal "..." instead of @dots{}?

> ++++
> +** New macro-writing macros, 'cl-with-gensyms' and 'cl-once-only'.

I suggest to add here a pointer to the node in the manual where they
are described, since this entry tells nothing about that to someone
who doesn't already know CL well enough.

Thanks.

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > >     Add two classic Common Lisp macro-writing macros
  > >     
  > >     * lisp/emacs-lisp/cl-macs.el (cl-with-gensyms, cl-once-only): New macros.

  > Doesn't this need documentation and an entry in NEWS?

Are they needed only for compatibility with some Common Lisp programs?

If these are useful new features, why define them with `cl-' in their names?

If they aren't, why define them at all?

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Sean Whitton]

Hello,

On Tue 12 Apr 2022 at 11:58pm -04, Richard Stallman wrote:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > >     Add two classic Common Lisp macro-writing macros
>   > >
>   > >     * lisp/emacs-lisp/cl-macs.el (cl-with-gensyms, cl-once-only): New macros.
>
>   > Doesn't this need documentation and an entry in NEWS?
>
> Are they needed only for compatibility with some Common Lisp programs?
>
> If these are useful new features, why define them with `cl-' in their names?
>
> If they aren't, why define them at all?

They're useful new features rather than for compat.

Stefan was concerned that "once-only" is not descriptive enough.  But
it's the usual CL name for this macro.  So I concluded that prefixing
both with cl- will be easiest to memorise.

-- 
Sean Whitton

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Sean Whitton]

[-- Attachment #1: Type: text/plain, Size: 2528 bytes --]

Hello,

Thank you for looking!

On Tue 12 Apr 2022 at 10:25pm +03, Eli Zaretskii wrote:

>> +This macro expands to code that executes @var{body} with each of the
>> +variables in @var{names} bound to a fresh uninterned symbol or
>> +``gensym''.
>
> Instead of "or" I suggest to say "a.k.a.@: @dfn{gensym}" (and add a
> @cindex entry for "gensym", as usual with any term in @dfn).

I've changed this to something else, but I'd prefer not to use an
abbreviation like "a.k.a.".  Thanks for pointing out @dfn.

>> +@defmac cl-once-only ((name form)@dots{}) body@dots{}
>> +This macro is primarily to help the macro programmer ensure that forms
>> +supplied by the user of the macro are evaluated just once by its
>> +expansion even though the result of evaluating the form is to occur
>> +more than once.  Less often, this macro is used to ensure that forms
>> +supplied by the macro programmer are evaluated just once.
>> +
>> +Each @var{name} is a variable which can be used to refer to the result
>> +of evaluating @var{form} in @var{body}.  @code{cl-once-only} binds
>> +each @var{name} to a fresh uninterned symbol during the evaluation of
>> +@var{body}.
>
> My recommendation is always to try to name parameters after their
> roles.  In this case, I'd use VAR or VARIABLE instead of the less
> specific NAME.  Then you could make the text shorter and thus clearer:
>
>   Each @var{variable} can be used to refer to the result of evaluating
>   @var{form} in @var{body}.  @code{cl-once-only} binds each
>   @var{variable} to a fresh uninterned symbol...

Yes, that's better.

> (And why not use "gensym" instead of the wordier "uninterned symbol"?
> that's why you introduced that terminology, right?)

I wanted to use "gensym" in the description of cl-with-gensyms because
of the name of that macro.  But otherwise, I was thinking that it's a
less familiar term in Elisp than it is in CL, and that "uninterned
symbol" was the most familiar Elisp term.  I don't mind changing it if
you think that's not so much of a concern.

>>            Then, @code{cl-once-only} wraps the final expansion in
>> +code to evaluate each @var{form} and bind it to the corresponding
>> +uninterned symbol.
>
> How can a form be bound to a symbol?

In this case it should say that the result of evaluation is bound to the
corresponding uninterned symbol, thanks.

In general, I would describe (let ((x '(+ 1 2))) ...) as a case where a
form is bound to a symbol -- would you describe that differently?

Revised patch attached.

-- 
Sean Whitton

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Document-additions-of-cl-with-gensyms-and-cl-once-on.patch --]
[-- Type: text/x-diff, Size: 5709 bytes --]

From 035d757599c546fffc5acb10a3e692cb2d27d329 Mon Sep 17 00:00:00 2001
From: Sean Whitton <spwhitton@spwhitton.name>
Date: Tue, 12 Apr 2022 11:38:32 -0700
Subject: [PATCH] Document additions of cl-with-gensyms and cl-once-only

* NEWS: Document additions of cl-with-gensyms and cl-once-only.
* doc/misc/cl.texi (Macro-Writing Macros): New section.
(Creating Symbols): Add to the concept index under the name "gensym".
(Obsolete Setf Customization): Use cl-once-only rather than
macroexp-let2, and fix a quotation bug in one example.
---
 doc/misc/cl.texi | 86 ++++++++++++++++++++++++++++++++++++++++++++++--
 etc/NEWS         |  4 +++
 2 files changed, 88 insertions(+), 2 deletions(-)

diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index a6fe29e102..0946510882 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -843,6 +843,7 @@ Control Structure
 * Iteration::              @code{cl-do}, @code{cl-dotimes}, @code{cl-dolist}, @code{cl-do-symbols}.
 * Loop Facility::          The Common Lisp @code{loop} macro.
 * Multiple Values::        @code{cl-values}, @code{cl-multiple-value-bind}, etc.
+* Macro-Writing Macros::   @code{cl-with-gensyms}, @code{cl-once-only}.
 @end menu
 
 @node Assignment
@@ -2513,6 +2514,86 @@ Multiple Values
 Since a perfect emulation is not feasible in Emacs Lisp, this
 package opts to keep it as simple and predictable as possible.
 
+@node Macro-Writing Macros
+@section Macro-Writing Macros
+
+@noindent
+This package includes two classic Common Lisp macro-writing macros to
+help render complex macrology easier to read.
+
+@defmac cl-with-gensyms names@dots{} body
+This macro expands to code that executes @var{body} with each of the
+variables in @var{names} bound to a fresh uninterned symbol, or
+@dfn{gensym}, in Common Lisp parlance.  For macros requiring more than
+one gensym, use of @code{cl-with-gensyms} shortens the code and
+renders one's intentions clearer.  Compare:
+
+@example
+(defmacro my-macro (foo)
+  (let ((bar (gensym "bar"))
+        (baz (gensym "baz"))
+        (quux (gensym "quux")))
+    `(let ((,bar (+ @dots{})))
+       @dots{})))
+
+(defmacro my-macro (foo)
+  (cl-with-gensyms (bar baz quux)
+    `(let ((,bar (+ @dots{})))
+       @dots{})))
+@end example
+@end defmac
+
+@defmac cl-once-only ((variable form)@dots{}) body
+This macro is primarily to help the macro programmer ensure that forms
+supplied by the user of the macro are evaluated just once by its
+expansion even though the result of evaluating the form is to occur
+more than once.  Less often, this macro is used to ensure that forms
+supplied by the macro programmer are evaluated just once.
+
+Each @var{variable} which can be used to refer to the result of
+evaluating @var{form} in @var{body}.  @code{cl-once-only} binds each
+@var{variable} to a fresh uninterned symbol during the evaluation of
+@var{body}.  Then, @code{cl-once-only} wraps the final expansion in
+code to evaluate each @var{form} and bind the result to the
+corresponding uninterned symbol.  Thus, when the macro writer
+substitutes the value for @var{variable} into the expansion they are
+effectively referring to the result of evaluating @var{form}, rather
+than @var{form} itself.  Another way to put this is that each
+@var{variable} is bound to an expression for the (singular) result of
+evaluating @var{form}.
+
+The most common case is where @var{variable} is one of the arguments
+to the macro being written, so @code{(variable variable)} may be
+abbreviated to just @code{variable}.
+
+For example, consider this macro:
+
+@example
+(defmacro my-list (x y &rest forms)
+  (let ((x-result (gensym))
+        (y-result (gensym)))
+    `(let ((,x-result ,x)
+           (,y-result ,y))
+       (list ,x-result ,y-result ,x-result ,y-result
+             (progn ,@@forms))))
+@end example
+
+In a call like @w{@code{(my-list (pop foo) @dots{})}} the intermediate
+binding to @code{x-result} ensures that the @code{pop} is not done
+twice.  But as a result the code is rather complex: the reader must
+keep track of how @code{x-result} really just means the first
+parameter of the call to the macro, and the required use of multiple
+gensyms to avoid variable capture by @code{(progn ,@@forms)} obscures
+things further.  @code{cl-once-only} takes care of these details:
+
+@example
+(defmacro my-list (x &rest forms)
+  (cl-once-only (x y)
+    `(list ,x ,y ,x ,y
+           (progn ,@@forms))))
+@end example
+@end defmac
+
 @node Macros
 @chapter Macros
 
@@ -2868,6 +2949,7 @@ Property Lists
 
 @node Creating Symbols
 @section Creating Symbols
+@cindex gensym
 
 @noindent
 These functions create unique symbols, typically for use as
@@ -5028,13 +5110,13 @@ Obsolete Setf Customization
 @example
 (defmacro incf (place &optional n)
   (gv-letplace (getter setter) place
-    (macroexp-let2 nil v (or n 1)
+    (cl-once-only ((v (or n 1)))
       (funcall setter `(+ ,v ,getter)))))
 @end example
 @ignore
 (defmacro concatf (place &rest args)
   (gv-letplace (getter setter) place
-    (macroexp-let2 nil v (mapconcat 'identity args)
+    (cl-once-only ((v `(mapconcat 'identity ',args)))
       (funcall setter `(concat ,getter ,v)))))
 @end ignore
 @end defmac
diff --git a/etc/NEWS b/etc/NEWS
index 79c27da549..24e45b0483 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1363,6 +1363,10 @@ functions.
 +++
 ** 'macroexp-let2*' can omit 'test' arg and use single-var bindings.
 
++++
+** New macro-writing macros, 'cl-with-gensyms' and 'cl-once-only'.
+See the '(cl) Macro-Writing Macros' manual section for descriptions.
+
 +++
 ** New variable 'last-event-device' and new function 'device-class'.
 On X Windows, 'last-event-device' specifies the input extension device
-- 
2.30.2

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Philip Kaludercic]

Sean Whitton <spwhitton@spwhitton.name> writes:

> branch: master
> commit 2e9111813b1dfdda1bf56c2b70a4220dbd8abce1
> Author: Sean Whitton <spwhitton@spwhitton.name>
> Commit: Sean Whitton <spwhitton@spwhitton.name>
>
>     Add two classic Common Lisp macro-writing macros
>     
>     * lisp/emacs-lisp/cl-macs.el (cl-with-gensyms, cl-once-only): New macros.

Is there a reason these were added cl-macs instead of something like
subr-x?

-- 
	Philip Kaludercic

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Eli Zaretskii]

> From: Sean Whitton <spwhitton@spwhitton.name>
> Cc: emacs-devel@gnu.org
> Date: Tue, 12 Apr 2022 22:48:42 -0700
> 
> > (And why not use "gensym" instead of the wordier "uninterned symbol"?
> > that's why you introduced that terminology, right?)
> 
> I wanted to use "gensym" in the description of cl-with-gensyms because
> of the name of that macro.  But otherwise, I was thinking that it's a
> less familiar term in Elisp than it is in CL, and that "uninterned
> symbol" was the most familiar Elisp term.  I don't mind changing it if
> you think that's not so much of a concern.

It isn't a big deal, but in general, if you introduce terminology, you
should use it.  "Chekhov's gun" and all that, you know...

> Revised patch attached.

Thanks, LGTM.

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Stefan Monnier]

> Is there a reason these were added cl-macs instead of something like
> subr-x?

These names come from the Common Lisp tradition.
In ELisp `cl-only-once` is named `macroexp-let2*` (with a slightly
different calling convention).


        Stefan

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Johann Klähn]

I think you missed the `y' parameter in your second example:

On Tue, Apr 12, 2022 at 22:48 -0700, Sean Whitton wrote:
> +@example
> +(defmacro my-list (x &rest forms)
                      ^^^ here

> +  (cl-once-only (x y)
> +    `(list ,x ,y ,x ,y
> +           (progn ,@@forms))))
> +@end example

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Sean Whitton]

Hello,

On Wed 13 Apr 2022 at 09:46PM +02, Johann Klähn wrote:

> I think you missed the `y' parameter in your second example:

Thank you, fixed.

-- 
Sean Whitton

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > Are they needed only for compatibility with some Common Lisp programs?
  > >
  > > If these are useful new features, why define them with `cl-' in their names?
  > >
  > > If they aren't, why define them at all?

  > They're useful new features rather than for compat.

  > Stefan was concerned that "once-only" is not descriptive enough.  But
  > it's the usual CL name for this macro.  So I concluded that prefixing
  > both with cl- will be easiest to memorise.

The purpose of the `cl-' prefix is so that we don't need to describe
those Common Lisp functions in the manual.  That is for functions
whose reason for existence in Emacs Lisp is compatibility.

When a function exists for other reasons, we should describe it
in the Emacs Lisp Reference Manual so that users can find it.
Giving it the`cl-' prefix is unnecessary and confusing.
Let's define it without a prefix.



-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Sean Whitton]

Hello,

On Wed 13 Apr 2022 at 10:56PM -04, Richard Stallman wrote:

> The purpose of the `cl-' prefix is so that we don't need to describe
> those Common Lisp functions in the manual.  That is for functions
> whose reason for existence in Emacs Lisp is compatibility.

That might have been the initial purpose, but there are already things
with that prefix which are not only for compatibility.  For example,
cl-letf, which isn't actually anywhere in CL but only in Elisp!

> When a function exists for other reasons, we should describe it
> in the Emacs Lisp Reference Manual so that users can find it.
> Giving it the`cl-' prefix is unnecessary and confusing.
> Let's define it without a prefix.

If the functions were to be moved to subr-x, then they wouldn't get an
entry in that manual, though.

-- 
Sean Whitton

RE: [External] : Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Drew Adams]

> > The purpose of the `cl-' prefix is so that we don't need to describe
> > those Common Lisp functions in the manual.  That is for functions
> > whose reason for existence in Emacs Lisp is compatibility.
> 
> That might have been the initial purpose, but there are already things
> with that prefix which are not only for compatibility.  For example,
> cl-letf, which isn't actually anywhere in CL but only in Elisp!

Yes, and FWIW, I (at least) complained about that
when it (and similar non-CL things) were added to
cl*.el.  I see (and got) no good reason for that.

> > When a function exists for other reasons, we should describe it
> > in the Emacs Lisp Reference Manual so that users can find it.
> > Giving it the`cl-' prefix is unnecessary and confusing.
> > Let's define it without a prefix.
> 
> If the functions were to be moved to subr-x, then they wouldn't get an
> entry in that manual, though.

Things that are not Common-Lisp emulation don't
belong in the cl*.el files, and they shouldn't
be documented in the CL manual.  IMHO.

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > The purpose of the `cl-' prefix is so that we don't need to describe
  > > those Common Lisp functions in the manual.  That is for functions
  > > whose reason for existence in Emacs Lisp is compatibility.

  > That might have been the initial purpose, but there are already things
  > with that prefix which are not only for compatibility.  For example,
  > cl-letf, which isn't actually anywhere in CL but only in Elisp!

Why was it given that name?  Is there a good reason for that to be its
name?  Should we rename it to `letf'?

Is it documented in the Emacs Lisp Ref Manual now?

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Thu, 14 Apr 2022 23:59:40 -0400
> Cc: luangruo@yahoo.com, emacs-devel@gnu.org
> 
>   > > The purpose of the `cl-' prefix is so that we don't need to describe
>   > > those Common Lisp functions in the manual.  That is for functions
>   > > whose reason for existence in Emacs Lisp is compatibility.
> 
>   > That might have been the initial purpose, but there are already things
>   > with that prefix which are not only for compatibility.  For example,
>   > cl-letf, which isn't actually anywhere in CL but only in Elisp!
> 
> Why was it given that name?  Is there a good reason for that to be its
> name?  Should we rename it to `letf'?
> 
> Is it documented in the Emacs Lisp Ref Manual now?

No.

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Michael Heerdegen]

Richard Stallman <rms@gnu.org> writes:

> Why was it given that name?  Is there a good reason for that to be its
> name?

Maybe because generalized variables once were implemented in cl, and
letf is about binding them?

> Should we rename it to `letf'?

Or maybe gv-letf, if we don't want to give it such a prominent name.

Michael.

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

Regarding `letf':

  > > Is it documented in the Emacs Lisp Ref Manual now?

  > No.

Why was it given that name?  Is there a good reason for that to be its
name?  Should we rename it to `letf'?

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > Should we rename it to `letf'?

  > Or maybe gv-letf, if we don't want to give it such a prominent name.

Since we use the name `setf' rather than `gv-setf', we may as well use `letf'
for the sake of regularity.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Sun, 17 Apr 2022 22:41:16 -0400
> Cc: luangruo@yahoo.com, emacs-devel@gnu.org, spwhitton@spwhitton.name
> 
> Since we use the name `setf' rather than `gv-setf', we may as well use `letf'
> for the sake of regularity.

I'm afraid it's too late: cl-letf exists and is widely used since
Emacs 24 at least.

Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > Since we use the name `setf' rather than `gv-setf', we may as well use `letf'
  > > for the sake of regularity.

  > I'm afraid it's too late: cl-letf exists and is widely used since
  > Emacs 24 at least.

It's not too late -- we could define letf as another name for the
construct.