new repository

1 files changed, 56 insertions, 0 deletions

diff --git a/devdocs/elisp/argument-evaluation.html b/devdocs/elisp/argument-evaluation.html
new file mode 100644
index 00000000..519be4f7
--- /dev/null
+++ b/devdocs/elisp/argument-evaluation.html
@@ -0,0 +1,56 @@
+ <h4 class="subsection">Evaluating Macro Arguments Repeatedly</h4> <p>When defining a macro you must pay attention to the number of times the arguments will be evaluated when the expansion is executed. The following macro (used to facilitate iteration) illustrates the problem. This macro allows us to write a for-loop construct. </p>  <div class="example"> <pre class="example">(defmacro for (var from init to final do &amp;rest body)
+  "Execute a simple \"for\" loop.
+For example, (for i from 1 to 10 do (print i))."
+  (list 'let (list (list var init))
+        (cons 'while
+              (cons (list '&lt;= var final)
+                    (append body (list (list 'inc var)))))))
+</pre>
+
+<pre class="example">(for i from 1 to 3 do
+   (setq square (* i i))
+   (princ (format "\n%d %d" i square)))
+→
+</pre>
+<pre class="example">(let ((i 1))
+  (while (&lt;= i 3)
+    (setq square (* i i))
+    (princ (format "\n%d %d" i square))
+    (inc i)))
+</pre>
+<pre class="example">
+
+     -|1       1
+     -|2       4
+     -|3       9
+⇒ nil
+</pre>
+</div> <p>The arguments <code>from</code>, <code>to</code>, and <code>do</code> in this macro are syntactic sugar; they are entirely ignored. The idea is that you will write noise words (such as <code>from</code>, <code>to</code>, and <code>do</code>) in those positions in the macro call. </p> <p>Here’s an equivalent definition simplified through use of backquote: </p> <div class="example"> <pre class="example">(defmacro for (var from init to final do &amp;rest body)
+  "Execute a simple \"for\" loop.
+For example, (for i from 1 to 10 do (print i))."
+  `(let ((,var ,init))
+     (while (&lt;= ,var ,final)
+       ,@body
+       (inc ,var))))
+</pre>
+</div> <p>Both forms of this definition (with backquote and without) suffer from the defect that <var>final</var> is evaluated on every iteration. If <var>final</var> is a constant, this is not a problem. If it is a more complex form, say <code>(long-complex-calculation x)</code>, this can slow down the execution significantly. If <var>final</var> has side effects, executing it more than once is probably incorrect. </p>  <p>A well-designed macro definition takes steps to avoid this problem by producing an expansion that evaluates the argument expressions exactly once unless repeated evaluation is part of the intended purpose of the macro. Here is a correct expansion for the <code>for</code> macro: </p> <div class="example"> <pre class="example">(let ((i 1)
+      (max 3))
+  (while (&lt;= i max)
+    (setq square (* i i))
+    (princ (format "%d      %d" i square))
+    (inc i)))
+</pre>
+</div> <p>Here is a macro definition that creates this expansion: </p> <div class="example"> <pre class="example">(defmacro for (var from init to final do &amp;rest body)
+  "Execute a simple for loop: (for i from 1 to 10 do (print i))."
+  `(let ((,var ,init)
+         (max ,final))
+     (while (&lt;= ,var max)
+       ,@body
+       (inc ,var))))
+</pre>
+</div> <p>Unfortunately, this fix introduces another problem, described in the following section. </p><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
+    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Argument-Evaluation.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Argument-Evaluation.html</a>
+  </p>
+</div>