1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985,86,87,93,94,95,97,2000,2001,2002,2003
3 @c Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Keyboard Macros, Files, Fixit, Top
6 @chapter Keyboard Macros
7 @cindex defining keyboard macros
12 @section Keyboard Macros
14 @cindex defining keyboard macros
15 @cindex keyboard macro
17 In this chapter we describe how a sequence of editing commands can
18 be recorded and repeated multiple times.
20 A @dfn{keyboard macro} is a command defined by the user to stand for
21 another sequence of keys. For example, if you discover that you are
22 about to type @kbd{C-n C-d} forty times, you can speed your work by
23 defining a keyboard macro to do @kbd{C-n C-d} and calling it with a
24 repeat count of forty.
26 You define a keyboard macro while executing the commands which are the
27 definition. Put differently, as you define a keyboard macro, the
28 definition is being executed for the first time. This way, you can see
29 what the effects of your commands are, so that you don't have to figure
30 them out in your head. When you are finished, the keyboard macro is
31 defined and also has been, in effect, executed once. You can then do the
32 whole thing over again by invoking the macro.
34 Keyboard macros differ from ordinary Emacs commands in that they are
35 written in the Emacs command language rather than in Lisp. This makes it
36 easier for the novice to write them, and makes them more convenient as
37 temporary hacks. However, the Emacs command language is not powerful
38 enough as a programming language to be useful for writing anything
39 intelligent or general. For such things, Lisp must be used.
42 * Basic Keyboard Macro:: Defining and running keyboard macros.
43 * Keyboard Macro Ring:: Where previous keyboard macros are saved.
44 * Keyboard Macro Counter:: Inserting incrementing numbers in macros.
45 * Keyboard Macro Query:: Making keyboard macros do different things each time.
46 * Save Keyboard Macro:: Giving keyboard macros names; saving them in files.
47 * Edit Keyboard Macro:: Editing keyboard macros.
48 * Keyboard Macro Step-Edit:: Interactively executing and editing a keyboard macro.
51 @node Basic Keyboard Macro
56 Start defining a keyboard macro (@code{kmacro-start-macro}).
58 End the definition of a keyboard macro (@code{kmacro-end-macro}).
60 Execute the most recent keyboard macro (@code{kmacro-end-and-call-macro}).
61 First end the definition of the keyboard macro, if currently defining it.
62 To immediately execute the keyboard macro again, just repeat the @kbd{e}.
64 Re-execute last keyboard macro, then add more keys to its definition.
66 Add more keys to the last keyboard macro without re-executing it.
68 When this point is reached during macro execution, ask for confirmation
69 (@code{kbd-macro-query}).
71 Give a command name (for the duration of the session) to the most
72 recently defined keyboard macro (@code{name-last-kbd-macro}).
74 Bind the most recently defined keyboard macro to a key sequence (for
75 the duration of the session) (@code{kmacro-bind-to-key}).
76 @item M-x insert-kbd-macro
77 Insert in the buffer a keyboard macro's definition, as Lisp code.
79 Edit a previously defined keyboard macro (@code{edit-kbd-macro}).
81 Run the last keyboard macro on each complete line in the region
82 (@code{apply-macro-to-region-lines}).
88 @findex kmacro-start-macro
89 @findex kmacro-end-macro
90 @findex kmacro-end-and-call-macro
91 To start defining a keyboard macro, type the @kbd{C-x (} command
92 (@code{kmacro-start-macro}). From then on, your keys continue to be
93 executed, but also become part of the definition of the macro. @samp{Def}
94 appears in the mode line to remind you of what is going on. When you are
95 finished, the @kbd{C-x )} command (@code{kmacro-end-macro}) terminates the
96 definition (without becoming part of it!). For example,
103 defines a macro to move forward a word and then insert @samp{foo}.
105 The macro thus defined can be invoked again with the @kbd{C-x e}
106 command (@code{kmacro-end-and-call-macro}), which may be given a
107 repeat count as a numeric argument to execute the macro many times.
108 If you enter @kbd{C-x e} while defining a macro, the macro is
109 terminated and executed immediately.
111 After executing the macro with @kbd{C-x e}, you can use @kbd{e}
112 repeatedly to immediately repeat the macro one or more times. For example,
119 inserts @samp{xyzxyzxyzxyz} in the current buffer.
121 @kbd{C-x )} can also be given a repeat count as an argument, in
122 which case it repeats the macro that many times right after defining
123 it, but defining the macro counts as the first repetition (since it is
124 executed as you define it). Therefore, giving @kbd{C-x )} an argument
125 of 4 executes the macro immediately 3 additional times. An argument
126 of zero to @kbd{C-x e} or @kbd{C-x )} means repeat the macro
127 indefinitely (until it gets an error or you type @kbd{C-g} or, on
128 MS-DOS, @kbd{C-@key{BREAK}}).
132 Alternatively, you can use @kbd{C-x C-k C-s} to start a keyboard macro,
133 and @kbd{C-x C-k C-k...} to end and execute it.
135 If you wish to repeat an operation at regularly spaced places in the
136 text, define a macro and include as part of the macro the commands to move
137 to the next place you want to use it. For example, if you want to change
138 each line, you should position point at the start of a line, and define a
139 macro to change that line and leave point at the start of the next line.
140 Then repeating the macro will operate on successive lines.
142 When a command reads an argument with the minibuffer, your
143 minibuffer input becomes part of the macro along with the command. So
144 when you replay the macro, the command gets the same argument as
145 when you entered the macro. For example,
148 C-x ( C-a C-@key{SPC} C-n M-w C-x b f o o @key{RET} C-y C-x b @key{RET} C-x )
152 defines a macro that copies the current line into the buffer
153 @samp{foo}, then returns to the original buffer.
155 You can use function keys in a keyboard macro, just like keyboard
156 keys. You can even use mouse events, but be careful about that: when
157 the macro replays the mouse event, it uses the original mouse position
158 of that event, the position that the mouse had while you were defining
159 the macro. The effect of this may be hard to predict. (Using the
160 current mouse position would be even less predictable.)
162 One thing that doesn't always work well in a keyboard macro is the
163 command @kbd{C-M-c} (@code{exit-recursive-edit}). When this command
164 exits a recursive edit that started within the macro, it works as you'd
165 expect. But if it exits a recursive edit that started before you
166 invoked the keyboard macro, it also necessarily exits the keyboard macro
167 as part of the process.
169 After you have terminated the definition of a keyboard macro, you can add
170 to the end of its definition by typing @kbd{C-u C-x (}. This is equivalent
171 to plain @kbd{C-x (} followed by retyping the whole definition so far. As
172 a consequence it re-executes the macro as previously defined.
174 You can also add to the end of the definition of the last keyboard
175 macro without re-execuing it by typing @kbd{C-u C-u C-x (}.
177 The variable @code{kmacro-execute-before-append} specifies whether
178 a single @kbd{C-u} prefix causes the existing macro to be re-executed
179 before appending to it.
181 @findex apply-macro-to-region-lines
183 The command @kbd{C-x C-k r} (@code{apply-macro-to-region-lines})
184 repeats the last defined keyboard macro on each complete line within
185 the current region. It does this line by line, by moving point to the
186 beginning of the line and then executing the macro.
188 @node Keyboard Macro Ring
189 @section Where previous keyboard macros are saved
191 All defined keyboard macros are recorded in the ``keyboard macro ring'',
192 a list of sequences of keys. There is only one keyboard macro ring,
193 shared by all buffers.
195 All commands which operates on the keyboard macro ring use the
196 same @kbd{C-x C-k} prefix. Most of these commands can be executed and
197 repeated immediately after each other without repeating the @kbd{C-x
198 C-k} prefix. For example,
201 C-x C-k C-p C-p C-k C-k C-k C-n C-n C-k C-p C-k C-d
205 will rotate the keyboard macro ring to the ``second previous'' macro,
206 execute the resulting head macro three times, rotate back to the
207 original head macro, execute that once, rotate to the ``previous''
208 macro, execute that, and finally delete it from the macro ring.
210 @findex kmacro-end-or-call-macro-repeat
212 The command @kbd{C-x C-k C-k} (@code{kmacro-end-or-call-macro-repeat})
213 executes the keyboard macro at the head of the macro ring. You can
214 repeat the macro immediately by typing another @kbd{C-k}, or you can
215 rotate the macro ring immediately by typing @kbd{C-n} or @kbd{C-p}.
217 @findex kmacro-cycle-ring-next
219 @findex kmacro-cycle-ring-previous
221 The commands @kbd{C-x C-k C-n} (@code{kmacro-cycle-ring-next}) and
222 @kbd{C-x C-k C-p} (@code{kmacro-cycle-ring-previous}) rotates the
223 macro ring, bringing the next or previous keyboard macro to the head
224 of the macro ring. The definition of the new head macro is displayed
225 in the echo area. You can continue to rotate the macro ring
226 immediately by repeating just @kbd{C-n} and @kbd{C-p} until the
227 desired macro is at the head of the ring. To execute the new macro
228 ring head immediately, just type @kbd{C-k}.
230 @findex kmacro-view-macro-repeat
233 The commands @kbd{C-x C-k C-v} (@code{kmacro-view-macro-repeat})
234 displays the last keyboard macro, or when repeated (with @kbd{C-v}),
235 it displays the previous macro on the macro ring, just like @kbd{C-x
236 C-k C-p}, but without actually rotating the macro ring. If you enter
237 @kbd{C-k} immediately after displaying a macro from the ring, that
238 macro is executed, but still without altering the macro ring.
240 So while e.g. @kbd{C-x C-k C-p C-p C-k C-k} makes the 3rd previous
241 macro the current macro and executes it twice, @kbd{C-x C-k C-v C-v
242 C-v C-k C-k} will display and execute the 3rd previous macro once and
243 then the current macro once.
245 @findex kmacro-delete-ring-head
248 The commands @kbd{C-x C-k C-d} (@code{kmacro-delete-ring-head})
249 removes and deletes the macro currently at the head of the macro
250 ring. You can use this to delete a macro that didn't work as
251 expected, or which you don't need anymore.
253 @findex kmacro-swap-ring
256 The commands @kbd{C-x C-k C-t} (@code{kmacro-swap-ring})
257 interchanges the head of the macro ring with the previous element on
260 @findex kmacro-call-ring-2nd-repeat
263 The commands @kbd{C-x C-k C-l} (@code{kmacro-call-ring-2nd-repeat})
264 executes the previous (rather than the head) element on the macro ring.
266 @node Keyboard Macro Counter
267 @section Inserting incrementing numbers in macros
269 Each keyboard macro has an associated counter which is automatically
270 incremented on every repetition of the keyboard macro. Normally, the
271 macro counter is initialized to 0 when you start defining the macro,
272 and incremented by 1 after each insertion of the counter value;
273 that is, if you insert the macro counter twice while defining the
274 macro, it will be incremented by 2 time for each repetition of the
277 @findex kmacro-insert-counter
279 The command @kbd{C-x C-k C-i} (@code{kmacro-insert-counter}) inserts
280 the current value of the keyboard macro counter and increments the
281 counter by 1. You can use a numeric prefix argument to specify a
282 different increment. If you specify a @kbd{C-u} prefix, the last
283 inserted counter value is repeated and the counter is not incremented.
284 For example, if you enter the following sequence while defining a macro
287 C-x C-k C-i C-x C-k C-i C-u C-x C-k C-i C-x C-k C-i
291 the text @samp{0112} is inserted in the buffer, and for the first and
292 second execution of the macro @samp{3445} and @samp{6778} are
295 @findex kmacro-set-counter
297 The command @kbd{C-x C-k C-c} (@code{kmacro-set-counter}) prompts
298 for the initial value of the keyboard macro counter if you use it
299 before you define a keyboard macro. If you use it while defining a
300 keyboard macro, you set the macro counter to the same (initial) value
301 on each repetition of the macro. If you specify a @kbd{C-u} prefix,
302 the counter is reset to the value it had prior to the current
303 repetition of the macro (undoing any increments so far in this
306 @findex kmacro-add-counter
308 The command @kbd{C-x C-k C-a} (@code{kmacro-add-counter}) prompts
309 for a value to add to the macro counter.
311 @findex kmacro-set-format
313 The command @kbd{C-x C-k C-f} (@code{kmacro-set-format}) prompts
314 for the format to use when inserting the macro counter. The default
315 format is @samp{%d}. If you set the counter format before you define a
316 macro, that format is restored before each repetition of the macro.
317 Consequently, any changes you make to the macro counter format while
318 defining a macro are only active for the rest of the macro.
320 @node Keyboard Macro Query
321 @section Executing Macros with Variations
324 @findex kbd-macro-query
325 Using @kbd{C-x q} (@code{kbd-macro-query}), you can get an effect
326 similar to that of @code{query-replace}, where the macro asks you each
327 time around whether to make a change. While defining the macro,
328 type @kbd{C-x q} at the point where you want the query to occur. During
329 macro definition, the @kbd{C-x q} does nothing, but when you run the
330 macro later, @kbd{C-x q} asks you interactively whether to continue.
332 The valid responses when @kbd{C-x q} asks are @key{SPC} (or @kbd{y}),
333 @key{DEL} (or @kbd{n}), @key{RET} (or @kbd{q}), @kbd{C-l} and @kbd{C-r}.
334 The answers are the same as in @code{query-replace}, though not all of
335 the @code{query-replace} options are meaningful.
337 These responses include @key{SPC} to continue, and @key{DEL} to skip
338 the remainder of this repetition of the macro and start right away with
339 the next repetition. @key{RET} means to skip the remainder of this
340 repetition and cancel further repetitions. @kbd{C-l} redraws the screen
341 and asks you again for a character to say what to do.
343 @kbd{C-r} enters a recursive editing level, in which you can perform
344 editing which is not part of the macro. When you exit the recursive
345 edit using @kbd{C-M-c}, you are asked again how to continue with the
346 keyboard macro. If you type a @key{SPC} at this time, the rest of the
347 macro definition is executed. It is up to you to leave point and the
348 text in a state such that the rest of the macro will do what you
351 @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument,
352 performs a completely different function. It enters a recursive edit
353 reading input from the keyboard, both when you type it during the
354 definition of the macro, and when it is executed from the macro. During
355 definition, the editing you do inside the recursive edit does not become
356 part of the macro. During macro execution, the recursive edit gives you
357 a chance to do some particularized editing on each repetition.
358 @xref{Recursive Edit}.
360 Another way to vary the behavior of a keyboard macro is to use a
361 register as a counter, incrementing it on each repetition of the macro.
364 @node Save Keyboard Macro
365 @section Naming and Saving Keyboard Macros
367 @cindex saving keyboard macros
368 @findex name-last-kbd-macro
370 If you wish to save a keyboard macro for later use, you can give it
371 a name using @kbd{C-x C-k n} (@code{name-last-kbd-macro}).
372 This reads a name as an argument using the minibuffer and defines that name
373 to execute the macro. The macro name is a Lisp symbol, and defining it in
374 this way makes it a valid command name for calling with @kbd{M-x} or for
375 binding a key to with @code{global-set-key} (@pxref{Keymaps}). If you
376 specify a name that has a prior definition other than another keyboard
377 macro, an error message is shown and nothing is changed.
379 @cindex binding keyboard macros
380 @findex kmacro-bind-to-key
382 Rather than giving a keyboard macro a name, you can bind it to a
383 key using @kbd{C-x C-k b} (@code{kmacro-bind-to-key}) followed by the
384 key sequence you want the keyboard macro to be bound to. You can
385 bind to any key sequence in the global keymap, but since most key
386 sequences already have other bindings, you should select the key
387 sequence carefylly. If you try to bind to a key sequence with an
388 existing binding (in any keymap), you will be asked if you really
389 want to replace the existing binding of that key.
391 To avoid problems caused by overriding existing bindings, the key
392 sequences @kbd{C-x C-k 0} through @kbd{C-x C-k 9} and @kbd{C-x C-k A}
393 through @kbd{C-x C-k Z} are reserved for your own keyboard macro
394 bindings. In fact, to bind to one of these key sequences, you only
395 need to type the digit or letter rather than the whole key sequences.
403 will bind the last keyboard macro to the key sequence @kbd{C-x C-k 4}.
405 @findex insert-kbd-macro
406 Once a macro has a command name, you can save its definition in a file.
407 Then it can be used in another editing session. First, visit the file
408 you want to save the definition in. Then use this command:
411 M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET}
415 This inserts some Lisp code that, when executed later, will define the
416 same macro with the same definition it has now. (You need not
417 understand Lisp code to do this, because @code{insert-kbd-macro} writes
418 the Lisp code for you.) Then save the file. You can load the file
419 later with @code{load-file} (@pxref{Lisp Libraries}). If the file you
420 save in is your init file @file{~/.emacs} (@pxref{Init File}) then the
421 macro will be defined each time you run Emacs.
423 If you give @code{insert-kbd-macro} a numeric argument, it makes
424 additional Lisp code to record the keys (if any) that you have bound to the
425 keyboard macro, so that the macro will be reassigned the same keys when you
428 @node Edit Keyboard Macro
429 @section Interactively executing and editing a keyboard macro
431 @findex kmacro-edit-macro
434 You can edit the last keyboard macro by typing @kbd{C-x C-k C-e} or
435 @kbd{C-x C-k RET} (@code{kmacro-edit-macro}). This formats the macro
436 definition in a buffer and enters a specialized major mode for editing
437 it. Type @kbd{C-h m} once in that buffer to display details of how to
438 edit the macro. When you are finished editing, type @kbd{C-c C-c}.
440 @findex edit-kbd-macro
442 You can edit a named keyboard macro or a macro bound to a key by typing
443 @kbd{C-x C-k e} (@code{edit-kbd-macro}). Follow that with the
444 keyboard input that you would use to invoke the macro---@kbd{C-x e} or
445 @kbd{M-x @var{name}} or some other key sequence.
447 @findex kmacro-edit-lossage
449 You can edit the last 100 keystrokes as a macro by typing
450 @kbd{C-x C-k l} (@code{kmacro-edit-lossage}).
452 @node Keyboard Macro Step-Edit
453 @section Interactively executing and editing a keyboard macro
455 @findex kmacro-step-edit-macro
457 You can interactively and stepwise replay and edit the last keyboard
458 macro one command at a time by typing @kbd{C-x C-k SPC}
459 (@code{kmacro-step-edit-macro}). Unless you quit the macro using
460 @kbd{q} or @kbd{C-g}, the edited macro replaces the last macro on the
463 This shows the last macro in the minibuffer together with the first
464 (or next) command to be executed, and prompts you for an action.
465 You can enter @kbd{?} to get a command summary.
467 The following commands are available in the step-edit mode and relate
468 to the first (or current) command in the keyboard macro:
472 @kbd{SPC} and @kbd{y} execute the current command, and advance to the
473 next command in the keyboard macro.
475 @kbd{n}, @kbd{d}, and @kbd{DEL} skip and delete the current command.
477 @kbd{f} skips the current command in this execution of the keyboard
478 macro, but doesn't delete it from the macro.
480 @kbd{TAB} executes the current command, as well as all similar
481 commands immediately following the current command; for example, TAB
482 may be used to insert a sequence of characters (corresponding to a
483 sequence of @code{self-insert-command} commands).
485 @kbd{c} continues execution (without further editing) until the end of
486 the keyboard macro. If execution terminates normally, the edited
487 macro replaces the original keyboard macro.
489 @kbd{C-k} skips and deletes the rest of the keyboard macro,
490 terminates step-editing, and replaces the original keyboard macro
491 with the edited macro.
493 @kbd{q} and @kbd{C-g} cancels the step-editing of the keyboard macro;
494 discarding any changes made to the keyboard macro.
496 @kbd{i KEY... C-j} reads and executes a series of key sequences (not
497 including the final @kbd{C-j}), and inserts them before the current
498 command in the keyboard macro, without advancing over the current
501 @kbd{I KEY...} reads one key sequence, executes it, and inserts it
502 before the current command in the keyboard macro, without advancing
503 over the current command.
505 @kbd{r KEY... C-j} reads and executes a series of key sequences (not
506 including the final @kbd{C-j}), and replaces the current command in
507 the keyboard macro with them, advancing over the inserted key
510 @kbd{R KEY...} reads one key sequence, executes it, and replaces the
511 current command in the keyboard macro with that key sequence,
512 advancing over the inserted key sequence.
514 @kbd{a KEY... C-j} executes the current command, then reads and
515 executes a series of key sequences (not including the final
516 @kbd{C-j}), and inserts them after the current command in the keyboard
517 macro; it then advances over the current command and the inserted key
520 @kbd{A KEY... C-j} executes the rest of the commands in the keyboard
521 macro, then reads and executes a series of key sequences (not
522 including the final @kbd{C-j}), and appends them at the end of the
523 keyboard macro; it then terminates the step-editing and replaces the
524 original keyboard macro with the edited macro.