| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
In this chapter we describe how to record a sequence of editing commands so you can repeat it conveniently later.
A keyboard macro is a command defined by an Emacs user to stand for another sequence of keys. For example, if you discover that you are about to type C-n M-d C-d forty times, you can speed your work by defining a keyboard macro to do C-n M-d C-d, and then executing it 39 more times.
You define a keyboard macro by executing and recording the commands which are its definition. Put differently, as you define a keyboard macro, the definition is being executed for the first time. This way, you can see the effects of your commands, so that you don't have to figure them out in your head. When you close the definition, the keyboard macro is defined and also has been, in effect, executed once. You can then do the whole thing over again by invoking the macro.
Keyboard macros differ from ordinary Emacs commands in that they are written in the Emacs command language rather than in Lisp. This makes it easier for the novice to write them, and makes them more convenient as temporary hacks. However, the Emacs command language is not powerful enough as a programming language to be useful for writing anything intelligent or general. For such things, Lisp must be used.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Start defining a keyboard macro (kmacro-start-macro).
If a keyboard macro is being defined, end the definition; otherwise,
execute the most recent keyboard macro
(kmacro-end-or-call-macro).
End the definition of a keyboard macro (kmacro-end-macro).
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.
Re-execute last keyboard macro, then add more keys to its definition.
Add more keys to the last keyboard macro without re-executing it.
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 F3 or 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 F4 or 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. For example,
F3 xyz F4 F4 F4 |
inserts `xyzxyzxyz' in the current buffer.
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 sometimes works badly 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 F3 or 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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
All defined keyboard macros are recorded in the "keyboard macro ring," a list of sequences of keys. There is only one keyboard macro ring, shared by all buffers.
Execute the keyboard macro at the head of the ring (kmacro-end-or-call-macro-repeat).
Rotate the keyboard macro ring to the next macro (defined earlier)
(kmacro-cycle-ring-next).
Rotate the keyboard macro ring to the previous macro (defined later)
(kmacro-cycle-ring-previous).
All commands which operate on the keyboard macro ring use the same C-x C-k prefix. Most of these commands can be executed and repeated immediately after each other without repeating the C-x C-k prefix. For example,
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 |
will rotate the keyboard macro ring to the "second previous" macro, execute the resulting head macro three times, rotate back to the original head macro, execute that once, rotate to the "previous" macro, execute that, and finally delete it from the macro ring.
The command C-x C-k C-k (kmacro-end-or-call-macro-repeat)
executes the keyboard macro at the head of the macro ring. You can
repeat the macro immediately by typing another C-k, or you can
rotate the macro ring immediately by typing C-n or C-p.
When a keyboard macro is being defined, C-x C-k C-k behaves like C-x ) except that, immediately afterward, you can use most key bindings of this section without the C-x C-k prefix. For instance, another C-k will re-execute the macro.
The commands C-x C-k C-n (kmacro-cycle-ring-next) and
C-x C-k C-p (kmacro-cycle-ring-previous) rotate the
macro ring, bringing the next or previous keyboard macro to the head
of the macro ring. The definition of the new head macro is displayed
in the echo area. You can continue to rotate the macro ring
immediately by repeating just C-n and C-p until the
desired macro is at the head of the ring. To execute the new macro
ring head immediately, just type C-k.
Note that Emacs treats the head of the macro ring as the "last defined keyboard macro." For instance, C-x e will execute that macro, and C-x C-k n will give it a name.
The maximum number of macros stored in the keyboard macro ring is
determined by the customizable variable kmacro-ring-max.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Insert the keyboard macro counter value in the buffer
(kmacro-insert-counter).
Set the keyboard macro counter (kmacro-set-counter).
Add the prefix arg to the keyboard macro counter (kmacro-add-counter).
Specify the format for inserting the keyboard macro counter
(kmacro-set-format).
Each keyboard macro has an associated counter. Normally, the macro counter is initialized to 0 when you start defining the macro, and incremented by 1 after each insertion of the counter value; that is, if you insert the macro counter twice while defining the macro, the counter will increase by 2 on each repetition of the macro.
The command C-x C-k C-i (kmacro-insert-counter) inserts
the current value of the current keyboard macro's counter, and
increments the counter by 1. You can use a numeric prefix argument to
specify a different increment. If you just specify a C-u
prefix, then the increment is zero, so it repeats the last inserted
counter value. For example, if you enter the following sequence while
defining a macro
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 |
it inserts `0112' in the buffer. The next two iterations of the macro will insert `3445' and `6778'.
This command usually only makes sense while defining a keyboard macro. But its behavior when no keyboard macro is being defined or executed is predictable: it inserts and increments the counter of the macro at the head of the keyboard macro ring.
The command C-x C-k C-c (kmacro-set-counter) sets the
current macro counter to the value of the numeric argument. If you use
it inside the macro, it operates on each repetition of the macro. If
you specify just C-u as the prefix, while executing the macro,
that resets the counter to the value it had at the beginning of the
current repetition of the macro (undoing any increments so far in this
repetition).
The command C-x C-k C-a (kmacro-add-counter) adds the
prefix argument to the current macro counter. With just C-u as
argument, it resets the counter to the last value inserted by any
keyboard macro. (Normally, when you use this, the last insertion
will be in the same macro and it will be the same counter.)
The command C-x C-k C-f (kmacro-set-format) prompts for
the format to use when inserting the macro counter. The default
format is `%d', which means to insert the number in decimal
without any padding. You can exit with empty minibuffer to reset the
format to this default. You can specify any format string that the
format function accepts and that makes sense with a single
integer extra argument (see (elisp)Formatting Strings section `Formatting Strings' in The Emacs Lisp Reference Manual). Do not put the format string inside double
quotes when you insert it in the minibuffer.
If you use this command while no keyboard macro is being defined or executed, the new format affects all subsequent macro definitions. Existing macros continue to use the format in effect when they were defined. If you set the format while defining a keyboard macro, this affects the macro being defined from that point on, but it does not affect subsequent macros. Execution of the macro will, at each step, use the format in effect at that step during its definition. Changes to the macro format during execution of a macro, like the corresponding changes during its definition, have no effect on subsequent macros.
The format set by C-x C-k C-f does not affect insertion of numbers stored in registers.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When this point is reached during macro execution, ask for confirmation
(kbd-macro-query).
Using C-x q (kbd-macro-query), you can get an effect
similar to that of query-replace, where the macro asks you each
time around whether to make a change. While defining the macro,
type C-x q at the point where you want the query to occur. During
macro definition, the C-x q does nothing, but when you run the
macro later, C-x q asks you interactively whether to continue.
The valid responses when C-x q asks are SPC (or y),
DEL (or n), RET (or q), C-l and C-r.
The answers are the same as in query-replace, though not all of
the query-replace options are meaningful.
These responses include SPC to continue, and DEL to skip the remainder of this repetition of the macro and start right away with the next repetition. RET means to skip the remainder of this repetition and cancel further repetitions. C-l redraws the screen and asks you again for a character to say what to do.
C-r enters a recursive editing level, in which you can perform editing which is not part of the macro. When you exit the recursive edit using C-M-c, you are asked again how to continue with the keyboard macro. If you type a SPC at this time, the rest of the macro definition is executed. It is up to you to leave point and the text in a state such that the rest of the macro will do what you want.
C-u C-x q, which is C-x q with a numeric argument, performs a completely different function. It enters a recursive edit reading input from the keyboard, both when you type it during the definition of the macro, and when it is executed from the macro. During definition, the editing you do inside the recursive edit does not become part of the macro. During macro execution, the recursive edit gives you a chance to do some particularized editing on each repetition. See section Recursive Editing Levels.
Another way to vary the behavior of a keyboard macro is to use a register as a counter, incrementing it on each repetition of the macro. See section Keeping Numbers in Registers.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Give a command name (for the duration of the Emacs session) to the most
recently defined keyboard macro (kmacro-name-last-macro).
Bind the most recently defined keyboard macro to a key sequence (for
the duration of the session) (kmacro-bind-to-key).
Insert in the buffer a keyboard macro's definition, as Lisp code.
If you wish to save a keyboard macro for later use, you can give it
a name using C-x C-k n (kmacro-name-last-macro).
This reads a name as an argument using the minibuffer and defines that
name to execute the last keyboard macro, in its current form. (If you
later add to the definition of this macro, that does not alter the
name's definition as a macro.) The macro name is a Lisp symbol, and
defining it in this way makes it a valid command name for calling with
M-x or for binding a key to with global-set-key
(see section Keymaps). If you specify a name that has a prior definition
other than a keyboard macro, an error message is shown and nothing is
changed.
You can also bind the last keyboard macro (in its current form) to a
key, using C-x C-k b (kmacro-bind-to-key) followed by the
key sequence you want to bind. You can bind to any key sequence in
the global keymap, but since most key sequences already have other
bindings, you should select the key sequence carefully. If you try to
bind to a key sequence with an existing binding (in any keymap), this
command asks you for confirmation before replacing the existing binding.
To avoid problems caused by overriding existing bindings, the key sequences C-x C-k 0 through C-x C-k 9 and C-x C-k A through C-x C-k Z are reserved for your own keyboard macro bindings. In fact, to bind to one of these key sequences, you only need to type the digit or letter rather than the whole key sequences. For example,
C-x C-k b 4 |
will bind the last keyboard macro to the key sequence C-x C-k 4.
Once a macro has a command name, you can save its definition in a file. Then it can be used in another editing session. First, visit the file you want to save the definition in. Then use this command:
M-x insert-kbd-macro RET macroname RET |
This inserts some Lisp code that, when executed later, will define the
same macro with the same definition it has now. (You need not
understand Lisp code to do this, because insert-kbd-macro writes
the Lisp code for you.) Then save the file. You can load the file
later with load-file (see section Libraries of Lisp Code for Emacs). If the file you
save in is your init file `~/.emacs' (see section The Init File, `~/.emacs') then the
macro will be defined each time you run Emacs.
If you give insert-kbd-macro a numeric argument, it makes
additional Lisp code to record the keys (if any) that you have bound
to macroname, so that the macro will be reassigned the same keys
when you load the file.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Edit the last defined keyboard macro (kmacro-edit-macro).
Edit a previously defined keyboard macro name (edit-kbd-macro).
Edit the last 100 keystrokes as a keyboard macro
(kmacro-edit-lossage).
You can edit the last keyboard macro by typing C-x C-k C-e or
C-x C-k RET (kmacro-edit-macro). 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.
You can edit a named keyboard macro or a macro bound to a key by typing
C-x C-k e (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.
You can edit the last 100 keystrokes as a macro by typing
C-x C-k l (kmacro-edit-lossage).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You can interactively replay and edit the last keyboard
macro, one command at a time, by typing C-x C-k SPC
(kmacro-step-edit-macro). Unless you quit the macro using
q or C-g, the edited macro replaces the last macro on the
macro ring.
This macro editing feature shows the last macro in the minibuffer together with the first (or next) command to be executed, and prompts you for an action. You can enter ? to get a summary of your options. These actions are available:
SPC and y execute the current command, and advance to the next command in the keyboard macro.
n, d, and DEL skip and delete the current command.
f skips the current command in this execution of the keyboard macro, but doesn't delete it from the macro.
TAB executes the current command, as well as all similar
commands immediately following the current command; for example, TAB
may be used to insert a sequence of characters (corresponding to a
sequence of self-insert-command commands).
c continues execution (without further editing) until the end of the keyboard macro. If execution terminates normally, the edited macro replaces the original keyboard macro.
C-k skips and deletes the rest of the keyboard macro, terminates step-editing, and replaces the original keyboard macro with the edited macro.
q and C-g cancels the step-editing of the keyboard macro; discarding any changes made to the keyboard macro.
i KEY... C-j reads and executes a series of key sequences (not including the final C-j), and inserts them before the current command in the keyboard macro, without advancing over the current command.
I KEY... reads one key sequence, executes it, and inserts it before the current command in the keyboard macro, without advancing over the current command.
r KEY... C-j reads and executes a series of key sequences (not including the final C-j), and replaces the current command in the keyboard macro with them, advancing over the inserted key sequences.
R KEY... reads one key sequence, executes it, and replaces the current command in the keyboard macro with that key sequence, advancing over the inserted key sequence.
a KEY... C-j executes the current command, then reads and executes a series of key sequences (not including the final C-j), and inserts them after the current command in the keyboard macro; it then advances over the current command and the inserted key sequences.
A KEY... C-j executes the rest of the commands in the keyboard macro, then reads and executes a series of key sequences (not including the final C-j), and appends them at the end of the keyboard macro; it then terminates the step-editing and replaces the original keyboard macro with the edited macro.
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by Mark Kaminski on July, 3 2008 using texi2html 1.70.