diff options
Diffstat (limited to 'devdocs/elisp/argument-list.html')
| -rw-r--r-- | devdocs/elisp/argument-list.html | 25 |
1 files changed, 25 insertions, 0 deletions
diff --git a/devdocs/elisp/argument-list.html b/devdocs/elisp/argument-list.html new file mode 100644 index 00000000..3c7b7d4a --- /dev/null +++ b/devdocs/elisp/argument-list.html @@ -0,0 +1,25 @@ + <h4 class="subsection">Features of Argument Lists</h4> <p>Our simple sample function, <code>(lambda (a b c) (+ a b c))</code>, specifies three argument variables, so it must be called with three arguments: if you try to call it with only two arguments or four arguments, you get a <code>wrong-number-of-arguments</code> error (see <a href="errors">Errors</a>). </p> <p>It is often convenient to write a function that allows certain arguments to be omitted. For example, the function <code>substring</code> accepts three arguments—a string, the start index and the end index—but the third argument defaults to the <var>length</var> of the string if you omit it. It is also convenient for certain functions to accept an indefinite number of arguments, as the functions <code>list</code> and <code>+</code> do. </p> <p>To specify optional arguments that may be omitted when a function is called, simply include the keyword <code>&optional</code> before the optional arguments. To specify a list of zero or more extra arguments, include the keyword <code>&rest</code> before one final argument. </p> <p>Thus, the complete syntax for an argument list is as follows: </p> <div class="example"> <pre class="example">(<var>required-vars</var>… + <span class="roman">[</span>&optional <span class="roman">[</span><var>optional-vars</var>…<span class="roman">]</span><span class="roman">]</span> + <span class="roman">[</span>&rest <var>rest-var</var><span class="roman">]</span>) +</pre> +</div> <p>The square brackets indicate that the <code>&optional</code> and <code>&rest</code> clauses, and the variables that follow them, are optional. </p> <p>A call to the function requires one actual argument for each of the <var>required-vars</var>. There may be actual arguments for zero or more of the <var>optional-vars</var>, and there cannot be any actual arguments beyond that unless the lambda list uses <code>&rest</code>. In that case, there may be any number of extra actual arguments. </p> <p>If actual arguments for the optional and rest variables are omitted, then they always default to <code>nil</code>. There is no way for the function to distinguish between an explicit argument of <code>nil</code> and an omitted argument. However, the body of the function is free to consider <code>nil</code> an abbreviation for some other meaningful value. This is what <code>substring</code> does; <code>nil</code> as the third argument to <code>substring</code> means to use the length of the string supplied. </p> <blockquote> <p><b>Common Lisp note:</b> Common Lisp allows the function to specify what default value to use when an optional argument is omitted; Emacs Lisp always uses <code>nil</code>. Emacs Lisp does not support <code>supplied-p</code> variables that tell you whether an argument was explicitly passed. </p> +</blockquote> <p>For example, an argument list that looks like this: </p> <div class="example"> <pre class="example">(a b &optional c d &rest e) +</pre> +</div> <p>binds <code>a</code> and <code>b</code> to the first two actual arguments, which are required. If one or two more arguments are provided, <code>c</code> and <code>d</code> are bound to them respectively; any arguments after the first four are collected into a list and <code>e</code> is bound to that list. Thus, if there are only two arguments, <code>c</code>, <code>d</code> and <code>e</code> are <code>nil</code>; if two or three arguments, <code>d</code> and <code>e</code> are <code>nil</code>; if four arguments or fewer, <code>e</code> is <code>nil</code>. Note that exactly five arguments with an explicit <code>nil</code> argument provided for <code>e</code> will cause that <code>nil</code> argument to be passed as a list with one element, <code>(nil)</code>, as with any other single value for <code>e</code>. </p> <p>There is no way to have required arguments following optional ones—it would not make sense. To see why this must be so, suppose that <code>c</code> in the example were optional and <code>d</code> were required. Suppose three actual arguments are given; which variable would the third argument be for? Would it be used for the <var>c</var>, or for <var>d</var>? One can argue for both possibilities. Similarly, it makes no sense to have any more arguments (either required or optional) after a <code>&rest</code> argument. </p> <p>Here are some examples of argument lists and proper calls: </p> <div class="example"> <pre class="example">(funcall (lambda (n) (1+ n)) ; <span class="roman">One required:</span> + 1) ; <span class="roman">requires exactly one argument.</span> + ⇒ 2 +(funcall (lambda (n &optional n1) ; <span class="roman">One required and one optional:</span> + (if n1 (+ n n1) (1+ n))) ; <span class="roman">1 or 2 arguments.</span> + 1 2) + ⇒ 3 +(funcall (lambda (n &rest ns) ; <span class="roman">One required and one rest:</span> + (+ n (apply '+ ns))) ; <span class="roman">1 or more arguments.</span> + 1 2 3 4 5) + ⇒ 15 +</pre> +</div><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/Argument-List.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Argument-List.html</a> + </p> +</div> |