Next: Keyboard Macro Ring, Up: Keyboard Macros
kmacro-start-macro-or-insert-counter).
kmacro-end-or-call-macro).
apply-macro-to-region-lines).
To start defining a keyboard macro, type <F3>. From then on,
your keys continue to be executed, but also become part of the
definition of the macro. ‘Def’ appears in the mode line to
remind you of what is going on. When you are finished, type <F4>
(kmacro-end-or-call-macro) to terminate the definition. For
example,
<F3> M-f foo <F4>
defines a macro to move forward a word and then insert ‘foo’. Note that <F3> and <F4> do not become part of the macro.
After defining the macro, you can call it with <F4>. For the above example, this has the same effect as typing M-f foo again. (Note the two roles of the <F4> command: it ends the macro if you are in the process of defining one, or calls the last macro otherwise.) You can also supply <F4> with a numeric prefix argument ‘n’, which means to invoke the macro ‘n’ times. An argument of zero repeats the macro indefinitely, until it gets an error or you type C-g (or, on MS-DOS, C-<BREAK>).
The above example demonstrates a handy trick that you can employ with keyboard macros: if you wish to repeat an operation at regularly spaced places in the text, include a motion command as part of the macro. In this case, repeating the macro inserts the string ‘foo’ after each successive word.
After terminating the definition of a keyboard macro, you can append
more keystrokes to its definition by typing C-u <F3>. This
is equivalent to plain <F3> followed by retyping the whole
definition so far. As a consequence, it re-executes the macro as
previously defined. If you change the variable
kmacro-execute-before-append to nil, the existing macro
will not be re-executed before appending to it (the default is
t). You can also add to the end of the definition of the last
keyboard macro without re-executing it by typing C-u C-u
<F3>.
When a command reads an argument with the minibuffer, your minibuffer input becomes part of the macro along with the command. So when you replay the macro, the command gets the same argument as when you entered the macro. For example,
<F3> C-a C-k C-x b foo <RET> C-y C-x b <RET> <F4>
defines a macro that kills the current line, yanks it into the buffer ‘foo’, then returns to the original buffer.
Most keyboard commands work as usual in a keyboard macro definition,
with some exceptions. Typing C-g (keyboard-quit) quits
the keyboard macro definition. Typing C-M-c
(exit-recursive-edit) can be unreliable: it works as you'd
expect if exiting a recursive edit that started within the macro, but
if it exits a recursive edit that started before you invoked the
keyboard macro, it also necessarily exits the keyboard macro too.
Mouse events are also unreliable, even though you can use them in a
keyboard macro: when the macro replays the mouse event, it uses the
original mouse position of that event, the position that the mouse had
while you were defining the macro. The effect of this may be hard to
predict.
The command C-x C-k r (apply-macro-to-region-lines)
repeats the last defined keyboard macro on each line that begins in
the region. It does this line by line, by moving point to the
beginning of the line and then executing the macro.
In addition to the <F3> and <F4> commands described above,
Emacs also supports an older set of key bindings for defining and
executing keyboard macros. To begin a macro definition, type C-x
( (kmacro-start-macro); as with <F3>, a prefix argument
appends this definition to the last keyboard macro. To end a macro
definition, type C-x ) (kmacro-end-macro). To execute
the most recent macro, type C-x e
(kmacro-end-and-call-macro). If you enter C-x e while
defining a macro, the macro is terminated and executed immediately.
Immediately after typing C-x e, you can type <e> repeatedly
to immediately repeat the macro one or more times. You can also give
C-x e a repeat argument, just like <F4>.
C-x ) can be given a repeat count as an argument. This means to repeat the macro right after defining it. The macro definition itself counts as the first repetition, since it is executed as you define it, so C-u 4 C-x ) executes the macro immediately 3 additional times.