本节描述用于向用户提出更复杂问题或多个同类问题的功能接口。
当你需要连续提出一系列相似问题时(例如逐个询问“是否保存此缓冲区?”),
应当使用 map-y-or-n-p 批量处理这些问题,而非逐个单独提问。
这能为用户提供便捷操作,比如一次性答复所有问题。
该函数向用户发起一系列提问,针对每个问题在回显区读取单个字符作为答复。
参数 list 指定要提问的对象集合,可为对象列表或生成器函数:
若为列表,则依次遍历列表中的对象;
若为函数,则无参调用该函数,返回下一个待提问对象;返回 nil 时终止提问。
参数 prompter 定义单个问题的生成方式: 若为字符串,问题文本通过格式化生成:
(format prompter object)
其中 object 是从 list 获取的当前待提问对象(format 用法见 See 格式化字符串)。
若为函数(单参数,参数为待提问对象),返回值规则:
返回字符串:作为向用户显示的问题文本;
返回 t:无需询问用户,直接处理该对象;
返回 nil:静默忽略该对象。
参数 actor 定义用户答复“是”时的处理逻辑,为单参数函数, 会以 list 中每个用户确认处理的对象为参数调用。
可选参数 help 若提供,需为如下格式的列表:
(singular plural action)
其中: singular:描述单个待处理对象的单数名词字符串; plural:对应的复数名词字符串; action:描述 actor 操作行为的及物动词。
若未指定 help,默认值为 ("object" "objects" "act on").。
每次提问时,用户可输入以下答复:
处理当前对象
跳过当前对象
处理剩余所有对象
退出(跳过剩余所有对象)
处理当前对象后退出
获取帮助信息
上述答复与 query-replace 兼容,其语义由键盘映射 query-replace-map 定义
(同时适用于 map-y-or-n-p 和 query-replace,详见 Search and Replace)。
可选参数 action-alist 用于扩展自定义答复,格式为 alist,元素结构:
(char function help)。
char:自定义答复字符;
function:单参数处理函数(参数为当前对象);
返回非 nil:视为处理完成,继续下一个对象;
返回 nil:重复当前对象的提问;
help:该答复的帮助说明文本(用户请求帮助时显示)。
默认情况下,该函数在提问时会绑定 cursor-in-echo-area 变量;
若 no-cursor-in-echo-area 非 nil,则不执行此绑定。
调用场景适配规则:
若在鼠标操作/菜单触发的命令中调用,且系统支持对话框,则使用对话框/弹出菜单提问。
可通过绑定 last-nonmenu-event 强制交互方式:
绑定为 t:强制键盘交互;
绑定为列表:强制对话框交互。
函数 map-y-or-n-p 返回值为实际处理的对象数量。
若需提出超过两个选项的问题,应使用 read-answer 函数。
该函数会使用 question 中的文本提示用户,其中 question 应以 ‘SPC’(空格)字符结尾。函数会将 answers 中的可选响应追加到 question 末尾,从而在提示信息中包含这些选项。 answers 中的可选响应以关联列表(alist)形式提供,其元素格式如下:
(long-answer short-answer help-message)
其中:long-answer 是用户响应的完整文本(字符串类型);
short-answer 是该响应的简写形式(单个字符或功能键);
help-message 是描述该答案含义的文本。
若变量 read-answer-short 的值非 nil,则提示信息会显示可选答案的简写形式,
且期望用户输入提示中显示的单个字符/按键;否则提示信息会显示答案的完整形式,
且期望用户输入其中一个答案的完整文本并按下 RET(回车键)确认。
若 use-dialog-box 的值非 nil,且该函数由鼠标事件触发调用,
则问题和答案会显示在图形界面(GUI)对话框中。
无论提示信息中显示的是完整答案还是简写答案,也无论用户输入的是哪种形式, 该函数最终都会返回用户所选答案对应的 long-answer 文本。
以下是该函数的使用示例:
(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"))))
该函数使用迷你缓冲区(minibuffer)读取并返回单个
字符。可选地,它会忽略所有不属于 chars 的输入(chars 是一个包含所有可接受字符的列表)。
history 参数指定要使用的历史列表符号;若省略该参数或其值为
nil,则该函数不会使用历史记录功能。
在调用 read-char-from-minibuffer 时,若将
help-form(see 帮助函数)绑定为非 nil 的值,
则按下 help-char 会触发对 help-form 的求值,并显示求值结果。