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