diff options
Diffstat (limited to 'devdocs/elisp/interactive-call.html')
| -rw-r--r-- | devdocs/elisp/interactive-call.html | 38 |
1 files changed, 38 insertions, 0 deletions
diff --git a/devdocs/elisp/interactive-call.html b/devdocs/elisp/interactive-call.html new file mode 100644 index 00000000..71887ec3 --- /dev/null +++ b/devdocs/elisp/interactive-call.html @@ -0,0 +1,38 @@ + <h3 class="section">Interactive Call</h3> <p>After the command loop has translated a key sequence into a command, it invokes that command using the function <code>command-execute</code>. If the command is a function, <code>command-execute</code> calls <code>call-interactively</code>, which reads the arguments and calls the command. You can also call these functions yourself. </p> <p>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 (see <a href="keymaps">Keymaps</a>). </p> <dl> <dt id="commandp">Function: <strong>commandp</strong> <em>object &optional for-call-interactively</em> +</dt> <dd> +<p>This function returns <code>t</code> if <var>object</var> is a command. Otherwise, it returns <code>nil</code>. </p> <p>Commands include strings and vectors (which are treated as keyboard macros), lambda expressions that contain a top-level <code>interactive</code> form (see <a href="using-interactive">Using Interactive</a>), byte-code function objects made from such lambda expressions, autoload objects that are declared as interactive (non-<code>nil</code> fourth argument to <code>autoload</code>), and some primitive functions. Also, a symbol is considered a command if it has a non-<code>nil</code> <code>interactive-form</code> property, or if its function definition satisfies <code>commandp</code>. </p> <p>If <var>for-call-interactively</var> is non-<code>nil</code>, then <code>commandp</code> returns <code>t</code> only for objects that <code>call-interactively</code> could call—thus, not for keyboard macros. </p> <p>See <code>documentation</code> in <a href="accessing-documentation">Accessing Documentation</a>, for a realistic example of using <code>commandp</code>. </p> +</dd> +</dl> <dl> <dt id="call-interactively">Function: <strong>call-interactively</strong> <em>command &optional record-flag keys</em> +</dt> <dd> +<p>This function calls the interactively callable function <var>command</var>, providing arguments according to its interactive calling specifications. It returns whatever <var>command</var> returns. </p> <p>If, for instance, you have a function with the following signature: </p> <div class="example"> <pre class="example">(defun foo (begin end) + (interactive "r") + ...) +</pre> +</div> <p>then saying </p> <div class="example"> <pre class="example">(call-interactively 'foo) +</pre> +</div> <p>will call <code>foo</code> with the region (<code>point</code> and <code>mark</code>) as the arguments. </p> <p>An error is signaled if <var>command</var> 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 <var>command</var> is a symbol, then <code>call-interactively</code> uses its function definition. </p> <p>If <var>record-flag</var> is non-<code>nil</code>, then this command and its arguments are unconditionally added to the list <code>command-history</code>. Otherwise, the command is added only if it uses the minibuffer to read an argument. See <a href="command-history">Command History</a>. </p> <p>The argument <var>keys</var>, 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 <var>keys</var> is omitted or <code>nil</code>, the default is the return value of <code>this-command-keys-vector</code>. See <a href="command-loop-info#Definition-of-this_002dcommand_002dkeys_002dvector">Definition of this-command-keys-vector</a>. </p> +</dd> +</dl> <dl> <dt id="funcall-interactively">Function: <strong>funcall-interactively</strong> <em>function &rest arguments</em> +</dt> <dd><p>This function works like <code>funcall</code> (see <a href="calling-functions">Calling Functions</a>), but it makes the call look like an interactive invocation: a call to <code>called-interactively-p</code> inside <var>function</var> will return <code>t</code>. If <var>function</var> is not a command, it is called without signaling an error. </p></dd> +</dl> <dl> <dt id="command-execute">Function: <strong>command-execute</strong> <em>command &optional record-flag keys special</em> +</dt> <dd> + <p>This function executes <var>command</var>. The argument <var>command</var> must satisfy the <code>commandp</code> predicate; i.e., it must be an interactively callable function or a keyboard macro. </p> <p>A string or vector as <var>command</var> is executed with <code>execute-kbd-macro</code>. A function is passed to <code>call-interactively</code> (see above), along with the <var>record-flag</var> and <var>keys</var> arguments. </p> <p>If <var>command</var> is a symbol, its function definition is used in its place. A symbol with an <code>autoload</code> 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. </p> <p>The argument <var>special</var>, if given, means to ignore the prefix argument and not clear it. This is used for executing special events (see <a href="special-events">Special Events</a>). </p> +</dd> +</dl> <dl> <dt id="execute-extended-command">Command: <strong>execute-extended-command</strong> <em>prefix-argument</em> +</dt> <dd> + <p>This function reads a command name from the minibuffer using <code>completing-read</code> (see <a href="completion">Completion</a>). Then it uses <code>command-execute</code> to call the specified command. Whatever that command returns becomes the value of <code>execute-extended-command</code>. </p> <p>If the command asks for a prefix argument, it receives the value <var>prefix-argument</var>. If <code>execute-extended-command</code> is called interactively, the current raw prefix argument is used for <var>prefix-argument</var>, and thus passed on to whatever command is run. </p> <p><code>execute-extended-command</code> is the normal definition of <kbd>M-x</kbd>, so it uses the string ‘<samp><span class="nolinebreak">M-x</span> </samp>’ as a prompt. (It would be better to take the prompt from the events used to invoke <code>execute-extended-command</code>, but that is painful to implement.) A description of the value of the prefix argument, if any, also becomes part of the prompt. </p> <div class="example"> <pre class="example">(execute-extended-command 3) +---------- Buffer: Minibuffer ---------- +3 M-x forward-word <span class="key">RET</span> +---------- Buffer: Minibuffer ---------- + ⇒ t +</pre> +</div> <p>This command heeds the <code>read-extended-command-predicate</code> variable, which can filter out commands that are not applicable to the current major mode (or enabled minor modes). By default, the value of this variable is <code>nil</code>, and no commands are filtered out. However, customizing it to invoke the function <code>command-completion-default-include-p</code> will perform mode-dependent filtering. <code>read-extended-command-predicate</code> can be any predicate function; it will be called with two parameters: the command’s symbol and the current buffer. If should return non-<code>nil</code> if the command is to be included when completing in that buffer. </p> +</dd> +</dl> <dl> <dt id="execute-extended-command-for-buffer">Command: <strong>execute-extended-command-for-buffer</strong> <em>prefix-argument</em> +</dt> <dd><p>This is like <code>execute-extended-command</code>, but limits the commands offered for completion to those commands that are of particular relevance to the current major mode (and enabled minor modes). This includes commands that are tagged with the modes (see <a href="using-interactive">Using Interactive</a>), and also commands that are bound to locally active keymaps. This command is the normal definition of <kbd>M-S-x</kbd> (that’s “meta shift x”). </p></dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Interactive-Call.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Interactive-Call.html</a> + </p> +</div> |