Info Catalog elisp: Defining Commands elisp: Command Loop elisp: Distinguish Interactive

elisp: Interactive Call

 
 20.3 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.
 
    Note that the term “command”, in this context, refers to an
 interactively callable function (or function-like object), or a keyboard
 macro.  It does not refer to the key sequence used to invoke a command
 (Keymaps).
 
  -- Function: commandp object &optional for-call-interactively
      This function returns ‘t’ if OBJECT is a command.  Otherwise, it
      returns ‘nil’.
 
      Commands include strings and vectors (which are treated as keyboard
      macros), lambda expressions that contain a top-level ‘interactive’
      form (Using 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
      primitive functions.  Also, a symbol is considered a command if it
      has a non-‘nil’ ‘interactive-form’ property, or if its function
      definition satisfies ‘commandp’.
 
      If FOR-CALL-INTERACTIVELY is non-‘nil’, then ‘commandp’ returns ‘t’
      only for objects that ‘call-interactively’ could call—thus, not for
      keyboard macros.
 
      See ‘documentation’ in 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,
      providing arguments according to its interactive calling
      specifications.  It returns whatever COMMAND returns.
 
      If, for instance, you have a function with the following signature:
 
           (defun foo (begin end)
             (interactive "r")
             ...)
 
      then saying
 
           (call-interactively 'foo)
 
      will call ‘foo’ with the region (‘point’ and ‘mark’) as the
      arguments.
 
      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
      COMMAND is a symbol, then ‘call-interactively’ uses its function
      definition.
 
      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.  Command History.
 
      The argument KEYS, if given, should be a vector which specifies the
      sequence of events to supply if the command inquires which events
      were used to invoke it.  If KEYS is omitted or ‘nil’, the default
      is the return value of ‘this-command-keys-vector’.  
      Definition of this-command-keys-vector.
 
  -- Function: funcall-interactively function &rest arguments
      This function works like ‘funcall’ (Calling Functions), but
      it makes the call look like an interactive invocation: a call to
      ‘called-interactively-p’ inside FUNCTION will return ‘t’.  If
      FUNCTION is not a command, it is called without signaling an error.
 
  -- 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’ (see above), along
      with the RECORD-FLAG and KEYS arguments.
 
      If COMMAND is a symbol, its function definition is used 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 SPECIAL, if given, means to ignore the prefix argument
      and not clear it.  This is used for executing special events (
      Special Events).
 
  -- Command: execute-extended-command prefix-argument
      This function reads a command name from the minibuffer using
      ‘completing-read’ (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 3)
           ---------- Buffer: Minibuffer ----------
           3 M-x forward-word RET
           ---------- Buffer: Minibuffer ----------
                ⇒ t
 

Info Catalog elisp: Defining Commands elisp: Command Loop elisp: Distinguish Interactive