8.6. Defining Triggers in the Command Line

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

Triggers are defined with the $world->trigger function. There are many ways to use this function, and we will start describing them here.

The simples way to use that function is with two arguments: $world->trigger(pattern, action). This defines a trigger that will match against pattern and execute action when a match happens.

Here's how to define the trigger in Example 8.1, “A very simple trigger” in the command line:

Example 8.10. A very simple trigger defined in the command line
$world->trigger('has attacked you!', 'wield sword')

To specify other trigger features an extra argument is passed to the trigger function. For those that know Perl, it is a reference to a hash, and this hash can contain some attributes specifying the trigger's behaviour. For those that do not understand the previous sentence, do not worry, the examples should make the usage clear.

Let's re-create a simple gag to omit all that is said by Joe (see Example 8.5, “A simple gag”):

Example 8.11. A simple gag (in the command line)
$world->trigger('^Joe chats',
                '/$world->echonl("Joe said something silly here.")',
                { gag => 1 })

See the difference? There is a third parameter, enclosed in curly braces {}, with the word gag, an arrow, and the number 1. What that means is that gag has the value 1, or, as usual in computer languages, is true. (False would be zero.)

Often gags do not have any action:

Example 8.12. A gag with no action (in the command line)
$world->trigger('^Joe chats',
                { gag => 1 })

The action has simply been omitted, but the argument that specifies that we are dealing with a gag remains, naturally. As a matter of fact, this kind of gag (with no action) is quite common, and there is a shorter way to do that. The command below has the exact same effect as the previous one:

Example 8.13. A shortcut function to define gags
$world->gag('^Joe chats')

The gag attribute only controls whether the line is displayed in the screen or not. If you have logging enabled (see Chapter 14, Logging the Output), a the line that matched a trigger with the gag attribute will be written in the log file normally. If you want the line to be omitted from the log file, you must set also the gaglog attribute. If it is set, then the line will not be written to the log file. Note that the two attributes are independent: you can gag the line from the screen, from the log file, from both or from neither.

To make case be ignored when matching, use a very similar construct as the above, but using the ignorecase attribute:

Example 8.14. A case-insensitive trigger
$world->trigger('^.* chats ".*joe.*"', '/callAttention()',
                { ignorecase => 1})

Another attribute that can be set for triggers is keepexecuting, corresponding to the Keep executing triggers after this one matches option (see Section 8.5, “Other trigger features”). This flag is specified just like gag. Just add the parameter { keepexecuting => 1 } to the function call. It is possible for a trigger to be both a gag and have the keepexecuting flag. In this case, include both in the last argument: { gag => 1, keepexecuting => 1 }. Note it is just one argument, with both flags separated by a comma. The order does not matter, keepexecuting could have come before gag.

Similarly, rewriter triggers (see Section 8.5.1, “Rewriter Triggers”) are created with the rewriter flag.

8.6.1. Editing Triggers

In the previous sections it was shown how to add triggers, but nothing was told about how to change them after they are defined. This and other points will be addressed in this section.

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

There are several columns: Num is the number of the trigger. Triggers are numbered sequentially starting at zero. This number will be useful when we start editing triggers. Next comes gag, which tells whether the trigger is a gag (for the screen). Next is GLo, which means "Gag from Log", and shows whether the line is omitted (that is, not written) in the log file also (if logging is enabled, of course). After that, Ena tells whether the trigger is enabled. Triggers that are disabled are not matched. This is a nice way to stop a trigger, but keep it stored for later use. We will see how to enable and disable triggers later in this section. Next there is KeE, which reports the status of the keepexecuting flag for the trigger. After that, IgC specifies the case is being ignored. The final two columns list the pattern and action of the trigger.

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

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

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

Naturally, it is possible to attributes such as gag or keepexecuting. The syntax is the same, include the new value inside the curly braces. To clear one of those flags, use the value 0, which means false. The example below makes trigger number 2 stop being a gag, and at the same time sets it not to prevent matching of other triggers:

Example 8.15. Changing several attributes at once
                { gag => 0,
                  keepexecuting => 1 })

It is also possible, naturally, to change attributes such as pattern or action at the same time that gag or keepexecuting are changed. All these attributes are equal, the only difference is that since the pattern and action are used much more often, there is a shorter way of specifying them. But even when you create a trigger you can use this extended syntax. Example 8.10, “A very simple trigger defined in the command line” could be also entered this way, with the exact same results:

Example 8.16. A very simple trigger, in another way
$world->trigger({ pattern => 'has attacked you!',
                  action => 'wield sword'})

The final attribute for triggers is enabled. It was mentioned briefly when we described how to list triggers. It can be set just like the other attributes, and like keepexecuting or gag it 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 trigger is matched normally. When it is zero, received lines are not matched against it. This way, disabling a trigger effectively turns if off, as if it did not exist, but the trigger is still saved, and can be turned on again when necessary.

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

Example 8.17. Disabling a trigger, the long way
                { enabled => 0 })

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

Example 8.18. Disabling a trigger, the short way

The corresponding function $world->enatrigger enables the specified trigger.

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

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

8.6.2. Assigning Names to Triggers

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

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

Example 8.19. Creating a trigger with a name
$world->trigger('has attacked you!', 'wield sword',
                { name => 'attack' })

You can now disable this trigger with $world->distrigger('attack'). The name can also be used in the $world->enatrigger, $world->deltrigger and $world->listtrigger functions.

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

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

8.6.3. Reordering Triggers

Triggers are tried from the first to the last, so in some cases the order of the triggers matters. It is possible to move a trigger to another position with the $world->movetrigger function.

The function takes two parameters: the first is the name or number of the trigger that you want to move. The second is the new position that the trigger 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 triggers, the trigger will be moved to the end of the list.

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