Interactive Declarations

When you define a command (using the defun special form in the same way you would define a function) the first of its body forms (after the optional documentation string) must be an interactive declaration.

This form looks like a call to the special form interactive, in actual fact this special form always returns nil and has no side-effects. The only effect of this form is to show the call-command function, which invokes commands, that this function definition is actually a command (i.e. it may be called interactively). The second element of the declaration form (after the interactive symbol) defines how the argument values applied to the command are computed.

The structure of an interactive declaration, then, is:

(interactive [calling-spec])

When a command is defined this is how it is defined with the interactive declaration:

(defun some-command (arg1)
  "Optional documentation string."
  (interactive ...)
  ...

The calling-spec form defines the argument values applied to the command when it is called interactively, it may be one of,

• nil or undefined (i.e. (interactive)); no arguments are given to the command, this type of interactive declaration just shows that the function may be called interactively.
• A string; zero or more lines (each separated by a newline character), each line defines how to compute one argument value. The first character of each line is a code letter defining exactly how to compute the argument, the rest of the line is an optional prompt string which some code letters show the user when prompting for the argument. The currently available code letters are,

  `a'

  Prompt, with completion, for a function object.

  `b'

  Prompt, with completion, for an existing buffer object.

  `B'

  Prompt, with completion, for a buffer; if it doesn't yet exist it will be created.

  `c'

  Prompt for a character.

  `C'

  Prompt with completion for a command.

  `d'

  The position of the cursor in the current window.

  `D'

  Prompt with completion for the name of a directory in the filing system.

  `e'

  The event which caused this command to be invoked.

  `E'

  The event which caused this command, cooked into a string.

  `f'

  Prompt with completion for the name of an existing file.

  `F'

  Prompt with completion for the name of a file; it doesn't have to exist.

  `k'

  Prompt for a single event.

  `m'

  The starting position of the marked block in the current window.

  `M'

  The ending position of the current block.

  `n'

  Prompt for a number.

  `N'

  The prefix argument (see section Prefix Arguments) as a number, if no prefix argument exists, prompt for a number.

  `p'

  The prefix argument as a number, this will be 1 if no prefix argument has been entered.

  `P'

  The raw prefix argument.

  `s'

  Prompt for a string.

  `S'

  Prompt with completion for a symbol.

  `t'

  The symbol t.

  `v'

  Prompt with completion for a variable.

  `x'

  Read one Lisp object.

  `X'

  Read a Lisp object, then evaluate it.

  A null line produces an argument value of nil. Any non-alphabetic characters at the beginning of the calling-spec are used as flags, the currently recognised flags are,

  `*'

  If the active buffer is read-only an error will be signalled.

  `-'

  After building the argument list the block marked in the current window will be unmarked.

• Anything else; the form is evaluated and expected to return a list of arguments to apply to the command.

Some example interactive declarations,

;; No arguments, but the function may be called
;; as a command.
(interactive)

;; One argument, an existing buffer
(interactive "bBuffer to kill:")

;; If buffer isn't read-only, three arguments:
;; nil, a Lisp object and t.
(interactive "*\nxLisp form:\nt")

Go to the first, previous, next, last section, table of contents.