declare
Formdeclare
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 TAB indentation
convention in Emacs Lisp mode.
This macro ignores its arguments and evaluates to nil
; it has
no run-time effect. However, when a declare
form occurs in the
declare argument of a defun
or defsubst
function
definition (see Defining Functions) or a defmacro
macro
definition (see Defining Macros), it appends the properties
specified by specs to the function or macro. This work is
specially performed by defun
, defsubst
, and
defmacro
.
Each element in specs should have the form (property
args…)
, which should not be quoted. These have the
following effects:
(advertised-calling-convention signature when)
This acts like a call to set-advertised-calling-convention
(see Declaring Functions Obsolete); signature specifies the correct
argument list for calling the function or macro, and when should
be a string indicating when the old argument list was first made obsolete.
(debug edebug-form-spec)
This is valid for macros only. When stepping through the macro with Edebug, use edebug-form-spec. See Instrumenting Macro Calls.
(doc-string n)
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 nth argument, if any, should be considered as a documentation string.
(indent indent-spec)
Indent calls to this function or macro according to indent-spec. This is typically used for macros, though it works for functions too. See Indenting Macros.
(interactive-only value)
Set the function’s interactive-only
property to value.
See The interactive-only property.
(obsolete current-name when)
Mark the function or macro as obsolete, similar to a call to
make-obsolete
(see Declaring Functions Obsolete). current-name
should be a symbol (in which case the warning message says to use that
instead), a string (specifying the warning message), or nil
(in
which case the warning message gives no extra details). when
should be a string indicating when the function or macro was first
made obsolete.
(compiler-macro expander)
This can only be used for functions, and tells the compiler to use
expander as an optimization function. When encountering a call to the
function, of the form (function args…)
, the macro
expander will call expander with that form as well as with
args…, and expander 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.
When expander is a lambda form it should be written with
a single argument (i.e., be of the form (lambda (arg)
body)
) because the function’s formal arguments are
automatically added to the lambda’s list of arguments for you.
(gv-expander expander)
Declare expander to be the function to handle calls to the macro (or
function) as a generalized variable, similarly to gv-define-expander
.
expander can be a symbol or it can be of the form (lambda
(arg) body)
in which case that function will additionally have
access to the macro (or function)’s arguments.
(gv-setter setter)
Declare setter to be the function to handle calls to the macro (or
function) as a generalized variable. setter can be a symbol in which
case it will be passed to gv-define-simple-setter
, or it can be of the
form (lambda (arg) body)
in which case that function will
additionally have access to the macro (or function)’s arguments and it will
be passed to gv-define-setter
.
(completion completion-predicate)
Declare completion-predicate as a function to determine whether
to include a function’s symbol in the list of functions when asking
for completions in M-x. This predicate function will only be
called when read-extended-command-predicate
is customized to
command-completion-default-include-p
; by default the value of
read-extended-command-predicate
is nil (see execute-extended-command). The predicate
completion-predicate is called with two arguments: the
function’s symbol and the current buffer.
(modes modes)
Specify that this command is meant to be applicable only to specified modes. See Specifying Modes For Commands.
(interactive-args arg ...)
Specify the arguments that should be stored for repeat-command
.
Each arg is on the form argument-name form
.
(pure val)
If val is non-nil
, this function is pure
(see What Is a Function?). This is the same as the pure
property of the function’s symbol (see Standard Symbol Properties).
(side-effect-free val)
If val is non-nil
, this function is free of side effects,
so the byte compiler can ignore calls whose value is ignored. This is
the same as the side-effect-free
property of the function’s
symbol, see Standard Symbol Properties.
(speed n)
Specify the value of native-comp-speed
in effect for native
compilation of this function (see Native-Compilation Variables).
This allows function-level control of the optimization level used for
native code emitted for the function. In particular, if n is
−1, native compilation of the function will emit bytecode
instead of native code for the function.
no-font-lock-keyword
This is valid for macros only. Macros with this declaration are highlighted by font-lock (see Font Lock Mode) as normal functions, not specially as macros.