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(. This defines a trigger
that will match against pattern,
action)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:
$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”):
$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:
$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:
$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:
$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.
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( 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:
number,
new pattern)$world->trigger(. 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:
number,
new pattern, new
action)$world->trigger(. 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
number, { action
=> new action })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:
$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:
$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):
$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:
$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 → 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.
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:
$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.
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.