11.2. Defining Timers in the Command Line

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

Timers are created with the $world->timer function. It is similar to other functions for adding triggers, aliases and macros, but the hash reference with attributes (the thing inside {}) must always be used.

Let us see an example of defining a timer that sends "who" once a minute:

Example 11.1. A simple timer
$world->timer({ interval => 60,
                action => 'who' })

Note that the interval is specified in seconds.

Our second example will be of a timer that executes a specified number of times:

Example 11.2. A timer that executes only five times
$count = 5;
$world->timer({ interval => 10,
                count => 5,
                action => '/$world->send("chat The count is at $count"); --$count' })

In these two commands, first a variable that will be used in the timer is defined. Then the timer is created, specifying count as 5, so that it is executed only five times. The timer's action is to send commands counting down to one. When the count reaches one, the timer is disabled, because it has already executed five times.

Now let us see a temporary timer:

Example 11.3. A one-shot timer
$world->timer({ interval => 30,
                count => 1,
                temporary => 1,
                action => 'say 30 seconds have elapsed' })

This timer has a count of one, meaning it will only be executed once. Also, temporary is defined as true, which means that after it is executed (which will happen in 30 seconds), the timer will be erased.

Of course, a temporary timer does not need to have a count of one. The countdown timer above could have been made temporary if it was not needed after it reached one.

11.2.1. Editing Timers

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

There are several columns: Num is the number of the timer. Timers are numbered sequentially starting at zero. This number will be useful when we start editing timers. After that, Int is the interval (in seconds) between timer firings. Next comes Count, which is the number of times the timer will still be fired before being disabled or erased. If the value is -1, that means that it will execute indefinitely. Ena tells whether the timer is enabled. enabled. Timers that are disabled are not run. This is a nice way to stop a timer from working, but keep it stored for later use. We will see how to enable and disable timer later in this section. After that, Temp tells whether the timer is temporary or not. Temporary timers were explained in the previous section. In brief, a temporary timer is deleted (and not only disabled) after its count reaches zero. The last column shows the action associated with the timer.

The listing produced by $world->listtimer is compact, showing all timers but possibly truncating the action. If you give a timer number as argument to listtimer, it will display that timer's information detailedly.

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

The generay way to edit a timer is like this: $world->timer(number, { new attributes }), where new attributes is a list of the attributes you want to change. For example, the code below changes the interval of timer number two:

Example 11.4. Changing the interval of a timer
$world->timer(2, { interval => 30 })

As a further example, consider the one below, that edits timer number five to be temporary and to run 10 times:

Example 11.5. Changing the interval of a timer
$world->timer(5, { temporary => 1,
                   count => 10 })

It is possible to enable and disable timers with the syntax above, but there is a shorter way: the $world->distimer function disables the timer whose number is passed as argument, as shown in the example below:

Example 11.6. Disabling a timer, the short way

The corresponding function $world->enatimer enables the specified timer.

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

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

11.2.2. Assigning Names to Timers

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

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

Example 11.7. Creating a timer with a name
$world->timer({ interval => 60,
                action => 'who',
                name => 'who' })

You can now disable this timer with $world->distimer('who'). The name can also be used in the $world->enatimer, $world->deltimer and $world->listtimer functions.

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

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

11.2.3. Reordering Timers

It is possible to move a timer to another position with the $world->movetimer function.

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

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