GNU Info

(elisp)Using Interactive

---

Next: Interactive Codes Up: Defining Commands

---

Enter node , (file) or (file)node

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 commands's `interactive' form.

 - Special Form: interactive arg-descriptor
     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 subroutine `call-interactively') scans through the
     function definition looking for it, before calling the function.
     Once the function is called, all its body forms including the
     `interactive' form are executed, but at this time `interactive'
     simply returns `nil' without even evaluating its argument.

   There are three possibilities for the argument ARG-DESCRIPTOR:

   * It may be omitted or `nil'; then the command is called with no
     arguments.  This leads quickly to an error if the command requires
     one or more arguments.

   * It may be a Lisp expression that is not a string; then it should
     be a form that is evaluated to get a list of arguments to pass to
     the command.

     If this expression reads keyboard input (this includes using the
     minibuffer), keep in mind that the integer value of point or the
     mark before reading input may be incorrect after reading input.
     This is because the current buffer may be receiving subprocess
     output; if subprocess output arrives while the command is waiting
     for input, it could relocate point and the mark.

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

   * It may be a string; then its contents should consist of a code
     character followed by a prompt (which some code characters use and
     some ignore).  The prompt ends either with the end of the string
     or with a newline.  Here is a simple example:

          (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' (Note: 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 `@').

 - Function: interactive-form function
     This function returns the `interactive' form of FUNCTION.  If
     FUNCTION is a command (Note: Interactive Call), the value is a
     list of the form `(interactive SPEC)', where SPEC is the
     descriptor specification used by the command's `interactive' form
     to compute the function's arguments (Note: Using Interactive).
     If FUNCTION is not a command, `interactive-form' returns `nil'.