new repository

1 files changed, 89 insertions, 0 deletions

diff --git a/devdocs/elisp/text-from-minibuffer.html b/devdocs/elisp/text-from-minibuffer.html
new file mode 100644
index 00000000..3e795c70
--- /dev/null
+++ b/devdocs/elisp/text-from-minibuffer.html
@@ -0,0 +1,89 @@
+ <h3 class="section">Reading Text Strings with the Minibuffer</h3>  <p>The most basic primitive for minibuffer input is <code>read-from-minibuffer</code>, which can be used to read either a string or a Lisp object in textual form. The function <code>read-regexp</code> is used for reading regular expressions (see <a href="regular-expressions">Regular Expressions</a>), which are a special kind of string. There are also specialized functions for reading commands, variables, file names, etc. (see <a href="completion">Completion</a>). </p> <p>In most cases, you should not call minibuffer input functions in the middle of a Lisp function. Instead, do all minibuffer input as part of reading the arguments for a command, in the <code>interactive</code> specification. See <a href="defining-commands">Defining Commands</a>. </p> <dl> <dt id="read-from-minibuffer">Function: <strong>read-from-minibuffer</strong> <em>prompt &amp;optional initial keymap read history default inherit-input-method</em>
+</dt> <dd>
+<p>This function is the most general way to get input from the minibuffer. By default, it accepts arbitrary text and returns it as a string; however, if <var>read</var> is non-<code>nil</code>, then it uses <code>read</code> to convert the text into a Lisp object (see <a href="input-functions">Input Functions</a>). </p> <p>The first thing this function does is to activate a minibuffer and display it with <var>prompt</var> (which must be a string) as the prompt. Then the user can edit text in the minibuffer. </p> <p>When the user types a command to exit the minibuffer, <code>read-from-minibuffer</code> constructs the return value from the text in the minibuffer. Normally it returns a string containing that text. However, if <var>read</var> is non-<code>nil</code>, <code>read-from-minibuffer</code> reads the text and returns the resulting Lisp object, unevaluated. (See <a href="input-functions">Input Functions</a>, for information about reading.) </p>  <p>The argument <var>default</var> specifies default values to make available through the history commands. It should be a string, a list of strings, or <code>nil</code>. The string or strings become the minibuffer’s “future history”, available to the user with <kbd>M-n</kbd>. </p> <p>If <var>read</var> is non-<code>nil</code>, then <var>default</var> is also used as the input to <code>read</code>, if the user enters empty input. If <var>default</var> is a list of strings, the first string is used as the input. If <var>default</var> is <code>nil</code>, empty input results in an <code>end-of-file</code> error. However, in the usual case (where <var>read</var> is <code>nil</code>), <code>read-from-minibuffer</code> ignores <var>default</var> when the user enters empty input and returns an empty string, <code>""</code>. In this respect, it differs from all the other minibuffer input functions in this chapter. </p> <p>If <var>keymap</var> is non-<code>nil</code>, that keymap is the local keymap to use in the minibuffer. If <var>keymap</var> is omitted or <code>nil</code>, the value of <code>minibuffer-local-map</code> is used as the keymap. Specifying a keymap is the most important way to customize the minibuffer for various applications such as completion. </p> <p>The argument <var>history</var> specifies a history list variable to use for saving the input and for history commands used in the minibuffer. It defaults to <code>minibuffer-history</code>. If <var>history</var> is the symbol <code>t</code>, history is not recorded. You can optionally specify a starting position in the history list as well. See <a href="minibuffer-history">Minibuffer History</a>. </p> <p>If the variable <code>minibuffer-allow-text-properties</code> is non-<code>nil</code>, then the string that is returned includes whatever text properties were present in the minibuffer. Otherwise all the text properties are stripped when the value is returned. </p>  <p>The text properties in <code>minibuffer-prompt-properties</code> are applied to the prompt. By default, this property list defines a face to use for the prompt. This face, if present, is applied to the end of the face list and merged before display. </p> <p>If the user wants to completely control the look of the prompt, the most convenient way to do that is to specify the <code>default</code> face at the end of all face lists. For instance: </p> <div class="lisp"> <pre class="lisp">(read-from-minibuffer
+ (concat
+  (propertize "Bold" 'face '(bold default))
+  (propertize " and normal: " 'face '(default))))
+</pre>
+</div> <p>If the argument <var>inherit-input-method</var> is non-<code>nil</code>, then the minibuffer inherits the current input method (see <a href="input-methods">Input Methods</a>) and the setting of <code>enable-multibyte-characters</code> (see <a href="text-representations">Text Representations</a>) from whichever buffer was current before entering the minibuffer. </p> <p>Use of <var>initial</var> is mostly deprecated; we recommend using a non-<code>nil</code> value only in conjunction with specifying a cons cell for <var>history</var>. See <a href="initial-input">Initial Input</a>. </p>
+</dd>
+</dl> <dl> <dt id="read-string">Function: <strong>read-string</strong> <em>prompt &amp;optional initial history default inherit-input-method</em>
+</dt> <dd>
+<p>This function reads a string from the minibuffer and returns it. The arguments <var>prompt</var>, <var>initial</var>, <var>history</var> and <var>inherit-input-method</var> are used as in <code>read-from-minibuffer</code>. The keymap used is <code>minibuffer-local-map</code>. </p> <p>The optional argument <var>default</var> is used as in <code>read-from-minibuffer</code>, except that, if non-<code>nil</code>, it also specifies a default value to return if the user enters null input. As in <code>read-from-minibuffer</code> it should be a string, a list of strings, or <code>nil</code>, which is equivalent to an empty string. When <var>default</var> is a string, that string is the default value. When it is a list of strings, the first string is the default value. (All these strings are available to the user in the “future minibuffer history”.) </p> <p>This function works by calling the <code>read-from-minibuffer</code> function: </p> <div class="example"> <pre class="example">(read-string <var>prompt</var> <var>initial</var> <var>history</var> <var>default</var> <var>inherit</var>)
+≡
+(let ((value
+       (read-from-minibuffer <var>prompt</var> <var>initial</var> nil nil
+                             <var>history</var> <var>default</var> <var>inherit</var>)))
+  (if (and (equal value "") <var>default</var>)
+      (if (consp <var>default</var>) (car <var>default</var>) <var>default</var>)
+    value))
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="read-regexp">Function: <strong>read-regexp</strong> <em>prompt &amp;optional defaults history</em>
+</dt> <dd>
+<p>This function reads a regular expression as a string from the minibuffer and returns it. If the minibuffer prompt string <var>prompt</var> does not end in ‘<samp>:</samp>’ (followed by optional whitespace), the function adds ‘<samp>: </samp>’ to the end, preceded by the default return value (see below), if that is non-empty. </p> <p>The optional argument <var>defaults</var> controls the default value to return if the user enters null input, and should be one of: a string; <code>nil</code>, which is equivalent to an empty string; a list of strings; or a symbol. </p> <p>If <var>defaults</var> is a symbol, <code>read-regexp</code> consults the value of the variable <code>read-regexp-defaults-function</code> (see below), and if that is non-<code>nil</code> uses it in preference to <var>defaults</var>. The value in this case should be either: </p> <ul class="no-bullet"> <li>- <code>regexp-history-last</code>, which means to use the first element of the appropriate minibuffer history list (see below). </li>
+<li>- A function of no arguments, whose return value (which should be <code>nil</code>, a string, or a list of strings) becomes the value of <var>defaults</var>. </li>
+</ul> <p><code>read-regexp</code> now ensures that the result of processing <var>defaults</var> is a list (i.e., if the value is <code>nil</code> or a string, it converts it to a list of one element). To this list, <code>read-regexp</code> then appends a few potentially useful candidates for input. These are: </p> <ul class="no-bullet"> <li>- The word or symbol at point. </li>
+<li>- The last regexp used in an incremental search. </li>
+<li>- The last string used in an incremental search. </li>
+<li>- The last string or pattern used in query-replace commands. </li>
+</ul> <p>The function now has a list of regular expressions that it passes to <code>read-from-minibuffer</code> to obtain the user’s input. The first element of the list is the default result in case of empty input. All elements of the list are available to the user as the “future minibuffer history” list (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Minibuffer-History.html#Minibuffer-History">future list</a> in <cite>The GNU Emacs Manual</cite>). </p> <p>The optional argument <var>history</var>, if non-<code>nil</code>, is a symbol specifying a minibuffer history list to use (see <a href="minibuffer-history">Minibuffer History</a>). If it is omitted or <code>nil</code>, the history list defaults to <code>regexp-history</code>. </p>
+</dd>
+</dl> <dl> <dt id="read-regexp-defaults-function">User Option: <strong>read-regexp-defaults-function</strong>
+</dt> <dd>
+<p>The function <code>read-regexp</code> may use the value of this variable to determine its list of default regular expressions. If non-<code>nil</code>, the value of this variable should be either: </p> <ul class="no-bullet"> <li>- The symbol <code>regexp-history-last</code>. </li>
+<li>- A function of no arguments that returns either <code>nil</code>, a string, or a list of strings. </li>
+</ul> <p>See <code>read-regexp</code> above for details of how these values are used. </p>
+</dd>
+</dl> <dl> <dt id="minibuffer-allow-text-properties">Variable: <strong>minibuffer-allow-text-properties</strong>
+</dt> <dd>
+<p>If this variable is <code>nil</code>, then <code>read-from-minibuffer</code> and <code>read-string</code> strip all text properties from the minibuffer input before returning it. However, <code>read-no-blanks-input</code> (see below), as well as <code>read-minibuffer</code> and related functions (see <a href="object-from-minibuffer">Reading Lisp Objects With the Minibuffer</a>), and all functions that do minibuffer input with completion, remove the <code>face</code> property unconditionally, regardless of the value of this variable. </p> <p>If this variable is non-<code>nil</code>, most text properties on strings from the completion table are preserved—but only on the part of the strings that were completed. </p> <div class="lisp"> <pre class="lisp">(let ((minibuffer-allow-text-properties t))
+  (completing-read "String: " (list (propertize "foobar" 'data 'zot))))
+=&gt; #("foobar" 3 6 (data zot))
+</pre>
+</div> <p>In this example, the user typed ‘<samp>foo</samp>’ and then hit the <kbd>TAB</kbd> key, so the text properties are only preserved on the last three characters. </p>
+</dd>
+</dl> <dl> <dt id="minibuffer-local-map">Variable: <strong>minibuffer-local-map</strong>
+</dt> <dd>
+<p>This is the default local keymap for reading from the minibuffer. By default, it makes the following bindings: </p> <dl compact> <dt><kbd>C-j</kbd></dt> <dd>
+<p><code>exit-minibuffer</code> </p> </dd> <dt><tt class="key">RET</tt></dt> <dd>
+<p><code>exit-minibuffer</code> </p> </dd> <dt><kbd>M-&lt;</kbd></dt> <dd>
+<p><code>minibuffer-beginning-of-buffer</code> </p> </dd> <dt><kbd>C-g</kbd></dt> <dd>
+<p><code>abort-recursive-edit</code> </p> </dd> <dt><kbd>M-n</kbd></dt> <dt><tt class="key">DOWN</tt></dt> <dd>
+<p><code>next-history-element</code> </p> </dd> <dt><kbd>M-p</kbd></dt> <dt><tt class="key">UP</tt></dt> <dd>
+<p><code>previous-history-element</code> </p> </dd> <dt><kbd>M-s</kbd></dt> <dd>
+<p><code>next-matching-history-element</code> </p> </dd> <dt><kbd>M-r</kbd></dt> <dd>
+<p><code>previous-matching-history-element</code> </p> </dd> </dl> </dd>
+</dl> <dl> <dt id="read-no-blanks-input">Function: <strong>read-no-blanks-input</strong> <em>prompt &amp;optional initial inherit-input-method</em>
+</dt> <dd>
+<p>This function reads a string from the minibuffer, but does not allow whitespace characters as part of the input: instead, those characters terminate the input. The arguments <var>prompt</var>, <var>initial</var>, and <var>inherit-input-method</var> are used as in <code>read-from-minibuffer</code>. </p> <p>This is a simplified interface to the <code>read-from-minibuffer</code> function, and passes the value of the <code>minibuffer-local-ns-map</code> keymap as the <var>keymap</var> argument for that function. Since the keymap <code>minibuffer-local-ns-map</code> does not rebind <kbd>C-q</kbd>, it <em>is</em> possible to put a space into the string, by quoting it. </p> <p>This function discards text properties, regardless of the value of <code>minibuffer-allow-text-properties</code>. </p> <div class="example"> <pre class="example">(read-no-blanks-input <var>prompt</var> <var>initial</var>)
+≡
+(let (minibuffer-allow-text-properties)
+  (read-from-minibuffer <var>prompt</var> <var>initial</var> minibuffer-local-ns-map))
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="minibuffer-local-ns-map">Variable: <strong>minibuffer-local-ns-map</strong>
+</dt> <dd>
+<p>This built-in variable is the keymap used as the minibuffer local keymap in the function <code>read-no-blanks-input</code>. By default, it makes the following bindings, in addition to those of <code>minibuffer-local-map</code>: </p> <dl compact> <dt><tt class="key">SPC</tt></dt> <dd>
+ <p><code>exit-minibuffer</code> </p> </dd> <dt><tt class="key">TAB</tt></dt> <dd>
+ <p><code>exit-minibuffer</code> </p> </dd> <dt><kbd>?</kbd></dt> <dd>
+ <p><code>self-insert-and-exit</code> </p>
+</dd> </dl> </dd>
+</dl>  <dl> <dt id="format-prompt">Function: <strong>format-prompt</strong> <em>prompt default &amp;rest format-args</em>
+</dt> <dd>
+<p>Format <var>prompt</var> with default value <var>default</var> according to the <code>minibuffer-default-prompt-format</code> variable. </p> <p><code>minibuffer-default-prompt-format</code> is a format string (defaulting to ‘<samp>" (default %s)"</samp>’ that says how the “default” bit in prompts like ‘<samp>"Local filename (default somefile): "</samp>’ are to be formatted. </p> <p>To allow the users to customize how this is displayed, code that prompts the user for a value (and has a default) should look something along the lines of this code snippet: </p> <div class="lisp"> <pre class="lisp">(read-file-name
+ (format-prompt "Local filename" file)
+ nil file)
+</pre>
+</div> <p>If <var>format-args</var> is <code>nil</code>, <var>prompt</var> is used as a literal string. If <var>format-args</var> is non-<code>nil</code>, <var>prompt</var> is used as a format control string, and <var>prompt</var> and <var>format-args</var> are passed to <code>format</code> (see <a href="formatting-strings">Formatting Strings</a>). </p> <p><code>minibuffer-default-prompt-format</code> can be ‘<samp>""</samp>’, in which case no default values are displayed. </p> <p>If <var>default</var> is <code>nil</code>, there is no default value, and therefore no “default value” string is included in the result value. If <var>default</var> is a non-<code>nil</code> list, the first element of the list is used in the prompt. </p>
+</dd>
+</dl> <dl> <dt id="read-minibuffer-restore-windows">Variable: <strong>read-minibuffer-restore-windows</strong>
+</dt> <dd>
+<p>If this option is non-<code>nil</code> (the default), getting input from the minibuffer will restore, on exit, the window configurations of the frame where the minibuffer was entered from and, if it is different, the frame that owns the minibuffer window. This means that if, for example, a user splits a window while getting input from the minibuffer on the same frame, that split will be undone when exiting the minibuffer. </p> <p>If this option is <code>nil</code>, no such restorations are done. Hence, the window split mentioned above will persist after exiting the minibuffer. </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/Text-from-Minibuffer.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Text-from-Minibuffer.html</a>
+  </p>
+</div>