Next: Keyboard Macro Query, Previous: Keyboard Macro Ring, Up: Keyboard Macros
Each keyboard macro has an associated counter, which is initialized to 0 when you start defining the macro. This counter allows you to insert a number into the buffer that depends on the number of times the macro has been called. The counter is incremented each time its value is inserted into the buffer.
kmacro-start-macro-or-insert-counter).
kmacro-insert-counter).
kmacro-set-counter).
kmacro-add-counter).
kmacro-set-format).
When you are defining a keyboard macro, the command <F3>
(kmacro-start-macro-or-insert-counter) inserts the current
value of the keyboard macro's counter into the buffer, and increments
the counter by 1. (If you are not defining a macro, <F3> begins a
macro definition instead. See Basic Keyboard Macro.) You can use
a numeric prefix argument to specify a different increment. If you
just specify a C-u prefix, that is the same as an increment of
zero: it inserts the current counter value without changing it.
As an example, let us show how the keyboard macro counter can be used to build a numbered list. Consider the following key sequence:
<F3> C-a <F3> . <SPC> <F4>
As part of this keyboard macro definition, the string ‘0. ’ was inserted into the beginning of the current line. If you now move somewhere else in the buffer and type <F4> to invoke the macro, the string ‘1. ’ is inserted at the beginning of that line. Subsequent invocations insert ‘2. ’, ‘3. ’, and so forth.
The command C-x C-k C-i (kmacro-insert-counter) does
the same thing as <F3>, but it can be used outside a keyboard
macro definition. When no keyboard macro is being defined or
executed, 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 Formatting Strings). 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.
If you use a register as a counter, incrementing it on each repetition of the macro, that accomplishes the same thing as a keyboard macro counter. See Number Registers. For most purposes, it is simpler to use a keyboard macro counter.