1 ;;; map-ynp.el --- General-purpose boolean question-asker.
3 ;; Author: Roland McGrath <roland@gnu.ai.mit.edu>
4 ;; Last-Modified: 14 Mar 1992
5 ;; Keywords: lisp, extensions
7 ;;; Copyright (C) 1991, 1992 Free Software Foundation, Inc.
9 ;;; This program is free software; you can redistribute it and/or modify
10 ;;; it under the terms of the GNU General Public License as published by
11 ;;; the Free Software Foundation; either version 2, or (at your option)
12 ;;; any later version.
14 ;;; This program is distributed in the hope that it will be useful,
15 ;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
16 ;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 ;;; GNU General Public License for more details.
19 ;;; A copy of the GNU General Public License can be obtained from this
20 ;;; program's author (send electronic mail to roland@ai.mit.edu) or from
21 ;;; the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA
26 ;;; map-y-or-n-p is a general-purpose question-asking function.
27 ;;; It asks a series of y/n questions (a la y-or-n-p), and decides to
28 ;;; applies an action to each element of a list based on the answer.
29 ;;; The nice thing is that you also get some other possible answers
30 ;;; to use, reminiscent of query-replace: ! to answer y to all remaining
31 ;;; questions; ESC or q to answer n to all remaining questions; . to answer
32 ;;; y once and then n for the remainder; and you can get help with C-h.
36 (defun map-y-or-n-p-help (object objects action)
37 (format "Type SPC or `y' to %s the current %s;
38 DEL or `n' to skip the current %s;
39 ! to %s all remaining %s;
41 or . (period) to %s the current %s and exit."
42 action object object action objects action object))
45 (defun map-y-or-n-p (prompter actor list &optional help)
46 "Ask a series of boolean questions.
47 Takes args PROMPTER ACTOR LIST, and optional arg HELP.
49 LIST is a list of objects, or a function of no arguments to return the next
52 If PROMPTER is a string, the prompt is \(format PROMPTER OBJECT\). If not
53 a string, PROMPTER is a function of one arg (an object from LIST), which
54 returns a string to be used as the prompt for that object. If the return
55 value is not a string, it is eval'd to get the answer; it may be nil to
56 ignore the object, t to act on the object without asking the user, or a
57 form to do a more complex prompt.
60 ACTOR is a function of one arg (an object from LIST),
61 which gets called with each object that the user answers `yes' for.
63 If HELP is given, it is a list (OBJECT OBJECTS ACTION),
64 where OBJECT is a string giving the singular noun for an elt of LIST;
65 OBJECTS is the plural noun for elts of LIST, and ACTION is a transitive
66 verb describing ACTOR. The default is \(\"object\" \"objects\" \"act on\"\).
68 At the prompts, the user may enter y, Y, or SPC to act on that object;
69 n, N, or DEL to skip that object; ! to act on all following objects;
70 ESC or q to exit (skip all following objects); . (period) to act on the
71 current object and then exit; or \\[help-command] to get help.
73 Returns the number of actions taken."
74 (let* ((old-help-form help-form)
75 (help-form (cons 'map-y-or-n-p-help
76 (or help '("object" "objects" "act on"))))
81 (next (if (or (symbolp list)
83 (compiled-function-p list)
85 (eq (car list) 'lambda)))
87 (setq elt (funcall list))))
95 (if (stringp prompter)
96 (setq prompter (` (lambda (object)
97 (format (, prompter) object)))))
99 (setq prompt (funcall prompter elt))
102 ;; Prompt the user about this object.
103 (let ((cursor-in-echo-area t))
104 (message "%s(y, n, ! ., q, or %s)"
105 prompt (key-description (char-to-string help-char)))
106 (setq char (read-char)))
107 (cond ((or (= ?q char)
109 (setq next (function (lambda () nil))))
113 ;; Act on the object.
114 (let ((help-form old-help-form))
116 (setq actions (1+ actions)))
123 ;; Act on the object and then exit.
125 (setq actions (1+ actions)
126 next (function (lambda () nil))))
128 ;; Act on this and all following objects.
129 (if (eval (funcall prompter elt))
132 (setq actions (1+ actions))))
133 (while (funcall next)
134 (if (eval (funcall prompter elt))
137 (setq actions (1+ actions))))))
139 (setq unread-command-char help-char)
140 (setq next (` (lambda ()
141 (setq next '(, next))
145 (message "Type %s for help."
146 (key-description (char-to-string help-char)))
149 (setq next (` (lambda ()
150 (setq next '(, next))
155 (setq actions (1+ actions))))))
156 ;; Clear the last prompt from the minibuffer.
158 ;; Return the number of actions that were taken.
161 ;;; map-ynp.el ends here