Basic Macros (ne’s manual)

Next: More Advanced Features, Previous: Basic Preferences, Up: Basics [Contents][Index]

### 2.6 Basic Macros

Very often, the programmer or the text writer has to repeat some complex editing action over a series of similar blocks of text. This is where macros come in.

A macro is a stored sequence of commands. Any sequence of commands you find yourself repeating is an excellent candidate for being made into a macro. You could create a macro by editing a document that only contains valid `ne` commands and saving it, but by far the easiest way to create a macro is to have `ne` record your actions. `ne` allows you to record macros and then play them (execute the commands they contain) many times. You can save them on disk for future use, edit them, or bind them to any key. You could even reconfigure each key of your keyboard to play a complex macro if you wanted to.

`ne` can have any number of named macros loaded at the same time. In addition, each document can also have one unnamed macro in its current macro buffer. Named macros are typically loaded from files, while each document’s current macro buffer is where your recorded macro is held before you save it, play it, or record over it.

Recording a macro is very simple. The keystroke `Control-T` starts and stops recording a macro. When you start recording a macro, `ne` starts recording all your actions (with a few exceptions). You can see that you are recording a macro if an ‘`R`’ appears on the status bar. After you stop the recording process (again using `Control-T`), you can play the macro with the ‘`Play Once`’ item of the ‘`Macros`’ menu or with the `f9` key. If you want to repeat the action many times, the `Play` command allows you to specify a number of times to repeat the macro. You can always interrupt the macro’s execution with `Control-\`.

A recorded macro has no name. It’s just an anonymous sequence of commands associated with your current document. It will go away when you record another macro, close the document, or exit `ne`. If you want to save your recorded macro for future use, you can give it a name and save it with the ‘`Save Macro...`’ menu item or the `SaveMacro` command. The macro is saved as a regular text file in your current directory by default or whatever directory you specify when prompted for the macro’s name. If you save it in your `~/.ne` directory then it will be easy to access it later from any other directory. The ‘`Open Macro...`’ menu item and the `OpenMacro` command load a macro from a file into the current document’s buffer just as if you had just `Record`ed it.

The current setting of your `VerboseMacros` flag determines whether long or abbreviated command names are used when saving a macro. For your convenience, `SaveMacro` will also convert sequences of `InsertChar` commands into single—usually much more readable— `InsertString` commands, but only if all the inserted characters are simple printable characters, and only if there are no subsequent `Undo` commands or macro invocations.

Any macro can be loaded from a file and played with the ‘`Play Macro...`’ menu item or the `Macro` command. (This won’t modify the recorded anonymous macro that may be in the current macro buffer; `OpenMacro` does that.) Useful macros can be permanently bound to a keystroke as explained in Key Bindings. Moreover, whenever a command line does not specify one of `ne`’s built in commands, it is assumed to specify the name of a macro to execute. Thus, you can execute macros just by typing their file names at the command line. Include a path if the macro file’s directory is different from your current directory or your `~/.ne` directory.

If the first attempt to open a macro fails, `ne` checks for a macro with the given name in your `~/.ne` directory. This allows you to program simple extensions to `ne`’s command set. For instance, all automatic preferences macros—which are just specially named macros that contain only commands to set preferences flags—can be executed just by typing their names. For example, if you have an automatic preference for the ‘`txt`’ extension for example, you can set `ne`’s flags exactly as if you had loaded a file ending with ‘`.txt`’ by typing the command `txt#ap`.

In general, it is a good idea to save frequently used macros in `~/.ne` so that you can invoke them by name without specifying a path regardless of your current directory. On the other hand, if you have a macro that is customized for one document or a set of documents that you store in one directory, then you might want to save the macro in that directory instead. If you do, then you would want to `cd` to that directory before you start `ne` so that you can access that macro without specifying a path.

If your macro has the same name as one of `ne`’s built-in commands, you can only access it with the `Macro name` command. Built-in command names are always searched before the `ne` command interpreter looks for macros.

The system administrator may make some macros available from the `macros` subdirectory of `ne`’s global directory. See Arguments.

Since loading a macro each time it is invoked would be a rather slow and expensive process, once a named macro has been executed it is cached internally. Subsequent invocations of the named macro will use the cached version.

Warning: while path and file names are case sensitive when initially loading macros, loaded macro names are not case sensitive or path sensitive. `ne` only caches the file name of an already loaded macro, not the path, and it uses a case insensitive comparison when resolving command names. As such, if you invoke `~/foobar/MyMacro`, `ne` remembers it with the case-insensitive name `mymacro`; a subsequent call for `/usr/MYMACRO` will instead find and use the cached version of `~/foobar/MyMacro`. You can clear the cache by using the `UnloadMacros` command. See UnloadMacros.

The behaviour of macros may vary with different preferences. If the user changes the `AutoIndent` and `WordWrap` flags, for example, new lines and new text may not appear in the same way they would have when a macro was recorded. Good general purpose macros avoid such problems by using the `PushPrefs` command first. This preserves the user’s preferences. Then they set any preferences that could affect their behaviour. Once that is taken care of they get on with the actual work for which they were intended. Finally, they use the `PopPrefs` command to restore the user’s preferences. Note that if a macro is stopped before it restores the preferences (either by the user pressing `Control-\` or by a command failing) then dealing with the changed preferences falls to the user.

Any changes made to a document by a macro are recorded just as if you had entered the commands yourself. Therefore you can use the `Undo` command to roll back those changes one at a time. This can be useful especially when developing macros, but you may want to be able to undo all the changes made by a macro with a single `Undo` command. The `AtomicUndo` command makes this possible. If you add `AtomicUndo +` at the start of your macro and `AtomicUndo -` at the end, then the `Undo` and `Redo` commands will handle all changes made by your macro atomically, i.e., as if they had been made by a single command, even if your macro calls other macros which could themselves contain matching `AtomicUndo +` and `AtomicUndo -` commands. See AtomicUndo.

Any line in a macro that starts with a non-alphabetical character is considered a comment, so you can add comments to a macro by starting a line with ‘`#`’. Recorded macros sometimes have comments added to them indicating calls to other macros.

Macros can operate across multiple documents, by using the `NextDoc` and `PrevDoc` commands for example. When you stop recording, the unnamed macro is associated with the current document, replacing that document’s prior unnamed macro.

You can cancel in-progress macro recording with the `Record 0` command, or by selecting `Record Cancel` from the `Macro` menu.

You can append additional recorded commands to your document’s current macro with the `Record 1` command, or by selecting `Record Append` from the `Macro` menu.

Next: More Advanced Features, Previous: Basic Preferences, Up: Basics [Contents][Index]