From 754bbf7a25a8dda49b5d08ef0d0443bbf5af0e36 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Sun, 7 Apr 2024 13:41:34 -0500
Subject: new repository

---
 devdocs/elisp/using-interactive.html | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)
 create mode 100644 devdocs/elisp/using-interactive.html

(limited to 'devdocs/elisp/using-interactive.html')

diff --git a/devdocs/elisp/using-interactive.html b/devdocs/elisp/using-interactive.html
new file mode 100644
index 00000000..d658472b
--- /dev/null
+++ b/devdocs/elisp/using-interactive.html
@@ -0,0 +1,28 @@
+ <h4 class="subsection">Using interactive</h4>   <p>This section describes how to write the <code>interactive</code> form that makes a Lisp function an interactively-callable command, and how to examine a command’s <code>interactive</code> form. </p> <dl> <dt id="interactive">Special Form: <strong>interactive</strong> <em>&amp;optional arg-descriptor &amp;rest modes</em>
+</dt> <dd>
+<p>This special form declares that a function is a command, and that it may therefore be called interactively (via <kbd>M-x</kbd> or by entering a key sequence bound to it). The argument <var>arg-descriptor</var> declares how to compute the arguments to the command when the command is called interactively. </p> <p>A command may be called from Lisp programs like any other function, but then the caller supplies the arguments and <var>arg-descriptor</var> has no effect. </p>  <p>The <code>interactive</code> form must be located at top-level in the function body, or in the function symbol’s <code>interactive-form</code> property (see <a href="symbol-properties">Symbol Properties</a>). It has its effect because the command loop looks for it before calling the function (see <a href="interactive-call">Interactive Call</a>). Once the function is called, all its body forms are executed; at this time, if the <code>interactive</code> form occurs within the body, the form simply returns <code>nil</code> without even evaluating its argument. </p> <p>The <var>modes</var> list allows specifying which modes the command is meant to be used in. See <a href="command-modes">Command Modes</a> for more details about the effect of specifying <var>modes</var>, and when to use it. </p> <p>By convention, you should put the <code>interactive</code> form in the function body, as the first top-level form. If there is an <code>interactive</code> form in both the <code>interactive-form</code> symbol property and the function body, the former takes precedence. The <code>interactive-form</code> symbol property can be used to add an interactive form to an existing function, or change how its arguments are processed interactively, without redefining the function. </p>
+</dd>
+</dl> <p>There are three possibilities for the argument <var>arg-descriptor</var>: </p> <ul> <li> It may be omitted or <code>nil</code>; then the command is called with no arguments. This leads quickly to an error if the command requires one or more arguments. </li>
+<li> It may be a string; its contents are a sequence of elements separated by newlines, one for each argument<a id="DOCF15" href="#FOOT15"><sup>15</sup></a>. Each element consists of a code character (see <a href="interactive-codes">Interactive Codes</a>) optionally followed by a prompt (which some code characters use and some ignore). Here is an example: <div class="example"> <pre class="example">(interactive "P\nbFrobnicate buffer: ")
+</pre>
+</div> <p>The code letter ‘<samp>P</samp>’ sets the command’s first argument to the raw command prefix (see <a href="prefix-command-arguments">Prefix Command Arguments</a>). ‘<samp>bFrobnicate buffer: </samp>’ prompts the user with ‘<samp>Frobnicate buffer: </samp>’ to enter the name of an existing buffer, which becomes the second and final argument. </p> <p>The prompt string can use ‘<samp>%</samp>’ to include previous argument values (starting with the first argument) in the prompt. This is done using <code>format-message</code> (see <a href="formatting-strings">Formatting Strings</a>). For example, here is how you could read the name of an existing buffer followed by a new name to give to that buffer: </p> <div class="example"> <pre class="example">(interactive "bBuffer to rename: \nsRename buffer %s to: ")
+</pre>
+</div>   <p>If ‘<samp>*</samp>’ appears at the beginning of the string, then an error is signaled if the buffer is read-only. </p>  <p>If ‘<samp>@</samp>’ appears at the beginning of the string, 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. </p>   <p>If ‘<samp>^</samp>’ appears at the beginning of the string, and if the command was invoked through <em>shift-translation</em>, set the mark and activate the region temporarily, or extend an already active region, before the command is run. If the command was invoked without shift-translation, and the region is temporarily active, deactivate the region before the command is run. Shift-translation is controlled on the user level by <code>shift-select-mode</code>; see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Shift-Selection.html#Shift-Selection">Shift Selection</a> in <cite>The GNU Emacs Manual</cite>. </p> <p>You can use ‘<samp>*</samp>’, ‘<samp>@</samp>’, and <code>^</code> 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 ‘<samp>*</samp>’, ‘<samp>@</samp>’, or ‘<samp>^</samp>’). </p> </li>
+<li> 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. Usually this form will call various functions to read input from the user, most often through the minibuffer (see <a href="minibuffers">Minibuffers</a>) or directly from the keyboard (see <a href="reading-input">Reading Input</a>). <p>Providing point or the mark as an argument value is also common, but if you do this <em>and</em> read input (whether using the minibuffer or not), be sure to get the integer values of point or the mark after reading. 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. </p> <p>Here’s an example of what <em>not</em> to do: </p> <div class="example"> <pre class="example">(interactive
+ (list (region-beginning) (region-end)
+       (read-string "Foo: " nil 'my-history)))
+</pre>
+</div> <p>Here’s how to avoid the problem, by examining point and the mark after reading the keyboard input: </p> <div class="example"> <pre class="example">(interactive
+ (let ((string (read-string "Foo: " nil 'my-history)))
+   (list (region-beginning) (region-end) string)))
+</pre>
+</div> <p><strong>Warning:</strong> the argument values should not include any data types that can’t be printed and then read. Some facilities save <code>command-history</code> in a file to be read in the subsequent sessions; if a command’s arguments contain a data type that prints using ‘<samp>#&lt;…&gt;</samp>’ syntax, those facilities won’t work. </p> <p>There are, however, a few exceptions: it is ok to use a limited set of expressions such as <code>(point)</code>, <code>(mark)</code>, <code>(region-beginning)</code>, and <code>(region-end)</code>, because Emacs recognizes them specially and puts the expression (rather than its value) into the command history. To see whether the expression you wrote is one of these exceptions, run the command, then examine <code>(car command-history)</code>. </p>
+</li>
+</ul>  <dl> <dt id="interactive-form">Function: <strong>interactive-form</strong> <em>function</em>
+</dt> <dd><p>This function returns the <code>interactive</code> form of <var>function</var>. If <var>function</var> is an interactively callable function (see <a href="interactive-call">Interactive Call</a>), the value is the command’s <code>interactive</code> form <code>(interactive <var>spec</var>)</code>, which specifies how to compute its arguments. Otherwise, the value is <code>nil</code>. If <var>function</var> is a symbol, its function definition is used. </p></dd>
+</dl><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright &copy; 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/Using-Interactive.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Using-Interactive.html</a>
+  </p>
+</div>
-- 
cgit v1.2.3