Here is a simple but complete plugin. It will be used to illustrate many things about plugins.
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.