path: root/devdocs/elisp/multiple-queries.html

 <h3 class="section">Asking Multiple-Choice Questions</h3> <p>This section describes facilities for asking the user more complex questions or several similar questions. </p>  <p>When you have a series of similar questions to ask, such as “Do you want to save this buffer?” for each buffer in turn, you should use <code>map-y-or-n-p</code> to ask the collection of questions, rather than asking each question individually. This gives the user certain convenient facilities such as the ability to answer the whole series at once. </p> <dl> <dt id="map-y-or-n-p">Function: <strong>map-y-or-n-p</strong> <em>prompter actor list &amp;optional help action-alist no-cursor-in-echo-area</em>
</dt> <dd>
<p>This function asks the user a series of questions, reading a single-character answer in the echo area for each one. </p> <p>The value of <var>list</var> specifies the objects to ask questions about. It should be either a list of objects or a generator function. If it is a function, it will be called with no arguments, and should return either the next object to ask about, or <code>nil</code>, meaning to stop asking questions. </p> <p>The argument <var>prompter</var> specifies how to ask each question. If <var>prompter</var> is a string, the question text is computed like this: </p> <div class="example"> <pre class="example">(format <var>prompter</var> <var>object</var>)
</pre>
</div> <p>where <var>object</var> is the next object to ask about (as obtained from <var>list</var>). See <a href="formatting-strings">Formatting Strings</a>, for more information about <code>format</code>. </p> <p>If <var>prompter</var> is not a string, it should be a function of one argument (the object to ask about) and should return the question text for that object. If the value <var>prompter</var> returns is a string, that is the question to ask the user. The function can also return <code>t</code>, meaning to act on this object without asking the user, or <code>nil</code>, which means to silently ignore this object. </p> <p>The argument <var>actor</var> says how to act on the objects for which the user answers yes. It should be a function of one argument, and will be called with each object from <var>list</var> for which the user answers yes. </p> <p>If the argument <var>help</var> is given, it should be a list of this form: </p> <div class="example"> <pre class="example">(<var>singular</var> <var>plural</var> <var>action</var>)
</pre>
</div> <p>where <var>singular</var> is a string containing a singular noun that describes a single object to be acted on, <var>plural</var> is the corresponding plural noun, and <var>action</var> is a transitive verb describing what <var>actor</var> does with the objects. </p> <p>If you don’t specify <var>help</var>, it defaults to the list <code>("object" "objects" "act on")</code>. </p> <p>Each time a question is asked, the user can answer as follows: </p> <dl compact> <dt>
<kbd>y</kbd>, <kbd>Y</kbd>, or <kbd><span class="key">SPC</span></kbd>
</dt> <dd><p>act on the object </p></dd> <dt>
<kbd>n</kbd>, <kbd>N</kbd>, or <kbd><span class="key">DEL</span></kbd>
</dt> <dd><p>skip the object </p></dd> <dt><kbd>!</kbd></dt> <dd><p>act on all the following objects </p></dd> <dt>
<kbd><span class="key">ESC</span></kbd> or <kbd>q</kbd>
</dt> <dd><p>exit (skip all following objects) </p></dd> <dt>
<kbd>.</kbd> (period)</dt> <dd><p>act on the object and then exit </p></dd> <dt><kbd>C-h</kbd></dt> <dd><p>get help </p></dd> </dl> <p>These are the same answers that <code>query-replace</code> accepts. The keymap <code>query-replace-map</code> defines their meaning for <code>map-y-or-n-p</code> as well as for <code>query-replace</code>; see <a href="search-and-replace">Search and Replace</a>. </p> <p>You can use <var>action-alist</var> to specify additional possible answers and what they mean. If provided, <var>action-alist</var> should be an alist whose elements are of the form <code>(<var>char</var> <var>function</var> <var>help</var>)</code>. Each of the alist elements defines one additional answer. In each element, <var>char</var> is a character (the answer); <var>function</var> is a function of one argument (an object from <var>list</var>); and <var>help</var> is a string. When the user responds with <var>char</var>, <code>map-y-or-n-p</code> calls <var>function</var>. If it returns non-<code>nil</code>, the object is considered to have been acted upon, and <code>map-y-or-n-p</code> advances to the next object in <var>list</var>. If it returns <code>nil</code>, the prompt is repeated for the same object. If the user requests help, the text in <var>help</var> is used to describe these additional answers. </p> <p>Normally, <code>map-y-or-n-p</code> binds <code>cursor-in-echo-area</code> while prompting. But if <var>no-cursor-in-echo-area</var> is non-<code>nil</code>, it does not do that. </p> <p>If <code>map-y-or-n-p</code> is called in a command that was invoked using the mouse—more precisely, if <code>last-nonmenu-event</code> (see <a href="command-loop-info">Command Loop Info</a>) is either <code>nil</code> or a list—then it uses a dialog box or pop-up menu to ask the question. In this case, it does not use keyboard input or the echo area. You can force use either of the mouse or of keyboard input by binding <code>last-nonmenu-event</code> to a suitable value around the call. </p> <p>The return value of <code>map-y-or-n-p</code> is the number of objects acted on. </p>
</dd>
</dl> <p>If you need to ask the user a question that might have more than just 2 answers, use <code>read-answer</code>. </p> <dl> <dt id="read-answer">Function: <strong>read-answer</strong> <em>question answers</em>
</dt> <dd>
 <p>This function prompts the user with text in <var>question</var>, which should end in the ‘<samp>SPC</samp>’ character. The function includes in the prompt the possible responses in <var>answers</var> by appending them to the end of <var>question</var>. The possible responses are provided in <var>answers</var> as an alist whose elements are of the following form: </p> <div class="lisp"> <pre class="lisp">(<var>long-answer</var> <var>short-answer</var> <var>help-message</var>)
