procyberian/emacs
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve documentation of 'map-y-or-n-p'

Browse source 
* lisp/emacs-lisp/map-ynp.el (map-y-or-n-p): Doc fix.  (Bug#47833)

* doc/lispref/minibuf.texi (Multiple Queries): Fix the wording in
the description of 'map-y-or-n-p'.
This commit is contained in:
Eli Zaretskii 2021-04-17 11:24:04 +03:00
parent eedad01b4b
commit 1789dcdb35
2 changed files with 98 additions and 65 deletions
Download patch file Download diff file Expand all files Collapse all files

89
doc/lispref/minibuf.texi
View file

@ -2128,9 +2128,10 @@ This function asks the user a series of questions, reading a
single-character answer in the echo area for each one. single-character answer in the echo area for each one.
The value of @var{list} specifies the objects to ask questions about. The value of @var{list} specifies the objects to ask questions about.
It should be either a list of objects or a generator function. If it is It should be either a list of objects or a generator function. If it
a function, it should expect no arguments, and should return either the is a function, it will be called with no arguments, and should return
next object to ask about, or @code{nil}, meaning to stop asking questions. either the next object to ask about, or @code{nil}, meaning to stop
asking questions.
The argument @var{prompter} specifies how to ask each question. If The argument @var{prompter} specifies how to ask each question. If
@var{prompter} is a string, the question text is computed like this: @var{prompter} is a string, the question text is computed like this:
@ -2141,19 +2142,20 @@ The argument @var{prompter} specifies how to ask each question. If
@noindent @noindent
where @var{object} is the next object to ask about (as obtained from where @var{object} is the next object to ask about (as obtained from
@var{list}). @var{list}). @xref{Formatting Strings}, for more information about
@code{format}.
If not a string, @var{prompter} should be a function of one argument If @var{prompter} is not a string, it should be a function of one
(the next object to ask about) and should return the question text. If argument (the object to ask about) and should return the question text
the value is a string, that is the question to ask the user. The for that object. If the value @var{prompter} returns is a string,
function can also return @code{t}, meaning do act on this object (and that is the question to ask the user. The function can also return
don't ask the user), or @code{nil}, meaning ignore this object (and don't @code{t}, meaning to act on this object without asking the user, or
ask the user). @code{nil}, which means to silently ignore this object.
The argument @var{actor} says how to act on the answers that the user The argument @var{actor} says how to act on the objects for which the
gives. It should be a function of one argument, and it is called with user answers yes. It should be a function of one argument, and will
each object that the user says yes for. Its argument is always an be called with each object from @var{LIST} for which the user answers
object obtained from @var{list}. yes.
If the argument @var{help} is given, it should be a list of this form: If the argument @var{help} is given, it should be a list of this form:
@ -2163,34 +2165,49 @@ If the argument @var{help} is given, it should be a list of this form:
@noindent @noindent
where @var{singular} is a string containing a singular noun that where @var{singular} is a string containing a singular noun that
describes the objects conceptually being acted on, @var{plural} is the describes a single object to be acted on, @var{plural} is the
corresponding plural noun, and @var{action} is a transitive verb corresponding plural noun, and @var{action} is a transitive verb
describing what @var{actor} does. describing what @var{actor} does with the objects.
If you don't specify @var{help}, the default is @code{("object" If you don't specify @var{help}, it defaults to the list
"objects" "act on")}. @w{@code{("object" "objects" "act on")}}.
Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or Each time a question is asked, the user can answer as follows:
@key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip
that object; @kbd{!} to act on all following objects; @key{ESC} or @table @asis
@kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on @item @kbd{y}, @kbd{Y}, or @kbd{@key{SPC}}
the current object and then exit; or @kbd{C-h} to get help. These are act on the object
the same answers that @code{query-replace} accepts. The keymap @item @kbd{n}, @kbd{N}, or @kbd{@key{DEL}}
@code{query-replace-map} defines their meaning for @code{map-y-or-n-p} skip the object
as well as for @code{query-replace}; see @ref{Search and Replace}. @item @kbd{!}
act on all the following objects
@item @kbd{@key{ESC}} or @kbd{q}
exit (skip all following objects)
@item @kbd{.} (period)
act on the object and then exit
@item @kbd{C-h}
get help
@end table
@noindent
These are the same answers that @code{query-replace} accepts. The
keymap @code{query-replace-map} defines their meaning for
@code{map-y-or-n-p} as well as for @code{query-replace}; see
@ref{Search and Replace}.
You can use @var{action-alist} to specify additional possible answers You can use @var{action-alist} to specify additional possible answers
and what they mean. It is an alist of elements of the form and what they mean. If provided, @var{action-alist} should be an
@code{(@var{char} @var{function} @var{help})}, each of which defines one alist whose elements are of the form @w{@code{(@var{char}
additional answer. In this element, @var{char} is a character (the @var{function} @var{help})}}. Each of the alist elements defines one
additional answer. In each element, @var{char} is a character (the
answer); @var{function} is a function of one argument (an object from answer); @var{function} is a function of one argument (an object from
@var{list}); @var{help} is a string. @var{list}); and @var{help} is a string. When the user responds with
@var{char}, @code{map-y-or-n-p} calls @var{function}. If it returns
When the user responds with @var{char}, @code{map-y-or-n-p} calls non-@code{nil}, the object is considered to have been acted upon, and
@var{function}. If it returns non-@code{nil}, the object is considered @code{map-y-or-n-p} advances to the next object in @var{list}. If it
acted upon, and @code{map-y-or-n-p} advances to the next object in returns @code{nil}, the prompt is repeated for the same object. If
@var{list}. If it returns @code{nil}, the prompt is repeated for the the user requests help, the text in @var{help} is used to describe
same object. these additional answers.
Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while
prompting. But if @var{no-cursor-in-echo-area} is non-@code{nil}, it prompting. But if @var{no-cursor-in-echo-area} is non-@code{nil}, it

