diff options
Diffstat (limited to 'devdocs/elisp/generic-functions.html')
| -rw-r--r-- | devdocs/elisp/generic-functions.html | 17 |
1 files changed, 17 insertions, 0 deletions
diff --git a/devdocs/elisp/generic-functions.html b/devdocs/elisp/generic-functions.html new file mode 100644 index 00000000..49cb99cc --- /dev/null +++ b/devdocs/elisp/generic-functions.html @@ -0,0 +1,17 @@ + <h3 class="section">Generic Functions</h3> <p>Functions defined using <code>defun</code> have a hard-coded set of assumptions about the types and expected values of their arguments. For example, a function that was designed to handle values of its argument that are either numbers or lists of numbers will fail or signal an error if called with a value of any other type, such as a vector or a string. This happens because the implementation of the function is not prepared to deal with types other than those assumed during the design. </p> <p>By contrast, object-oriented programs use <em>polymorphic functions</em>: a set of specialized functions having the same name, each one of which was written for a certain specific set of argument types. Which of the functions is actually called is decided at run time based on the types of the actual arguments. </p> <p>Emacs provides support for polymorphism. Like other Lisp environments, notably Common Lisp and its Common Lisp Object System (<acronym>CLOS</acronym>), this support is based on <em>generic functions</em>. The Emacs generic functions closely follow <acronym>CLOS</acronym>, including use of similar names, so if you have experience with <acronym>CLOS</acronym>, the rest of this section will sound very familiar. </p> <p>A generic function specifies an abstract operation, by defining its name and list of arguments, but (usually) no implementation. The actual implementation for several specific classes of arguments is provided by <em>methods</em>, which should be defined separately. Each method that implements a generic function has the same name as the generic function, but the method’s definition indicates what kinds of arguments it can handle by <em>specializing</em> the arguments defined by the generic function. These <em>argument specializers</em> can be more or less specific; for example, a <code>string</code> type is more specific than a more general type, such as <code>sequence</code>. </p> <p>Note that, unlike in message-based OO languages, such as C<tt>++</tt> and Simula, methods that implement generic functions don’t belong to a class, they belong to the generic function they implement. </p> <p>When a generic function is invoked, it selects the applicable methods by comparing the actual arguments passed by the caller with the argument specializers of each method. A method is applicable if the actual arguments of the call are compatible with the method’s specializers. If more than one method is applicable, they are combined using certain rules, described below, and the combination then handles the call. </p> <dl> <dt id="cl-defgeneric">Macro: <strong>cl-defgeneric</strong> <em>name arguments [documentation] [options-and-methods…] &rest body</em> +</dt> <dd> +<p>This macro defines a generic function with the specified <var>name</var> and <var>arguments</var>. If <var>body</var> is present, it provides the default implementation. If <var>documentation</var> is present (it should always be), it specifies the documentation string for the generic function, in the form <code>(:documentation <var>docstring</var>)</code>. The optional <var>options-and-methods</var> can be one of the following forms: </p> <dl compact> <dt><code>(declare <var>declarations</var>)</code></dt> <dd><p>A declare form, as described in <a href="declare-form">Declare Form</a>. </p></dd> <dt><code>(:argument-precedence-order &rest <var>args</var>)</code></dt> <dd><p>This form affects the sorting order for combining applicable methods. Normally, when two methods are compared during combination, method arguments are examined left to right, and the first method whose argument specializer is more specific will come before the other one. The order defined by this form overrides that, and the arguments are examined according to their order in this form, and not left to right. </p></dd> <dt><code>(:method [<var>qualifiers</var>…] args &rest body)</code></dt> <dd><p>This form defines a method like <code>cl-defmethod</code> does. </p></dd> </dl> </dd> +</dl> <dl> <dt id="cl-defmethod">Macro: <strong>cl-defmethod</strong> <em>name [extra] [qualifier] arguments [&context (expr spec)…] &rest [docstring] body</em> +</dt> <dd> +<p>This macro defines a particular implementation for the generic function called <var>name</var>. The implementation code is given by <var>body</var>. If present, <var>docstring</var> is the documentation string for the method. The <var>arguments</var> list, which must be identical in all the methods that implement a generic function, and must match the argument list of that function, provides argument specializers of the form <code>(<var>arg</var> <var>spec</var>)</code>, where <var>arg</var> is the argument name as specified in the <code>cl-defgeneric</code> call, and <var>spec</var> is one of the following specializer forms: </p> <dl compact> <dt><code><var>type</var></code></dt> <dd><p>This specializer requires the argument to be of the given <var>type</var>, one of the types from the type hierarchy described below. </p></dd> <dt><code>(eql <var>object</var>)</code></dt> <dd><p>This specializer requires the argument be <code>eql</code> to the given <var>object</var>. </p></dd> <dt><code>(head <var>object</var>)</code></dt> <dd><p>The argument must be a cons cell whose <code>car</code> is <code>eql</code> to <var>object</var>. </p></dd> <dt><code><var>struct-type</var></code></dt> <dd><p>The argument must be an instance of a class named <var>struct-type</var> defined with <code>cl-defstruct</code> (see <a href="https://www.gnu.org/software/emacs/manual/html_node/cl/Structures.html#Structures">Structures</a> in <cite>Common Lisp Extensions for GNU Emacs Lisp</cite>), or of one of its child classes. </p></dd> </dl> <p>Method definitions can make use of a new argument-list keyword, <code>&context</code>, which introduces extra specializers that test the environment at the time the method is run. This keyword should appear after the list of required arguments, but before any <code>&rest</code> or <code>&optional</code> keywords. The <code>&context</code> specializers look much like regular argument specializers—(<var>expr</var> <var>spec</var>)—except that <var>expr</var> is an expression to be evaluated in the current context, and the <var>spec</var> is a value to compare against. For example, <code>&context (overwrite-mode (eql t))</code> will make the method applicable only when <code>overwrite-mode</code> is turned on. The <code>&context</code> keyword can be followed by any number of context specializers. Because the context specializers are not part of the generic function’s argument signature, they may be omitted in methods that don’t require them. </p> <p>The type specializer, <code>(<var>arg</var> <var>type</var>)</code>, can specify one of the <em>system types</em> in the following list. When a parent type is specified, an argument whose type is any of its more specific child types, as well as grand-children, grand-grand-children, etc. will also be compatible. </p> <dl compact> <dt><code>integer</code></dt> <dd><p>Parent type: <code>number</code>. </p></dd> <dt><code>number</code></dt> <dt><code>null</code></dt> <dd><p>Parent type: <code>symbol</code> </p></dd> <dt><code>symbol</code></dt> <dt><code>string</code></dt> <dd><p>Parent type: <code>array</code>. </p></dd> <dt><code>array</code></dt> <dd><p>Parent type: <code>sequence</code>. </p></dd> <dt><code>cons</code></dt> <dd><p>Parent type: <code>list</code>. </p></dd> <dt><code>list</code></dt> <dd><p>Parent type: <code>sequence</code>. </p></dd> <dt><code>marker</code></dt> <dt><code>overlay</code></dt> <dt><code>float</code></dt> <dd><p>Parent type: <code>number</code>. </p></dd> <dt><code>window-configuration</code></dt> <dt><code>process</code></dt> <dt><code>window</code></dt> <dt><code>subr</code></dt> <dt><code>compiled-function</code></dt> <dt><code>buffer</code></dt> <dt><code>char-table</code></dt> <dd><p>Parent type: <code>array</code>. </p></dd> <dt><code>bool-vector</code></dt> <dd><p>Parent type: <code>array</code>. </p></dd> <dt><code>vector</code></dt> <dd><p>Parent type: <code>array</code>. </p></dd> <dt><code>frame</code></dt> <dt><code>hash-table</code></dt> <dt><code>font-spec</code></dt> <dt><code>font-entity</code></dt> <dt><code>font-object</code></dt> </dl> <p>The optional <var>extra</var> element, expressed as ‘<samp>:extra <var>string</var></samp>’, allows you to add more methods, distinguished by <var>string</var>, for the same specializers and qualifiers. </p> <p>The optional <var>qualifier</var> allows combining several applicable methods. If it is not present, the defined method is a <em>primary</em> method, responsible for providing the primary implementation of the generic function for the specialized arguments. You can also define <em>auxiliary methods</em>, by using one of the following values as <var>qualifier</var>: </p> <dl compact> <dt><code>:before</code></dt> <dd><p>This auxiliary method will run before the primary method. More accurately, all the <code>:before</code> methods will run before the primary, in the most-specific-first order. </p></dd> <dt><code>:after</code></dt> <dd><p>This auxiliary method will run after the primary method. More accurately, all such methods will run after the primary, in the most-specific-last order. </p></dd> <dt><code>:around</code></dt> <dd><p>This auxiliary method will run <em>instead</em> of the primary method. The most specific of such methods will be run before any other method. Such methods normally use <code>cl-call-next-method</code>, described below, to invoke the other auxiliary or primary methods. </p></dd> </dl> <p>Functions defined using <code>cl-defmethod</code> cannot be made interactive, i.e. commands (see <a href="defining-commands">Defining Commands</a>), by adding the <code>interactive</code> form to them. If you need a polymorphic command, we recommend defining a normal command that calls a polymorphic function defined via <code>cl-defgeneric</code> and <code>cl-defmethod</code>. </p> +</dd> +</dl> <p>Each time a generic function is called, it builds the <em>effective method</em> which will handle this invocation by combining the applicable methods defined for the function. The process of finding the applicable methods and producing the effective method is called <em>dispatch</em>. The applicable methods are those all of whose specializers are compatible with the actual arguments of the call. Since all of the arguments must be compatible with the specializers, they all determine whether a method is applicable. Methods that explicitly specialize more than one argument are called <em>multiple-dispatch methods</em>. </p> <p>The applicable methods are sorted into the order in which they will be combined. The method whose left-most argument specializer is the most specific one will come first in the order. (Specifying <code>:argument-precedence-order</code> as part of <code>cl-defmethod</code> overrides that, as described above.) If the method body calls <code>cl-call-next-method</code>, the next most-specific method will run. If there are applicable <code>:around</code> methods, the most-specific of them will run first; it should call <code>cl-call-next-method</code> to run any of the less specific <code>:around</code> methods. Next, the <code>:before</code> methods run in the order of their specificity, followed by the primary method, and lastly the <code>:after</code> methods in the reverse order of their specificity. </p> <dl> <dt id="cl-call-next-method">Function: <strong>cl-call-next-method</strong> <em>&rest args</em> +</dt> <dd><p>When invoked from within the lexical body of a primary or an <code>:around</code> auxiliary method, call the next applicable method for the same generic function. Normally, it is called with no arguments, which means to call the next applicable method with the same arguments that the calling method was invoked. Otherwise, the specified arguments are used instead. </p></dd> +</dl> <dl> <dt id="cl-next-method-p">Function: <strong>cl-next-method-p</strong> +</dt> <dd><p>This function, when called from within the lexical body of a primary or an <code>:around</code> auxiliary method, returns non-<code>nil</code> if there is a next method to call. </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/Generic-Functions.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Generic-Functions.html</a> + </p> +</div> |