@c This is part of the Emacs manual.
-@c Copyright (C) 1985,86,87,93,94,95,97,2000,2001,2002,2003,2004
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
+@c 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Keyboard Macros, Files, Fixit, Top
@chapter Keyboard Macros
@cindex defining keyboard macros
@cindex keyboard macro
- In this chapter we describe how a sequence of editing commands can
-be recorded and repeated multiple times.
+ In this chapter we describe how to record a sequence of editing
+commands so you can repeat it conveniently later.
- A @dfn{keyboard macro} is a command defined by the user to stand for
+ A @dfn{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 @kbd{C-n C-d} forty times, you can speed your work by
-defining a keyboard macro to do @kbd{C-n C-d} and calling it with a
-repeat count of forty.
-
- You define a keyboard macro while executing the commands which are the
-definition. Put differently, as you define a keyboard macro, the
-definition is being executed for the first time. This way, you can see
-what the effects of your commands are, so that you don't have to figure
-them out in your head. When you are finished, 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.
+about to type @kbd{C-n M-d C-d} forty times, you can speed your work by
+defining a keyboard macro to do @kbd{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
* Keyboard Macro Query:: Making keyboard macros do different things each time.
* Save Keyboard Macro:: Giving keyboard macros names; saving them in files.
* Edit Keyboard Macro:: Editing keyboard macros.
-* Keyboard Macro Step-Edit:: Interactively executing and editing a keyboard macro.
+* Keyboard Macro Step-Edit:: Interactively executing and editing a keyboard
+ macro.
@end menu
@node Basic Keyboard Macro
@table @kbd
@item C-x (
+@itemx @key{F3}
Start defining a keyboard macro (@code{kmacro-start-macro}).
@item C-x )
End the definition of a keyboard macro (@code{kmacro-end-macro}).
Execute the most recent keyboard macro (@code{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 @kbd{e}.
+@item @key{F4}
+If a keyboard macro is being defined, end the definition; otherwise,
+execute the most recent keyboard macro
+(@code{kmacro-end-or-call-macro}).
@item C-u C-x (
Re-execute last keyboard macro, then add more keys to its definition.
@item C-u C-u C-x (
Add more keys to the last keyboard macro without re-executing it.
-@item C-x q
-When this point is reached during macro execution, ask for confirmation
-(@code{kbd-macro-query}).
-@item C-x C-k n
-Give a command name (for the duration of the session) to the most
-recently defined keyboard macro (@code{kmacro-name-last-macro}).
-@item C-x C-k b
-Bind the most recently defined keyboard macro to a key sequence (for
-the duration of the session) (@code{kmacro-bind-to-key}).
-@item M-x insert-kbd-macro
-Insert in the buffer a keyboard macro's definition, as Lisp code.
-@item C-x C-k e
-Edit a previously defined keyboard macro (@code{edit-kbd-macro}).
@item C-x C-k r
Run the last keyboard macro on each line that begins in the region
(@code{apply-macro-to-region-lines}).
indefinitely (until it gets an error or you type @kbd{C-g} or, on
MS-DOS, @kbd{C-@key{BREAK}}).
-@kindex C-x C-k C-s
-@kindex C-x C-k C-k
-Alternatively, you can use @kbd{C-x C-k C-s} to start a keyboard macro,
-and @kbd{C-x C-k C-k...} to end and execute it.
+ The key @key{F4} is like a combination of @kbd{C-x )} and @kbd{C-x
+e}. If you're defining a macro, @key{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
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
+ One thing that sometimes works badly in a keyboard macro is the
command @kbd{C-M-c} (@code{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.
+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 @kbd{C-u C-x (}. This is equivalent
a list of sequences of keys. There is only one keyboard macro ring,
shared by all buffers.
- All commands which operates on the keyboard macro ring use the
+@table @kbd
+@item C-x C-k C-k
+Execute the keyboard macro at the head of the ring (@code{kmacro-end-or-call-macro-repeat}).
+@item C-x C-k C-n
+Rotate the keyboard macro ring to the next macro (defined earlier)
+(@code{kmacro-cycle-ring-next}).
+@item C-x C-k C-p
+Rotate the keyboard macro ring to the previous macro (defined later)
+(@code{kmacro-cycle-ring-previous}).
+@end table
+
+ All commands which operate on the keyboard macro ring use the
same @kbd{C-x C-k} prefix. Most of these commands can be executed and
repeated immediately after each other without repeating the @kbd{C-x
C-k} prefix. For example,
repeat the macro immediately by typing another @kbd{C-k}, or you can
rotate the macro ring immediately by typing @kbd{C-n} or @kbd{C-p}.
+ When a keyboard macro is being defined, @kbd{C-x C-k C-k} behaves like
+@kbd{C-x )} except that, immediately afterward, you can use most key
+bindings of this section without the @kbd{C-x C-k} prefix. For
+instance, another @kbd{C-k} will re-execute the macro.
+
@findex kmacro-cycle-ring-next
@kindex C-x C-k C-n
@findex kmacro-cycle-ring-previous
@kindex C-x C-k C-p
The commands @kbd{C-x C-k C-n} (@code{kmacro-cycle-ring-next}) and
-@kbd{C-x C-k C-p} (@code{kmacro-cycle-ring-previous}) rotates the
+@kbd{C-x C-k C-p} (@code{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
ring head immediately, just type @kbd{C-k}.
Note that Emacs treats the head of the macro ring as the ``last
-defined keyboard macro''. For instance, it is the keyboard macro that
-@kbd{C-x e} will execute.
+defined keyboard macro.'' For instance, @kbd{C-x e} will execute that
+macro, and @kbd{C-x C-k n} will give it a name.
+@ignore @c This interface is too kludgy
+ @c and the functionality duplicates the functionality above -- rms.
@findex kmacro-view-macro-repeat
@kindex C-x C-k C-v
-
- The commands @kbd{C-x C-k C-v} (@code{kmacro-view-macro-repeat})
+ The command @kbd{C-x C-k C-v} (@code{kmacro-view-macro-repeat})
displays the last keyboard macro, or when repeated (with @kbd{C-v}),
it displays the previous macro on the macro ring, just like @kbd{C-x
C-k C-p}, but without actually rotating the macro ring. If you enter
@kbd{C-k} immediately after displaying a macro from the ring, that
macro is executed, but still without altering the macro ring.
- So while e.g. @kbd{C-x C-k C-p C-p C-k C-k} makes the 3rd previous
+ So while e.g. @kbd{C-x C-k C-p C-p C-p C-k C-k} makes the 3rd previous
macro the current macro and executes it twice, @kbd{C-x C-k C-v C-v
C-v C-k C-k} will display and execute the 3rd previous macro once and
then the current macro once.
+@end ignore
+@ignore @c This is just too much feeping creaturism.
+ @c If you are reusing certain macros enough to want these,
+ @c you should give then names. -- rms
@findex kmacro-delete-ring-head
@kindex C-x C-k C-d
- The commands @kbd{C-x C-k C-d} (@code{kmacro-delete-ring-head})
+ The command @kbd{C-x C-k C-d} (@code{kmacro-delete-ring-head})
removes and deletes the macro currently at the head of the macro
ring. You can use this to delete a macro that didn't work as
expected, or which you don't need anymore.
@findex kmacro-swap-ring
@kindex C-x C-k C-t
- The commands @kbd{C-x C-k C-t} (@code{kmacro-swap-ring})
+ The command @kbd{C-x C-k C-t} (@code{kmacro-swap-ring})
interchanges the head of the macro ring with the previous element on
the macro ring.
@findex kmacro-call-ring-2nd-repeat
@kindex C-x C-k C-l
- The commands @kbd{C-x C-k C-l} (@code{kmacro-call-ring-2nd-repeat})
+ The command @kbd{C-x C-k C-l} (@code{kmacro-call-ring-2nd-repeat})
executes the previous (rather than the head) element on the macro ring.
+@end ignore
+
+@vindex kmacro-ring-max
+ The maximum number of macros stored in the keyboard macro ring is
+determined by the customizable variable @code{kmacro-ring-max}.
@node Keyboard Macro Counter
@section The Keyboard Macro Counter
- Each keyboard macro has an associated counter which is automatically
-incremented on every repetition of the keyboard macro. Normally, the
+@table @kbd
+@item C-x C-k C-i
+Insert the keyboard macro counter value in the buffer
+(@code{kmacro-insert-counter}).
+@item C-x C-k C-c
+Set the keyboard macro counter (@code{kmacro-set-counter}).
+@item C-x C-k C-a
+Add the prefix arg to the keyboard macro counter (@code{kmacro-add-counter}).
+@item C-x C-k C-f
+Specify the format for inserting the keyboard macro counter
+(@code{kmacro-set-format}).
+@end table
+
+ 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
@findex kmacro-insert-counter
@kindex C-x C-k C-i
The command @kbd{C-x C-k C-i} (@code{kmacro-insert-counter}) inserts
-the current value of the keyboard macro counter and increments the
-counter by 1. You can use a numeric prefix argument to specify a
-different increment. If you specify a @kbd{C-u} prefix, the last
-inserted counter value is repeated and the counter is not incremented.
-For example, if you enter the following sequence while defining a macro
+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 @kbd{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
@example
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
@end example
@noindent
-the text @samp{0112} is inserted in the buffer, and for the first and
-second execution of the macro @samp{3445} and @samp{6778} are
-inserted.
+it inserts @samp{0112} in the buffer. The next two iterations
+of the macro will insert @samp{3445} and @samp{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.
@findex kmacro-set-counter
@kindex C-x C-k C-c
- The command @kbd{C-x C-k C-c} (@code{kmacro-set-counter}) prompts
-for the initial value of the keyboard macro counter if you use it
-before you define a keyboard macro. If you use it while defining a
-keyboard macro, you set the macro counter to the same (initial) value
-on each repetition of the macro. If you specify a @kbd{C-u} prefix,
-the counter is reset to the value it had prior to the current
-repetition of the macro (undoing any increments so far in this
+ The command @kbd{C-x C-k C-c} (@code{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 @kbd{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).
@findex kmacro-add-counter
@kindex C-x C-k C-a
- The command @kbd{C-x C-k C-a} (@code{kmacro-add-counter}) prompts
-for a value to add to the macro counter.
+ The command @kbd{C-x C-k C-a} (@code{kmacro-add-counter}) adds the
+prefix argument to the current macro counter. With just @kbd{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.)
@findex kmacro-set-format
@kindex C-x C-k C-f
- The command @kbd{C-x C-k C-f} (@code{kmacro-set-format}) prompts
-for the format to use when inserting the macro counter. The default
-format is @samp{%d}. If you set the counter format before you define a
-macro, that format is restored before each repetition of the macro.
-Consequently, any changes you make to the macro counter format while
-defining a macro are only active for the rest of the macro.
+ The command @kbd{C-x C-k C-f} (@code{kmacro-set-format}) prompts for
+the format to use when inserting the macro counter. The default
+format is @samp{%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
+@code{format} function accepts and that makes sense with a single
+integer extra argument (@pxref{Formatting Strings,,, elisp, 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 @kbd{C-x C-k C-f} does not affect insertion of
+numbers stored in registers.
@node Keyboard Macro Query
@section Executing Macros with Variations
+@table @kbd
+@item C-x q
+When this point is reached during macro execution, ask for confirmation
+(@code{kbd-macro-query}).
+@end table
+
@kindex C-x q
@findex kbd-macro-query
Using @kbd{C-x q} (@code{kbd-macro-query}), you can get an effect
@node Save Keyboard Macro
@section Naming and Saving Keyboard Macros
+@table @kbd
+@item C-x C-k n
+Give a command name (for the duration of the Emacs session) to the most
+recently defined keyboard macro (@code{kmacro-name-last-macro}).
+@item C-x C-k b
+Bind the most recently defined keyboard macro to a key sequence (for
+the duration of the session) (@code{kmacro-bind-to-key}).
+@item M-x insert-kbd-macro
+Insert in the buffer a keyboard macro's definition, as Lisp code.
+@end table
+
@cindex saving keyboard macros
@findex kmacro-name-last-macro
@kindex C-x C-k n
@cindex binding keyboard macros
@findex kmacro-bind-to-key
@kindex C-x C-k b
- You can also bind the last keyboard macro to a key, using
-@kbd{C-x C-k b} (@code{kmacro-bind-to-key}) followed by the
-key sequence you want the keyboard macro to be bound to. 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), you will be asked if you really
-want to replace the existing binding of that key.
-
-To avoid problems caused by overriding existing bindings, the key
+ You can also bind the last keyboard macro (in its current form) to a
+key, using @kbd{C-x C-k b} (@code{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 @kbd{C-x C-k 0} through @kbd{C-x C-k 9} and @kbd{C-x C-k A}
through @kbd{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
@node Edit Keyboard Macro
@section Editing a Keyboard Macro
+@table @kbd
+@item C-x C-k C-e
+Edit the last defined keyboard macro (@code{kmacro-edit-macro}).
+@item C-x C-k e @var{name} @key{RET}
+Edit a previously defined keyboard macro @var{name} (@code{edit-kbd-macro}).
+@item C-x C-k l
+Edit the last 100 keystrokes as a keyboard macro
+(@code{kmacro-edit-lossage}).
+@end table
+
@findex kmacro-edit-macro
@kindex C-x C-k C-e
@kindex C-x C-k RET
@findex kmacro-step-edit-macro
@kindex C-x C-k SPC
- You can interactively and stepwise replay and edit the last keyboard
-macro one command at a time by typing @kbd{C-x C-k SPC}
+ You can interactively replay and edit the last keyboard
+macro, one command at a time, by typing @kbd{C-x C-k SPC}
(@code{kmacro-step-edit-macro}). Unless you quit the macro using
@kbd{q} or @kbd{C-g}, the edited macro replaces the last macro on the
macro ring.
-This 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 @kbd{?} to get a command summary.
-
-The following commands are available in the step-edit mode and relate
-to the first (or current) command in the keyboard macro:
+ 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 @kbd{?} to get a summary of your
+options. These actions are available:
@itemize @bullet{}
@item
@kbd{f} skips the current command in this execution of the keyboard
macro, but doesn't delete it from the macro.
@item
-@kbd{TAB} executes the current command, as well as all similar
-commands immediately following the current command; for example, TAB
+@kbd{@key{TAB}} executes the current command, as well as all similar
+commands immediately following the current command; for example, @key{TAB}
may be used to insert a sequence of characters (corresponding to a
sequence of @code{self-insert-command} commands).
@item