Improve documentation of 'map-y-or-n-p'
* 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
parent
eedad01b4b
commit
1789dcdb35
2 changed files with 98 additions and 65 deletions
|
|
@ -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.
|
||||
|
||||
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
|
||||
a function, it should expect no arguments, and should return either the
|
||||
next object to ask about, or @code{nil}, meaning to stop asking questions.
|
||||
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}, meaning to stop
|
||||
asking questions.
|
||||
|
||||
The argument @var{prompter} specifies how to ask each question. If
|
||||
@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
|
||||
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
|
||||
(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 @code{t}, meaning do act on this object (and
|
||||
don't ask the user), or @code{nil}, meaning ignore this object (and don't
|
||||
ask the user).
|
||||
If @var{prompter} 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} returns is a string,
|
||||
that is the question to ask the user. The function can also return
|
||||
@code{t}, meaning to act on this object without asking the user, or
|
||||
@code{nil}, which means to silently ignore this object.
|
||||
|
||||
The argument @var{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 @var{list}.
|
||||
The argument @var{actor} 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} for which the user answers
|
||||
yes.
|
||||
|
||||
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
|
||||
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
|
||||
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"
|
||||
"objects" "act on")}.
|
||||
If you don't specify @var{help}, it defaults to the list
|
||||
@w{@code{("object" "objects" "act on")}}.
|
||||
|
||||
Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or
|
||||
@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
|
||||
@kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on
|
||||
the current object and then exit; or @kbd{C-h} to get help. 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}.
|
||||
Each time a question is asked, the user can answer as follows:
|
||||
|
||||
@table @asis
|
||||
@item @kbd{y}, @kbd{Y}, or @kbd{@key{SPC}}
|
||||
act on the object
|
||||
@item @kbd{n}, @kbd{N}, or @kbd{@key{DEL}}
|
||||
skip the object
|
||||
@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
|
||||
and what they mean. It is an alist of elements of the form
|
||||
@code{(@var{char} @var{function} @var{help})}, each of which defines one
|
||||
additional answer. In this element, @var{char} is a character (the
|
||||
and what they mean. If provided, @var{action-alist} should be an
|
||||
alist whose elements are of the form @w{@code{(@var{char}
|
||||
@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
|
||||
@var{list}); @var{help} is a string.
|
||||
|
||||
When the user responds with @var{char}, @code{map-y-or-n-p} calls
|
||||
@var{function}. If it returns non-@code{nil}, the object is considered
|
||||
acted upon, and @code{map-y-or-n-p} advances to the next object in
|
||||
@var{list}. If it returns @code{nil}, the prompt is repeated for the
|
||||
same object.
|
||||
@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
|
||||
non-@code{nil}, the object is considered to have been acted upon, and
|
||||
@code{map-y-or-n-p} advances to the next object in @var{list}. If it
|
||||
returns @code{nil}, the prompt is repeated for the same object. If
|
||||
the user requests help, the text in @var{help} is used to describe
|
||||
these additional answers.
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -38,46 +38,62 @@
|
|||
|
||||
(defun map-y-or-n-p (prompter actor list &optional help action-alist
|
||||
no-cursor-in-echo-area)
|
||||
"Ask a series of boolean questions.
|
||||
Takes args PROMPTER ACTOR LIST, and optional args HELP and ACTION-ALIST.
|
||||
"Ask a boolean question per PROMPTER for each object in LIST, then call ACTOR.
|
||||
|
||||
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
|
||||
a string, PROMPTER is a function of one arg (an object from LIST), which
|
||||
returns a string to be used as the prompt for that object. If the return
|
||||
value is not a string, it may be nil to ignore the object or non-nil to act
|
||||
on the object without asking the user.
|
||||
If PROMPTER is a string, it should be a format string to be used to format
|
||||
the question as \(format PROMPTER OBJECT).
|
||||
If PROMPTER is not a string, it should be a function of one argument, an
|
||||
object from LIST, which returns a string to be used as the question for
|
||||
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),
|
||||
which gets called with each object that the user answers `yes' for.
|
||||
ACTOR is a function of one argument, an object from LIST,
|
||||
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),
|
||||
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\").
|
||||
The user's answers to the questions may be one of the following:
|
||||
|
||||
At the prompts, 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 \\[help-command] to get help.
|
||||
- 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
|
||||
- \\[help-command] to get help.
|
||||
|
||||
If ACTION-ALIST is given, it is an alist (KEY FUNCTION HELP) of extra keys
|
||||
that will be accepted. KEY is a character; FUNCTION is a function of one
|
||||
arg (an object from LIST); HELP is a string. When the user hits KEY,
|
||||
FUNCTION is called. If it returns non-nil, the object is considered
|
||||
\"acted upon\", and the next object from LIST is processed. If it returns
|
||||
nil, the prompt is repeated for the same object.
|
||||
HELP provides information for displaying help when the user
|
||||
types \\[help-command]. If HELP is given, it should be a list of
|
||||
the form (OBJECT OBJECTS ACTION), where OBJECT is a string giving
|
||||
the singular noun describing an element of LIST; OBJECTS is the
|
||||
plural noun describing several elements of LIST, and ACTION is a
|
||||
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
|
||||
`cursor-in-echo-area' while prompting.
|
||||
If ACTION-ALIST is given, it is an alist specifying additional keys
|
||||
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,
|
||||
but not all of the responses which `query-replace' understands
|
||||
are meaningful here.
|
||||
but only some of the responses which `query-replace' understands
|
||||
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)
|
||||
(msg (current-message))
|
||||
user-keys mouse-event map prompt char elt def
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue