new repository

1 files changed, 61 insertions, 0 deletions

diff --git a/devdocs/elisp/calling-functions.html b/devdocs/elisp/calling-functions.html
new file mode 100644
index 00000000..d840175b
--- /dev/null
+++ b/devdocs/elisp/calling-functions.html
@@ -0,0 +1,61 @@
+ <h3 class="section">Calling Functions</h3>   <p>Defining functions is only half the battle. Functions don’t do anything until you <em>call</em> them, i.e., tell them to run. Calling a function is also known as <em>invocation</em>. </p> <p>The most common way of invoking a function is by evaluating a list. For example, evaluating the list <code>(concat "a" "b")</code> calls the function <code>concat</code> with arguments <code>"a"</code> and <code>"b"</code>. See <a href="evaluation">Evaluation</a>, for a description of evaluation. </p> <p>When you write a list as an expression in your program, you specify which function to call, and how many arguments to give it, in the text of the program. Usually that’s just what you want. Occasionally you need to compute at run time which function to call. To do that, use the function <code>funcall</code>. When you also need to determine at run time how many arguments to pass, use <code>apply</code>. </p> <dl> <dt id="funcall">Function: <strong>funcall</strong> <em>function &amp;rest arguments</em>
+</dt> <dd>
+<p><code>funcall</code> calls <var>function</var> with <var>arguments</var>, and returns whatever <var>function</var> returns. </p> <p>Since <code>funcall</code> is a function, all of its arguments, including <var>function</var>, are evaluated before <code>funcall</code> is called. This means that you can use any expression to obtain the function to be called. It also means that <code>funcall</code> does not see the expressions you write for the <var>arguments</var>, only their values. These values are <em>not</em> evaluated a second time in the act of calling <var>function</var>; the operation of <code>funcall</code> is like the normal procedure for calling a function, once its arguments have already been evaluated. </p> <p>The argument <var>function</var> must be either a Lisp function or a primitive function. Special forms and macros are not allowed, because they make sense only when given the unevaluated argument expressions. <code>funcall</code> cannot provide these because, as we saw above, it never knows them in the first place. </p> <p>If you need to use <code>funcall</code> to call a command and make it behave as if invoked interactively, use <code>funcall-interactively</code> (see <a href="interactive-call">Interactive Call</a>). </p> <div class="example"> <pre class="example">(setq f 'list)
+     ⇒ list
+</pre>
+<pre class="example">(funcall f 'x 'y 'z)
+     ⇒ (x y z)
+</pre>
+<pre class="example">(funcall f 'x 'y '(z))
+     ⇒ (x y (z))
+</pre>
+<pre class="example">(funcall 'and t nil)
+error→ Invalid function: #&lt;subr and&gt;
+</pre>
+</div> <p>Compare these examples with the examples of <code>apply</code>. </p>
+</dd>
+</dl> <dl> <dt id="apply">Function: <strong>apply</strong> <em>function &amp;rest arguments</em>
+</dt> <dd>
+<p><code>apply</code> calls <var>function</var> with <var>arguments</var>, just like <code>funcall</code> but with one difference: the last of <var>arguments</var> is a list of objects, which are passed to <var>function</var> as separate arguments, rather than a single list. We say that <code>apply</code> <em>spreads</em> this list so that each individual element becomes an argument. </p> <p><code>apply</code> with a single argument is special: the first element of the argument, which must be a non-empty list, is called as a function with the remaining elements as individual arguments. Passing two or more arguments will be faster. </p> <p><code>apply</code> returns the result of calling <var>function</var>. As with <code>funcall</code>, <var>function</var> must either be a Lisp function or a primitive function; special forms and macros do not make sense in <code>apply</code>. </p> <div class="example"> <pre class="example">(setq f 'list)
+     ⇒ list
+</pre>
+<pre class="example">(apply f 'x 'y 'z)
+error→ Wrong type argument: listp, z
+</pre>
+<pre class="example">(apply '+ 1 2 '(3 4))
+     ⇒ 10
+</pre>
+<pre class="example">(apply '+ '(1 2 3 4))
+     ⇒ 10
+</pre>
+
+<pre class="example">(apply 'append '((a b c) nil (x y z) nil))
+     ⇒ (a b c x y z)
+</pre>
+
+<pre class="example">(apply '(+ 3 4))
+     ⇒ 7
+</pre>
+</div> <p>For an interesting example of using <code>apply</code>, see <a href="mapping-functions#Definition-of-mapcar">Definition of mapcar</a>. </p>
+</dd>
+</dl>   <p>Sometimes it is useful to fix some of the function’s arguments at certain values, and leave the rest of arguments for when the function is actually called. The act of fixing some of the function’s arguments is called <em>partial application</em> of the function<a id="DOCF12" href="#FOOT12"><sup>12</sup></a>. The result is a new function that accepts the rest of arguments and calls the original function with all the arguments combined. </p> <p>Here’s how to do partial application in Emacs Lisp: </p> <dl> <dt id="apply-partially">Function: <strong>apply-partially</strong> <em>func &amp;rest args</em>
+</dt> <dd>
+<p>This function returns a new function which, when called, will call <var>func</var> with the list of arguments composed from <var>args</var> and additional arguments specified at the time of the call. If <var>func</var> accepts <var>n</var> arguments, then a call to <code>apply-partially</code> with <code><var>m</var> &lt;= <var>n</var></code> arguments will produce a new function of <code><var>n</var> <span class="nolinebreak">-</span> <var>m</var></code> arguments<a id="DOCF13" href="#FOOT13"><sup>13</sup></a>. </p> <p>Here’s how we could define the built-in function <code>1+</code>, if it didn’t exist, using <code>apply-partially</code> and <code>+</code>, another built-in function<a id="DOCF14" href="#FOOT14"><sup>14</sup></a>: </p> <div class="example"> <pre class="example">(defalias '1+ (apply-partially '+ 1)
+  "Increment argument by one.")
+</pre>
+<pre class="example">(1+ 10)
+     ⇒ 11
+</pre>
+</div> </dd>
+</dl>  <p>It is common for Lisp functions to accept functions as arguments or find them in data structures (especially in hook variables and property lists) and call them using <code>funcall</code> or <code>apply</code>. Functions that accept function arguments are often called <em>functionals</em>. </p> <p>Sometimes, when you call a functional, it is useful to supply a no-op function as the argument. Here are two different kinds of no-op function: </p> <dl> <dt id="identity">Function: <strong>identity</strong> <em>argument</em>
+</dt> <dd><p>This function returns <var>argument</var> and has no side effects. </p></dd>
+</dl> <dl> <dt id="ignore">Function: <strong>ignore</strong> <em>&amp;rest arguments</em>
+</dt> <dd><p>This function ignores any <var>arguments</var> and returns <code>nil</code>. </p></dd>
+</dl> <dl> <dt id="always">Function: <strong>always</strong> <em>&amp;rest arguments</em>
+</dt> <dd><p>This function ignores any <var>arguments</var> and returns <code>t</code>. </p></dd>
+</dl> <p>Some functions are user-visible <em>commands</em>, which can be called interactively (usually by a key sequence). It is possible to invoke such a command exactly as though it was called interactively, by using the <code>call-interactively</code> function. See <a href="interactive-call">Interactive Call</a>. </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/Calling-Functions.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Calling-Functions.html</a>
+  </p>
+</div>