Extending Megasus
=================

Extending Megasus is rather simple. Megasus uses Module::Pluggable to
allow Plugins, there are two different kinds of plugins, the first are
Command Plugins and the others are Brain Plugins.

Command Plugins
===============

If you wan't to extend Megasus' abilities, this might be the place to
look. Command Plugins have to be under Megasus/Plugin. A template to
create a new plugin can be found in this direcory and is called
Plugin.temp. Don't forget to complete the 'package' line in the
beginning of the file.

The important part of a new plugin is:

    if ($msg->text =~ //) {

    }    

You have to change the regex to match you actual command. For example,
if you want your new command to be 'foo', you have to change write it
as follows:

    if ($msg->text =~ /^foo$/) {

    }    


Command Plugins have to return Megasus::Answer objects. The code is
the documentation, but the usage is rather simple:

    if ($msg->text =~ /^foo$/) {
	return Megasus::Answer( 'bar', $msg );
    }    

You have to call it with the $msg object because it has to know how
the message was send in order ot answer over the same channel
(i.e. message or direct addressed).

There are three answer shortcuts:
	Megasus::Answer::OK( $msg ); # a positive reply
	Megasus::Answer::FAILED( $msg ); # a negative reply
	Megasus::Answer::NOTRUST( $msg );# the talking person is not trusted
	
There are four ways to address megasus and you can access this
information in the message object via $msg->type():

	'direct': a line prefixed with megasus: 
	'other' : a line prefixed with 'somethin:'(not talking to the bot)
	'msg'   : beeing msgd
	'channel': none of the above

If you want your command to only work if megasus is directly addressed
(i.e. a $msg->type of 'direct' or 'msg') you can use the
$msg->is_direct shortcut:

    return unless $msg->is_direct();

    if ($msg->text =~ /^foo$/) {
	return Megasus::Answer( 'bar', $msg );
    }    

In case you need access to the Brain Object, it is accessible via 
$self->brain().
	
There are 37 examples in the Megasus/Plugin directory, beginning with
quite easy ones (Version.pm or Author.pm) over more complex ones
(Amazon.pm or Google.pm) to really complex core plugins (Factlet.pm or
Karma.pm). Have a look at them.

Command Plugins are automatically loaded during startup.

If you want't to use your custom options, use the following methods
	$brain->add_option('option_name', 'initial_value') in your 
constructor.
To get the value of an option use $brain->get_option('option_name') to
access the value again. The options will be automatically accessible
via the "config" command. See Megasus::Plugin::Shorten for details.

Brain Plugins
=============

Brain Plugins are located in the Megasus/Brain/Plugin/ directory. They
are basically data structures used by Command Plugins to store stuff
or do stuff, like the Factlet, Karma or Watch Command Plugins. 

There is no template, but have a look at Megasus/Brain/Plugin.pm which
is the base class for Brain Plugins. Basically, your plugin has to
specify it's name ($self->{name}) which defaults to the actual name of
the plugin and wheather or not it should be saved ($self->{save})
which defaults to true.

Brain Plugins are automatically loaded during startup and added to the
brain object. Have a look at the files in the Brain Plugin directory
to get an idea of what is happening.