Base module

Introduction

The two base modules are used to abstract some aspects of module creation.

The class //BasePassiveModule// offers basic functions for core modules. It saves a reference to the Bot class, allows the creation of links in the Bot class to access the module from other modules and handles registration of events like cron, private group joins or parsing specific chat channels.

The class //BaseActiveModule// is a wrapper for the basic functions of all modules which register commands. In addition to the functions offered by //BasePassiveModule// it offers functions for the following aspects

 * Command registrations
 * Defining command aliases
 * Uniform command handling
 * Command parsing
 * Centralize and uniform error handling

All a developer has to do to use these functions is to extend the respective class when creating his module class.

Extending the base module

The class declarations have been changed. The way to extend the base module is by using this code:

$module = new module(&$bot);

class Module extends BaseActiveModule { This will define a child class of //BaseActiveModule// named Module. If no commands are needed the module can use //BasePassiveModule// as parent by simply replacing the name after //extends//.

The constructor

The constructor has also been changed from 'function Module(&$bot)'. The constructor should now look something like this:

function __construct(&$bot) {

 parent::__construct(&$bot, get_class($this));

Notice how the first line calls the parent constructor and passes a reference to the bot along with the name of this class. This MUST be done in order for the base module to be properly initialized.

Afterwards all other needed initialization can be done like before.

Registering commands

Registrations of commands has been moved from //$command['channel']['command']=&$Module;// and should now be registered in the following manner

 $this -> register_command($channel, $command, $access, $subcommands);

This will automagically register the command and set the default access level for it as well as possible subcommands. Calling any access control function directly is no longer neccessary.

The following is an explanation of the parameters:

 * //$channel// is the name of the channel. This can be one of the following: //gc//, //tell//, //pgmsg//, //extpgmsg// or //all//. The pseudo-channel //all// registers commands for the common three channels //gc//, //pgmsg// and //tell// at once.
 * //$command// is the name of the command to register. The name may not contain any spaces.
 * //$access// is an optional parameter defaulting to //OWNER//. With setting this parameter you can define the default access level for the new command. //ANONYMOUS//, //GUEST//, //MEMBER//, //LEADER//, //ADMIN//, //SUPERADMIN// or //OWNER// are accepted as default levels.
 * //$subcommands// is an optional parameter defining default access rights for possible subcommands of //$command//. To define access levels for subcommands a default access level must be defined in the //register_command()// function, though this can be //OWNER// too. The definition of access levels for subcommands are done using an array with the subcommands as keys and the default rights as entries. The following code defines access rights for //!command// only (using the pseudo-variable $) and for //!command sub1// to //GUEST// and //OWNER// respectively, while all other instances of calls require //ADMIN// access rights

$this -> register_command("all", "command", "ADMIN", array("$" => "GUEST", "sub1" => "OWNER"));

For more about access control read the commands entry.

Registering with the Bot core to offer an interface

Modules can register themself with the Bot core using the //register_module($name)// function. This allows other modules to access functions in the registered module with calls to //$this->bot->core($name)->function()//. The old access using direct access to Bot variables is deprecated.

Registering events

Also registering events (non-commands) have been abstracted. Instead of calling //$command['connect'][]=&$Module;// we now use the //register_event($type, $target)// function.

Registerable events are pgjoin, pgleave, connect, disconnect, buddy, privgroup, gmsg*, cron* *, logon_notify and timer* * *

• gmsg takes an additional argument that is the channel to listen to.\\
• * cron takes an additional argument that is the frequency of the cron job.\\
• * * timer takes an additional argument that is the name used to find the correct callback function.

 $this -> register_event('connect');
 $this -> register_event('pgjoin');
 $this -> register_event('gmsg', 'IRRK News Wire');
 $this -> register_event('cron', '1hour');

Defining command aliases

It's possible to define aliases for commands when developing a module, e.g. to cover a shortcut for a command. To simplify parsing and access control in those instances BeBot supports pre-defined command aliases, which will be replaced with the aliased command in the input handler, before any input is handed over to a module. //$command// must be a valid existing command, //$alias// must be a single word. $this -> register_alias($command, $alias);

Creating settings, preferences and help

The creation of settings, preference and help have not been abstracted and should be managed the same way as before.

Handling commands

The base module holds a command parser that will help (you guessed it!) parse the command.

To start with the base module holds an abstract function named 'command_handler'. This method MUST be re-declared in the module like this:

 function command_handler($name, $msg, $origin)
 {
   $this->error->reset(); //Reset the error message so we don't trigger the handler by old error messages.

Then you want to call parse_com with the $msg and a pattern holding the parameters to the command. This is done like this

   $com = $this->parse_com($msg, array('com', 'sub', 'args'));

After this $com will be an array containing the following elements

 * $com['com'] The command (including prefix for now) used to invoke the module
 * $com['sub'] The sub command passed along with the command
 * $com['args'] Any remaining arguments.

Note that you can define your own pattern here. Anything left over after the pattern is filled will be put in the last element of the array. If there are not enough words in $msg to fill the pattern the remaining elements will not be set in the $com array.

You are now ready to switch on either $com['com'] or if only one command invokes this module you can go directly to $com['sub'] and handle sub commands.

Changing the default behaviour of tell(), gc() and pgmsg()

The default behaviour of the base module is to send a reply to the same channel that the command was invoked in unless an error was caused in which case the person invoking the command recieves an error message. This is not always desireable. To avoid this you can re-delcare gc() to do something else. If you want a command invoked in GC to behave exactly as if it was called from a tell you could do: function gc($name, $msg) {

 $this -> tell($name, $msg);

}

Defining event handlers

Event handlers need to be defined as before. For example an event registered with $this -> register_event('connect'); has to be implemented with code looking something like this: function connect() {

 $this -> start = time() + $this -> bot -> crondelay;

}