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