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