22.1 Basic Use

C-x (

<F3>

Start defining a keyboard macro (kmacro-start-macro).

C-x )

End the definition of a keyboard macro (kmacro-end-macro).

C-x e

Execute the most recent keyboard macro (kmacro-end-and-call-macro). First end the definition of the keyboard macro, if currently defining it. To immediately execute the keyboard macro again, just repeat the e.

<F4>

If a keyboard macro is being defined, end the definition; otherwise, execute the most recent keyboard macro (kmacro-end-or-call-macro).

C-u C-x (

Re-execute last keyboard macro, then add more keys to its definition.

C-u C-u C-x (

Add more keys to the last keyboard macro without re-executing it.

C-x q

When this point is reached during macro execution, ask for confirmation (kbd-macro-query).

C-x C-k n

Give a command name (for the duration of the session) to the most recently defined keyboard macro (kmacro-name-last-macro).

C-x C-k b

Bind the most recently defined keyboard macro to a key sequence (for the duration of the session) (kmacro-bind-to-key).

M-x insert-kbd-macro

Insert in the buffer a keyboard macro's definition, as Lisp code.

C-x C-k e

Edit a previously defined keyboard macro (edit-kbd-macro).

C-x C-k r

Run the last keyboard macro on each line that begins in the region (apply-macro-to-region-lines).

To start defining a keyboard macro, type the C-x ( command (kmacro-start-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 (kmacro-end-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 (kmacro-end-and-call-macro), which may be given a repeat count as a numeric argument to execute the macro many times. If you enter C-x e while defining a macro, the macro is terminated and executed immediately.

After executing the macro with C-x e, you can use e repeatedly to immediately repeat the macro one or more times. For example,

     C-x ( xyz C-x e e e

inserts ‘xyzxyzxyzxyz’ in the current buffer.

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>).

The key <F4> is like a combination of C-x ) and C-x e. If you're defining a macro, <F4> ends the definition. Otherwise it executes the last macro.

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 also add to the end of the definition of the last keyboard macro without re-executing it by typing C-u C-u C-x (.

The variable kmacro-execute-before-append specifies whether a single C-u prefix causes the existing macro to be re-executed before appending to it.

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.