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