1;;; map-ynp.el --- general-purpose boolean question-asker 2 3;; Copyright (C) 1991, 1992, 1993, 1994, 1995, 2000, 2001, 2002, 2003, 4;; 2004, 2005, 2006, 2007 Free Software Foundation, Inc. 5 6;; Author: Roland McGrath <roland@gnu.org> 7;; Maintainer: FSF 8;; Keywords: lisp, extensions 9 10;; This file is part of GNU Emacs. 11 12;; GNU Emacs is free software; you can redistribute it and/or modify 13;; it under the terms of the GNU General Public License as published by 14;; the Free Software Foundation; either version 2, or (at your option) 15;; any later version. 16 17;; GNU Emacs is distributed in the hope that it will be useful, 18;; but WITHOUT ANY WARRANTY; without even the implied warranty of 19;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 20;; GNU General Public License for more details. 21 22;; You should have received a copy of the GNU General Public License 23;; along with GNU Emacs; see the file COPYING. If not, write to the 24;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 25;; Boston, MA 02110-1301, USA. 26 27;;; Commentary: 28 29;; map-y-or-n-p is a general-purpose question-asking function. 30;; It asks a series of y/n questions (a la y-or-n-p), and decides to 31;; apply an action to each element of a list based on the answer. 32;; The nice thing is that you also get some other possible answers 33;; to use, reminiscent of query-replace: ! to answer y to all remaining 34;; questions; ESC or q to answer n to all remaining questions; . to answer 35;; y once and then n for the remainder; and you can get help with C-h. 36 37;;; Code: 38 39(defun map-y-or-n-p (prompter actor list &optional help action-alist 40 no-cursor-in-echo-area) 41 "Ask a series of boolean questions. 42Takes args PROMPTER ACTOR LIST, and optional args HELP and ACTION-ALIST. 43 44LIST is a list of objects, or a function of no arguments to return the next 45object or nil. 46 47If PROMPTER is a string, the prompt is \(format PROMPTER OBJECT\). If not 48a string, PROMPTER is a function of one arg (an object from LIST), which 49returns a string to be used as the prompt for that object. If the return 50value is not a string, it may be nil to ignore the object or non-nil to act 51on the object without asking the user. 52 53ACTOR is a function of one arg (an object from LIST), 54which gets called with each object that the user answers `yes' for. 55 56If HELP is given, it is a list (OBJECT OBJECTS ACTION), 57where OBJECT is a string giving the singular noun for an elt of LIST; 58OBJECTS is the plural noun for elts of LIST, and ACTION is a transitive 59verb describing ACTOR. The default is \(\"object\" \"objects\" \"act on\"\). 60 61At the prompts, the user may enter y, Y, or SPC to act on that object; 62n, N, or DEL to skip that object; ! to act on all following objects; 63ESC or q to exit (skip all following objects); . (period) to act on the 64current object and then exit; or \\[help-command] to get help. 65 66If ACTION-ALIST is given, it is an alist (KEY FUNCTION HELP) of extra keys 67that will be accepted. KEY is a character; FUNCTION is a function of one 68arg (an object from LIST); HELP is a string. When the user hits KEY, 69FUNCTION is called. If it returns non-nil, the object is considered 70\"acted upon\", and the next object from LIST is processed. If it returns 71nil, the prompt is repeated for the same object. 72 73Final optional argument NO-CURSOR-IN-ECHO-AREA non-nil says not to set 74`cursor-in-echo-area' while prompting. 75 76This function uses `query-replace-map' to define the standard responses, 77but not all of the responses which `query-replace' understands 78are meaningful here. 79 80Returns the number of actions taken." 81 (let* ((actions 0) 82 user-keys mouse-event map prompt char elt tail def 83 ;; Non-nil means we should use mouse menus to ask. 84 use-menus 85 delayed-switch-frame 86 (next (if (or (and list (symbolp list)) 87 (subrp list) 88 (byte-code-function-p list) 89 (and (consp list) 90 (eq (car list) 'lambda))) 91 (function (lambda () 92 (setq elt (funcall list)))) 93 (function (lambda () 94 (if list 95 (progn 96 (setq elt (car list) 97 list (cdr list)) 98 t) 99 nil)))))) 100 (if (and (listp last-nonmenu-event) 101 use-dialog-box) 102 ;; Make a list describing a dialog box. 103 (let ((object (if help (capitalize (nth 0 help)))) 104 (objects (if help (capitalize (nth 1 help)))) 105 (action (if help (capitalize (nth 2 help))))) 106 (setq map `(("Yes" . act) ("No" . skip) 107 ,@(mapcar (lambda (elt) 108 (cons (with-syntax-table 109 text-mode-syntax-table 110 (capitalize (nth 2 elt))) 111 (vector (nth 1 elt)))) 112 action-alist) 113 (,(if help (concat action " This But No More") 114 "Do This But No More") . act-and-exit) 115 (,(if help (concat action " All " objects) 116 "Do All") . automatic) 117 ("No For All" . exit)) 118 use-menus t 119 mouse-event last-nonmenu-event)) 120 (setq user-keys (if action-alist 121 (concat (mapconcat (function 122 (lambda (elt) 123 (key-description 124 (char-to-string (car elt))))) 125 action-alist ", ") 126 " ") 127 "") 128 ;; Make a map that defines each user key as a vector containing 129 ;; its definition. 130 map (cons 'keymap 131 (append (mapcar (lambda (elt) 132 (cons (car elt) (vector (nth 1 elt)))) 133 action-alist) 134 query-replace-map)))) 135 (unwind-protect 136 (progn 137 (if (stringp prompter) 138 (setq prompter `(lambda (object) 139 (format ,prompter object)))) 140 (while (funcall next) 141 (setq prompt (funcall prompter elt)) 142 (cond ((stringp prompt) 143 ;; Prompt the user about this object. 144 (setq quit-flag nil) 145 (if use-menus 146 (setq def (or (x-popup-dialog (or mouse-event use-menus) 147 (cons prompt map)) 148 'quit)) 149 ;; Prompt in the echo area. 150 (let ((cursor-in-echo-area (not no-cursor-in-echo-area)) 151 (message-log-max nil)) 152 (message (apply 'propertize "%s(y, n, !, ., q, %sor %s) " 153 minibuffer-prompt-properties) 154 prompt user-keys 155 (key-description (vector help-char))) 156 (if minibuffer-auto-raise 157 (raise-frame (window-frame (minibuffer-window)))) 158 (while (progn 159 (setq char (read-event)) 160 ;; If we get -1, from end of keyboard 161 ;; macro, try again. 162 (equal char -1))) 163 ;; Show the answer to the question. 164 (message "%s(y, n, !, ., q, %sor %s) %s" 165 prompt user-keys 166 (key-description (vector help-char)) 167 (single-key-description char))) 168 (setq def (lookup-key map (vector char)))) 169 (cond ((eq def 'exit) 170 (setq next (function (lambda () nil)))) 171 ((eq def 'act) 172 ;; Act on the object. 173 (funcall actor elt) 174 (setq actions (1+ actions))) 175 ((eq def 'skip) 176 ;; Skip the object. 177 ) 178 ((eq def 'act-and-exit) 179 ;; Act on the object and then exit. 180 (funcall actor elt) 181 (setq actions (1+ actions) 182 next (function (lambda () nil)))) 183 ((eq def 'quit) 184 (setq quit-flag t) 185 (setq next `(lambda () 186 (setq next ',next) 187 ',elt))) 188 ((eq def 'automatic) 189 ;; Act on this and all following objects. 190 (if (funcall prompter elt) 191 (progn 192 (funcall actor elt) 193 (setq actions (1+ actions)))) 194 (while (funcall next) 195 (if (funcall prompter elt) 196 (progn 197 (funcall actor elt) 198 (setq actions (1+ actions)))))) 199 ((eq def 'help) 200 (with-output-to-temp-buffer "*Help*" 201 (princ 202 (let ((object (if help (nth 0 help) "object")) 203 (objects (if help (nth 1 help) "objects")) 204 (action (if help (nth 2 help) "act on"))) 205 (concat 206 (format "Type SPC or `y' to %s the current %s; 207DEL or `n' to skip the current %s; 208RET or `q' to give up on the %s (skip all remaining %s); 209C-g to quit (cancel the whole command); 210! to %s all remaining %s;\n" 211 action object object action objects action 212 objects) 213 (mapconcat (function 214 (lambda (elt) 215 (format "%s to %s" 216 (single-key-description 217 (nth 0 elt)) 218 (nth 2 elt)))) 219 action-alist 220 ";\n") 221 (if action-alist ";\n") 222 (format "or . (period) to %s \ 223the current %s and exit." 224 action object)))) 225 (save-excursion 226 (set-buffer standard-output) 227 (help-mode))) 228 229 (setq next `(lambda () 230 (setq next ',next) 231 ',elt))) 232 ((vectorp def) 233 ;; A user-defined key. 234 (if (funcall (aref def 0) elt) ;Call its function. 235 ;; The function has eaten this object. 236 (setq actions (1+ actions)) 237 ;; Regurgitated; try again. 238 (setq next `(lambda () 239 (setq next ',next) 240 ',elt)))) 241 ((and (consp char) 242 (eq (car char) 'switch-frame)) 243 ;; switch-frame event. Put it off until we're done. 244 (setq delayed-switch-frame char) 245 (setq next `(lambda () 246 (setq next ',next) 247 ',elt))) 248 (t 249 ;; Random char. 250 (message "Type %s for help." 251 (key-description (vector help-char))) 252 (beep) 253 (sit-for 1) 254 (setq next `(lambda () 255 (setq next ',next) 256 ',elt))))) 257 (prompt 258 (funcall actor elt) 259 (setq actions (1+ actions)))))) 260 (if delayed-switch-frame 261 (setq unread-command-events 262 (cons delayed-switch-frame unread-command-events)))) 263 ;; Clear the last prompt from the minibuffer. 264 (let ((message-log-max nil)) 265 (message "")) 266 ;; Return the number of actions that were taken. 267 actions)) 268 269;;; arch-tag: 1d0a3201-a151-4c10-b231-4da47c9e6dc3 270;;; map-ynp.el ends here 271