new repository

1 files changed, 32 insertions, 0 deletions

diff --git a/devdocs/elisp/expansion.html b/devdocs/elisp/expansion.html
new file mode 100644
index 00000000..b3ad6cb3
--- /dev/null
+++ b/devdocs/elisp/expansion.html
@@ -0,0 +1,32 @@
+ <h3 class="section">Expansion of a Macro Call</h3>   <p>A macro call looks just like a function call in that it is a list which starts with the name of the macro. The rest of the elements of the list are the arguments of the macro. </p> <p>Evaluation of the macro call begins like evaluation of a function call except for one crucial difference: the macro arguments are the actual expressions appearing in the macro call. They are not evaluated before they are given to the macro definition. By contrast, the arguments of a function are results of evaluating the elements of the function call list. </p> <p>Having obtained the arguments, Lisp invokes the macro definition just as a function is invoked. The argument variables of the macro are bound to the argument values from the macro call, or to a list of them in the case of a <code>&amp;rest</code> argument. And the macro body executes and returns its value just as a function body does. </p> <p>The second crucial difference between macros and functions is that the value returned by the macro body is an alternate Lisp expression, also known as the <em>expansion</em> of the macro. The Lisp interpreter proceeds to evaluate the expansion as soon as it comes back from the macro. </p> <p>Since the expansion is evaluated in the normal manner, it may contain calls to other macros. It may even be a call to the same macro, though this is unusual. </p> <p>Note that Emacs tries to expand macros when loading an uncompiled Lisp file. This is not always possible, but if it is, it speeds up subsequent execution. See <a href="how-programs-do-loading">How Programs Do Loading</a>. </p> <p>You can see the expansion of a given macro call by calling <code>macroexpand</code>. </p> <dl> <dt id="macroexpand">Function: <strong>macroexpand</strong> <em>form &amp;optional environment</em>
+</dt> <dd>
+ <p>This function expands <var>form</var>, if it is a macro call. If the result is another macro call, it is expanded in turn, until something which is not a macro call results. That is the value returned by <code>macroexpand</code>. If <var>form</var> is not a macro call to begin with, it is returned as given. </p> <p>Note that <code>macroexpand</code> does not look at the subexpressions of <var>form</var> (although some macro definitions may do so). Even if they are macro calls themselves, <code>macroexpand</code> does not expand them. </p> <p>The function <code>macroexpand</code> does not expand calls to inline functions. Normally there is no need for that, since a call to an inline function is no harder to understand than a call to an ordinary function. </p> <p>If <var>environment</var> is provided, it specifies an alist of macro definitions that shadow the currently defined macros. Byte compilation uses this feature. </p> <div class="example"> <pre class="example">(defmacro inc (var)
+    (list 'setq var (list '1+ var)))
+</pre>
+
+<pre class="example">(macroexpand '(inc r))
+     ⇒ (setq r (1+ r))
+</pre>
+
+<pre class="example">(defmacro inc2 (var1 var2)
+    (list 'progn (list 'inc var1) (list 'inc var2)))
+</pre>
+
+<pre class="example">(macroexpand '(inc2 r s))
+     ⇒ (progn (inc r) (inc s))  ; <span class="roman"><code>inc</code> not expanded here.</span>
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="macroexpand-all">Function: <strong>macroexpand-all</strong> <em>form &amp;optional environment</em>
+</dt> <dd>
+<p><code>macroexpand-all</code> expands macros like <code>macroexpand</code>, but will look for and expand all macros in <var>form</var>, not just at the top-level. If no macros are expanded, the return value is <code>eq</code> to <var>form</var>. </p> <p>Repeating the example used for <code>macroexpand</code> above with <code>macroexpand-all</code>, we see that <code>macroexpand-all</code> <em>does</em> expand the embedded calls to <code>inc</code>: </p> <div class="example"> <pre class="example">(macroexpand-all '(inc2 r s))
+     ⇒ (progn (setq r (1+ r)) (setq s (1+ s)))
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="macroexpand-1">Function: <strong>macroexpand-1</strong> <em>form &amp;optional environment</em>
+</dt> <dd><p>This function expands macros like <code>macroexpand</code>, but it only performs one step of the expansion: if the result is another macro call, <code>macroexpand-1</code> will not expand it. </p></dd>
+</dl><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/Expansion.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Expansion.html</a>
+  </p>
+</div>