summaryrefslogtreecommitdiff
path: root/devdocs/elisp/a-sample-function-description.html
diff options
context:
space:
mode:
authorCraig Jennings <c@cjennings.net>2025-08-14 22:58:58 -0500
committerCraig Jennings <c@cjennings.net>2025-08-14 22:58:58 -0500
commit82ba818ff456bcd6d56a06226e3f27e98fbb55c3 (patch)
tree158cfc17b2f644a10f063cb546752cfaae12c97f /devdocs/elisp/a-sample-function-description.html
parent9278ddd4ea1a8b1a4c1edaa8894516e3f48d245b (diff)
downloaddotemacs-82ba818ff456bcd6d56a06226e3f27e98fbb55c3.tar.gz
dotemacs-82ba818ff456bcd6d56a06226e3f27e98fbb55c3.zip
removing all downloaded devdocs files
Diffstat (limited to 'devdocs/elisp/a-sample-function-description.html')
-rw-r--r--devdocs/elisp/a-sample-function-description.html32
1 files changed, 0 insertions, 32 deletions
diff --git a/devdocs/elisp/a-sample-function-description.html b/devdocs/elisp/a-sample-function-description.html
deleted file mode 100644
index eddc3d51..00000000
--- a/devdocs/elisp/a-sample-function-description.html
+++ /dev/null
@@ -1,32 +0,0 @@
- <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>&amp;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>&amp;optional</code> when you call the function. </p> <p>The keyword <code>&amp;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>&amp;rest</code> receives, as its value, a list of all the remaining arguments passed to the function. Do not write <code>&amp;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 &amp;optional integer2 &amp;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>&amp;optional</code> and <code>&amp;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 &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/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>