diff options
Diffstat (limited to 'devdocs/elisp/defining-functions.html')
| -rw-r--r-- | devdocs/elisp/defining-functions.html | 39 |
1 files changed, 39 insertions, 0 deletions
diff --git a/devdocs/elisp/defining-functions.html b/devdocs/elisp/defining-functions.html new file mode 100644 index 00000000..e04e4b71 --- /dev/null +++ b/devdocs/elisp/defining-functions.html @@ -0,0 +1,39 @@ + <h3 class="section">Defining Functions</h3> <p>We usually give a name to a function when it is first created. This is called <em>defining a function</em>, and we usually do it with the <code>defun</code> macro. This section also describes other ways to define a function. </p> <dl> <dt id="defun">Macro: <strong>defun</strong> <em>name args [doc] [declare] [interactive] body…</em> +</dt> <dd> +<p><code>defun</code> is the usual way to define new Lisp functions. It defines the symbol <var>name</var> as a function with argument list <var>args</var> (see <a href="argument-list">Argument List</a>) and body forms given by <var>body</var>. Neither <var>name</var> nor <var>args</var> should be quoted. </p> <p><var>doc</var>, if present, should be a string specifying the function’s documentation string (see <a href="function-documentation">Function Documentation</a>). <var>declare</var>, if present, should be a <code>declare</code> form specifying function metadata (see <a href="declare-form">Declare Form</a>). <var>interactive</var>, if present, should be an <code>interactive</code> form specifying how the function is to be called interactively (see <a href="interactive-call">Interactive Call</a>). </p> <p>The return value of <code>defun</code> is undefined. </p> <p>Here are some examples: </p> <div class="example"> <pre class="example">(defun foo () 5) +(foo) + ⇒ 5 +</pre> + +<pre class="example">(defun bar (a &optional b &rest c) + (list a b c)) +(bar 1 2 3 4 5) + ⇒ (1 2 (3 4 5)) +</pre> +<pre class="example">(bar 1) + ⇒ (1 nil nil) +</pre> +<pre class="example">(bar) +error→ Wrong number of arguments. +</pre> + +<pre class="example">(defun capitalize-backwards () + "Upcase the last letter of the word at point." + (interactive) + (backward-word 1) + (forward-word 1) + (backward-char 1) + (capitalize-word 1)) +</pre> +</div> <p>Be careful not to redefine existing functions unintentionally. <code>defun</code> redefines even primitive functions such as <code>car</code> without any hesitation or notification. Emacs does not prevent you from doing this, because redefining a function is sometimes done deliberately, and there is no way to distinguish deliberate redefinition from unintentional redefinition. </p> +</dd> +</dl> <dl> <dt id="defalias">Function: <strong>defalias</strong> <em>name definition &optional doc</em> +</dt> <dd> +<p>This function defines the symbol <var>name</var> as a function, with definition <var>definition</var> (which can be any valid Lisp function). Its return value is <em>undefined</em>. </p> <p>If <var>doc</var> is non-<code>nil</code>, it becomes the function documentation of <var>name</var>. Otherwise, any documentation provided by <var>definition</var> is used. </p> <p>Internally, <code>defalias</code> normally uses <code>fset</code> to set the definition. If <var>name</var> has a <code>defalias-fset-function</code> property, however, the associated value is used as a function to call in place of <code>fset</code>. </p> <p>The proper place to use <code>defalias</code> is where a specific function name is being defined—especially where that name appears explicitly in the source file being loaded. This is because <code>defalias</code> records which file defined the function, just like <code>defun</code> (see <a href="unloading">Unloading</a>). </p> <p>By contrast, in programs that manipulate function definitions for other purposes, it is better to use <code>fset</code>, which does not keep such records. See <a href="function-cells">Function Cells</a>. </p> +</dd> +</dl> <p>You cannot create a new primitive function with <code>defun</code> or <code>defalias</code>, but you can use them to change the function definition of any symbol, even one such as <code>car</code> or <code>x-popup-menu</code> whose normal definition is a primitive. However, this is risky: for instance, it is next to impossible to redefine <code>car</code> without breaking Lisp completely. Redefining an obscure function such as <code>x-popup-menu</code> is less dangerous, but it still may not work as you expect. If there are calls to the primitive from C code, they call the primitive’s C definition directly, so changing the symbol’s definition will have no effect on them. </p> <p>See also <code>defsubst</code>, which defines a function like <code>defun</code> and tells the Lisp compiler to perform inline expansion on it. See <a href="inline-functions">Inline Functions</a>. </p> <p>To undefine a function name, use <code>fmakunbound</code>. See <a href="function-cells">Function Cells</a>. </p><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/Defining-Functions.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Defining-Functions.html</a> + </p> +</div> |