File: kmacro.el.html

The kmacro package provides the user interface to Emacs's basic keyboard macro functionality. With kmacro, two function keys are dedicated to keyboard macros, by default F3 and F4.

Note: The traditional bindings C-x (, C-x ), and C-x e are still supported, but for some users these bindings are too hard to type to be really useful for doing small repeated tasks.

To start defining a keyboard macro, use F3. To end the macro, use F4, and to call the macro also use F4. This makes it very easy to repeat a macro immediately after defining it.

You can call the macro repeatedly by pressing F4 multiple times, or you can give a numeric prefix argument specifying the number of times to repeat the macro. Macro execution automatically terminates when point reaches the end of the buffer or if an error is signaled by ringing the bell.

When you define a macro with F3/F4, it is automatically added to the head of the "keyboard macro ring", and F4 actually executes the first element of the macro ring.

Note: an empty macro is never added to the macro ring.

You can execute the second element on the macro ring with C-u F4 or C-x C-k C-l, you can use C-x C-k C-p and C-x C-k C-n to cycle through the macro ring, and you can swap the first and second elements with C-x C-k C-t. To delete the first element in the macro ring, use C-x C-k C-d.

You can also use C-x C-k C-s to start a macro, and C-x C-k C-k to end it; then use C-k to execute it immediately, or C-x C-k C-k to execute it later.

In general, immediately after using C-x C-k followed by one of C-k, C-l, C-p, or C-n, you can further cycle the macro ring using C-p or C-n, execute the first or second macro using C-k or C-l, delete the head macro with C-d, or edit the current macro with C-e without repeating the C-x C-k prefix.

If you enter F3 while defining the macro, the numeric value of kmacro-counter is inserted using the kmacro-counter-format, and kmacro-counter is incremented by 1 (or the numeric prefix value of F3).

The initial value of kmacro-counter is 0, or the numeric prefix value given to F3 when starting the macro.

Now, each time you call the macro using F4, the current value of kmacro-counter is inserted and incremented, making it easy to insert incremental numbers in the buffer.

Example:

The following sequence: M-5 F3 x M-2 F3 y F4 F4 F4 F4
inserts the following string: x5yx7yx9yx11y

A macro can also be called using a mouse click, default S-mouse-3. This calls the macro at the point where you click the mouse.

You can edit the last macro using C-x C-k C-e.

You can append to the last macro using C-u F3.

You can set the macro counter using C-x C-k C-c, add to it using C-x C-k C-a, and you can set the macro counter format with C-x C-k C-f.

The following key bindings are performed:

          Normal While defining macro
          --------------------------- ------------------------------
 f3 Define macro Insert current counter value
          Prefix arg specifies initial and increase counter by prefix
          counter value (default 0) (default increment: 1)

 C-u f3 APPENDs to last macro

 f4 Call last macro End macro
          Prefix arg specifies number
          of times to execute macro.

 C-u f4 Swap last and head of macro ring.

 S-mouse-3 Set point at click and End macro and execute macro at
            execute last macro. click.

Defined variables (22)

Defined functions (91)

Defined faces (3)