10.2. Defining Macros in the Command Line

For those more used to Perl and to command lines, it is also possible to define and alter macros from the command line. This is done with a series of Perl function.

Macros are set defining, as mentioned above, a key and an action. The key is key keycode for the key you wish to assign the macro to. The easiest way to get the keycode for a given key is with the $world->getkeycode function. This function takes no parameters. When run, it prompts you to press a key, and then prints the keycode for the key. It also returns the keycode as a string, so you can save it in a variable and use when defining the macro.

Here's a way to define a macro:

Example 10.1. Defining a macro
/$key = $world->getkeycode
Press a key to get its keycode.
Press the F5 key
Key code: F5
/$world->macro($key, 'drink from fountain')

The above session shows how to assign drink from fountain to the F5 key. Note that $world->getkeycode prompts you for a key and prints its keycode. Additionally, the keycode is returned, and it is stored in the $key variable. This variable is used as the first argument to the $world->macro function, that takes two arguments: the keycode and the action. We could have entered 'F5' directly, but using the keycode returned by $world->getkeycode is easier and less error-prone.

That's pretty much all about defining macros. They do not take arguments, it is all about executing simple commands. Other things that could be done are executing several commands (separating them with %;) or executing a Perl statement or function.

10.2.1. Editing Macros

Before going into editing, let us see how to get a list of all macros that are currently defined for the World. Just use the $world->listmacro function without arguments. You will be presented with a list of the currently defined macros.

There are four columns: Num is the number of the macro. Macros are numbered sequentially starting at zero. This number will be useful when we start editing them. After that, Ena tells whether the macro is enabled. Macros that are disabled are not executed even if the key is pressed. This is a nice way to stop a macro from working, but keep it stored for later use. We will see how to enable and disable macros later in this section. The final two columns list the keycode and action of the alias.

The listing produced by $world->listmacro is compact, showing all macros but possibly truncating the keycode and/or action. If you give a macro number as argument to listmacro, it will display that macro's information detailedly.

To edit a macro, you need to know that macro's number. (And that can be discovered with the listing functions just described. Alternatively, the $world->getmacronumber can be used to discover a macro's number if its name is known.) The same function used to add macros can also change existing ones, you just need to pass the macro number as the first argument.

Calling $world->macro(number, new keycode) changes the key of the macro with that number. If you want to change the key and action, include the substitution as a third argument: $world->macro(number, new key, new action). What if you want to change only the action? Since passing only one string argument would change the key, this is done in a different way. In brief, this is how you would change only the key: $world->macro(number, { action => new action }). Notice that the key is passed as an attribute inside the curly braces. It is also possible to change the key this way, just use the attribute key.

The only attribute for macros, besides the key and action, is enabled. It was mentioned briefly when we described how to list macros. It can be set just like the other attributes and is binary, that is, takes the values true (represented by anything different from 0) or false (represented by 0). When the value of this attribute is true (which is the default), the macro is run normally. When it is zero, even if the key is pressed, the macros is not run. This way, disabling an alias effectively turns if off, as if it did not exist, but the macro is still saved, and can be turned on again when necessary.

Here's an example of disabling a macro (number 3 in this case):

Example 10.2. Disabling a macro, the long way
              { enabled => 0 })

However, there is a shorter way: the $world->dismacro function disables the meacro whose number is passed as argument. So the example above can be rewritten in a shorter way as:

Example 10.3. Disabling a macro, the short way

The corresponding function $world->enamacro enables the specified macro.

It is also possible to temporarily disable all macros. Just use the menu PreferencesDisable Macros and this will prevent macros from running. This does not change the "enabled" status of any macros, it just prevents all macros from running. When you select the menu again, macros that were enabled will run again, and those that were disabled will remain disabled.

There are times when you want to delete a macro. This is easy to do, use the $world->delmacro function. It takes as argument the number of the macro you wish to delete. Be aware that once deleted it is not possible to recover the macro (unless you create it again). Many times just disabling the macro is a better idea. The second thing to note is that when you delete a macro the numbers of the other macros may change, so be careful when you try to delete several macros in sequence.

10.2.2. Assigning Names to Macros

It is possible to assign names to macros. When a macro has a name, you can enable, disable, or delete it using its name instead of its number.

To assign a name to a macro, specify the name attribute when creating it:

Example 10.4. Creating a macro with a name
$world->macro($key, 'drink from fountain',
              { name => 'drink' })

You can now disable this macro with $world->dismacro('drink'). The name can also be used in the $world->enamacro, $world->delmacro and $world->listmacro functions.

It is also possible to assign a name to an existing macro. Just edit it as described in Section 10.2.1, “Editing Macros”, passing the name attribute. Use this same process to change the name of a macro.

Another feature of macro names is that several macros can have the same name. In this case, all these macros will be treated as a single group. The functions above, when passed a macro name, will act upon all macros of the group, that is, on all macros with that name.

10.2.3. Reordering Macros

Macros are tried from the first to the last, so in some cases the order of the macros matters. It is possible to move an macro to another position with the $world->movemacro function.

The function takes two parameters: the first is the name or number of the macro that you want to move. The second is the new position that the macro will take in the list. 0 means move the the first position. If you specify a negative number or a number greater than the number of macros, the macro will be moved to the end of the list.

If there are several macros with the same name, only the first one found will be moved. And when an macro is moved, other macros might move up or down to accomodate the change.