Mercurial > emacs
comparison man/kmacro.texi @ 68548:cd4235065942
Minor clarifications.
(Keyboard Macro Ring): Comment out some excessive commands.
(Basic Keyboard Macro): Split up the table, putting part in each node.
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Thu, 02 Feb 2006 04:38:27 +0000 |
parents | 20ff812ba5b3 |
children | 9d15d9eabbde |
comparison
equal
deleted
inserted
replaced
68547:e709385ba493 | 68548:cd4235065942 |
---|---|
5 @node Keyboard Macros, Files, Fixit, Top | 5 @node Keyboard Macros, Files, Fixit, Top |
6 @chapter Keyboard Macros | 6 @chapter Keyboard Macros |
7 @cindex defining keyboard macros | 7 @cindex defining keyboard macros |
8 @cindex keyboard macro | 8 @cindex keyboard macro |
9 | 9 |
10 In this chapter we describe how a sequence of editing commands can | 10 In this chapter we describe how to record a sequence of editing |
11 be recorded and repeated multiple times. | 11 commands so you can repeat it conveniently later. |
12 | 12 |
13 A @dfn{keyboard macro} is a command defined by the user to stand for | 13 A @dfn{keyboard macro} is a command defined by the user to stand for |
14 another sequence of keys. For example, if you discover that you are | 14 another sequence of keys. For example, if you discover that you are |
15 about to type @kbd{C-n C-d} forty times, you can speed your work by | 15 about to type @kbd{C-n M-d C-d} forty times, you can speed your work by |
16 defining a keyboard macro to do @kbd{C-n C-d} and calling it with a | 16 defining a keyboard macro to do @kbd{C-n M-d C-d}, and then executing |
17 repeat count of forty. | 17 it 39 more times. |
18 | 18 |
19 You define a keyboard macro while executing the commands which are the | 19 You define a keyboard macro by executing and recording the commands |
20 definition. Put differently, as you define a keyboard macro, the | 20 which are its definition. Put differently, as you define a keyboard |
21 definition is being executed for the first time. This way, you can see | 21 macro, the definition is being executed for the first time. This way, |
22 what the effects of your commands are, so that you don't have to figure | 22 you can see the effects of your commands, so that you don't have to |
23 them out in your head. When you are finished, the keyboard macro is | 23 figure them out in your head. When you close the definition, the |
24 defined and also has been, in effect, executed once. You can then do the | 24 keyboard macro is defined and also has been, in effect, executed once. |
25 whole thing over again by invoking the macro. | 25 You can then do the whole thing over again by invoking the macro. |
26 | 26 |
27 Keyboard macros differ from ordinary Emacs commands in that they are | 27 Keyboard macros differ from ordinary Emacs commands in that they are |
28 written in the Emacs command language rather than in Lisp. This makes it | 28 written in the Emacs command language rather than in Lisp. This makes it |
29 easier for the novice to write them, and makes them more convenient as | 29 easier for the novice to write them, and makes them more convenient as |
30 temporary hacks. However, the Emacs command language is not powerful | 30 temporary hacks. However, the Emacs command language is not powerful |
61 (@code{kmacro-end-or-call-macro}). | 61 (@code{kmacro-end-or-call-macro}). |
62 @item C-u C-x ( | 62 @item C-u C-x ( |
63 Re-execute last keyboard macro, then add more keys to its definition. | 63 Re-execute last keyboard macro, then add more keys to its definition. |
64 @item C-u C-u C-x ( | 64 @item C-u C-u C-x ( |
65 Add more keys to the last keyboard macro without re-executing it. | 65 Add more keys to the last keyboard macro without re-executing it. |
66 @item C-x q | |
67 When this point is reached during macro execution, ask for confirmation | |
68 (@code{kbd-macro-query}). | |
69 @item C-x C-k n | |
70 Give a command name (for the duration of the session) to the most | |
71 recently defined keyboard macro (@code{kmacro-name-last-macro}). | |
72 @item C-x C-k b | |
73 Bind the most recently defined keyboard macro to a key sequence (for | |
74 the duration of the session) (@code{kmacro-bind-to-key}). | |
75 @item M-x insert-kbd-macro | |
76 Insert in the buffer a keyboard macro's definition, as Lisp code. | |
77 @item C-x C-k e | |
78 Edit a previously defined keyboard macro (@code{edit-kbd-macro}). | |
79 @item C-x C-k r | 66 @item C-x C-k r |
80 Run the last keyboard macro on each line that begins in the region | 67 Run the last keyboard macro on each line that begins in the region |
81 (@code{apply-macro-to-region-lines}). | 68 (@code{apply-macro-to-region-lines}). |
82 @end table | 69 @end table |
83 | 70 |
155 the macro replays the mouse event, it uses the original mouse position | 142 the macro replays the mouse event, it uses the original mouse position |
156 of that event, the position that the mouse had while you were defining | 143 of that event, the position that the mouse had while you were defining |
157 the macro. The effect of this may be hard to predict. (Using the | 144 the macro. The effect of this may be hard to predict. (Using the |
158 current mouse position would be even less predictable.) | 145 current mouse position would be even less predictable.) |
159 | 146 |
160 One thing that doesn't always work well in a keyboard macro is the | 147 One thing that sometimes works badly in a keyboard macro is the |
161 command @kbd{C-M-c} (@code{exit-recursive-edit}). When this command | 148 command @kbd{C-M-c} (@code{exit-recursive-edit}). When this command |
162 exits a recursive edit that started within the macro, it works as you'd | 149 exits a recursive edit that started within the macro, it works as |
163 expect. But if it exits a recursive edit that started before you | 150 you'd expect. But if it exits a recursive edit that started before |
164 invoked the keyboard macro, it also necessarily exits the keyboard macro | 151 you invoked the keyboard macro, it also necessarily exits the keyboard |
165 as part of the process. | 152 macro as part of the process. |
166 | 153 |
167 After you have terminated the definition of a keyboard macro, you can add | 154 After you have terminated the definition of a keyboard macro, you can add |
168 to the end of its definition by typing @kbd{C-u C-x (}. This is equivalent | 155 to the end of its definition by typing @kbd{C-u C-x (}. This is equivalent |
169 to plain @kbd{C-x (} followed by retyping the whole definition so far. As | 156 to plain @kbd{C-x (} followed by retyping the whole definition so far. As |
170 a consequence it re-executes the macro as previously defined. | 157 a consequence it re-executes the macro as previously defined. |
188 | 175 |
189 All defined keyboard macros are recorded in the ``keyboard macro ring'', | 176 All defined keyboard macros are recorded in the ``keyboard macro ring'', |
190 a list of sequences of keys. There is only one keyboard macro ring, | 177 a list of sequences of keys. There is only one keyboard macro ring, |
191 shared by all buffers. | 178 shared by all buffers. |
192 | 179 |
180 @table @kbd | |
181 @item C-x C-k C-k | |
182 Execute the keyboard macro at the head of the ring (@code{kmacro-end-or-call-macro-repeat}). | |
183 @item C-x C-k C-n | |
184 Rotate the keyboard macro ring to the next macro (defined earlier) | |
185 (@code{kmacro-cycle-ring-next}). | |
186 @item C-x C-k C-p | |
187 Rotate the keyboard macro ring to the previous macro (defined later) | |
188 (@code{kmacro-cycle-ring-previous}). | |
189 @end table | |
190 | |
193 All commands which operate on the keyboard macro ring use the | 191 All commands which operate on the keyboard macro ring use the |
194 same @kbd{C-x C-k} prefix. Most of these commands can be executed and | 192 same @kbd{C-x C-k} prefix. Most of these commands can be executed and |
195 repeated immediately after each other without repeating the @kbd{C-x | 193 repeated immediately after each other without repeating the @kbd{C-x |
196 C-k} prefix. For example, | 194 C-k} prefix. For example, |
197 | 195 |
210 The command @kbd{C-x C-k C-k} (@code{kmacro-end-or-call-macro-repeat}) | 208 The command @kbd{C-x C-k C-k} (@code{kmacro-end-or-call-macro-repeat}) |
211 executes the keyboard macro at the head of the macro ring. You can | 209 executes the keyboard macro at the head of the macro ring. You can |
212 repeat the macro immediately by typing another @kbd{C-k}, or you can | 210 repeat the macro immediately by typing another @kbd{C-k}, or you can |
213 rotate the macro ring immediately by typing @kbd{C-n} or @kbd{C-p}. | 211 rotate the macro ring immediately by typing @kbd{C-n} or @kbd{C-p}. |
214 | 212 |
215 When a keyboard macro is being defined, @kbd{C-x C-k C-k} behaves like | 213 When a keyboard macro is being defined, @kbd{C-x C-k C-k} behaves like |
216 @kbd{C-x )} except that, immediately afterward, you can use most key | 214 @kbd{C-x )} except that, immediately afterward, you can use most key |
217 bindings of this section without the @kbd{C-x C-k} prefix. For | 215 bindings of this section without the @kbd{C-x C-k} prefix. For |
218 instance, another @kbd{C-k} will re-execute the macro. | 216 instance, another @kbd{C-k} will re-execute the macro. |
219 | 217 |
220 @findex kmacro-cycle-ring-next | 218 @findex kmacro-cycle-ring-next |
229 immediately by repeating just @kbd{C-n} and @kbd{C-p} until the | 227 immediately by repeating just @kbd{C-n} and @kbd{C-p} until the |
230 desired macro is at the head of the ring. To execute the new macro | 228 desired macro is at the head of the ring. To execute the new macro |
231 ring head immediately, just type @kbd{C-k}. | 229 ring head immediately, just type @kbd{C-k}. |
232 | 230 |
233 Note that Emacs treats the head of the macro ring as the ``last | 231 Note that Emacs treats the head of the macro ring as the ``last |
234 defined keyboard macro''. For instance, it is the keyboard macro that | 232 defined keyboard macro.'' For instance, @kbd{C-x e} will execute that |
235 @kbd{C-x e} will execute. | 233 macro, and @kbd{C-x C-k n} will give it a name. |
236 | 234 |
235 @ignore @c This interface is too kludgy | |
236 @c and the functionality duplicates the functionality above -- rms. | |
237 @findex kmacro-view-macro-repeat | 237 @findex kmacro-view-macro-repeat |
238 @kindex C-x C-k C-v | 238 @kindex C-x C-k C-v |
239 | |
240 The command @kbd{C-x C-k C-v} (@code{kmacro-view-macro-repeat}) | 239 The command @kbd{C-x C-k C-v} (@code{kmacro-view-macro-repeat}) |
241 displays the last keyboard macro, or when repeated (with @kbd{C-v}), | 240 displays the last keyboard macro, or when repeated (with @kbd{C-v}), |
242 it displays the previous macro on the macro ring, just like @kbd{C-x | 241 it displays the previous macro on the macro ring, just like @kbd{C-x |
243 C-k C-p}, but without actually rotating the macro ring. If you enter | 242 C-k C-p}, but without actually rotating the macro ring. If you enter |
244 @kbd{C-k} immediately after displaying a macro from the ring, that | 243 @kbd{C-k} immediately after displaying a macro from the ring, that |
246 | 245 |
247 So while e.g. @kbd{C-x C-k C-p C-p C-p C-k C-k} makes the 3rd previous | 246 So while e.g. @kbd{C-x C-k C-p C-p C-p C-k C-k} makes the 3rd previous |
248 macro the current macro and executes it twice, @kbd{C-x C-k C-v C-v | 247 macro the current macro and executes it twice, @kbd{C-x C-k C-v C-v |
249 C-v C-k C-k} will display and execute the 3rd previous macro once and | 248 C-v C-k C-k} will display and execute the 3rd previous macro once and |
250 then the current macro once. | 249 then the current macro once. |
251 | 250 @end ignore |
251 | |
252 @ignore @c This is just too much feeping creaturism. | |
253 @c If you are reusing certain macros enough to want these, | |
254 @c you should give then names. -- rms | |
252 @findex kmacro-delete-ring-head | 255 @findex kmacro-delete-ring-head |
253 @kindex C-x C-k C-d | 256 @kindex C-x C-k C-d |
254 | 257 |
255 The command @kbd{C-x C-k C-d} (@code{kmacro-delete-ring-head}) | 258 The command @kbd{C-x C-k C-d} (@code{kmacro-delete-ring-head}) |
256 removes and deletes the macro currently at the head of the macro | 259 removes and deletes the macro currently at the head of the macro |
267 @findex kmacro-call-ring-2nd-repeat | 270 @findex kmacro-call-ring-2nd-repeat |
268 @kindex C-x C-k C-l | 271 @kindex C-x C-k C-l |
269 | 272 |
270 The command @kbd{C-x C-k C-l} (@code{kmacro-call-ring-2nd-repeat}) | 273 The command @kbd{C-x C-k C-l} (@code{kmacro-call-ring-2nd-repeat}) |
271 executes the previous (rather than the head) element on the macro ring. | 274 executes the previous (rather than the head) element on the macro ring. |
275 @end ignore | |
272 | 276 |
273 @vindex kmacro-ring-max | 277 @vindex kmacro-ring-max |
274 The maximum number of macros stored in the keyboard macro ring is | 278 The maximum number of macros stored in the keyboard macro ring is |
275 determined by the customizable variable @code{kmacro-ring-max}. | 279 determined by the customizable variable @code{kmacro-ring-max}. |
276 | 280 |
277 @node Keyboard Macro Counter | 281 @node Keyboard Macro Counter |
278 @section The Keyboard Macro Counter | 282 @section The Keyboard Macro Counter |
283 | |
284 @table @kbd | |
285 @item C-x C-k C-i | |
286 Insert the keyboard macro counter value in the buffer | |
287 (@code{kmacro-insert-counter}). | |
288 @item C-x C-k C-c | |
289 Set the keyboard macro counter (@code{kmacro-set-counter}). | |
290 @item C-x C-k C-a | |
291 Add the prefix arg to the keyboard macro counter (@code{kmacro-add-counter}). | |
292 @item C-x C-k C-f | |
293 Specify the format for inserting the keyboard macro counter | |
294 (@code{kmacro-set-format}). | |
295 @end table | |
279 | 296 |
280 Each keyboard macro has an associated counter. Normally, the | 297 Each keyboard macro has an associated counter. Normally, the |
281 macro counter is initialized to 0 when you start defining the macro, | 298 macro counter is initialized to 0 when you start defining the macro, |
282 and incremented by 1 after each insertion of the counter value; | 299 and incremented by 1 after each insertion of the counter value; |
283 that is, if you insert the macro counter twice while defining the | 300 that is, if you insert the macro counter twice while defining the |
362 numbers stored in registers. | 379 numbers stored in registers. |
363 | 380 |
364 @node Keyboard Macro Query | 381 @node Keyboard Macro Query |
365 @section Executing Macros with Variations | 382 @section Executing Macros with Variations |
366 | 383 |
384 @table @kbd | |
385 @item C-x q | |
386 When this point is reached during macro execution, ask for confirmation | |
387 (@code{kbd-macro-query}). | |
388 @end table | |
389 | |
367 @kindex C-x q | 390 @kindex C-x q |
368 @findex kbd-macro-query | 391 @findex kbd-macro-query |
369 Using @kbd{C-x q} (@code{kbd-macro-query}), you can get an effect | 392 Using @kbd{C-x q} (@code{kbd-macro-query}), you can get an effect |
370 similar to that of @code{query-replace}, where the macro asks you each | 393 similar to that of @code{query-replace}, where the macro asks you each |
371 time around whether to make a change. While defining the macro, | 394 time around whether to make a change. While defining the macro, |
405 register as a counter, incrementing it on each repetition of the macro. | 428 register as a counter, incrementing it on each repetition of the macro. |
406 @xref{RegNumbers}. | 429 @xref{RegNumbers}. |
407 | 430 |
408 @node Save Keyboard Macro | 431 @node Save Keyboard Macro |
409 @section Naming and Saving Keyboard Macros | 432 @section Naming and Saving Keyboard Macros |
433 | |
434 @table | |
435 @item C-x C-k n | |
436 Give a command name (for the duration of the Emacs session) to the most | |
437 recently defined keyboard macro (@code{kmacro-name-last-macro}). | |
438 @item C-x C-k b | |
439 Bind the most recently defined keyboard macro to a key sequence (for | |
440 the duration of the session) (@code{kmacro-bind-to-key}). | |
441 @item M-x insert-kbd-macro | |
442 Insert in the buffer a keyboard macro's definition, as Lisp code. | |
443 @end table | |
410 | 444 |
411 @cindex saving keyboard macros | 445 @cindex saving keyboard macros |
412 @findex kmacro-name-last-macro | 446 @findex kmacro-name-last-macro |
413 @kindex C-x C-k n | 447 @kindex C-x C-k n |
414 If you wish to save a keyboard macro for later use, you can give it | 448 If you wish to save a keyboard macro for later use, you can give it |
432 the global keymap, but since most key sequences already have other | 466 the global keymap, but since most key sequences already have other |
433 bindings, you should select the key sequence carefully. If you try to | 467 bindings, you should select the key sequence carefully. If you try to |
434 bind to a key sequence with an existing binding (in any keymap), this | 468 bind to a key sequence with an existing binding (in any keymap), this |
435 command asks you for confirmation before replacing the existing binding. | 469 command asks you for confirmation before replacing the existing binding. |
436 | 470 |
437 To avoid problems caused by overriding existing bindings, the key | 471 To avoid problems caused by overriding existing bindings, the key |
438 sequences @kbd{C-x C-k 0} through @kbd{C-x C-k 9} and @kbd{C-x C-k A} | 472 sequences @kbd{C-x C-k 0} through @kbd{C-x C-k 9} and @kbd{C-x C-k A} |
439 through @kbd{C-x C-k Z} are reserved for your own keyboard macro | 473 through @kbd{C-x C-k Z} are reserved for your own keyboard macro |
440 bindings. In fact, to bind to one of these key sequences, you only | 474 bindings. In fact, to bind to one of these key sequences, you only |
441 need to type the digit or letter rather than the whole key sequences. | 475 need to type the digit or letter rather than the whole key sequences. |
442 For example, | 476 For example, |
472 when you load the file. | 506 when you load the file. |
473 | 507 |
474 @node Edit Keyboard Macro | 508 @node Edit Keyboard Macro |
475 @section Editing a Keyboard Macro | 509 @section Editing a Keyboard Macro |
476 | 510 |
511 @table @kbd | |
512 @item C-x C-k C-e | |
513 Edit the last defined keyboard macro (@code{kmacro-edit-macro}). | |
514 @item C-x C-k e @var{name} @key{RET} | |
515 Edit a previously defined keyboard macro @var{name} (@code{edit-kbd-macro}). | |
516 @item C-x C-k l | |
517 Edit the last 100 keystrokes as a keyboard macro | |
518 (@code{kmacro-edit-lossage}). | |
519 @end table | |
520 | |
477 @findex kmacro-edit-macro | 521 @findex kmacro-edit-macro |
478 @kindex C-x C-k C-e | 522 @kindex C-x C-k C-e |
479 @kindex C-x C-k RET | 523 @kindex C-x C-k RET |
480 You can edit the last keyboard macro by typing @kbd{C-x C-k C-e} or | 524 You can edit the last keyboard macro by typing @kbd{C-x C-k C-e} or |
481 @kbd{C-x C-k RET} (@code{kmacro-edit-macro}). This formats the macro | 525 @kbd{C-x C-k RET} (@code{kmacro-edit-macro}). This formats the macro |