From: Kim F. Storm Date: Sun, 17 Aug 2003 22:10:38 +0000 (+0000) Subject: New file describing enhanced keyboard macro functionality. X-Git-Tag: ttn-vms-21-2-B4~9080 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=eef59362ac0323dc9c8474dae6890ea5782d289f;p=emacs.git New file describing enhanced keyboard macro functionality. --- diff --git a/man/kmacro.texi b/man/kmacro.texi new file mode 100644 index 00000000000..9d7810ad3f4 --- /dev/null +++ b/man/kmacro.texi @@ -0,0 +1,525 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985,86,87,93,94,95,97,2000,2001,2002,2003 +@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 + + +@node Keyboard Macros +@section 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-execuing 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 Where previous keyboard macros are saved + + 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}. + +@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, it will be incremented by 2 time for 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 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. + +@cindex binding keyboard macros +@findex kmacro-bind-to-key +@kindex C-x C-k b + Rather than giving a keyboard macro a name, you can bind it 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 carefylly. 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 the +keyboard macro, so that the macro will be reassigned the same keys when you +load the file. + +@node Edit Keyboard Macro +@section Interactively executing and 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