</pre>
</div> <p>where <var>long-answer</var> is the complete text of the user response, a string; <var>short-answer</var> is a short form of the same response, a single character or a function key; and <var>help-message</var> is the text that describes the meaning of the answer. If the variable <code>read-answer-short</code> is non-<code>nil</code>, the prompt will show the short variants of the possible answers and the user is expected to type the single characters/keys shown in the prompt; otherwise the prompt will show the long variants of the answers, and the user is expected to type the full text of one of the answers and end by pressing <tt class="key">RET</tt>. If <code>use-dialog-box</code> is non-<code>nil</code>, and this function was invoked by mouse events, the question and the answers will be displayed in a GUI dialog box. </p> <p>The function returns the text of the <var>long-answer</var> selected by the user, regardless of whether long or short answers were shown in the prompt and typed by the user. </p> <p>Here is an example of using this function: </p> <div class="lisp"> <pre class="lisp">(let ((read-answer-short t))
  (read-answer "Foo "
     '(("yes"  ?y "perform the action")
       ("no"   ?n "skip to the next")
       ("all"  ?! "perform for the rest without more questions")
       ("help" ?h "show help")
       ("quit" ?q "exit"))))
</pre>
</div> </dd>
</dl> <dl> <dt id="read-char-from-minibuffer">Function: <strong>read-char-from-minibuffer</strong> <em>prompt &amp;optional chars history</em>
</dt> <dd>
<p>This function uses the minibuffer to read and return a single character. Optionally, it ignores any input that is not a member of <var>chars</var>, a list of accepted characters. The <var>history</var> argument specifies the history list symbol to use; if it is omitted or <code>nil</code>, this function doesn’t use the history. </p> <p>If you bind <code>help-form</code> (see <a href="help-functions">Help Functions</a>) to a non-<code>nil</code> value while calling <code>read-char-from-minibuffer</code>, then pressing <code>help-char</code> causes it to evaluate <code>help-form</code> and display the result. </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/Multiple-Queries.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Multiple-Queries.html</a>
  </p>
</div>