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 recorded macros as files 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 has one unnamed macro in its current macro buffer.
Named macros are loaded from—and get the name of—files, while each document’s
unnamed 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. When you stop
recording (again using Control-T), ne throws away the
current document’s current macro and replaces it with the one you just finished
recording. You can then 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-\.
These commands are omitted from recorded macros:
Escape Help Play Exec KeyCode Quit Flags Macro Record
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 by saving 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 macro buffer just as if you had just Recorded 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 consecutive
InsertChar commands into single—usually much more readable—
InsertString commands, but only if all the inserted characters are
simple printable characters, and only if the macro contains no Undo
commands or macro invocations later in the macro.
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’s first non-blank character is an ASCII letter but 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. If the file
containing your macro is somewhere besides your current directory or
your ~/.ne directory, and you have not already loaded it, then
use the Macro command on the command line followed by the path
to the macro. That’s only necessary the first time you use such a macro.
From then on, you can use the macro’s base name on the command line without
the preceding Macro command.
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, 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 and macro 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 all macros from 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 the way they would have when a macro was
recorded. A good general purpose macro avoids such problems by using the
PushPrefs command first to preserve the current preferences.
The macro then sets any preferences that could affect its behaviour. Once
that is taken care of it can get on with the actual work for which it
were intended. Finally, it will use the PopPrefs command to restore
the original preferences. Note that if a macro stops 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 text and 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.
Leading spaces in macros are ignored, so you can indent your macros to make them more readable. Any line in a macro that starts with a non-blank, 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—and thus avoid wiping out a
document’s existing unnamed macro—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.
Finally, you can insert the current document’s unnamed macro into your
in-progress macro recording as many times as you like either by pressing the
f9 key or entering the Play 1 command. Although the unnamed macro
is distroyed and replaced when you stop recording your new macro, until then
it’s available for use like any other.