Learning GNU Emacs, 3rd Edition

What is a macro? In Emacs, a macro is simply a group of recorded keystrokes you can play back over and over again. Macros are a great way to save yourself repetitive work. For example, let's say you want to delete the third column of a table. Normally, you would go to the first line; move over to the third column; delete it; then go to the second line; give the same set of commands; and so on, until you finish, your fingers wear out, or you get too bored. Emacs lets you record the keystrokes you used to work on the first line of the table, and then "play these back" repeatedly until the job is done.[32]

Any command or action you do within Emacs, from typing text to editing to switching buffers, can be done within a macro. The key to using macros well is, not too surprisingly, recognizing when you're doing repetitive work: sensing that you have pressed more or less the same sequence of keys several times in a row. Once you learn to recognize repetitious work, you have a good feel for when to use macros. The next talent that you'll need is, given that you've recognized a cycle of "almost identical" keystrokes, figuring out how to make that cycle precisely identical—that is, figuring out a set of keystrokes that, if repeated, will do exactly what you want. Neither of these skills is particularly difficult; with a little practice, you'll be using macros all the time.

If this sounds like lazy man's programming, it is: macros give you a simple way to do very complicated things without learning Lisp and without learning any customization tricks. If the task you build the macro for is something you have to do frequently, you can save macros and load them when you want to use them. In this way, you can build up a set of convenient macros that become your own editing commands. Even if you don't write Lisp, you're not limited to the commands Emacs gives you; you can make your own!

What you use macros for will depend on the kind of work you do in Emacs. We've used macros to:

• Mark up text for formatting.

• Copy headings from one buffer to another to create an outline.

• Perform complex search-and-replace type operations that query-replace can't quite handle.

• Create index entries.

• Reformat files that were imported from another application.

• Edit tables.

• Compile, run, and test the output from a program with a single command.

• Manipulate and clean large datasets.

You'll be able to think of many more things to do with macros after you learn the few basic commands you need to use them.

6.1 Defining a Macro

To start defining a macro, press F3 or C-x (.[33] The abbreviation Def appears on the mode line, showing that you are in macro definition mode. In this mode, Emacs records all the keystrokes that you type, whether they are commands or literal text, so that you can replay them later. To end the macro, press F4 or C-x ); you leave macro definition mode, and Emacs stops recording your keystrokes. Emacs also stops recording your keystrokes automatically if an error occurs or if you press C-g.

While you're defining a macro, Emacs acts on your keystrokes as well as recording them: that is, anything you type while in macro definition mode is treated as a regular command and executed. While you're defining a macro, you're doing completely normal editing. That way you can see that the macro does exactly what you want it to, and you can cancel it (with C-g) if you notice that the macro isn't really quite what you want.

