Commit a0d0adaf authored by Kim F. Storm's avatar Kim F. Storm
Browse files

(Customization): Add xref to Keyboard Macros chapter.

(Keyboard Macros): Move to new kmacro.texi file.
parent baf2630d
......@@ -19,15 +19,17 @@ between sessions unless you save the customization in a file such as
customizations for future sessions, this actually works by editing
@file{.emacs} for you.
Another means of customization is the keyboard macro, which is a
sequence of keystrokes to be replayed with a single command.
@xref{Keyboard Macros}, for full instruction how to record, manage, and
replay sequences of keys.
@menu
* Minor Modes:: Each minor mode is one feature you can turn on
independently of any others.
* Variables:: Many Emacs commands examine Emacs variables
to decide what to do; by setting variables,
you can control their functioning.
* Keyboard Macros:: A keyboard macro records a sequence of
keystrokes to be replayed with a single
command.
* Key Bindings:: The keymaps say what command each key runs.
By changing them, you can "redefine keys".
* Keyboard Translations::
......@@ -1058,231 +1060,6 @@ value are @code{t}, @code{nil}, and anything else, just as for
neither @code{t} nor @code{nil}, so normally Emacs does ask for
confirmation about file settings for these variables.
@node Keyboard Macros
@section Keyboard Macros
@cindex defining keyboard macros
@cindex keyboard macro
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.
@table @kbd
@item C-x (
Start defining a keyboard macro (@code{start-kbd-macro}).
@item C-x )
End the definition of a keyboard macro (@code{end-kbd-macro}).
@item C-x e
Execute the most recent keyboard macro (@code{call-last-kbd-macro}).
@item C-u C-x (
Re-execute last keyboard macro, then add more keys to its definition.
@item C-x q
When this point is reached during macro execution, ask for confirmation
(@code{kbd-macro-query}).
@item M-x name-last-kbd-macro
Give a command name (for the duration of the session) to the most
recently defined keyboard macro.
@item M-x insert-kbd-macro
Insert in the buffer a keyboard macro's definition, as Lisp code.
@item C-x C-k
Edit a previously defined keyboard macro (@code{edit-kbd-macro}).
@item M-x apply-macro-to-region-lines
Run the last keyboard macro on each complete line in the region.
@end table
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.
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.
@menu
* Basic Kbd Macro:: Defining and running keyboard macros.
* Save Kbd Macro:: Giving keyboard macros names; saving them in files.
* Kbd Macro Query:: Making keyboard macros do different things each time.
@end menu
@node Basic Kbd Macro
@subsection Basic Use
@kindex C-x (
@kindex C-x )
@kindex C-x e
@findex start-kbd-macro
@findex end-kbd-macro
@findex call-last-kbd-macro
To start defining a keyboard macro, type the @kbd{C-x (} command
(@code{start-kbd-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{end-kbd-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{call-last-kbd-macro}), which may be given a repeat count
as a numeric argument to execute the macro many times. @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}}).
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.
@findex edit-kbd-macro
@kindex C-x C-k
You can edit a keyboard macro already defined by typing @kbd{C-x C-k}
(@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. 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 apply-macro-to-region-lines
The command @kbd{M-x 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 Save Kbd Macro
@subsection Naming and Saving Keyboard Macros
@cindex saving keyboard macros
@findex name-last-kbd-macro
If you wish to save a keyboard macro for longer than until you define the
next one, you must give it a name using @kbd{M-x name-last-kbd-macro}.
This reads a name as an argument using the minibuffer and defines that name
to execute the 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 another keyboard
macro, an error message is shown and nothing is changed.
@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 the
keyboard macro, so that the macro will be reassigned the same keys when you
load the file.
@node Kbd Macro Query
@subsection 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 Key Bindings
@section Customizing Key Bindings
@cindex key bindings
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment