13.15 The declare Form

declare 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.

Macro: declare specs… ¶

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.

(important-return-value val)

If val is non-nil, the byte compiler will warn about calls to this function that do not use the returned value. This is the same as the important-return-value 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.

(safety n)

Specify the value of compilation-safety in effect for this function. This allows function-level control of the safety level used for the code emitted for the function (see Native-Compilation Variables).

(ftype type &optional function)

Declare type to be the type of this function. This is used for documentation by describe-function. Also it can be used by the native compiler (see Compilation of Lisp to Native Code) for improving code generation and for deriving more precisely the type of other functions without type declaration.

type is a type specifier (see Type Specifiers) in the form (function (arg-1-type … arg-n-type) RETURN-TYPE). Argument types can be interleaved with symbols &optional and &rest to match the function’s arguments (see Features of Argument Lists).

function if present should be the name of function being defined.

Here’s an example of using ftype inside declare to declare a function positive-p that takes an argument of type number and return a boolean:

(defun positive-p (x)
  (declare (ftype (function (number) boolean)))
  (when (> x 0)
    t))

Similarly this declares a function cons-or-number that: expects a first argument being a cons or a number, a second optional argument of type string and return one of the symbols is-cons or is-number:

(defun cons-or-number (x &optional err-msg)
  (declare (ftype (function ((or cons number) &optional string)
			    (member is-cons is-number))))
  (if (consp x)
      'is-cons
    (if (numberp x)
	'is-number
      (error (or err-msg "Unexpected input")))))

For description of additional types, see Lisp Data Types).

Declaring a function with an incorrect type produces undefined behavior and could lead to unexpected results or might even crash Emacs when natively-compiled code is loaded, if it was compiled with compilation-safety level of zero (see compilation-safety). Note also that when redefining (or advising) a type-declared function, the replacement should respect the original signature to avoid such undefined behavior.

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.