74
lisp/emacs-lisp/map-ynp.el
View file

@ -38,46 +38,62 @@
(defun map-y-or-n-p (prompter actor list &optional help action-alist (defun map-y-or-n-p (prompter actor list &optional help action-alist
no-cursor-in-echo-area) no-cursor-in-echo-area)
"Ask a series of boolean questions. "Ask a boolean question per PROMPTER for each object in LIST, then call ACTOR.
Takes args PROMPTER ACTOR LIST, and optional args HELP and ACTION-ALIST.
LIST is a list of objects, or a function of no arguments to return the next LIST is a list of objects, or a function of no arguments to return the next
object or nil. object; when it returns nil, the list of objects is considered exhausted.
If PROMPTER is a string, the prompt is \(format PROMPTER OBJECT). If not If PROMPTER is a string, it should be a format string to be used to format
a string, PROMPTER is a function of one arg (an object from LIST), which the question as \(format PROMPTER OBJECT).
returns a string to be used as the prompt for that object. If the return If PROMPTER is not a string, it should be a function of one argument, an
value is not a string, it may be nil to ignore the object or non-nil to act object from LIST, which returns a string to be used as the question for
on the object without asking the user. that object. If the function's return value is not a string, it may be
nil to ignore the object, or non-nil to act on the object with ACTOR
without asking the user.
ACTOR is a function of one arg (an object from LIST), ACTOR is a function of one argument, an object from LIST,
which gets called with each object that the user answers `yes' for. which gets called with each object for which the user answers `yes'
to the question presented by PROMPTER.
If HELP is given, it is a list (OBJECT OBJECTS ACTION), The user's answers to the questions may be one of the following:
where OBJECT is a string giving the singular noun for an elt of LIST;
OBJECTS is the plural noun for elts of LIST, and ACTION is a transitive
verb describing ACTOR. The default is \(\"object\" \"objects\" \"act on\").
At the prompts, the user may enter y, Y, or SPC to act on that object; - y, Y, or SPC to act on that object;
n, N, or DEL to skip that object; ! to act on all following objects; - n, N, or DEL to skip that object;
ESC or q to exit (skip all following objects); . (period) to act on the - ! to act on all following objects;
current object and then exit; or \\[help-command] to get help. - ESC or q to exit (skip all following objects);
- . (period) to act on the current object and then exit; or
- \\[help-command] to get help.
If ACTION-ALIST is given, it is an alist (KEY FUNCTION HELP) of extra keys HELP provides information for displaying help when the user
that will be accepted. KEY is a character; FUNCTION is a function of one types \\[help-command]. If HELP is given, it should be a list of
arg (an object from LIST); HELP is a string. When the user hits KEY, the form (OBJECT OBJECTS ACTION), where OBJECT is a string giving
FUNCTION is called. If it returns non-nil, the object is considered the singular noun describing an element of LIST; OBJECTS is the
\"acted upon\", and the next object from LIST is processed. If it returns plural noun describing several elements of LIST, and ACTION is a
nil, the prompt is repeated for the same object. transitive verb describing action by ACTOR on one or more elements
of LIST. If HELP is omitted or nil, it defaults
to \(\"object\" \"objects\" \"act on\").
Final optional argument NO-CURSOR-IN-ECHO-AREA non-nil says not to set If ACTION-ALIST is given, it is an alist specifying additional keys
`cursor-in-echo-area' while prompting. that will be accepted as an answer to the questions. Each element
of the alist has the form (KEY FUNCTION HELP), where KEY is a character;
FUNCTION is a function of one argument (an object from LIST); and HELP
is a string. When the user presses KEY, FUNCTION is called; if it
returns non-nil, the object is considered to have been \"acted upon\",
and `map-y-or-n-p' proceeeds to the next object from LIST. If
FUNCTION returns nil, the prompt is re-issued for the same object: this
comes in handy if FUNCTION produces some display that will allow the
user to make an intelligent decision whether the object in question
should be acted upon. If the user types \\[help-command], the string
given by HELP is used to describe the effect of KEY.
Optional argument NO-CURSOR-IN-ECHO-AREA, if non-nil, means not to set
`cursor-in-echo-area' while prompting with the questions.
This function uses `query-replace-map' to define the standard responses, This function uses `query-replace-map' to define the standard responses,
but not all of the responses which `query-replace' understands but only some of the responses which `query-replace' understands
are meaningful here. are meaningful here, as described above.
Returns the number of actions taken." The function's value is the number of actions taken."
(let* ((actions 0) (let* ((actions 0)
(msg (current-message)) (msg (current-message))
user-keys mouse-event map prompt char elt def user-keys mouse-event map prompt char elt def