Commit | Line | Data |
---|---|---|
eef59362 | 1 | @c This is part of the Emacs manual. |
ae48b251 | 2 | @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, |
3f548a7c | 3 | @c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. |
eef59362 KS |
4 | @c See file emacs.texi for copying conditions. |
5 | @node Keyboard Macros, Files, Fixit, Top | |
6 | @chapter Keyboard Macros | |
eef59362 KS |
7 | @cindex defining keyboard macros |
8 | @cindex keyboard macro | |
9 | ||
f8c2e4d5 RS |
10 | In this chapter we describe how to record a sequence of editing |
11 | commands so you can repeat it conveniently later. | |
eef59362 | 12 | |
c9106f67 | 13 | A @dfn{keyboard macro} is a command defined by an Emacs user to stand for |
eef59362 | 14 | another sequence of keys. For example, if you discover that you are |
f8c2e4d5 RS |
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 M-d C-d}, and then executing | |
17 | it 39 more times. | |
18 | ||
19 | You define a keyboard macro by executing and recording the commands | |
20 | which are its definition. Put differently, as you define a keyboard | |
21 | macro, the definition is being executed for the first time. This way, | |
22 | you can see the effects of your commands, so that you don't have to | |
23 | figure them out in your head. When you close the definition, the | |
24 | keyboard macro is defined and also has been, in effect, executed once. | |
25 | You can then do the whole thing over again by invoking the macro. | |
eef59362 KS |
26 | |
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 | |
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 | |
31 | enough as a programming language to be useful for writing anything | |
32 | intelligent or general. For such things, Lisp must be used. | |
33 | ||
34 | @menu | |
35 | * Basic Keyboard Macro:: Defining and running keyboard macros. | |
36 | * Keyboard Macro Ring:: Where previous keyboard macros are saved. | |
37 | * Keyboard Macro Counter:: Inserting incrementing numbers in macros. | |
38 | * Keyboard Macro Query:: Making keyboard macros do different things each time. | |
39 | * Save Keyboard Macro:: Giving keyboard macros names; saving them in files. | |
40 | * Edit Keyboard Macro:: Editing keyboard macros. | |
ae48b251 LK |
41 | * Keyboard Macro Step-Edit:: Interactively executing and editing a keyboard |
42 | macro. | |
eef59362 KS |
43 | @end menu |
44 | ||
45 | @node Basic Keyboard Macro | |
46 | @section Basic Use | |
47 | ||
48 | @table @kbd | |
947ebc5f KS |
49 | @item @key{F3} |
50 | @itemx C-x ( | |
eef59362 | 51 | Start defining a keyboard macro (@code{kmacro-start-macro}). |
947ebc5f KS |
52 | @item @key{F4} |
53 | If a keyboard macro is being defined, end the definition; otherwise, | |
54 | execute the most recent keyboard macro | |
55 | (@code{kmacro-end-or-call-macro}). | |
eef59362 KS |
56 | @item C-x ) |
57 | End the definition of a keyboard macro (@code{kmacro-end-macro}). | |
58 | @item C-x e | |
59 | Execute the most recent keyboard macro (@code{kmacro-end-and-call-macro}). | |
60 | First end the definition of the keyboard macro, if currently defining it. | |
61 | To immediately execute the keyboard macro again, just repeat the @kbd{e}. | |
62 | @item C-u C-x ( | |
63 | Re-execute last keyboard macro, then add more keys to its definition. | |
64 | @item C-u C-u C-x ( | |
65 | Add more keys to the last keyboard macro without re-executing it. | |
eef59362 | 66 | @item C-x C-k r |
8871f2ba | 67 | Run the last keyboard macro on each line that begins in the region |
eef59362 KS |
68 | (@code{apply-macro-to-region-lines}). |
69 | @end table | |
70 | ||
947ebc5f KS |
71 | @kindex F3 |
72 | @kindex F4 | |
eef59362 KS |
73 | @kindex C-x ( |
74 | @kindex C-x ) | |
75 | @kindex C-x e | |
76 | @findex kmacro-start-macro | |
77 | @findex kmacro-end-macro | |
78 | @findex kmacro-end-and-call-macro | |
947ebc5f | 79 | To start defining a keyboard macro, type the @kbd{F3} or @kbd{C-x (} command |
eef59362 KS |
80 | (@code{kmacro-start-macro}). From then on, your keys continue to be |
81 | executed, but also become part of the definition of the macro. @samp{Def} | |
82 | appears in the mode line to remind you of what is going on. When you are | |
947ebc5f | 83 | finished, the @kbd{F4} or @kbd{C-x )} command (@code{kmacro-end-macro}) terminates the |
eef59362 KS |
84 | definition (without becoming part of it!). For example, |
85 | ||
86 | @example | |
87 | C-x ( M-f foo C-x ) | |
88 | @end example | |
89 | ||
90 | @noindent | |
91 | defines a macro to move forward a word and then insert @samp{foo}. | |
92 | ||
93 | The macro thus defined can be invoked again with the @kbd{C-x e} | |
94 | command (@code{kmacro-end-and-call-macro}), which may be given a | |
95 | repeat count as a numeric argument to execute the macro many times. | |
96 | If you enter @kbd{C-x e} while defining a macro, the macro is | |
97 | terminated and executed immediately. | |
98 | ||
99 | After executing the macro with @kbd{C-x e}, you can use @kbd{e} | |
100 | repeatedly to immediately repeat the macro one or more times. For example, | |
101 | ||
102 | @example | |
103 | C-x ( xyz C-x e e e | |
104 | @end example | |
105 | ||
106 | @noindent | |
107 | inserts @samp{xyzxyzxyzxyz} in the current buffer. | |
108 | ||
109 | @kbd{C-x )} can also be given a repeat count as an argument, in | |
110 | which case it repeats the macro that many times right after defining | |
111 | it, but defining the macro counts as the first repetition (since it is | |
112 | executed as you define it). Therefore, giving @kbd{C-x )} an argument | |
113 | of 4 executes the macro immediately 3 additional times. An argument | |
114 | of zero to @kbd{C-x e} or @kbd{C-x )} means repeat the macro | |
115 | indefinitely (until it gets an error or you type @kbd{C-g} or, on | |
116 | MS-DOS, @kbd{C-@key{BREAK}}). | |
117 | ||
bb18ce6a RS |
118 | The key @key{F4} is like a combination of @kbd{C-x )} and @kbd{C-x |
119 | e}. If you're defining a macro, @key{F4} ends the definition. | |
947ebc5f KS |
120 | Otherwise it executes the last macro. For example, |
121 | ||
122 | @example | |
123 | F3 xyz F4 F4 F4 | |
124 | @end example | |
125 | ||
126 | @noindent | |
127 | inserts @samp{xyzxyzxyz} in the current buffer. | |
bb18ce6a | 128 | |
eef59362 KS |
129 | If you wish to repeat an operation at regularly spaced places in the |
130 | text, define a macro and include as part of the macro the commands to move | |
131 | to the next place you want to use it. For example, if you want to change | |
132 | each line, you should position point at the start of a line, and define a | |
133 | macro to change that line and leave point at the start of the next line. | |
134 | Then repeating the macro will operate on successive lines. | |
135 | ||
136 | When a command reads an argument with the minibuffer, your | |
137 | minibuffer input becomes part of the macro along with the command. So | |
138 | when you replay the macro, the command gets the same argument as | |
139 | when you entered the macro. For example, | |
140 | ||
141 | @example | |
142 | 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 ) | |
143 | @end example | |
144 | ||
145 | @noindent | |
146 | defines a macro that copies the current line into the buffer | |
147 | @samp{foo}, then returns to the original buffer. | |
148 | ||
149 | You can use function keys in a keyboard macro, just like keyboard | |
150 | keys. You can even use mouse events, but be careful about that: when | |
151 | the macro replays the mouse event, it uses the original mouse position | |
152 | of that event, the position that the mouse had while you were defining | |
153 | the macro. The effect of this may be hard to predict. (Using the | |
154 | current mouse position would be even less predictable.) | |
155 | ||
f8c2e4d5 | 156 | One thing that sometimes works badly in a keyboard macro is the |
eef59362 | 157 | command @kbd{C-M-c} (@code{exit-recursive-edit}). When this command |
f8c2e4d5 RS |
158 | exits a recursive edit that started within the macro, it works as |
159 | you'd expect. But if it exits a recursive edit that started before | |
160 | you invoked the keyboard macro, it also necessarily exits the keyboard | |
161 | macro as part of the process. | |
eef59362 KS |
162 | |
163 | After you have terminated the definition of a keyboard macro, you can add | |
947ebc5f KS |
164 | to the end of its definition by typing @kbd{C-u F3} or @kbd{C-u C-x (}. |
165 | This is equivalent | |
eef59362 KS |
166 | to plain @kbd{C-x (} followed by retyping the whole definition so far. As |
167 | a consequence it re-executes the macro as previously defined. | |
168 | ||
169 | You can also add to the end of the definition of the last keyboard | |
977d0bea | 170 | macro without re-executing it by typing @kbd{C-u C-u C-x (}. |
eef59362 KS |
171 | |
172 | The variable @code{kmacro-execute-before-append} specifies whether | |
173 | a single @kbd{C-u} prefix causes the existing macro to be re-executed | |
174 | before appending to it. | |
175 | ||
176 | @findex apply-macro-to-region-lines | |
177 | @kindex C-x C-k r | |
178 | The command @kbd{C-x C-k r} (@code{apply-macro-to-region-lines}) | |
8871f2ba LT |
179 | repeats the last defined keyboard macro on each line that begins in |
180 | the region. It does this line by line, by moving point to the | |
eef59362 KS |
181 | beginning of the line and then executing the macro. |
182 | ||
183 | @node Keyboard Macro Ring | |
2935e788 | 184 | @section The Keyboard Macro Ring |
eef59362 | 185 | |
5a7f4c1b | 186 | All defined keyboard macros are recorded in the ``keyboard macro ring,'' |
eef59362 KS |
187 | a list of sequences of keys. There is only one keyboard macro ring, |
188 | shared by all buffers. | |
189 | ||
f8c2e4d5 RS |
190 | @table @kbd |
191 | @item C-x C-k C-k | |
192 | Execute the keyboard macro at the head of the ring (@code{kmacro-end-or-call-macro-repeat}). | |
193 | @item C-x C-k C-n | |
194 | Rotate the keyboard macro ring to the next macro (defined earlier) | |
195 | (@code{kmacro-cycle-ring-next}). | |
196 | @item C-x C-k C-p | |
197 | Rotate the keyboard macro ring to the previous macro (defined later) | |
198 | (@code{kmacro-cycle-ring-previous}). | |
199 | @end table | |
200 | ||
34768dde | 201 | All commands which operate on the keyboard macro ring use the |
eef59362 KS |
202 | same @kbd{C-x C-k} prefix. Most of these commands can be executed and |
203 | repeated immediately after each other without repeating the @kbd{C-x | |
204 | C-k} prefix. For example, | |
205 | ||
206 | @example | |
207 | 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 | |
208 | @end example | |
209 | ||
210 | @noindent | |
211 | will rotate the keyboard macro ring to the ``second previous'' macro, | |
212 | execute the resulting head macro three times, rotate back to the | |
213 | original head macro, execute that once, rotate to the ``previous'' | |
214 | macro, execute that, and finally delete it from the macro ring. | |
215 | ||
216 | @findex kmacro-end-or-call-macro-repeat | |
217 | @kindex C-x C-k C-k | |
218 | The command @kbd{C-x C-k C-k} (@code{kmacro-end-or-call-macro-repeat}) | |
219 | executes the keyboard macro at the head of the macro ring. You can | |
220 | repeat the macro immediately by typing another @kbd{C-k}, or you can | |
221 | rotate the macro ring immediately by typing @kbd{C-n} or @kbd{C-p}. | |
222 | ||
f8c2e4d5 | 223 | When a keyboard macro is being defined, @kbd{C-x C-k C-k} behaves like |
34768dde LT |
224 | @kbd{C-x )} except that, immediately afterward, you can use most key |
225 | bindings of this section without the @kbd{C-x C-k} prefix. For | |
226 | instance, another @kbd{C-k} will re-execute the macro. | |
227 | ||
eef59362 KS |
228 | @findex kmacro-cycle-ring-next |
229 | @kindex C-x C-k C-n | |
230 | @findex kmacro-cycle-ring-previous | |
231 | @kindex C-x C-k C-p | |
232 | The commands @kbd{C-x C-k C-n} (@code{kmacro-cycle-ring-next}) and | |
34768dde | 233 | @kbd{C-x C-k C-p} (@code{kmacro-cycle-ring-previous}) rotate the |
eef59362 KS |
234 | macro ring, bringing the next or previous keyboard macro to the head |
235 | of the macro ring. The definition of the new head macro is displayed | |
236 | in the echo area. You can continue to rotate the macro ring | |
237 | immediately by repeating just @kbd{C-n} and @kbd{C-p} until the | |
238 | desired macro is at the head of the ring. To execute the new macro | |
977d0bea | 239 | ring head immediately, just type @kbd{C-k}. |
eef59362 | 240 | |
2935e788 | 241 | Note that Emacs treats the head of the macro ring as the ``last |
f8c2e4d5 RS |
242 | defined keyboard macro.'' For instance, @kbd{C-x e} will execute that |
243 | macro, and @kbd{C-x C-k n} will give it a name. | |
2935e788 | 244 | |
f8c2e4d5 RS |
245 | @ignore @c This interface is too kludgy |
246 | @c and the functionality duplicates the functionality above -- rms. | |
eef59362 KS |
247 | @findex kmacro-view-macro-repeat |
248 | @kindex C-x C-k C-v | |
34768dde | 249 | The command @kbd{C-x C-k C-v} (@code{kmacro-view-macro-repeat}) |
eef59362 KS |
250 | displays the last keyboard macro, or when repeated (with @kbd{C-v}), |
251 | it displays the previous macro on the macro ring, just like @kbd{C-x | |
252 | C-k C-p}, but without actually rotating the macro ring. If you enter | |
253 | @kbd{C-k} immediately after displaying a macro from the ring, that | |
254 | macro is executed, but still without altering the macro ring. | |
255 | ||
34768dde | 256 | So while e.g. @kbd{C-x C-k C-p C-p C-p C-k C-k} makes the 3rd previous |
eef59362 KS |
257 | macro the current macro and executes it twice, @kbd{C-x C-k C-v C-v |
258 | C-v C-k C-k} will display and execute the 3rd previous macro once and | |
259 | then the current macro once. | |
f8c2e4d5 | 260 | @end ignore |
eef59362 | 261 | |
f8c2e4d5 RS |
262 | @ignore @c This is just too much feeping creaturism. |
263 | @c If you are reusing certain macros enough to want these, | |
264 | @c you should give then names. -- rms | |
eef59362 KS |
265 | @findex kmacro-delete-ring-head |
266 | @kindex C-x C-k C-d | |
267 | ||
34768dde | 268 | The command @kbd{C-x C-k C-d} (@code{kmacro-delete-ring-head}) |
eef59362 KS |
269 | removes and deletes the macro currently at the head of the macro |
270 | ring. You can use this to delete a macro that didn't work as | |
271 | expected, or which you don't need anymore. | |
272 | ||
273 | @findex kmacro-swap-ring | |
274 | @kindex C-x C-k C-t | |
275 | ||
34768dde | 276 | The command @kbd{C-x C-k C-t} (@code{kmacro-swap-ring}) |
eef59362 KS |
277 | interchanges the head of the macro ring with the previous element on |
278 | the macro ring. | |
279 | ||
280 | @findex kmacro-call-ring-2nd-repeat | |
281 | @kindex C-x C-k C-l | |
282 | ||
34768dde | 283 | The command @kbd{C-x C-k C-l} (@code{kmacro-call-ring-2nd-repeat}) |
eef59362 | 284 | executes the previous (rather than the head) element on the macro ring. |
f8c2e4d5 | 285 | @end ignore |
eef59362 | 286 | |
34768dde LT |
287 | @vindex kmacro-ring-max |
288 | The maximum number of macros stored in the keyboard macro ring is | |
289 | determined by the customizable variable @code{kmacro-ring-max}. | |
290 | ||
eef59362 | 291 | @node Keyboard Macro Counter |
1dec4064 | 292 | @section The Keyboard Macro Counter |
eef59362 | 293 | |
f8c2e4d5 RS |
294 | @table @kbd |
295 | @item C-x C-k C-i | |
296 | Insert the keyboard macro counter value in the buffer | |
297 | (@code{kmacro-insert-counter}). | |
298 | @item C-x C-k C-c | |
299 | Set the keyboard macro counter (@code{kmacro-set-counter}). | |
300 | @item C-x C-k C-a | |
301 | Add the prefix arg to the keyboard macro counter (@code{kmacro-add-counter}). | |
302 | @item C-x C-k C-f | |
303 | Specify the format for inserting the keyboard macro counter | |
304 | (@code{kmacro-set-format}). | |
305 | @end table | |
306 | ||
34768dde | 307 | Each keyboard macro has an associated counter. Normally, the |
eef59362 KS |
308 | macro counter is initialized to 0 when you start defining the macro, |
309 | and incremented by 1 after each insertion of the counter value; | |
310 | that is, if you insert the macro counter twice while defining the | |
2935e788 | 311 | macro, the counter will increase by 2 on each repetition of the macro. |
eef59362 KS |
312 | |
313 | @findex kmacro-insert-counter | |
314 | @kindex C-x C-k C-i | |
315 | The command @kbd{C-x C-k C-i} (@code{kmacro-insert-counter}) inserts | |
c9106f67 RS |
316 | the current value of the current keyboard macro's counter, and |
317 | increments the counter by 1. You can use a numeric prefix argument to | |
318 | specify a different increment. If you just specify a @kbd{C-u} | |
319 | prefix, then the increment is zero, so it repeats the last inserted | |
320 | counter value. For example, if you enter the following sequence while | |
321 | defining a macro | |
eef59362 KS |
322 | |
323 | @example | |
324 | 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 | |
325 | @end example | |
326 | ||
327 | @noindent | |
c9106f67 RS |
328 | it inserts @samp{0112} in the buffer. The next two iterations |
329 | of the macro will insert @samp{3445} and @samp{6778}. | |
eef59362 | 330 | |
c9106f67 RS |
331 | This command usually only makes sense while defining a keyboard |
332 | macro. But its behavior when no keyboard macro is being defined or | |
333 | executed is predictable: it inserts and increments the counter of the | |
334 | macro at the head of the keyboard macro ring. | |
34768dde | 335 | |
eef59362 KS |
336 | @findex kmacro-set-counter |
337 | @kindex C-x C-k C-c | |
c9106f67 RS |
338 | The command @kbd{C-x C-k C-c} (@code{kmacro-set-counter}) sets the |
339 | current macro counter to the value of the numeric argument. If you use | |
340 | it inside the macro, it operates on each repetition of the macro. If | |
341 | you specify just @kbd{C-u} as the prefix, while executing the macro, | |
342 | that resets the counter to the value it had at the beginning of the | |
343 | current repetition of the macro (undoing any increments so far in this | |
344 | repetition). | |
eef59362 KS |
345 | |
346 | @findex kmacro-add-counter | |
347 | @kindex C-x C-k C-a | |
c9106f67 RS |
348 | The command @kbd{C-x C-k C-a} (@code{kmacro-add-counter}) adds the |
349 | prefix argument to the current macro counter. With just @kbd{C-u} as | |
350 | argument, it resets the counter to the last value inserted by any | |
351 | keyboard macro. (Normally, when you use this, the last insertion | |
352 | will be in the same macro and it will be the same counter.) | |
eef59362 KS |
353 | |
354 | @findex kmacro-set-format | |
355 | @kindex C-x C-k C-f | |
34768dde LT |
356 | The command @kbd{C-x C-k C-f} (@code{kmacro-set-format}) prompts for |
357 | the format to use when inserting the macro counter. The default | |
358 | format is @samp{%d}, which means to insert the number in decimal | |
359 | without any padding. You can exit with empty minibuffer to reset the | |
360 | format to this default. You can specify any format string that the | |
361 | @code{format} function accepts and that makes sense with a single | |
362 | integer extra argument (@pxref{Formatting Strings,,, elisp, The Emacs | |
363 | Lisp Reference Manual}). Do not put the format string inside double | |
364 | quotes when you insert it in the minibuffer. | |
365 | ||
c9106f67 | 366 | If you use this command while no keyboard macro is being defined or |
34768dde LT |
367 | executed, the new format affects all subsequent macro definitions. |
368 | Existing macros continue to use the format in effect when they were | |
369 | defined. If you set the format while defining a keyboard macro, this | |
370 | affects the macro being defined from that point on, but it does not | |
371 | affect subsequent macros. Execution of the macro will, at each step, | |
372 | use the format in effect at that step during its definition. Changes | |
373 | to the macro format during execution of a macro, like the | |
374 | corresponding changes during its definition, have no effect on | |
375 | subsequent macros. | |
376 | ||
c9106f67 | 377 | The format set by @kbd{C-x C-k C-f} does not affect insertion of |
34768dde | 378 | numbers stored in registers. |
eef59362 KS |
379 | |
380 | @node Keyboard Macro Query | |
381 | @section Executing Macros with Variations | |
382 | ||
f8c2e4d5 RS |
383 | @table @kbd |
384 | @item C-x q | |
385 | When this point is reached during macro execution, ask for confirmation | |
386 | (@code{kbd-macro-query}). | |
387 | @end table | |
388 | ||
eef59362 KS |
389 | @kindex C-x q |
390 | @findex kbd-macro-query | |
391 | Using @kbd{C-x q} (@code{kbd-macro-query}), you can get an effect | |
392 | similar to that of @code{query-replace}, where the macro asks you each | |
393 | time around whether to make a change. While defining the macro, | |
394 | type @kbd{C-x q} at the point where you want the query to occur. During | |
395 | macro definition, the @kbd{C-x q} does nothing, but when you run the | |
396 | macro later, @kbd{C-x q} asks you interactively whether to continue. | |
397 | ||
398 | The valid responses when @kbd{C-x q} asks are @key{SPC} (or @kbd{y}), | |
399 | @key{DEL} (or @kbd{n}), @key{RET} (or @kbd{q}), @kbd{C-l} and @kbd{C-r}. | |
400 | The answers are the same as in @code{query-replace}, though not all of | |
401 | the @code{query-replace} options are meaningful. | |
402 | ||
403 | These responses include @key{SPC} to continue, and @key{DEL} to skip | |
404 | the remainder of this repetition of the macro and start right away with | |
405 | the next repetition. @key{RET} means to skip the remainder of this | |
406 | repetition and cancel further repetitions. @kbd{C-l} redraws the screen | |
407 | and asks you again for a character to say what to do. | |
408 | ||
409 | @kbd{C-r} enters a recursive editing level, in which you can perform | |
410 | editing which is not part of the macro. When you exit the recursive | |
411 | edit using @kbd{C-M-c}, you are asked again how to continue with the | |
412 | keyboard macro. If you type a @key{SPC} at this time, the rest of the | |
413 | macro definition is executed. It is up to you to leave point and the | |
414 | text in a state such that the rest of the macro will do what you | |
415 | want.@refill | |
416 | ||
417 | @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument, | |
418 | performs a completely different function. It enters a recursive edit | |
419 | reading input from the keyboard, both when you type it during the | |
420 | definition of the macro, and when it is executed from the macro. During | |
421 | definition, the editing you do inside the recursive edit does not become | |
422 | part of the macro. During macro execution, the recursive edit gives you | |
423 | a chance to do some particularized editing on each repetition. | |
424 | @xref{Recursive Edit}. | |
425 | ||
426 | Another way to vary the behavior of a keyboard macro is to use a | |
427 | register as a counter, incrementing it on each repetition of the macro. | |
428 | @xref{RegNumbers}. | |
429 | ||
430 | @node Save Keyboard Macro | |
431 | @section Naming and Saving Keyboard Macros | |
432 | ||
85aea0a0 | 433 | @table @kbd |
f8c2e4d5 RS |
434 | @item C-x C-k n |
435 | Give a command name (for the duration of the Emacs session) to the most | |
436 | recently defined keyboard macro (@code{kmacro-name-last-macro}). | |
437 | @item C-x C-k b | |
438 | Bind the most recently defined keyboard macro to a key sequence (for | |
439 | the duration of the session) (@code{kmacro-bind-to-key}). | |
440 | @item M-x insert-kbd-macro | |
441 | Insert in the buffer a keyboard macro's definition, as Lisp code. | |
442 | @end table | |
443 | ||
eef59362 | 444 | @cindex saving keyboard macros |
8e887df4 | 445 | @findex kmacro-name-last-macro |
eef59362 KS |
446 | @kindex C-x C-k n |
447 | If you wish to save a keyboard macro for later use, you can give it | |
8e887df4 | 448 | a name using @kbd{C-x C-k n} (@code{kmacro-name-last-macro}). |
2935e788 LT |
449 | This reads a name as an argument using the minibuffer and defines that |
450 | name to execute the last keyboard macro, in its current form. (If you | |
451 | later add to the definition of this macro, that does not alter the | |
452 | name's definition as a macro.) The macro name is a Lisp symbol, and | |
453 | defining it in this way makes it a valid command name for calling with | |
454 | @kbd{M-x} or for binding a key to with @code{global-set-key} | |
455 | (@pxref{Keymaps}). If you specify a name that has a prior definition | |
456 | other than a keyboard macro, an error message is shown and nothing is | |
457 | changed. | |
eef59362 KS |
458 | |
459 | @cindex binding keyboard macros | |
460 | @findex kmacro-bind-to-key | |
461 | @kindex C-x C-k b | |
34768dde LT |
462 | You can also bind the last keyboard macro (in its current form) to a |
463 | key, using @kbd{C-x C-k b} (@code{kmacro-bind-to-key}) followed by the | |
464 | key sequence you want to bind. You can bind to any key sequence in | |
465 | the global keymap, but since most key sequences already have other | |
466 | bindings, you should select the key sequence carefully. If you try to | |
467 | bind to a key sequence with an existing binding (in any keymap), this | |
468 | command asks you for confirmation before replacing the existing binding. | |
eef59362 | 469 | |
f8c2e4d5 | 470 | To avoid problems caused by overriding existing bindings, the key |
eef59362 KS |
471 | sequences @kbd{C-x C-k 0} through @kbd{C-x C-k 9} and @kbd{C-x C-k A} |
472 | through @kbd{C-x C-k Z} are reserved for your own keyboard macro | |
473 | bindings. In fact, to bind to one of these key sequences, you only | |
474 | need to type the digit or letter rather than the whole key sequences. | |
475 | For example, | |
476 | ||
477 | @example | |
478 | C-x C-k b 4 | |
479 | @end example | |
480 | ||
481 | @noindent | |
482 | will bind the last keyboard macro to the key sequence @kbd{C-x C-k 4}. | |
483 | ||
484 | @findex insert-kbd-macro | |
485 | Once a macro has a command name, you can save its definition in a file. | |
486 | Then it can be used in another editing session. First, visit the file | |
487 | you want to save the definition in. Then use this command: | |
488 | ||
489 | @example | |
490 | M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET} | |
491 | @end example | |
492 | ||
493 | @noindent | |
494 | This inserts some Lisp code that, when executed later, will define the | |
495 | same macro with the same definition it has now. (You need not | |
496 | understand Lisp code to do this, because @code{insert-kbd-macro} writes | |
497 | the Lisp code for you.) Then save the file. You can load the file | |
498 | later with @code{load-file} (@pxref{Lisp Libraries}). If the file you | |
499 | save in is your init file @file{~/.emacs} (@pxref{Init File}) then the | |
500 | macro will be defined each time you run Emacs. | |
501 | ||
502 | If you give @code{insert-kbd-macro} a numeric argument, it makes | |
2935e788 LT |
503 | additional Lisp code to record the keys (if any) that you have bound |
504 | to @var{macroname}, so that the macro will be reassigned the same keys | |
505 | when you load the file. | |
eef59362 KS |
506 | |
507 | @node Edit Keyboard Macro | |
2935e788 | 508 | @section Editing a Keyboard Macro |
eef59362 | 509 | |
f8c2e4d5 RS |
510 | @table @kbd |
511 | @item C-x C-k C-e | |
512 | Edit the last defined keyboard macro (@code{kmacro-edit-macro}). | |
513 | @item C-x C-k e @var{name} @key{RET} | |
514 | Edit a previously defined keyboard macro @var{name} (@code{edit-kbd-macro}). | |
515 | @item C-x C-k l | |
516 | Edit the last 100 keystrokes as a keyboard macro | |
517 | (@code{kmacro-edit-lossage}). | |
518 | @end table | |
519 | ||
eef59362 KS |
520 | @findex kmacro-edit-macro |
521 | @kindex C-x C-k C-e | |
522 | @kindex C-x C-k RET | |
523 | You can edit the last keyboard macro by typing @kbd{C-x C-k C-e} or | |
524 | @kbd{C-x C-k RET} (@code{kmacro-edit-macro}). This formats the macro | |
525 | definition in a buffer and enters a specialized major mode for editing | |
526 | it. Type @kbd{C-h m} once in that buffer to display details of how to | |
527 | edit the macro. When you are finished editing, type @kbd{C-c C-c}. | |
528 | ||
529 | @findex edit-kbd-macro | |
530 | @kindex C-x C-k e | |
531 | You can edit a named keyboard macro or a macro bound to a key by typing | |
532 | @kbd{C-x C-k e} (@code{edit-kbd-macro}). Follow that with the | |
533 | keyboard input that you would use to invoke the macro---@kbd{C-x e} or | |
534 | @kbd{M-x @var{name}} or some other key sequence. | |
535 | ||
536 | @findex kmacro-edit-lossage | |
537 | @kindex C-x C-k l | |
538 | You can edit the last 100 keystrokes as a macro by typing | |
539 | @kbd{C-x C-k l} (@code{kmacro-edit-lossage}). | |
540 | ||
541 | @node Keyboard Macro Step-Edit | |
1dec4064 | 542 | @section Stepwise Editing a Keyboard Macro |
eef59362 KS |
543 | |
544 | @findex kmacro-step-edit-macro | |
545 | @kindex C-x C-k SPC | |
bb18ce6a RS |
546 | You can interactively replay and edit the last keyboard |
547 | macro, one command at a time, by typing @kbd{C-x C-k SPC} | |
eef59362 KS |
548 | (@code{kmacro-step-edit-macro}). Unless you quit the macro using |
549 | @kbd{q} or @kbd{C-g}, the edited macro replaces the last macro on the | |
550 | macro ring. | |
551 | ||
bb18ce6a RS |
552 | This macro editing feature shows the last macro in the minibuffer |
553 | together with the first (or next) command to be executed, and prompts | |
554 | you for an action. You can enter @kbd{?} to get a summary of your | |
555 | options. These actions are available: | |
eef59362 KS |
556 | |
557 | @itemize @bullet{} | |
558 | @item | |
559 | @kbd{SPC} and @kbd{y} execute the current command, and advance to the | |
560 | next command in the keyboard macro. | |
561 | @item | |
562 | @kbd{n}, @kbd{d}, and @kbd{DEL} skip and delete the current command. | |
563 | @item | |
564 | @kbd{f} skips the current command in this execution of the keyboard | |
565 | macro, but doesn't delete it from the macro. | |
566 | @item | |
ee6c21a7 EZ |
567 | @kbd{@key{TAB}} executes the current command, as well as all similar |
568 | commands immediately following the current command; for example, @key{TAB} | |
eef59362 KS |
569 | may be used to insert a sequence of characters (corresponding to a |
570 | sequence of @code{self-insert-command} commands). | |
571 | @item | |
572 | @kbd{c} continues execution (without further editing) until the end of | |
573 | the keyboard macro. If execution terminates normally, the edited | |
574 | macro replaces the original keyboard macro. | |
575 | @item | |
576 | @kbd{C-k} skips and deletes the rest of the keyboard macro, | |
577 | terminates step-editing, and replaces the original keyboard macro | |
578 | with the edited macro. | |
579 | @item | |
580 | @kbd{q} and @kbd{C-g} cancels the step-editing of the keyboard macro; | |
581 | discarding any changes made to the keyboard macro. | |
582 | @item | |
583 | @kbd{i KEY... C-j} reads and executes a series of key sequences (not | |
584 | including the final @kbd{C-j}), and inserts them before the current | |
585 | command in the keyboard macro, without advancing over the current | |
586 | command. | |
587 | @item | |
588 | @kbd{I KEY...} reads one key sequence, executes it, and inserts it | |
589 | before the current command in the keyboard macro, without advancing | |
590 | over the current command. | |
591 | @item | |
592 | @kbd{r KEY... C-j} reads and executes a series of key sequences (not | |
593 | including the final @kbd{C-j}), and replaces the current command in | |
594 | the keyboard macro with them, advancing over the inserted key | |
595 | sequences. | |
596 | @item | |
597 | @kbd{R KEY...} reads one key sequence, executes it, and replaces the | |
598 | current command in the keyboard macro with that key sequence, | |
599 | advancing over the inserted key sequence. | |
600 | @item | |
601 | @kbd{a KEY... C-j} executes the current command, then reads and | |
602 | executes a series of key sequences (not including the final | |
603 | @kbd{C-j}), and inserts them after the current command in the keyboard | |
604 | macro; it then advances over the current command and the inserted key | |
605 | sequences. | |
606 | @item | |
607 | @kbd{A KEY... C-j} executes the rest of the commands in the keyboard | |
608 | macro, then reads and executes a series of key sequences (not | |
609 | including the final @kbd{C-j}), and appends them at the end of the | |
610 | keyboard macro; it then terminates the step-editing and replaces the | |
611 | original keyboard macro with the edited macro. | |
612 | @end itemize | |
ab5796a9 MB |
613 | |
614 | @ignore | |
615 | arch-tag: c1b0dd3b-3159-4c08-928f-52e763953e9c | |
616 | @end ignore |