Macros are an extremely powerful tool that allow you to record and replay a set of actions.

Let's perform the same operation as before, using macros. We have the following code in farm.py:

...
def act(self, target):
    for animal in self.animals:
        if animal.get_kind() == 'cat':
            print(animal.act(target, 'meows'))
        elif animal.get_kind() == 'dog':
            print(animal.act(target, 'barks'))
        elif animal.get_kind() == 'sheep':
            print(animal.act(target, 'baas'))
        else:
            print(animal.act(target, 'looks'))
...

We'd like to reorder arguments in animal.act calls. Open farm.py, and move your cursor to the top of the file with gg:

Enter macro recording mode using q followed by any register (let's pick a), as follows: qa. You'll see recording @a in a status line, which indicates that the macro is recording:

Every movement or edit you make when in macro mode will be repeated when you replay the macro later on. That's why it's important to be deliberate when recording macros, and try to consider replayability when moving or performing actions.

Let's navigate to the first instance by searching for /animal.act:

We're searching (and not navigating by line numbers, for instance) to make it possible to apply the macro to the rest of the text.

Now, move your cursor to the word target. You can move by word (4w), or navigate to the opening parenthesis (f() followed by moving one character to the right (l):

Since we want to paste target later, let's copy it into a register. "bdw will delete the word target into the b register, as follows:

Now, let's delete the remaining comma (for this we don't need a special register, and we don't need to worry about overwriting target as it's been moved to its own register):

Now navigate to the end of meows with f':

Add the missing comma followed by a space: a (to enter insert after the cursor), , , followed by Esc:

Now paste from the register b: "bp:

Done! Hit q to finish recording the macro, you'll see that the recording @a line has disappeared.

Fantastic! Now you can replay the macro using @a:

You can repeat the macro multiple times by prefixing it with a number: 2@a. However, if, for instance, you are searching as part of your macro, the search may wrap back to the beginning of the file and replay a macro on a portion of file you've already modified:

That's where working with macros can get messy. All macros do is record your actions and replay them back.

So, how can we make this macro not do this?

A macro stops executing if it encounters an error. If there are no patterns we're searching for below the cursor, Vim just looks for one above the cursor—without producing an error. So we just need to manually produce an error, to make sure the macro doesn't continue running when it doesn't have to.

In this particular case, we can tell search to stop wrapping back around, and, instead, produce an error when reaching the end of the file:

:set nowrapscan

If you replay the macro, you'll now get an error:

Now you can safely execute this macro any number of times.

Due to errors like these, or if you're not confident about the matches, sometimes it's useful to carry out a separate search. It might make sense to search for an occurrence outside the macro (such as /animal.act), and then play the macro if you decide that the change is warranted.

Then, you can run n to search for the next search occurrence of animal.act, decide whether you'd like to make changes, and run the macro again with @a or @@.