*** empty log message ***
[emacs.git] / lisp / repeat.el
blob8e97abf32e9a0ec8f868c0039b0acf14ee2d21b2
1 ;;; repeat.el --- convenient way to repeat the previous command
3 ;; Copyright (C) 1998, 2001, 2002, 2003, 2004, 2005,
4 ;; 2006, 2007, 2008 Free Software Foundation, Inc.
6 ;; Author: Will Mengarini <seldon@eskimo.com>
7 ;; Created: Mo 02 Mar 98
8 ;; Version: 0.51, We 13 May 98
9 ;; Keywords: convenience, vi, repeat
11 ;; This file is part of GNU Emacs.
13 ;; GNU Emacs is free software; you can redistribute it and/or modify
14 ;; it under the terms of the GNU General Public License as published by
15 ;; the Free Software Foundation; either version 3, or (at your option)
16 ;; any later version.
18 ;; GNU Emacs is distributed in the hope that it will be useful,
19 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 ;; GNU General Public License for more details.
23 ;; You should have received a copy of the GNU General Public License
24 ;; along with GNU Emacs; see the file COPYING. If not, write to the
25 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
26 ;; Boston, MA 02110-1301, USA.
28 ;;; Commentary:
30 ;; Sometimes the fastest way to get something done is just to lean on a key;
31 ;; moving forward through a series of words by leaning on M-f is an example.
32 ;; But 'forward-page is orthodoxily bound to C-x ], so moving forward through
33 ;; several pages requires
34 ;; Loop until desired page is reached:
35 ;; Hold down control key with left pinkie.
36 ;; Tap <x>.
37 ;; Lift left pinkie off control key.
38 ;; Tap <]>.
39 ;; This is a pain in the ass.
41 ;; This package defines a command that repeats the preceding command,
42 ;; whatever that was, including its arguments, whatever they were.
43 ;; This command is connected to the key C-x z.
44 ;; To repeat the previous command once, type C-x z.
45 ;; To repeat it a second time immediately after, type just z.
46 ;; By typing z again and again, you can repeat the command over and over.
48 ;; This works correctly inside a keyboard macro as far as recording and
49 ;; playback go, but `edit-kbd-macro' gets it wrong. That shouldn't really
50 ;; matter; if you need to edit something like
51 ;; C-x ] ;; forward-page
52 ;; C-x z ;; repeat
53 ;; zz ;; self-insert-command * 2
54 ;; C-x ;; Control-X-prefix
55 ;; you can just kill the bogus final 2 lines, then duplicate the repeat line
56 ;; as many times as it's really needed. Also, `edit-kbd-macro' works
57 ;; correctly if `repeat' is invoked through a rebinding to a single keystroke
58 ;; and the global variable repeat-on-final-keystroke is set to a value
59 ;; that doesn't include that keystroke. For example, the lines
60 ;; (global-set-key "\C-z" 'repeat)
61 ;; (setq repeat-on-final-keystroke "z")
62 ;; in your .emacs would allow `edit-kbd-macro' to work correctly when C-z was
63 ;; used in a keyboard macro to invoke `repeat', but would still allow C-x z
64 ;; to be used for `repeat' elsewhere. The real reason for documenting this
65 ;; isn't that anybody would need it for the `edit-kbd-macro' problem, but
66 ;; that there might be other unexpected ramifications of re-executing on
67 ;; repetitions of the final keystroke, and this shows how to do workarounds.
69 ;; If the preceding command had a prefix argument, that argument is applied
70 ;; to the repeat command, unless the repeat command is given a new prefix
71 ;; argument, in which case it applies that new prefix argument to the
72 ;; preceding command. This means a key sequence like C-u - C-x C-t can be
73 ;; repeated. (It shoves the preceding line upward in the buffer.)
75 ;; Here are some other key sequences with which repeat might be useful:
76 ;; C-u - C-t [shove preceding character backward in line]
77 ;; C-u - M-t [shove preceding word backward in sentence]
78 ;; C-x ^ enlarge-window [one line] (assuming frame has > 1 window)
79 ;; C-u - C-x ^ [shrink window one line]
80 ;; C-x ` next-error
81 ;; C-u - C-x ` [previous error]
82 ;; C-x DEL backward-kill-sentence
83 ;; C-x e call-last-kbd-macro
84 ;; C-x r i insert-register
85 ;; C-x r t string-rectangle
86 ;; C-x TAB indent-rigidly [one character]
87 ;; C-u - C-x TAB [outdent rigidly one character]
88 ;; C-x { shrink-window-horizontally
89 ;; C-x } enlarge-window-horizontally
91 ;; This command was first called `vi-dot', because
92 ;; it was inspired by the `.' command in the vi editor,
93 ;; but it was renamed to make its name more meaningful.
95 ;;; Code:
97 ;;;;; ************************* USER OPTIONS ************************** ;;;;;
99 (defcustom repeat-too-dangerous '(kill-this-buffer)
100 "Commands too dangerous to repeat with \\[repeat]."
101 :group 'convenience
102 :type '(repeat function))
104 ;; If the last command was self-insert-command, the char to be inserted was
105 ;; obtained by that command from last-command-char, which has now been
106 ;; clobbered by the command sequence that invoked `repeat'. We could get it
107 ;; from (recent-keys) & set last-command-char to that, "unclobbering" it, but
108 ;; this has the disadvantage that if the user types a sequence of different
109 ;; chars then invokes repeat, only the final char will be inserted. In vi,
110 ;; the dot command can reinsert the entire most-recently-inserted sequence.
112 (defvar repeat-message-function nil
113 "If non-nil, function used by `repeat' command to say what it's doing.
114 Message is something like \"Repeating command glorp\".
115 To disable such messages, set this variable to `ignore'. To customize
116 display, assign a function that takes one string as an arg and displays
117 it however you want.")
119 (defcustom repeat-on-final-keystroke t
120 "Allow `repeat' to re-execute for repeating lastchar of a key sequence.
121 If this variable is t, `repeat' determines what key sequence
122 it was invoked by, extracts the final character of that sequence, and
123 re-executes as many times as that final character is hit; so for example
124 if `repeat' is bound to C-x z, typing C-x z z z repeats the previous command
125 3 times. If this variable is a sequence of characters, then re-execution
126 only occurs if the final character by which `repeat' was invoked is a
127 member of that sequence. If this variable is nil, no re-execution occurs."
128 :group 'convenience
129 :type 'boolean)
131 ;;;;; ****************** HACKS TO THE REST OF EMACS ******************* ;;;;;
133 ;; The basic strategy is to use last-command, a variable built in to Emacs.
134 ;; There are 2 issues that complicate this strategy. The first is that
135 ;; last-command is given a bogus value when any kill command is executed;
136 ;; this is done to make it easy for `yank-pop' to know that it's being invoked
137 ;; after a kill command. The second is that the meaning of the command is
138 ;; often altered by the prefix arg, but although Emacs (19.34) has a
139 ;; builtin prefix-arg specifying the arg for the next command, as well as a
140 ;; builtin current-prefix-arg, it has no builtin last-prefix-arg.
142 ;; There's a builtin (this-command-keys), the return value of which could be
143 ;; executed with (command-execute), but there's no (last-command-keys).
144 ;; Using (last-command-keys) if it existed wouldn't be optimal, however,
145 ;; since it would complicate checking membership in repeat-too-dangerous.
147 ;; It would of course be trivial to implement last-prefix-arg &
148 ;; true-last-command by putting something in post-command-hook, but that
149 ;; entails a performance hit; the approach taken below avoids that.
151 ;; Coping with strings of self-insert commands gets hairy when they interact
152 ;; with auto-filling. Most problems are eliminated by remembering what we're
153 ;; self-inserting, so we only need to get it from the undo information once.
155 ;; With Emacs 22.2 the variable `last-repeatable-command' stores the
156 ;; most recently executed command that was not bound to an input event.
157 ;; `repeat' now repeats that command instead of `real-last-command' to
158 ;; avoid a "... must be bound to an event with parameters" error.
160 (defvar repeat-last-self-insert nil
161 "If last repeated command was `self-insert-command', it inserted this.")
163 ;; That'll require another keystroke count so we know we're in a string of
164 ;; repetitions of self-insert commands:
166 (defvar repeat-num-input-keys-at-self-insert -1
167 "# key sequences read in Emacs session when `self-insert-command' repeated.")
169 ;;;;; *************** ANALOGOUS HACKS TO `repeat' ITSELF **************** ;;;;;
171 ;; That mechanism of checking num-input-keys to figure out what's really
172 ;; going on can be useful to other commands that need to fine-tune their
173 ;; interaction with repeat. Instead of requiring them to advise repeat, we
174 ;; can just defvar the value they need here, & setq it in the repeat command:
176 (defvar repeat-num-input-keys-at-repeat -1
177 "# key sequences read in Emacs session when `repeat' last invoked.")
179 ;; Also, we can assign a name to the test for which that variable is
180 ;; intended, which thereby documents here how to use it, & makes code that
181 ;; uses it self-documenting:
183 (defsubst repeat-is-really-this-command ()
184 "Return t if this command is happening because user invoked `repeat'.
185 Usually, when a command is executing, the Emacs builtin variable
186 `this-command' identifies the command the user invoked. Some commands modify
187 that variable on the theory they're doing more good than harm; `repeat' does
188 that, and usually does do more good than harm. However, like all do-gooders,
189 sometimes `repeat' gets surprising results from its altruism. The value of
190 this function is always whether the value of `this-command' would've been
191 'repeat if `repeat' hadn't modified it."
192 (= repeat-num-input-keys-at-repeat num-input-keys))
194 ;; An example of the use of (repeat-is-really-this-command) may still be
195 ;; available in <http://www.eskimo.com/~seldon/dotemacs.el>; search for
196 ;; "defun wm-switch-buffer".
198 ;;;;; ******************* THE REPEAT COMMAND ITSELF ******************* ;;;;;
200 (defvar repeat-previous-repeated-command nil
201 "The previous repeated command.")
203 ;;;###autoload
204 (defun repeat (repeat-arg)
205 "Repeat most recently executed command.
206 With prefix arg, apply new prefix arg to that command; otherwise,
207 use the prefix arg that was used before (if any).
208 This command is like the `.' command in the vi editor.
210 If this command is invoked by a multi-character key sequence, it
211 can then be repeated by repeating the final character of that
212 sequence. This behavior can be modified by the global variable
213 `repeat-on-final-keystroke'.
215 `repeat' ignores commands bound to input events. Hence the term
216 \"most recently executed command\" shall be read as \"most
217 recently executed command not bound to an input event\"."
218 ;; The most recently executed command could be anything, so surprises could
219 ;; result if it were re-executed in a context where new dynamically
220 ;; localized variables were shadowing global variables in a `let' clause in
221 ;; here. (Remember that GNU Emacs 19 is dynamically localized.)
222 ;; To avoid that, I tried the `lexical-let' of the Common Lisp extensions,
223 ;; but that entails a very noticeable performance hit, so instead I use the
224 ;; "repeat-" prefix, reserved by this package, for *local* variables that
225 ;; might be visible to re-executed commands, including this function's arg.
226 (interactive "P")
227 (when (eq last-repeatable-command 'repeat)
228 (setq last-repeatable-command repeat-previous-repeated-command))
229 (cond
230 ((null last-repeatable-command)
231 (error "There is nothing to repeat"))
232 ((eq last-repeatable-command 'mode-exit)
233 (error "last-repeatable-command is mode-exit & can't be repeated"))
234 ((memq last-repeatable-command repeat-too-dangerous)
235 (error "Command %S too dangerous to repeat automatically"
236 last-repeatable-command)))
237 (setq this-command last-repeatable-command
238 repeat-previous-repeated-command last-repeatable-command
239 repeat-num-input-keys-at-repeat num-input-keys)
240 (when (null repeat-arg)
241 (setq repeat-arg last-prefix-arg))
242 ;; Now determine whether to loop on repeated taps of the final character
243 ;; of the key sequence that invoked repeat. The Emacs global
244 ;; last-command-char contains the final character now, but may not still
245 ;; contain it after the previous command is repeated, so the character
246 ;; needs to be saved.
247 (let ((repeat-repeat-char
248 (if (eq repeat-on-final-keystroke t)
249 ;; The following commented out since it's equivalent to
250 ;; last-comment-char (martin 2007-08-29).
251 ;;; ;; allow any final input event that was a character
252 ;;; (when (eq last-command-char
253 ;;; last-command-event)
254 ;;; last-command-char)
255 last-command-char
256 ;; allow only specified final keystrokes
257 (car (memq last-command-char
258 (listify-key-sequence
259 repeat-on-final-keystroke))))))
260 (if (memq last-repeatable-command '(exit-minibuffer
261 minibuffer-complete-and-exit
262 self-insert-and-exit))
263 (let ((repeat-command (car command-history)))
264 (repeat-message "Repeating %S" repeat-command)
265 (eval repeat-command))
266 (if (null repeat-arg)
267 (repeat-message "Repeating command %S" last-repeatable-command)
268 (setq current-prefix-arg repeat-arg)
269 (repeat-message
270 "Repeating command %S %S" repeat-arg last-repeatable-command))
271 (if (eq last-repeatable-command 'self-insert-command)
272 (let ((insertion
273 (if (<= (- num-input-keys
274 repeat-num-input-keys-at-self-insert)
276 repeat-last-self-insert
277 (let ((range (nth 1 buffer-undo-list)))
278 (condition-case nil
279 (setq repeat-last-self-insert
280 (buffer-substring (car range)
281 (cdr range)))
282 (error (error "%s %s %s" ;Danger, Will Robinson!
283 "repeat can't intuit what you"
284 "inserted before auto-fill"
285 "clobbered it, sorry")))))))
286 (setq repeat-num-input-keys-at-self-insert num-input-keys)
287 ;; If the self-insert had a repeat count, INSERTION
288 ;; includes that many copies of the same character.
289 ;; So use just the first character
290 ;; and repeat it the right number of times.
291 (setq insertion (substring insertion -1))
292 (let ((count (prefix-numeric-value repeat-arg))
293 (i 0))
294 ;; Run pre- and post-command hooks for self-insertion too.
295 (run-hooks 'pre-command-hook)
296 (while (< i count)
297 (repeat-self-insert insertion)
298 (setq i (1+ i)))
299 (run-hooks 'post-command-hook)))
300 (let ((indirect (indirect-function last-repeatable-command)))
301 (if (or (stringp indirect)
302 (vectorp indirect))
303 ;; Bind real-last-command so that executing the macro does
304 ;; not alter it. Do the same for last-repeatable-command.
305 (let ((real-last-command real-last-command)
306 (last-repeatable-command last-repeatable-command))
307 (execute-kbd-macro last-repeatable-command))
308 (run-hooks 'pre-command-hook)
309 (call-interactively last-repeatable-command)
310 (run-hooks 'post-command-hook)))))
311 (when repeat-repeat-char
312 ;; A simple recursion here gets into trouble with max-lisp-eval-depth
313 ;; on long sequences of repetitions of a command like `forward-word'
314 ;; (only 32 repetitions are possible given the default value of 200 for
315 ;; max-lisp-eval-depth), but if I now locally disable the repeat char I
316 ;; can iterate indefinitely here around a single level of recursion.
317 (let (repeat-on-final-keystroke)
318 (setq real-last-command 'repeat)
319 (while (eq (read-event) repeat-repeat-char)
320 ;; Make each repetition undo separately.
321 (undo-boundary)
322 (repeat repeat-arg))
323 (setq unread-command-events (list last-input-event))))))
325 (defun repeat-self-insert (string)
326 (let ((i 0))
327 (while (< i (length string))
328 (let ((last-command-char (aref string i)))
329 (self-insert-command 1))
330 (setq i (1+ i)))))
332 (defun repeat-message (format &rest args)
333 "Like `message' but displays with `repeat-message-function' if non-nil."
334 (let ((message (apply 'format format args)))
335 (if repeat-message-function
336 (funcall repeat-message-function message)
337 (message "%s" message))))
339 ;; OK, there's one situation left where that doesn't work correctly: when the
340 ;; most recent self-insertion provoked an auto-fill. The problem is that
341 ;; unravelling the undo information after an auto-fill is too hard, since all
342 ;; kinds of stuff can get in there as a result of comment prefixes etc. It'd
343 ;; be possible to advise do-auto-fill to record the most recent
344 ;; self-insertion before it does its thing, but that's a performance hit on
345 ;; auto-fill, which already has performance problems; so it's better to just
346 ;; leave it like this. If text didn't provoke an auto-fill when the user
347 ;; typed it, this'll correctly repeat its self-insertion, even if the
348 ;; repetition does cause auto-fill.
350 ;; If you wanted perfection, probably it'd be necessary to hack do-auto-fill
351 ;; into 2 functions, maybe-do-auto-fill & really-do-auto-fill, because only
352 ;; really-do-auto-fill should be advised. As things are, either the undo
353 ;; information would need to be scanned on every do-auto-fill invocation, or
354 ;; the code at the top of do-auto-fill deciding whether filling is necessary
355 ;; would need to be duplicated in the advice, wasting execution time when
356 ;; filling does turn out to be necessary.
358 ;; I thought maybe this story had a moral, something about functional
359 ;; decomposition; but now I'm not even sure of that, since a function
360 ;; call per se is a performance hit, & even the code that would
361 ;; correspond to really-do-auto-fill has performance problems that
362 ;; can make it necessary to stop typing while Emacs catches up.
363 ;; Maybe the real moral is that perfection is a chimera.
365 ;; Ah, hell, it's all going to fall into a black hole someday anyway.
367 ;;;;; ************************* EMACS CONTROL ************************* ;;;;;
369 (provide 'repeat)
371 ;;; arch-tag: cd569600-a1ad-4fa7-9062-bb91dfeaf1db
372 ;;; repeat.el ends here