path: root/devdocs/elisp/what-is-a-function.html

 <h3 class="section">What Is a Function?</h3>     <p>In a general sense, a function is a rule for carrying out a computation given input values called <em>arguments</em>. The result of the computation is called the <em>value</em> or <em>return value</em> of the function. The computation can also have side effects, such as lasting changes in the values of variables or the contents of data structures (see <a href="intro-eval#Definition-of-side-effect">Definition of side effect</a>). A <em>pure function</em> is a function which, in addition to having no side effects, always returns the same value for the same combination of arguments, regardless of external factors such as machine type or system state. </p> <p>In most computer languages, every function has a name. But in Lisp, a function in the strictest sense has no name: it is an object which can <em>optionally</em> be associated with a symbol (e.g., <code>car</code>) that serves as the function name. See <a href="function-names">Function Names</a>. When a function has been given a name, we usually also refer to that symbol as a “function” (e.g., we refer to “the function <code>car</code>”). In this manual, the distinction between a function name and the function object itself is usually unimportant, but we will take note wherever it is relevant. </p> <p>Certain function-like objects, called <em>special forms</em> and <em>macros</em>, also accept arguments to carry out computations. However, as explained below, these are not considered functions in Emacs Lisp. </p> <p>Here are important terms for functions and function-like objects: </p> <dl compact> <dt><em>lambda expression</em></dt> <dd>
<p>A function (in the strict sense, i.e., a function object) which is written in Lisp. These are described in the following section. See <a href="lambda-expressions">Lambda Expressions</a>. </p> </dd> <dt><em>primitive</em></dt> <dd>
   <p>A function which is callable from Lisp but is actually written in C. Primitives are also called <em>built-in functions</em>, or <em>subrs</em>. Examples include functions like <code>car</code> and <code>append</code>. In addition, all special forms (see below) are also considered primitives. </p> <p>Usually, a function is implemented as a primitive because it is a fundamental part of Lisp (e.g., <code>car</code>), or because it provides a low-level interface to operating system services, or because it needs to run fast. Unlike functions defined in Lisp, primitives can be modified or added only by changing the C sources and recompiling Emacs. See <a href="writing-emacs-primitives">Writing Emacs Primitives</a>. </p> </dd> <dt><em>special form</em></dt> <dd>
<p>A primitive that is like a function but does not evaluate all of its arguments in the usual way. It may evaluate only some of the arguments, or may evaluate them in an unusual order, or several times. Examples include <code>if</code>, <code>and</code>, and <code>while</code>. See <a href="special-forms">Special Forms</a>. </p> </dd> <dt><em>macro</em></dt> <dd>
 <p>A construct defined in Lisp, which differs from a function in that it translates a Lisp expression into another expression which is to be evaluated instead of the original expression. Macros enable Lisp programmers to do the sorts of things that special forms can do. See <a href="macros">Macros</a>. </p> </dd> <dt><em>command</em></dt> <dd>
 <p>An object which can be invoked via the <code>command-execute</code> primitive, usually due to the user typing in a key sequence <em>bound</em> to that command. See <a href="interactive-call">Interactive Call</a>. A command is usually a function; if the function is written in Lisp, it is made into a command by an <code>interactive</code> form in the function definition (see <a href="defining-commands">Defining Commands</a>). Commands that are functions can also be called from Lisp expressions, just like other functions. </p> <p>Keyboard macros (strings and vectors) are commands also, even though they are not functions. See <a href="keyboard-macros">Keyboard Macros</a>. We say that a symbol is a command if its function cell contains a command (see <a href="symbol-components">Symbol Components</a>); such a <em>named command</em> can be invoked with <kbd>M-x</kbd>. </p> </dd> <dt><em>closure</em></dt> <dd>
<p>A function object that is much like a lambda expression, except that it also encloses an environment of lexical variable bindings. See <a href="closures">Closures</a>. </p> </dd> <dt><em>byte-code function</em></dt> <dd>
<p>A function that has been compiled by the byte compiler. See <a href="byte_002dcode-type">Byte-Code Type</a>. </p> </dd> <dt><em>autoload object</em></dt> <dd>
 <p>A place-holder for a real function. If the autoload object is called, Emacs loads the file containing the definition of the real function, and then calls the real function. See <a href="autoload">Autoload</a>. </p>
</dd> </dl> <p>You can use the function <code>functionp</code> to test if an object is a function: </p> <dl> <dt id="functionp">Function: <strong>functionp</strong> <em>object</em>
</dt> <dd><p>This function returns <code>t</code> if <var>object</var> is any kind of function, i.e., can be passed to <code>funcall</code>. Note that <code>functionp</code> returns <code>t</code> for symbols that are function names, and returns <code>nil</code> for special forms. </p></dd>
</dl> <p>It is also possible to find out how many arguments an arbitrary function expects: </p> <dl> <dt id="func-arity">Function: <strong>func-arity</strong> <em>function</em>
</dt> <dd>
<p>This function provides information about the argument list of the specified <var>function</var>. The returned value is a cons cell of the form <code>(<var>min</var> . <var>max</var>)</code>, where <var>min</var> is the minimum number of arguments, and <var>max</var> is either the maximum number of arguments, or the symbol <code>many</code> for functions with <code>&amp;rest</code> arguments, or the symbol <code>unevalled</code> if <var>function</var> is a special form. </p> <p>Note that this function might return inaccurate results in some situations, such as the following: </p> <ul class="no-bullet"> <li>- Functions defined using <code>apply-partially</code> (see <a href="calling-functions">apply-partially</a>). </li>
<li>- Functions that are advised using <code>advice-add</code> (see <a href="advising-named-functions">Advising Named Functions</a>). </li>
<li>- Functions that determine the argument list dynamically, as part of their code. </li>
</ul> </dd>
</dl> <p>Unlike <code>functionp</code>, the next three functions do <em>not</em> treat a symbol as its function definition. </p> <dl> <dt id="subrp">Function: <strong>subrp</strong> <em>object</em>
</dt> <dd>
<p>This function returns <code>t</code> if <var>object</var> is a built-in function (i.e., a Lisp primitive). </p> <div class="example"> <pre class="example">(subrp 'message)            ; <span class="roman"><code>message</code> is a symbol,</span>
     ⇒ nil                 ;   <span class="roman">not a subr object.</span>
</pre>
<pre class="example">(subrp (symbol-function 'message))
     ⇒ t
</pre>
</div> </dd>
</dl> <dl> <dt id="byte-code-function-p">Function: <strong>byte-code-function-p</strong> <em>object</em>
</dt> <dd>
<p>This function returns <code>t</code> if <var>object</var> is a byte-code function. For example: </p> <div class="example"> <pre class="example">(byte-code-function-p (symbol-function 'next-line))
     ⇒ t
</pre>
</div> </dd>
</dl> <dl> <dt id="subr-arity">Function: <strong>subr-arity</strong> <em>subr</em>
</dt> <dd><p>This works like <code>func-arity</code>, but only for built-in functions and without symbol indirection. It signals an error for non-built-in functions. We recommend to use <code>func-arity</code> instead. </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/What-Is-a-Function.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/What-Is-a-Function.html</a>
  </p>
</div>