(Keyboard Macro Ring): Rename section.

[bpt/emacs.git] / man / kmacro.texi

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

  A @dfn{keyboard macro} is a command defined by the 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.

  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.

@menu
* Basic Keyboard Macro::     Defining and running keyboard macros.
* Keyboard Macro Ring::      Where previous keyboard macros are saved.
* Keyboard Macro Counter::   Inserting incrementing numbers in macros.
* 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.
@end menu

@node Basic Keyboard Macro
@section Basic Use

@table @kbd
@item C-x (
Start defining a keyboard macro (@code{kmacro-start-macro}).
@item C-x )
End the definition of a keyboard macro (@code{kmacro-end-macro}).
@item C-x e
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 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{name-last-kbd-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 complete line in the region
(@code{apply-macro-to-region-lines}).
@end table

@kindex C-x (
@kindex C-x )
@kindex C-x e
@findex kmacro-start-macro
@findex kmacro-end-macro
@findex kmacro-end-and-call-macro
  To start defining a keyboard macro, type the @kbd{C-x (} command
(@code{kmacro-start-macro}).  From then on, your keys continue to be
executed, but also become part of the definition of the macro.  @samp{Def}
appears in the mode line to remind you of what is going on.  When you are
finished, the @kbd{C-x )} command (@code{kmacro-end-macro}) terminates the
definition (without becoming part of it!).  For example,

@example
C-x ( M-f foo C-x )
@end example

@noindent
defines a macro to move forward a word and then insert @samp{foo}.

  The macro thus defined can be invoked again with the @kbd{C-x e}
command (@code{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 @kbd{C-x e} while defining a macro, the macro is
terminated and executed immediately.

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

@example
C-x ( xyz C-x e e e
@end example

@noindent
inserts @samp{xyzxyzxyzxyz} in the current buffer.

  @kbd{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 @kbd{C-x )} an argument
of 4 executes the macro immediately 3 additional times.  An argument
of zero to @kbd{C-x e} or @kbd{C-x )} means repeat the macro
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.

  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,

@example
C-x ( C-a C-@key{SPC} C-n M-w C-x b f o o @key{RET} C-y C-x b @key{RET} C-x )
@end example

@noindent
defines a macro that copies the current line into the buffer
@samp{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 @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.

  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
to plain @kbd{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 @kbd{C-u C-u C-x (}.

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

@findex apply-macro-to-region-lines
@kindex C-x C-k r
  The command @kbd{C-x C-k r} (@code{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.

@node Keyboard Macro Ring
@section The Keyboard Macro Ring

  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.

  All commands which operates 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,

@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
@end example

@noindent
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.

@findex kmacro-end-or-call-macro-repeat
@kindex C-x C-k C-k
  The command @kbd{C-x C-k C-k} (@code{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 @kbd{C-k}, or you can
rotate the macro ring immediately by typing @kbd{C-n} or @kbd{C-p}.

@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
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 @kbd{C-n} and @kbd{C-p} until the
desired macro is at the head of the ring.  To execute the new macro
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.

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

@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})
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})
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})
executes the previous (rather than the head) element on the macro ring.

@node Keyboard Macro Counter
@section Inserting incrementing numbers in macros

  Each keyboard macro has an associated counter which is automatically
incremented on every repetition of the keyboard macro.  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.

@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

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

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

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

@node Keyboard Macro Query
@section Executing Macros with Variations

@kindex C-x q
@findex kbd-macro-query
  Using @kbd{C-x q} (@code{kbd-macro-query}), you can get an effect
similar to that of @code{query-replace}, where the macro asks you each
time around whether to make a change.  While defining the macro,
type @kbd{C-x q} at the point where you want the query to occur.  During
macro definition, the @kbd{C-x q} does nothing, but when you run the
macro later, @kbd{C-x q} asks you interactively whether to continue.

  The valid responses when @kbd{C-x q} asks are @key{SPC} (or @kbd{y}),
@key{DEL} (or @kbd{n}), @key{RET} (or @kbd{q}), @kbd{C-l} and @kbd{C-r}.
The answers are the same as in @code{query-replace}, though not all of
the @code{query-replace} options are meaningful.

  These responses include @key{SPC} to continue, and @key{DEL} to skip
the remainder of this repetition of the macro and start right away with
the next repetition.  @key{RET} means to skip the remainder of this
repetition and cancel further repetitions.  @kbd{C-l} redraws the screen
and asks you again for a character to say what to do.

  @kbd{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 @kbd{C-M-c}, you are asked again how to continue with the
keyboard macro.  If you type a @key{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.@refill

  @kbd{C-u C-x q}, which is @kbd{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.
@xref{Recursive Edit}.

  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.
@xref{RegNumbers}.

@node Save Keyboard Macro
@section Naming and Saving Keyboard Macros

@cindex saving keyboard macros
@findex name-last-kbd-macro
@kindex C-x C-k n
  If you wish to save a keyboard macro for later use, you can give it
a name using @kbd{C-x C-k n} (@code{name-last-kbd-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
@kbd{M-x} or for binding a key to with @code{global-set-key}
(@pxref{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.

@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
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
need to type the digit or letter rather than the whole key sequences.
For example,

@example
C-x C-k b 4
@end example

@noindent
will bind the last keyboard macro to the key sequence @kbd{C-x C-k 4}.

@findex insert-kbd-macro
  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:

@example
M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET}
@end example

@noindent
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 @code{insert-kbd-macro} writes
the Lisp code for you.)  Then save the file.  You can load the file
later with @code{load-file} (@pxref{Lisp Libraries}).  If the file you
save in is your init file @file{~/.emacs} (@pxref{Init File}) then the
macro will be defined each time you run Emacs.

  If you give @code{insert-kbd-macro} a numeric argument, it makes
additional Lisp code to record the keys (if any) that you have bound
to @var{macroname}, so that the macro will be reassigned the same keys
when you load the file.

@node Edit Keyboard Macro
@section Editing a Keyboard Macro

@findex kmacro-edit-macro
@kindex C-x C-k C-e
@kindex C-x C-k RET
  You can edit the last keyboard macro by typing @kbd{C-x C-k C-e} or
@kbd{C-x C-k RET} (@code{kmacro-edit-macro}).  This formats the macro
definition in a buffer and enters a specialized major mode for editing
it.  Type @kbd{C-h m} once in that buffer to display details of how to
edit the macro.  When you are finished editing, type @kbd{C-c C-c}.

@findex edit-kbd-macro
@kindex C-x C-k e
  You can edit a named keyboard macro or a macro bound to a key by typing
@kbd{C-x C-k e} (@code{edit-kbd-macro}).  Follow that with the
keyboard input that you would use to invoke the macro---@kbd{C-x e} or
@kbd{M-x @var{name}} or some other key sequence.

@findex kmacro-edit-lossage
@kindex C-x C-k l
  You can edit the last 100 keystrokes as a macro by typing
@kbd{C-x C-k l} (@code{kmacro-edit-lossage}).

@node Keyboard Macro Step-Edit
@section Interactively executing and editing a keyboard macro

@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}
(@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:

@itemize @bullet{}
@item
@kbd{SPC} and @kbd{y} execute the current command, and advance to the
next command in the keyboard macro.
@item
@kbd{n}, @kbd{d}, and @kbd{DEL} skip and delete the current command.
@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
may be used to insert a sequence of characters (corresponding to a
sequence of @code{self-insert-command} commands).
@item
@kbd{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.
@item
@kbd{C-k} skips and deletes the rest of the keyboard macro,
terminates step-editing, and replaces the original keyboard macro
with the edited macro.
@item
@kbd{q} and @kbd{C-g} cancels the step-editing of the keyboard macro;
discarding any changes made to the keyboard macro.
@item
@kbd{i KEY... C-j} reads and executes a series of key sequences (not
including the final @kbd{C-j}), and inserts them before the current
command in the keyboard macro, without advancing over the current
command.
@item
@kbd{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.
@item
@kbd{r KEY... C-j} reads and executes a series of key sequences (not
including the final @kbd{C-j}), and replaces the current command in
the keyboard macro with them, advancing over the inserted key
sequences.
@item
@kbd{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.
@item
@kbd{a KEY... C-j} executes the current command, then reads and
executes a series of key sequences (not including the final
@kbd{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.
@item
@kbd{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 @kbd{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.
@end itemize

@ignore
   arch-tag: c1b0dd3b-3159-4c08-928f-52e763953e9c
@end ignore