GNU Info

(elisp)Interactive Call

---

Next: Command Loop Info Prev: Defining Commands Up: Command Loop

---

Enter node , (file) or (file)node

Interactive Call
================

   After the command loop has translated a key sequence into a command
it invokes that command using the function `command-execute'.  If the
command is a function, `command-execute' calls `call-interactively',
which reads the arguments and calls the command.  You can also call
these functions yourself.

 - Function: commandp object
     Returns `t' if OBJECT is suitable for calling interactively; that
     is, if OBJECT is a command.  Otherwise, returns `nil'.

     The interactively callable objects include strings and vectors
     (treated as keyboard macros), lambda expressions that contain a
     top-level call to `interactive', byte-code function objects made
     from such lambda expressions, autoload objects that are declared
     as interactive (non-`nil' fourth argument to `autoload'), and some
     of the primitive functions.

     A symbol satisfies `commandp' if its function definition satisfies
     `commandp'.

     Keys and keymaps are not commands.  Rather, they are used to look
     up commands (Note: Keymaps).

     See `documentation' in Note: Accessing Documentation, for a
     realistic example of using `commandp'.

 - Function: call-interactively command &optional record-flag keys
     This function calls the interactively callable function COMMAND,
     reading arguments according to its interactive calling
     specifications.  An error is signaled if COMMAND is not a function
     or if it cannot be called interactively (i.e., is not a command).
     Note that keyboard macros (strings and vectors) are not accepted,
     even though they are considered commands, because they are not
     functions.

     If RECORD-FLAG is non-`nil', then this command and its arguments
     are unconditionally added to the list `command-history'.
     Otherwise, the command is added only if it uses the minibuffer to
     read an argument.  Note: Command History.

     The argument KEYS, if given, specifies the sequence of events to
     supply if the command inquires which events were used to invoke it.

 - Function: command-execute command &optional record-flag keys special
     This function executes COMMAND.  The argument COMMAND must satisfy
     the `commandp' predicate; i.e., it must be an interactively
     callable function or a keyboard macro.

     A string or vector as COMMAND is executed with
     `execute-kbd-macro'.  A function is passed to
     `call-interactively', along with the optional RECORD-FLAG.

     A symbol is handled by using its function definition in its place.
     A symbol with an `autoload' definition counts as a command if it
     was declared to stand for an interactively callable function.
     Such a definition is handled by loading the specified library and
     then rechecking the definition of the symbol.

     The argument KEYS, if given, specifies the sequence of events to
     supply if the command inquires which events were used to invoke it.

     The argument SPECIAL, if given, means to ignore the prefix
     argument and not clear it.  This is used for executing special
     events (Note: Special Events).

 - Command: execute-extended-command prefix-argument
     This function reads a command name from the minibuffer using
     `completing-read' (Note: Completion).  Then it uses
     `command-execute' to call the specified command.  Whatever that
     command returns becomes the value of `execute-extended-command'.

     If the command asks for a prefix argument, it receives the value
     PREFIX-ARGUMENT.  If `execute-extended-command' is called
     interactively, the current raw prefix argument is used for
     PREFIX-ARGUMENT, and thus passed on to whatever command is run.

     `execute-extended-command' is the normal definition of `M-x', so
     it uses the string `M-x ' as a prompt.  (It would be better to
     take the prompt from the events used to invoke
     `execute-extended-command', but that is painful to implement.)  A
     description of the value of the prefix argument, if any, also
     becomes part of the prompt.

          (execute-extended-command 1)
          ---------- Buffer: Minibuffer ----------
          1 M-x forward-word RET
          ---------- Buffer: Minibuffer ----------
               => t

 - Function: interactive-p
     This function returns `t' if the containing function (the one whose
     code includes the call to `interactive-p') was called
     interactively, with the function `call-interactively'.  (It makes
     no difference whether `call-interactively' was called from Lisp or
     directly from the editor command loop.)  If the containing
     function was called by Lisp evaluation (or with `apply' or
     `funcall'), then it was not called interactively.

   The most common use of `interactive-p' is for deciding whether to
print an informative message.  As a special exception, `interactive-p'
returns `nil' whenever a keyboard macro is being run.  This is to
suppress the informative messages and speed execution of the macro.

   For example:

     (defun foo ()
       (interactive)
       (when (interactive-p)
         (message "foo")))
          => foo
     
     (defun bar ()
       (interactive)
       (setq foobar (list (foo) (interactive-p))))
          => bar
     
     ;; Type `M-x foo'.
          -| foo
     
     ;; Type `M-x bar'.
     ;; This does not print anything.
     
     foobar
          => (nil t)

   The other way to do this sort of job is to make the command take an
argument `print-message' which should be non-`nil' in an interactive
call, and use the `interactive' spec to make sure it is non-`nil'.
Here's how:

     (defun foo (&optional print-message)
       (interactive "p")
       (when print-message
         (message "foo")))

   The numeric prefix argument, provided by `p', is never `nil'.