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