From: Eli Zaretskii Date: Sat, 17 Apr 2021 08:24:04 +0000 (+0300) Subject: Improve documentation of 'map-y-or-n-p' X-Git-Tag: emacs-28.0.90~2730^2~8 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=1789dcdb35;p=emacs.git 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'. --- diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 726b786905f..f16212abdca 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -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 diff --git a/lisp/emacs-lisp/map-ynp.el b/lisp/emacs-lisp/map-ynp.el index 14112a1c147..8d3a42b09f6 100644 --- a/lisp/emacs-lisp/map-ynp.el +++ b/lisp/emacs-lisp/map-ynp.el @@ -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. - -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. - -ACTOR is a function of one arg (an object from LIST), -which gets called with each object that the user answers `yes' for. - -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\"). - -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. - -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. - -Final optional argument NO-CURSOR-IN-ECHO-AREA non-nil says not to set -`cursor-in-echo-area' while prompting. +object; when it returns nil, the list of objects is considered exhausted. + +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 argument, an object from LIST, +which gets called with each object for which the user answers `yes' +to the question presented by PROMPTER. + +The user's answers to the questions may be one of the following: + + - 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. + +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\"). + +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