## 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

    $world->trigger(2,
                    { 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

    $world->trigger(3,
                    { 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

    $world->distrigger(3)

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

It is also possible to temporarily disable all triggers. Just use the menu Preferences → Disable 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.