1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
|
<h4 class="subsubsection">A Sample Function Description</h4> <p>In a function description, the name of the function being described appears first. It is followed on the same line by a list of argument names. These names are also used in the body of the description, to stand for the values of the arguments. </p> <p>The appearance of the keyword <code>&optional</code> in the argument list indicates that the subsequent arguments may be omitted (omitted arguments default to <code>nil</code>). Do not write <code>&optional</code> when you call the function. </p> <p>The keyword <code>&rest</code> (which must be followed by a single argument name) indicates that any number of arguments can follow. The single argument name following <code>&rest</code> receives, as its value, a list of all the remaining arguments passed to the function. Do not write <code>&rest</code> when you call the function. </p> <p>Here is a description of an imaginary function <code>foo</code>: </p> <dl> <dt id="foo">Function: <strong>foo</strong> <em>integer1 &optional integer2 &rest integers</em>
</dt> <dd>
<p>The function <code>foo</code> subtracts <var>integer1</var> from <var>integer2</var>, then adds all the rest of the arguments to the result. If <var>integer2</var> is not supplied, then the number 19 is used by default. </p> <div class="example"> <pre class="example">(foo 1 5 3 9)
⇒ 16
(foo 5)
⇒ 14
</pre>
</div> <p>More generally, </p> <div class="example"> <pre class="example">(foo <var>w</var> <var>x</var> <var>y</var>…)
≡
(+ (- <var>x</var> <var>w</var>) <var>y</var>…)
</pre>
</div> </dd>
</dl> <p>By convention, any argument whose name contains the name of a type (e.g., <var>integer</var>, <var>integer1</var> or <var>buffer</var>) is expected to be of that type. A plural of a type (such as <var>buffers</var>) often means a list of objects of that type. An argument named <var>object</var> may be of any type. (For a list of Emacs object types, see <a href="lisp-data-types">Lisp Data Types</a>.) An argument with any other sort of name (e.g., <var>new-file</var>) is specific to the function; if the function has a documentation string, the type of the argument should be described there (see <a href="documentation">Documentation</a>). </p> <p>See <a href="lambda-expressions">Lambda Expressions</a>, for a more complete description of arguments modified by <code>&optional</code> and <code>&rest</code>. </p> <p>Command, macro, and special form descriptions have the same format, but the word ‘<samp>Function</samp>’ is replaced by ‘<samp>Command</samp>’, ‘<samp>Macro</samp>’, or ‘<samp>Special Form</samp>’, respectively. Commands are simply functions that may be called interactively; macros process their arguments differently from functions (the arguments are not evaluated), but are presented the same way. </p> <p>The descriptions of macros and special forms use a more complex notation to specify optional and repeated arguments, because they can break the argument list down into separate arguments in more complicated ways. ‘<samp><span class="roman">[</span><var>optional-arg</var><span class="roman">]</span></samp>’ means that <var>optional-arg</var> is optional and ‘<samp><var>repeated-args</var>…</samp>’ stands for zero or more arguments. Parentheses are used when several arguments are grouped into additional levels of list structure. Here is an example: </p> <dl> <dt id="count-loop">Special Form: <strong>count-loop</strong> <em>(var [from to [inc]]) body…</em>
</dt> <dd>
<p>This imaginary special form implements a loop that executes the <var>body</var> forms and then increments the variable <var>var</var> on each iteration. On the first iteration, the variable has the value <var>from</var>; on subsequent iterations, it is incremented by one (or by <var>inc</var> if that is given). The loop exits before executing <var>body</var> if <var>var</var> equals <var>to</var>. Here is an example: </p> <div class="example"> <pre class="example">(count-loop (i 0 10)
(prin1 i) (princ " ")
(prin1 (aref vector i))
(terpri))
</pre>
</div> <p>If <var>from</var> and <var>to</var> are omitted, <var>var</var> is bound to <code>nil</code> before the loop begins, and the loop exits if <var>var</var> is non-<code>nil</code> at the beginning of an iteration. Here is an example: </p> <div class="example"> <pre class="example">(count-loop (done)
(if (pending)
(fixit)
(setq done t)))
</pre>
</div> <p>In this special form, the arguments <var>from</var> and <var>to</var> are optional, but must both be present or both absent. If they are present, <var>inc</var> may optionally be specified as well. These arguments are grouped with the argument <var>var</var> into a list, to distinguish them from <var>body</var>, which includes all remaining elements of the form. </p>
</dd>
</dl><div class="_attribution">
<p class="_attribution-p">
Copyright © 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/A-Sample-Function-Description.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/A-Sample-Function-Description.html</a>
</p>
</div>
|