To execute your macro, press F4 or C-x e. Emacs then replays your keystrokes exactly. (You can see that F4 has two different functions relating to macros: to end a macro definition and, after it's defined, to execute the macro.)

This macro is referred to as the "last" keyboard macro, with last here meaning most recent. Only one macro is the last keyboard macro. A macro ring, much like the kill ring, allows you to access a number of macros during an Emacs session.

Table 6-1 shows the steps required to define and execute a macro. This macro takes a list of names in the ordinary First Name Last Name order and changes it to the frequently needed Last Name, First Name order.

Table 6-1. Steps for creating name transposition macro

Def

Define the macro using the keystrokes given in Table 6-1.

In defining the macro, you transposed the names on the first line, leaving the cursor on the second line.

Now let's be brave and assume the macro works; we'll try repeating it five times by prefacing the command to execute a macro with M-5. Of course, in real life, you'd be better off trying it once before doing anything so bold.

Type M-5 F4 or M-5 C-x e

Now we've done the first six lines: one by defining the macro and five more by executing it.

The macro works well, so we can finish the rest of the buffer with confidence: type M-100, then C-x e or F4. Emacs stops automatically when you reach the end of the buffer, so it doesn't matter if you repeat the macro more times than necessary.

Here are a few points to remember:

• Don't forget to press F4 or C-x ) when you've finished the macro. If you try to execute a macro before it has been defined, Emacs complains and forgets the macro's definition.

• C-g terminates a macro, causing Emacs to forget its definition.

• Virtually any error automatically terminates a macro. If Emacs beeps at you, you have to start over.

• Emacs executes the keystrokes exactly as you type them, with no intelligence whatsoever. Avoid making assumptions like, "Of course I'll be at the beginning (or end) of the line when I execute the macro."

If you invoke a macro and it does the wrong thing, you can use C-_ to undo it. Emacs is smart enough to realize that "undo the last command" means "undo the entire macro" rather than "undo the last command within the macro." However, if you repeat a macro multiple times using M-n, C-_ undoes only the last instance of the macro, not all the instances.

6.2 Tips for Creating Good Macros

It's easy to learn how to record and reuse your keystrokes. However, when you're starting out, you make a few mistakes: you create a macro, use it, and then find out that it doesn't do exactly what you thought. With a little care, it's easy to make your macros more useful and less vulnerable to mistakes.

Good macros work in all situations. Therefore, within a macro, you should use commands that are absolute rather than relative. For example, if you write a macro that puts a formatting string around the word the cursor is on, you want the macro to work no matter how long the word is. Therefore, you would use an absolute command such as M-f (for forward-word) rather than a few C-fs to move forward one character at a time. Similarly, commands such as C-e and C-a are good for finding the beginning or end of a line rather than moving the cursor forward or backward.

Often, macros start with a search command that brings you to the place in the file you want the macro to start. It's a good idea to type the search argument (as in C-s

searchstring

It is often a good idea to add extra commands (typically C-a and C-e) that aren't strictly necessary, just to make sure that you're positioned correctly on the line. The fewer assumptions that a macro makes, the better it works. So, if a sequence of commands works correctly only if you start at the end of the line, start the macro with C-e, even if you already "know" that you want to give the command only when you're at the end of the line.

Finally, while we're reciting rules and cautions, here's one more: keep in mind that you probably want to execute macros repeatedly. With a little foresight, you'll be able to create macros that can be executed in long chains without problems.

In general, good macros have three parts:

• They find the place you want the macro to start working (often using search).

• They do the work that needs to be done on the text.

• They prepare themselves to repeat.

How can a macro prepare itself to repeat? For example, assume that you're writing a macro to delete the third column of a table. After deleting the column, the macro should position itself at the beginning of the next line (or wherever it needs to be) so you don't have to reposition the cursor before reusing it.

Here's a slightly more complex example. If you start a macro with a search, you have to make sure that the end of the macro moves the cursor past the last spot you searched for. If you don't, the macro will keep finding the same place in the file and never go on to the next occurrence of what you're searching for. As a general rule, if your macro operates on a line of text, it should end by moving to the beginning of the next line. Remember that your goal is to create a sequence of keystrokes that can be executed many times in a row, with no interruption.

6.3 A More Complicated Macro Example

Sometimes you may want to find all the references to a particular topic in a file. Table 6-2 lists steps for creating a macro that takes takes every sentence in the buffer that contains the word Emacs and copies it to another buffer. If you try this macro, you'll need to type some text about Emacs into a buffer. You can also get a test file to work with by opening the Emacs NEWS file (using C-h n), then writing it to a file (C-x C-w NEWS). This buffer is in view mode by default; change to text mode by typing M-x text-mode Enter.

Table 6-2. Steps for macro that creates a buffer of Emacs references

Def

emacsrefs

Def

Now, assume that you've already constructed the macro outlined in Table 6-2 and that you can invoke it with F4. The following screen shows what happens when you run it five times and then display the

emacsrefs

Type: M-5 F4 or M-5 C-x e, followed by C-x b Enter

By executing the macro repeatedly, we've created a buffer that contains references to the Emacs editor.

As in the previous example, you can jump back and forth between an unlimited number of buffers while defining a macro. Macros don't need to be confined to one buffer. Macros that work with several buffers are more difficult to debug; when several buffers are involved, it becomes harder for you to keep track of where the cursor and the mark are. It is also easy to make mistaken assumptions about what buffer you're visiting; hence, it's a good idea to specify the buffer name explicitly. However, after you get accustomed to working with macros and multiple buffers, you'll be amazed at how much work you can do with almost no effort.

Windows are sometimes useful in macros, but, again, you have to watch out. It's better to start a macro with one window on the screen, have the macro open other windows, and finally close all but one window (C-x 1). If you write a macro with two windows on the screen and later try to execute it with four windows on the screen, the results will be unpredictable at best! In general, moving to a named buffer, C-x b

buffername

*Help*

*Completion*

*shell*

6.4 Editing a Macro

You can edit a macro and make changes to it in a few different ways. For this example, we chose an all-purpose editing command, edit-kbd-macro, which is bound to C-x C-k e. Several macro editing commands are available, but this one works for all types of macros, so it's good to learn.

Our macro could use a bit of tweaking. First of all, finding references to Emacs in our copy of the Emacs NEWS file is pretty lame. Perhaps we're interested in using a mouse more frequently with Emacs and would like to know about changes to that part of the interface. We'll edit the macro to search for the word mouse. We'll also modify it so it marks a paragraph rather than a sentence since a sentence doesn't really provide enough context to be helpful.

Let's start editing the macro.

Type: C-x C-k e

Emacs prompts you for the type of macro to edit.

Emacs asks you if you want to edit the last keyboard macro (C-x e), a named macro (M-x), the last 100 keystrokes as a macro, termed "lossage" (C-h l), or keys (meaning the keystrokes you bound a macro to). Yes, that's a lot of choices, and later in the chapter we describe named macros and binding macros to keys (you can experiment on your own with creating a macro from lossage). For now, just choose C-x e to edit the last keyboard macro.

Type: C-x e

Emacs opens an

*Edit Macro*

Notice two fields near the top of this buffer,

Command:

Key:

Command:

last-kbd-macro

Key:

none

Note that Emacs inserts comments all through the macro. It's attempting to map keystrokes to commands. You do not need to update these comments or add comments if you add commands to your macro; Emacs does that itself.

To tweak our macro, we change the search string on the second line from emacs to mouse. Note that we can just press C-k to wipe out the line and type mouse. Now change M-a to M-{ and M-e to M-}. We change the buffer name from

emacsrefs

mouseinfo

We've made the edits from the previous paragraph. The screen looks like this:

A modified macro that captures information about using a mouse in Emacs.

To exit the macro editing buffer, we have to type C-c C-c and go back to our

NEWS

Type: C-c C-c C-x b Enter M-< M-5 F4 C-x b Enter M-<

The

mouseinfo

6.5 The Macro Ring

Although our latest macro is interesting, it's not really a general purpose macro. It is a temporary solution to a one-time problem. It saves you some work, but it isn't general enough to save and use again. On the other hand, our macro to transpose names is generally useful. We'd like to use it again. We'd like to bind it to a key. But it is no longer the "latest" keyboard macro.

As we mentioned earlier, Emacs has a macro ring much like the infamous kill ring. It's useful in the case we've just described, but it's also useful because of the fragility of the macro definition process. You create a macro and make a wrong move that rings the bell, and your macro is canceled. It's fairly easy to create a macro that does nothing. Perhaps the macro that you just created was wonderful, and this new nonfunctional nothing macro has supplanted it. Again, the macro ring is the solution. To delete a macro from the ring, type C-x C-k C-d (for kmacro-delete-ring-head). This deletes the most recently defined keyboard macro.

What if you want to swap the positions of two macros? Instead, type C-x C-k C-t (for kmacro-swap-ring). This transposes macros 1 and 2.

In a more general sense, you can cycle to the previously defined macro by typing C-c C-k C-p (for kmacro-cycle-ring-previous). To move the ring the other way, type C-x C-k C-n (for kmacro-cycle-ring-next). The familiar C-p for previous and C-n for next bindings are appended to the general macro keyboard prefix C-x C-k.

Before we can work with the transpose names macro, we must either define it again or, if you've been working through our examples, type C-x C-k C-p to move to the previous macro.

6.6 Binding Your Macro to a Key

Binding a macro to a key is easy. The key sequences C-x C-k 0 through 9 and capital A through Z are reserved for user macro bindings. You can choose one that strikes you as mnemonic for your macro.

For example, to bind our transpose names macro to C-x C-k T, type C-x C-k b. Emacs prompts for the key binding. Type C-x C-k T Enter. Emacs confirms,

Keyboard macro bound to C-x C-k T

6.7 Naming, Saving, and Executing Your Macros

In this section, we'll describe how to save macros so that you can use them in different editing sessions. To save a macro, bind it permanently to a key, and load it in subsequent Emacs sessions, follow these steps:

1. Define the macro, if you haven't already.

2. Type C-x C-k n (for name-last-kbd-macro). Now type a name for your macro and press Enter. A non-Emacs sounding name is best so that Emacs doesn't confuse it with one of its own commands. Once you've executed this command, Emacs remembers the macro for the rest of the editing session. To use it again, type the command M-x name (where name is the name you've chosen). Emacs treats your named macro like one of its own commands; it shows up in completion lists if you press Tab after typing a few letters of the name.

3. If you want to save the macro definition permanently, you must insert the macro definition into a file. This could be your .emacs file or a macro file that you load through your .emacs file. Type C-x C-f filename Enter to find the file into which to insert the definition and move to the end of it by typing M->.

4. Type M-x insert-kbd-macro Enter macroname Enter. Emacs inserts Lisp code that represents your macro.

5. Add a line to .emacs make the key binding permanent. For example, if we called our macro transpose-names and bound it to C-x C-k T, we would add this line to our .emacs file (or other macro definition file):

(global-set-key "\C-x\C-kT" 'transpose-names)

6. If you save the macro in some other file, it won't be loaded automatically. For example, let's say that you have defined a macro called transpose-names and placed it in the file html.macs, in the directory ~/macros. Add this line to your .emacs file to load your macros automatically:

(load-file "~/macros/html.macs")

7. Save the .emacs file and, if different, the file in which you inserted your macro. Exit and restart Emacs. You can now execute this macro either by typing M-x transpose-names Enter or by pressing C-x C-k T.

6.8 Building More Complicated Macros

Type your address and press C-M-c

Type recipient name and address and press C-M-c

Type date and press C-M-c

Proceed with macro? (y, n, RET, C-l, C-r)

comments

6.9 Executing Macros on a Region

A special command lets you execute a macro on each line in a region. How frequently do you encounter an email with text that you want to yank, but that is quoted several indentation levels? Of course, we can think of several ways to delete the indentation quickly, but a line-oriented macro is a quick approach too. You define the macro and execute it on a region by typing C-x C-k r (for apply-macro-to-region-lines). Remember that earlier we said that macros should set themselves up to repeat? This command is different because it expects to work on one line at a time. You don't want to set it up to repeat by moving to the next line; it does that automatically.

Table 6-5 shows a quick line-oriented macro that deletes indentation marks from text quoted in an email or newsgroup message.

Table 6-5. Macro for deleting indentation marks

Initial state:

Text indented at various levels (Mac OS X).

Mark the text as a region, move to the beginning of the region, then type: C-x C-k r

Indentation is deleted (Mac OS X).

6.10 Beyond Macros

Macros are an important tool for streamlining repetitive editing. They let you write your own commands for performing complex tasks without needing to know anything more than you already know: the basic Emacs commands for moving around and manipulating text. Even if you're an Emacs novice, you should be able to use macros with little difficulty.

However, Emacs is almost infinitely flexible, and macros cannot do everything. In many situations, there's no substitute for writing a Lisp function that does exactly what you want. If you know Lisp or would like to learn some, you can write your own Lisp functions to do more complex tasks than keyboard macros can handle. Chapter 11 covers the basics of writing Lisp functions.

Table 6-6 summarizes macro commands.

Table 6-6. Macro commands