path: root/devdocs/elisp/declare-form.html

 <h3 class="section">The declare Form</h3>  <p><code>declare</code> is a special macro which can be used to add meta properties to a function or macro: for example, marking it as obsolete, or giving its forms a special <tt class="key">TAB</tt> indentation convention in Emacs Lisp mode. </p> <dl> <dt id="declare">Macro: <strong>declare</strong> <em>specs…</em>
</dt> <dd>
<p>This macro ignores its arguments and evaluates to <code>nil</code>; it has no run-time effect. However, when a <code>declare</code> form occurs in the <var>declare</var> argument of a <code>defun</code> or <code>defsubst</code> function definition (see <a href="defining-functions">Defining Functions</a>) or a <code>defmacro</code> macro definition (see <a href="defining-macros">Defining Macros</a>), it appends the properties specified by <var>specs</var> to the function or macro. This work is specially performed by <code>defun</code>, <code>defsubst</code>, and <code>defmacro</code>. </p> <p>Each element in <var>specs</var> should have the form <code>(<var>property</var>
<var>args</var>…)</code>, which should not be quoted. These have the following effects: </p> <dl compact> <dt><code>(advertised-calling-convention <var>signature</var> <var>when</var>)</code></dt> <dd>
<p>This acts like a call to <code>set-advertised-calling-convention</code> (see <a href="obsolete-functions">Obsolete Functions</a>); <var>signature</var> specifies the correct argument list for calling the function or macro, and <var>when</var> should be a string indicating when the old argument list was first made obsolete. </p> </dd> <dt><code>(debug <var>edebug-form-spec</var>)</code></dt> <dd>
<p>This is valid for macros only. When stepping through the macro with Edebug, use <var>edebug-form-spec</var>. See <a href="instrumenting-macro-calls">Instrumenting Macro Calls</a>. </p> </dd> <dt><code>(doc-string <var>n</var>)</code></dt> <dd>
<p>This is used when defining a function or macro which itself will be used to define entities like functions, macros, or variables. It indicates that the <var>n</var>th argument, if any, should be considered as a documentation string. </p> </dd> <dt><code>(indent <var>indent-spec</var>)</code></dt> <dd>
<p>Indent calls to this function or macro according to <var>indent-spec</var>. This is typically used for macros, though it works for functions too. See <a href="indenting-macros">Indenting Macros</a>. </p> </dd> <dt><code>(interactive-only <var>value</var>)</code></dt> <dd>
<p>Set the function’s <code>interactive-only</code> property to <var>value</var>. See <a href="defining-commands#The-interactive_002donly-property">The interactive-only property</a>. </p> </dd> <dt><code>(obsolete <var>current-name</var> <var>when</var>)</code></dt> <dd>
<p>Mark the function or macro as obsolete, similar to a call to <code>make-obsolete</code> (see <a href="obsolete-functions">Obsolete Functions</a>). <var>current-name</var> should be a symbol (in which case the warning message says to use that instead), a string (specifying the warning message), or <code>nil</code> (in which case the warning message gives no extra details). <var>when</var> should be a string indicating when the function or macro was first made obsolete. </p> </dd> <dt><code>(compiler-macro <var>expander</var>)</code></dt> <dd>
<p>This can only be used for functions, and tells the compiler to use <var>expander</var> as an optimization function. When encountering a call to the function, of the form <code>(<var>function</var> <var>args</var>…)</code>, the macro expander will call <var>expander</var> with that form as well as with <var>args</var>…, and <var>expander</var> can either return a new expression to use instead of the function call, or it can return just the form unchanged, to indicate that the function call should be left alone. <var>expander</var> can be a symbol, or it can be a form <code>(lambda (<var>arg</var>) <var>body</var>)</code> in which case <var>arg</var> will hold the original function call expression, and the (unevaluated) arguments to the function can be accessed using the function’s formal arguments. </p> </dd> <dt><code>(gv-expander <var>expander</var>)</code></dt> <dd>
<p>Declare <var>expander</var> to be the function to handle calls to the macro (or function) as a generalized variable, similarly to <code>gv-define-expander</code>. <var>expander</var> can be a symbol or it can be of the form <code>(lambda
(<var>arg</var>) <var>body</var>)</code> in which case that function will additionally have access to the macro (or function)’s arguments. </p> </dd> <dt><code>(gv-setter <var>setter</var>)</code></dt> <dd>
<p>Declare <var>setter</var> to be the function to handle calls to the macro (or function) as a generalized variable. <var>setter</var> can be a symbol in which case it will be passed to <code>gv-define-simple-setter</code>, or it can be of the form <code>(lambda (<var>arg</var>) <var>body</var>)</code> in which case that function will additionally have access to the macro (or function)’s arguments and it will be passed to <code>gv-define-setter</code>. </p> </dd> <dt><code>(completion <var>completion-predicate</var>)</code></dt> <dd>
<p>Declare <var>completion-predicate</var> as a function to determine whether to include the symbol in the list of functions when asking for completions in <kbd>M-x</kbd>. <var>completion-predicate</var> is called with two parameters: The first parameter is the symbol, and the second is the current buffer. </p> </dd> <dt><code>(modes <var>modes</var>)</code></dt> <dd>
<p>Specify that this command is meant to be applicable for <var>modes</var> only. </p> </dd> <dt><code>(pure <var>val</var>)</code></dt> <dd>
<p>If <var>val</var> is non-<code>nil</code>, this function is <em>pure</em> (see <a href="what-is-a-function">What Is a Function</a>). This is the same as the <code>pure</code> property of the function’s symbol (see <a href="standard-properties">Standard Properties</a>). </p> </dd> <dt><code>(side-effect-free <var>val</var>)</code></dt> <dd>
<p>If <var>val</var> is non-<code>nil</code>, this function is free of side effects, so the byte compiler can ignore calls whose value is ignored. This is the same as the <code>side-effect-free</code> property of the function’s symbol, see <a href="standard-properties">Standard Properties</a>. </p> </dd> <dt><code>(speed <var>n</var>)</code></dt> <dd>
<p>Specify the value of <code>native-comp-speed</code> in effect for native compilation of this function (see <a href="native_002dcompilation-variables">Native-Compilation Variables</a>). This allows function-level control of the optimization level used for native code emitted for the function. In particular, if <var>n</var> is -1, native compilation of the function will emit bytecode instead of native code for the function. </p> </dd> <dt><code>no-font-lock-keyword</code></dt> <dd><p>This is valid for macros only. Macros with this declaration are highlighted by font-lock (see <a href="font-lock-mode">Font Lock Mode</a>) as normal functions, not specially as macros. </p></dd> </dl> </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/Declare-Form.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Declare-Form.html</a>
  </p>
</div>