Next: , Up: Defining Commands

21.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 arg-descriptor

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 Plists). 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.

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.


[1] Some elements actually supply two parameters.