22.2.1 Using interactive

This section describes how to write the interactive form that makes a Lisp function an interactively-callable command, and how to examine a command’s interactive form.

Special Form: interactive &optional arg-descriptor &rest modes

This special form declares that a function is a command, and that it may therefore be called interactively (via M-x or by entering a key sequence bound to it). The argument arg-descriptor declares how to compute the arguments to the command when the command is called interactively.

A command may be called from Lisp programs like any other function, but then the caller supplies the arguments and arg-descriptor has no effect.

The interactive form must be located at top-level in the function body, or in the function symbol’s interactive-form property (see Symbol Properties). It has its effect because the command loop looks for it before calling the function (see Interactive Call). Once the function is called, all its body forms are executed; at this time, if the interactive form occurs within the body, the form simply returns nil without even evaluating its argument.

The modes list allows specifying which modes the command is meant to be used in. See Specifying Modes For Commands for more details about the effect of specifying modes, and when to use it.

By convention, you should put the interactive form in the function body, as the first top-level form. If there is an interactive form in both the interactive-form symbol property and the function body, the former takes precedence. The interactive-form symbol property can be used to add an interactive form to an existing function, or change how its arguments are processed interactively, without redefining the function.

There are three possibilities for the argument arg-descriptor:

Function: interactive-form function

This function returns the interactive form of function. If function is an interactively callable function (see Interactive Call), the value is the command’s interactive form (interactive spec), which specifies how to compute its arguments. Otherwise, the value is nil. If function is a symbol, its function definition is used. When called on an OClosure, the work is delegated to the generic function oclosure-interactive-form.

Function: oclosure-interactive-form function

Just like interactive-form, this function takes a command and returns its interactive form. The difference is that it is a generic function and it is only called when function is an OClosure (see Open Closures). The purpose is to make it possible for some OClosure types to compute their interactive forms dynamically instead of carrying it in one of their slots.

This is used for example for kmacro functions in order to reduce their memory size, since they all share the same interactive form. It is also used for advice functions, where the interactive form is computed from the interactive forms of its components, so as to make this computation more lazily and to correctly adjust the interactive form when one of its component’s is redefined.



Some elements actually supply two arguments.