Next: Interactive Codes, Up: Defining Commands
interactive
This section describes how to write the interactive
form that
makes a Lisp function an interactively-callable command, and how to
examine a commands's interactive
form.
This special form declares that the function in which it appears 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 has its effect because the command loop (actually, its subroutinecall-interactively
) scans through the function definition looking for it, before calling the function. Once the function is called, all its body forms including theinteractive
form are executed, but at this timeinteractive
simply returnsnil
without even evaluating its argument.
There are three possibilities for the argument arg-descriptor:
nil
; then the command is called with no
arguments. This leads quickly to an error if the command requires one
or more arguments.
Here's an example of what not to do:
(interactive (list (region-beginning) (region-end) (read-string "Foo: " nil 'my-history)))
Here's how to avoid the problem, by examining point and the mark only after reading the keyboard input:
(interactive (let ((string (read-string "Foo: " nil 'my-history))) (list (region-beginning) (region-end) string)))
(interactive "bFrobnicate buffer: ")
The code letter ‘b’ says to read the name of an existing buffer, with completion. The buffer name is the sole argument passed to the command. The rest of the string is a prompt.
If there is a newline character in the string, it terminates the prompt. If the string does not end there, then the rest of the string should contain another code character and prompt, specifying another argument. You can specify any number of arguments in this way.
The prompt string can use ‘%’ to include previous argument values
(starting with the first argument) in the prompt. This is done using
format
(see Formatting Strings). For example, here is how
you could read the name of an existing buffer followed by a new name to
give to that buffer:
(interactive "bBuffer to rename: \nsRename buffer %s to: ")
If the first character in the string is ‘*’, then an error is signaled if the buffer is read-only.
If the first character in the string is ‘@’, and if the key sequence used to invoke the command includes any mouse events, then the window associated with the first of those events is selected before the command is run.
You can use ‘*’ and ‘@’ together; the order does not matter. Actual reading of arguments is controlled by the rest of the prompt string (starting with the first character that is not ‘*’ or ‘@’).
This function returns the
interactive
form of function. If function is a command (see Interactive Call), the value is a list of the form(interactive
spec)
, where spec is the descriptor specification used by the command'sinteractive
form to compute the function's arguments (see Using Interactive). If function is not a command,interactive-form
returnsnil
.