elisp: Multiple Queries
19.8 Asking Multiple Y-or-N Questions
=====================================
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
‘map-y-or-n-p’ 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.
-- Function: map-y-or-n-p prompter actor list &optional help
action-alist no-cursor-in-echo-area
This function asks the user a series of questions, reading a
single-character answer in the echo area for each one.
The value of LIST 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 should expect no arguments, and should return
either the next object to ask about, or ‘nil’, meaning to stop
asking questions.
The argument PROMPTER specifies how to ask each question. If
PROMPTER is a string, the question text is computed like this:
(format PROMPTER OBJECT)
where OBJECT is the next object to ask about (as obtained from
LIST).
If not a string, PROMPTER should be a function of one argument (the
next object to ask about) and should return the question text. If
the value is a string, that is the question to ask the user. The
function can also return ‘t’, meaning do act on this object (and
don’t ask the user), or ‘nil’, meaning ignore this object (and
don’t ask the user).
The argument ACTOR says how to act on the answers that the user
gives. It should be a function of one argument, and it is called
with each object that the user says yes for. Its argument is
always an object obtained from LIST.
If the argument HELP is given, it should be a list of this form:
(SINGULAR PLURAL ACTION)
where SINGULAR is a string containing a singular noun that
describes the objects conceptually being acted on, PLURAL is the
corresponding plural noun, and ACTION is a transitive verb
describing what ACTOR does.
If you don’t specify HELP, the default is ‘("object" "objects" "act
on")’.
Each time a question is asked, the user may enter ‘y’, ‘Y’, or
<SPC> to act on that object; ‘n’, ‘N’, or <DEL> to skip that
object; ‘!’ to act on all following objects; <ESC> or ‘q’ to exit
(skip all following objects); ‘.’ (period) to act on the current
object and then exit; or ‘C-h’ to get help. These are the same
answers that ‘query-replace’ accepts. The keymap
‘query-replace-map’ defines their meaning for ‘map-y-or-n-p’ as
well as for ‘query-replace’; see 
Search and Replace.
You can use ACTION-ALIST to specify additional possible answers and
what they mean. It is an alist of elements of the form ‘(CHAR
FUNCTION HELP)’, each of which defines one additional answer. In
this element, CHAR is a character (the answer); FUNCTION is a
function of one argument (an object from LIST); HELP is a string.
When the user responds with CHAR, ‘map-y-or-n-p’ calls FUNCTION.
If it returns non-‘nil’, the object is considered acted upon, and
‘map-y-or-n-p’ advances to the next object in LIST. If it returns
‘nil’, the prompt is repeated for the same object.
Normally, ‘map-y-or-n-p’ binds ‘cursor-in-echo-area’ while
prompting. But if NO-CURSOR-IN-ECHO-AREA is non-‘nil’, it does not
do that.
If ‘map-y-or-n-p’ is called in a command that was invoked using the
Info::) is either ‘nil’ 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 ‘last-nonmenu-event’ to a
suitable value around the call.
The return value of ‘map-y-or-n-p’ is the number of objects acted
on.
Info Catalog
elisp: Yes-or-No Queries
elisp: Minibuffers
elisp: Reading a Password