E.2. A Sample Plugin
Prev Appendix E. Writing Plugins Next

E.2. A Sample Plugin

Here is a simple but complete plugin. It will be used to illustrate many things about plugins.

Example E.1. A Sample Plugin
package sample;
#: Version: 1.0
#: Description: A Sample Plugin
#: Author: Eduardo M Kalinowski

$::world->trigger('First', 'of the plugin', { name => 'sample:misc' });
$::world->trigger('Second', 'of the plugin', { name => 'sample:misc' });

$::world->timer({ interval => 5, action => 'sample plugin',
                  name => 'sample:misc' });

$::world->macro('F8', '/sample::stop',  { name => 'sample:enadis' });
$::world->macro('F9', '/sample::start', { name => 'sample:enadis' });


sub testplugin {
  $::world->echonl("The plugin works.");
}

sub stop {
  $::world->distimer('sample:misc');
}

sub start {
  $::world->enatimer('sample:misc');
}

sub help {
  $::world->echonl("This is a sample plugin, that does nothing useful.");
  $::world->echonl("It outputs a short string every now and them. This");
  $::world->echonl("behaviour can be stopped by pressing the F8 key, and");
  $::world->echonl("re-enabled with the F9 key.");
  $::world->echonl("One function is defined: sample::testplugin. It");
  $::world->echonl("outputs something to show that the plugin is working.");
}

The first thing in the file is the header, in the format described above. then comes trigger, timer, and macro definitions. All definitions of triggers, aliases, macros, timers, hook and permanent variables, if any, should be in the top-level scope (which means they will be executed when the plugin is loaded). (Alternatively, you could put them in a BEGIN block, which would have the same result, but there isn't a reason for that.) You should not create any of those objects in any function.

It should be noted that the $world variable is refereed as $::world. It is just because we are inside a package, and $world does not belong to this package. Otherwise, the calls are equal.

After that, some functions are defined. testplugin is meant to be called by the user. stop and start are used by the macros (but they could also be called by the user). Finally, a help is defined, that outputs some information about the plugin. All plugins should define a help describing themselves.