Macros

This chapter describes the macro facilities available in Emacs. These facilities allow you to build macros on the fly, and then use them to replace multiple keystrokes. You can also use macros to write generalised facilities, map them into the function name-space and bind key sequences to them.

Macros differ from Mock Lisp (MLisp) functions because they are key sequences that are replayed into the Emacs keyboard processor and are subject to the current bindings. The effect of a macro will be unpredictable if the key bindings used in a macro change between the macro's definition and its use. There are no facilities to alter control flow while a macro is being executed.

keyboard macros

(start-remembering) ^X-( Starts defining a keyboard macro.
(stop-remembering) ^X-) Ends the definition of a keyboard macro.
(execute-keyboard-macro) ^X-e Executes the most recently-defined keyboard macro.
(define-keyboard-macro) Turns the most recent keyboard macro into a named macro.

A keyboard macro is a command defined by you to abbreviate a sequence of other commands. For example, if you discover that you are about to type ^U-^D forty times, you can define a keyboard macro to execute ^U-^D and call it with a repeat count of forty.

You define a keyboard macro while executing the commands which are part of the definition. In this way, you can see what the effects of your commands are---you do not have to work them out in your head. When you have finished, the keyboard macro is defined and has also been, in effect, executed once. You can execute the sequence of commands again by invoking the macro.

To start defining a keyboard macro, type the ^X-( (start-remembering) command. From then on, your commands continue to be executed, but also become part of the macro definition. When you have finished, the ^X-) (stop-remembering) command terminates the definition (without becoming part of it).

You can call the newly-defined macro the ^X-e (execute-keyboard-macro) command. You can give ^X-e a repeat count as a prefix argument to execute the macro several times.

There are two ways of using a keyboard macro to perform some action on each line in the buffer. The first is to start by positioning dot on the line above the first line to be processed, then begin the macro definition with a ^N (next-line). The second method is to start on the proper line, and end the macro with a ^N. Repeating the macro will operate on successive lines using either method.

Emacs can have only one current keyboard macro. When you define a new keyboard macro, the old macro definition is lost. To save a keyboard macro definition, you must give it a name. If you execute define-keyboard-macro, the last keyboard macro defined is turned into a named macro . When a named macro has been created, you can bind it to any key sequence in the usual way.

named macros

The named macro facility in Emacs allows you to specify a collection of keystrokes to act as an Emacs function, and then associate the function with another key sequence.

(define-buffer-macro) Defines a macro using the current buffer's contents as the keystroke sequence. The name of the macro is obtained from the buffer-specific variable current-buffer-macro-name.
(define-keyboard-macro function-name) Defines a named macro with the current contents of the keyboard macro.
(define-string-macro function-name keys) Defines a macro given its name and the key sequence as arguments.
ESC-x edit-macro Inserts the body of the specified macro into the buffer Macro edit to allow editing of the keystroke sequence.
(rename-macro old-name new-name) Changes the name of a macro or function.

You normally define a named macro by first defining it as a keyboard macro, then using ESC-x define-keyboard-macro to give the macro a name. When a macro has been given a name, you can execute it using ESC-x as if it were an ordinary Emacs function. The fact that it is a macro is transparent to ESC-x.

A quick way to define a short macro is to use ESC-x define-string-macro. This command prompts you for the name of the macro and the key sequence to use for the macro's body. Special characters have to be quoted, otherwise they will be executed as commands in the Mini-buffer. A disadvantage of this type of macro definition is that you must know, or be able to visualise, the key sequence while you are typing it in. ESC-x define-string-macro does not execute the macro key sequence while it is being defined.

If you discover a mistake in a macro, or you wish to change the macro's definition, use ESC-x edit-macro. This command generates a buffer called Macro edit with the body of the macro inserted in the buffer. The name of the macro is associated with the buffer, and the buffer's type is Macro. You can identify the name of the macro by looking at the variable current-buffer-macro-name. When you have finished editing the macro, the buffer contents can replace the body of the macro. Use ESC-x define-buffer-macro to re-define the macro.

If you wish to change the name of a macro (or any Emacs function, including MLisp and wired-in functions), use the rename-macro command. rename-macro asks you to specify the old name of the macro, followed by the new name you wish to give it. If the new name already exists, the existing MLisp or macro function will be overwritten. If the new function name already exists and is a wired-in function, an error message will be generated. This prevents you from removing wired-in parts of Emacs that packages may need.