AD.3.1 Basic Use

To start defining a keyboard macro, type the C-x ( command (start-kbd-macro). 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, the C-x ) command (end-kbd-macro) terminates the definition (without becoming part of it!). For example,

C-x ( M-f foo C-x )

defines a macro to move forward a word and then insert `foo'.

The macro thus defined can be invoked again with the C-x e command (call-last-kbd-macro), which may be given a repeat count as a numeric argument to execute the macro many times. C-x ) can also be given a repeat count as an argument, in which case it repeats the macro that many times right after defining it, but defining the macro counts as the first repetition (since it is executed as you define it). Therefore, giving C-x ) an argument of 4 executes the macro immediately 3 additional times. An argument of zero to C-x e or C-x ) means repeat the macro indefinitely (until it gets an error or you type C-g or, on MS-DOS, C-BREAK).

If you wish to repeat an operation at regularly spaced places in the text, define a macro and include as part of the macro the commands to move to the next place you want to use it. For example, if you want to change each line, you should position point at the start of a line, and define a macro to change that line and leave point at the start of the next line. Then repeating the macro will operate on successive lines.

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,

C-x ( C-a C-SPC C-n M-w C-x b f o o RET C-y C-x b RET C-x )

defines a macro that copies the current line into the buffer `foo', then returns to the original buffer.

You can use function keys in a keyboard macro, just like keyboard keys. You can even use mouse events, but be careful about that: 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. (Using the current mouse position would be even less predictable.)

One thing that doesn't always work well in a keyboard macro is the command C-M-c (exit-recursive-edit). When this command exits a recursive edit that started within the macro, it works as you'd expect. But if it exits a recursive edit that started before you invoked the keyboard macro, it also necessarily exits the keyboard macro as part of the process.

After you have terminated the definition of a keyboard macro, you can add to the end of its definition by typing C-u C-x (. This is equivalent to plain C-x ( followed by retyping the whole definition so far. As a consequence it re-executes the macro as previously defined.

You can edit a keyboard macro already defined by typing C-x C-k (edit-kbd-macro). Follow that with the keyboard input that you would use to invoke the macro---C-x e or M-x name or some other key sequence. This formats the macro definition in a buffer and enters a specialized major mode for editing it. Type C-h m once in that buffer to display details of how to edit the macro. When you are finished editing, type C-c C-c.

The command M-x apply-macro-to-region-lines repeats the last defined keyboard macro on each complete line within the current region. It does this line by line, by moving point to the beginning of the line and then executing the macro.