=pod
=head1 NAME
Bot::Cobalt::Manual::Plugins - Bot::Cobalt plugin authoring reference
=head1 DESCRIPTION
This POD attempts to be a reasonably complete guide to writing
L<Bot::Cobalt> plugins.
For a quick-start guide, try L<Bot::Cobalt::Manual::Plugins::Tutorial>.
Refer to L</SEE ALSO> for other relevant documentation, such as instructions
on packaging up your plugin for installation.
Plugin authors likely want to at least read the L<Bot::Cobalt::IRC> POD.
=head1 PLUGIN FUNDAMENTALS
=head2 A basic plugin outline
package Bot::Cobalt::Plugin::User::MyPlugin;
our $VERSION = '0.001';
use strict;
use warnings;
## Import some helpful sugar:
use Bot::Cobalt;
## Import useful constants and utilities:
use Bot::Cobalt::Common;
## Minimalist object constructor:
sub new { bless {}, shift }
## Called when we are loaded:
sub Cobalt_register {
## Handlers receive $self and $core as first two args:
## $self is "this object"
## $core gives us access to core attributes and methods
## (Since we have Bot::Cobalt, core() is the same thing.)
my ($self, $core) = splice @_, 0, 2;
## Register to only receive public msg events
## (We could also register for a list or 'all')
## Uses register() sugar from Bot::Cobalt
register( $self, 'SERVER',
'public_msg'
);
## Log that we're here now:
logger->info("Registered");
## Always return an Object::Pluggable::Constants value from an
## event handler.
##
## (Importing Bot::Cobalt::Common will pull _NONE and _ALL in)
## See "Returning proper values" under "Handling events"
##
## PLUGIN_EAT_NONE is the most common:
return PLUGIN_EAT_NONE
}
## Called when we are unloaded:
sub Cobalt_unregister {
my ($self, $core) = splice @_, 0, 2;
. . . do some clean up, perhaps . . .
logger->info("Unregistering; bye!");
return PLUGIN_EAT_NONE
}
## Syndicated events become prefixed with 'Bot_' when dispatched
sub Bot_public_msg {
my ($self, $core) = splice @_, 0, 2;
## Receives a Bot::Cobalt::IRC::Message::Public object:
my $msg = ${ $_[0] };
my $context = $msg->context;
my $as_array = $msg->message_array;
. . . do something with message @$as_array . . .
return PLUGIN_EAT_NONE
}
1; ## perl modules end in '1'
=head2 Module paths and configuration
=head3 plugins.conf
C<plugins.conf> is YAML in the following structure:
---
MyPlugin:
Module: Bot::Cobalt::Plugin::User::MyPlugin
Config: plugins/mine/myplugin.conf
## Enable to skip runtime auto-loading:
#NoAutoLoad: 1
## Optional, overrides Config: file:
Opts:
Level: 2
Configuration files specified in 'Config: ' are expected to be valid
B<YAML1.0>. You can read more about YAML at L<http://www.yaml.org> --
for the most part, the basics are fairly self-explanatory.
See L<Bot::Cobalt::Manual::Plugins::Config> for more about simple YAML
syntax for plugin configuration files.
=head3 Accessing plugin configuration
The normal way to access a plugin's configuration structure is via the
core method B<get_plugin_cfg> (or
L<Bot::Cobalt::Core::Sugar/plugin_cfg>):
## Our $self object or our alias must be specified:
my $plug_cf = core()->get_plugin_cfg( $self );
## ... or with Bot::Cobalt sugar:
use Bot::Cobalt;
my $plug_cf = plugin_cfg($self);
See also: L</"Core methods">
These accessors will return the B<opts> hash from the plugin's
configuration object. The per-plugin configuration object itself is a
L<Bot::Cobalt::Conf::File::PerPlugin> and can be accessed via the core's
L<Bot::Cobalt::Conf::File::Plugins> instance:
my $plug_alias = core()->get_plugin_alias( $self );
my $plug_cf_obj = core()->cfg->plugins->plugin( $plug_alias );
my $module = $plug_cf_obj->module;
my $opts = $plug_cf_obj->opts;
## Same as:
my $opts = plugin_cfg( $self );
See the documentation for L<Bot::Cobalt::Conf::File::PerPlugin> for more
details.
=head2 Handling events
Plugins are event driven.
A plugin will (usually at load-time) register to receive some set of
events, which are pushed through the plugin pipeline by the Cobalt core
(with help from L<POE::Component::Syndicator> and L<Object::Pluggable>).
Pipeline priority is initially chosen via B<Priority:>
directives in C<plugins.conf>; however, online plugin loads/unloads
can alter the pipeline order. If your plugin needs to have a
certain priority in the pipeline, you are likely
going to want to spend some quality time reading the L<Object::Pluggable>
and especially L<Object::Pluggable::Pipeline> documentation. The methods
described regarding pipeline manipulation are available via C<core()>.
=head3 Registering for events
Registering for events typically happens at plugin load-time; in other
words, inside C<Cobalt_register>:
my ($self, $core) = @_;
## Using Bot::Cobalt sugar:
register( $self, 'SERVER',
'chan_sync',
'public_msg',
);
## Same thing without sugar:
$core->plugin_register( $self, 'SERVER',
'chan_sync',
'public_msg',
);
=head3 Event handlers
Events from IRC and internal events are classified as 'SERVER' events.
Syndicated SERVER event handlers are prefixed with 'Bot_':
sub Bot_some_event {
my ($self, $core) = splice @_, 0, 2;
my $deref_first_arg = ${ $_[0] };
. . .
}
The arguments passed to event handlers are always references.
(Sometimes, they're references to references, such as a hashref.
If you don't know what that means, it's time to stop here and read
L<perlreftut> & L<perlref>)
=head3 Sending events
Events can be broadcast to the plugin pipeline via either the Core
method B<send_event>:
$core->send_event( $event, @args );
... or via exported sugar from L<Bot::Cobalt::Core::Sugar>
(B<broadcast>):
use Bot::Cobalt;
broadcast $event, @args;
=head3 Returning proper values
The plugin system is a pipeline, usually beginning with
the L<Bot::Cobalt::IRC> plugin. Events will be handed on down the
pipeline, B<unless> a handler for a syndicated event returns a
B<PLUGIN_EAT_ALL> or B<PLUGIN_EAT_PLUGIN> value.
Your Bot_* event handlers should return an
L<Object::Pluggable::Constants> value. The two commonly used values are:
=head4 PLUGIN_EAT_NONE
Allow the event to continue to pass through the pipeline.
This is the most common return value for event handlers
=head4 PLUGIN_EAT_ALL
Eat the event, removing it from the plugin pipeline.
Typically you might return PLUGIN_EAT_ALL on self-syndicated events
(that is to say, events the plugin intends for itself to handle,
such as a L<Bot::Cobalt::Plugin::WWW> response, timed event, event-aware
loop as described in L</"ADVANCED CONCEPTS">, etc).
This can also be useful when there is a good reason to terminate an
event's lifetime; for example, implementing a plugin that loads itself
at the front of the pipeline and restricts outgoing events based on
some criteria.
=head1 USING IRC
=head2 Receiving IRC events
See L<Bot::Cobalt::IRC> for a complete list of IRC events and their
event syntax.
=head3 Understanding server context
IRC-driven events come with a 'server context' attached, mapping
the server's configured "name" to server state information and allowing a
plugin to make sure responses get to the right place.
For example, when receiving a public message:
sub Bot_public_msg {
my ($self, $core) = splice @_, 0, 2;
## Get this message's server context
my $msg = ${ $_[0] };
my $context = $msg->context;
## ... later, when sending a response ...
my $channel = $msg->channel;
broadcast(
'message', ## send_event 'message'
$context, ## make sure it goes to the right server
$channel, ## destination channel on specified context
$response, ## some response string
);
}
IRC-related events always come from or are sent to a specific context.
Each context also has a L<Bot::Cobalt::IRC::Server> object; it
can be used to retrieve context-specific metadata such as connected
status and the named server's announced casemapping.
See L</get_irc_server>.
=head3 Messages
The most common use-case for an IRC bot is, of course, responding to
messages.
Incoming messages are handled by B<Bot_public_msg> and B<Bot_private_msg>
plugin event handlers. (If they are prefixed by our CmdChar, they'll
I<also> trigger a Bot_public_cmd_ event -- see L</"Commands">, below).
A _msg event is passed a context and a L<Bot::Cobalt::IRC::Message> object:
sub Bot_public_msg {
my ($self, $core) = splice @_, 0, 2;
my $msg = ${ $_[0] };
my $context = $msg->context;
my $channel = $msg->channel;
my $src_nick = $msg->src_nick;
. . .
return PLUGIN_EAT_NONE
}
See L<Bot::Cobalt::IRC::Event>, L<Bot::Cobalt::IRC::Message> and
L<Bot::Cobalt::IRC::Message::Public> for the complete
documentation regarding message object methods. The most
commonly-used message methods are:
=head4 target
The (first-seen) destination of the message.
=head4 channel
If a message appears to have been delivered to a channel, the B<channel>
method will return the same value as B<target> -- otherwise it will
return an empty string.
=head4 src_nick
The nickname of the sender.
=head4 src_user
The username of the sender.
=head4 src_host
The hostname of the sender.
=head4 message
The original, unparsed message text.
=head4 stripped
The color/formatting-stripped message text.
=head4 message_array
The content of the message as an array, split on white space.
=head4 message_array_sp
Similar to B<message_array>, except spaces are preserved, including
leading spaces.
Note that a '/ME' is a CTCP ACTION and not handled by _msg handlers.
For that, you'll need to catch B<Bot_ctcp_action>, which carries
essentially the same syntax.
Additionally, a '/NOTICE' is not a _msg. B<Bot_got_notice> also carries
the same syntax.
B<< See L<Bot::Cobalt::IRC> for more details. >>
=head3 Commands
A L<Bot::Cobalt> instance has a B<CmdChar>, usually defined in
I<etc/cobalt.conf>.
When any user issues a command prefixed with the bot's CmdChar, the event
B<public_cmd_$CMD> is broadcast in place of a B<public_msg> event.
<JoeUser> !shorten http://www.cobaltirc.org/dev/bots
## -> event 'Bot_public_cmd_shorten'
The command is automatically lowercased before being transformed into an event.
A plugin can register to receive commands in this format:
## in Cobalt_register, usually:
register( $self, 'SERVER',
## register to receive the 'shorten' command:
'public_cmd_shorten',
);
## handler for same:
sub Bot_public_cmd_shorten {
my ($self, $core) = splice @_, 0, 2;
my $msg = ${ $_[0] };
## since this is a command, our message_array is shifted
## the command will be stripped
my $args = $msg->message_array;
. . .
## if this command is "ours" we might want to eat it:
return PLUGIN_EAT_ALL
}
It's important to note that B<< $msg->message_array >> is shifted leftwards
in B<public_cmd_> handlers; it won't contain the CmdChar-prefixed
command. B<< $msg->message_array_sp >> remains unchanged, as do the
B<message> and B<stripped> strings.
=head3 Other events
Most of the typical instances of "stuff going on" on IRC are
reported by the core IRC module.
The documentation for all events parsed and re-broadcast from IRC
is available via the L<Bot::Cobalt::IRC> POD.
=head2 Sending IRC events
L<Bot::Cobalt::IRC> receives the following commonly-used events:
=head3 Sending messages
=head4 message
The B<message> event triggers an IRC PRIVMSG to either a channel
or user.
The arguments specify the server context, target (user or channel), and
string, respectively:
broadcast( 'message',
$context, $target, $string
);
The message will be sent after being processed by any B<Outgoing_message>
handlers in the pipeline. See L<Bot::Cobalt::IRC> for more about Outgoing_*
handlers.
=head4 notice
B<notice> operates essentially the same as L</message>, except
a NOTICE is sent (rather than PRIVMSG).
Event arguments are the same.
=head4 action
B<action> sends a CTCP ACTION rather than a normal PRIVMSG or
NOTICE string.
Event arguments are the same as L</message> and L</notice>.
=head3 Channel-related commands
The following common IRC commands are handled.
Like any other interaction, they are sent as events:
## (attempt to) join a channel on $context:
broadcast( 'join', $context, $channel );
=over
=item *
B<join>
=item *
B<part>
=item *
B<mode>
=item *
B<kick>
=item *
B<topic>
=back
See L<Bot::Cobalt::IRC> for event argument syntax and details.
=head3 Accessing the IRC component directly
The IRC backend for the core distribution is L<POE::Component::IRC>,
more specifically the L<POE::Component::IRC::State> subclass.
L<POE::Component::IRC> is a very mature and complete IRC framework.
If your plugin does any kind of IRC-related heavy lifting, you will
almost certainly want to consult the documentation for
L<POE::Component::IRC> and L<POE::Component::IRC::State>.
=head4 Obtaining the IRC component
You can retrieve the IRC component object for direct access via the
core's get_irc_obj method. Expects a server context:
sub Bot_public_msg {
my ($self, $core) = @_;
my $msg = ${$_[0]};
my $context = $msg->context;
my $irc = $core->get_irc_obj($context);
. . .
}
See L<POE::Component::IRC> and L<POE::Component::IRC::State> for
details on using the IRC Component object directly.
=head1 USING THE CORE
=head2 Core methods
The Cobalt core provides various convenience accessors and methods for
plugins.
The object reference to the Cobalt core object is referred to here
as C<$core>.
L<Bot::Cobalt::Core> is actually an instanced singleton; it can be retrieved
from any loaded plugin via B<instance>:
require Bot::Cobalt::Core;
my $core = Bot::Cobalt::Core->instance;
... or 'use Bot::Cobalt' and thereby import the
L<Bot::Cobalt::Core::Sugar> wrappers:
use Bot::Cobalt;
my $irc_obj = core()->get_irc_object($context);
See the documentation for L<Bot::Cobalt::Core::Sugar> for the complete
list of exported wrappers.
=head3 Attributes
=head4 Provided
The B<Provided> hash allows plugins to declare that some functionality
or event provided by the plugin is available (for example, the
B<< $core->Provided->{www_request} >> element is boolean true if
L<Bot::Cobalt::Plugin::WWW> is registered).
This is useful when your plugin provides some event interface usable
by other plugins, or when the presence of this plugin may alter
another plugin's behavior.
A plugin should declare its Provided functionality at register-time:
sub Cobalt_register {
my ($self, $core) = splice @_, 0, 2;
## ... register for events, etc ...
## declare that 'tasty_snacks' functionality is available
## this example does nothing if it's already defined (//):
$core->Provided->{tasty_snacks} //= 1;
return PLUGIN_EAT_NONE
}
The core has no way of automatically knowing that this functionality
disappears when your plugin does. You should delete the Provided element
in your _unregister:
sub Cobalt_unregister {
my ($self, $core) = splice @_, 0, 2;
delete $core->Provided->{tasty_snacks};
$core->log->info("Bye!");
return PLUGIN_EAT_NONE
}
Some plugins use this to share simple bits of state information in
addition to their advisory nature; for example, L<Bot::Cobalt::Plugin::RDB>
shares the number of items in the 'main' RDB via the integer value of
B<< $core->Provided->{randstuff_items} >>.
Therefore, when attempting to determine whether a specific piece of
functionality is available, it may be advisable to check for 'defined'
status instead of boolean value:
if ( defined $core->Provided->{randstuff_items} ) {
## we have RDB.pm
}
Since plugin load order is generally not guaranteed and plugins may
be dynamically (un)loaded, it is good practice to only check for
B<Provided> functionality in the narrowest possible scope; that is to
say, directly prior to execution of the dependent code, rather than at
plugin register-time.
=head4 Servers
B<< $core->Servers >> is a hashref keyed on server "context" name; see
L</"Understanding server context">.
You should probably be using L</get_irc_server>.
## Iterate all contexts:
for my $context ( keys %{ $core->Servers } ) {
. . .
}
The values are L<Bot::Cobalt::IRC::Server> objects.
=head4 var
Returns the path to the current VAR dir, typically used for log files,
databases, or other potentially dynamic data.
Plugins should typically dump serialized data and place databases in a
path under C<< $core->var >>.
=head4 version
Returns the current L<Bot::Cobalt::Core> version.
=head4 detached
Returns a boolean value indicating whether or not this Cobalt instance
is attached to a terminal or daemonized.
=head3 Configuration-related methods
=head4 get_channels_cfg
Retrieves per-context channel configuration from C<channels.conf>:
my $chan_cf = $core->get_channels_cfg( $context );
The server context must be specified.
Returns an empty hash if there is no channel configuration for this
server context.
=head4 get_core_cfg
Retrieves the 'core' configuration object
(L<Bot::Cobalt::Conf::File::Core>), representing the "cobalt.conf"
configuration values:
my $core_cf = $core->get_core_cfg();
my $lang = $core_cf->language;
See L<Bot::Cobalt::Conf::File::Core> for more details.
=head4 get_plugin_cfg
Retrieves the configuration hash for a specific plugin:
my $plug_cf = $core->get_plugin_cfg( $self ) || {};
Either the plugin's $self object or its current alias must be
specified.
$core->log->warn("Missing config!")
unless $core->get_plugin_cfg($self);
If you 'use Bot::Cobalt' you can make use of the exported B<plugin_cfg>
wrapper (see L<Bot::Cobalt::Core::Sugar>):
logger->warn("Missing config!")
unless plugin_cfg($self);
=head4 get_plugin_alias
Retrieve a plugin object's alias
Your plugin's $self object can be specified to get the current plugin
alias, for example:
my $plugin_alias = $core->get_plugin_alias($self);
A wrapper is provided if you use 'Bot::Cobalt' (see
L<Bot::Cobalt::Core::Sugar>):
my $plugin_alias = plugin_alias($self);
=head3 IRC-related methods
=head4 get_irc_casemap
Retrieves the CASEMAPPING rules for the specified server context,
which should be one of I<rfc1459>, I<strict-rfc1459>, I<ascii> :
my $casemapping = $core->get_irc_casemap( $context );
The server's casemapping is usually declared in ISUPPORT (numeric
005) upon connect and can be used to establish whether or not the
character sets {}|^ are equivalent to []\~ -- see L</"IRC CAVEATS">
below for more information.
This can be used to feed the C<lc_irc/uc_irc/eq_irc> functions from
L<IRC::Utils> (or L<Bot::Cobalt::Common> and determine issues like
nickname equivalency:
use Bot::Cobalt::Common;
my $casemapping = $core->get_irc_casemap( $context );
my $irc_lower = lc_irc($nickname, $casemapping);
my $is_eqal = eq_irc($old, $new, $casemapping);
=head4 get_irc_obj
my $irc = $core->get_irc_obj( $context );
Retrieve the L<POE::Component::IRC> object for a specified context, which
is likely to actually be a L<POE::Component::IRC::State> instance.
This can be used to query or post events to the IRC component directly.
See the L<POE::Component::IRC> and L<POE::Component::IRC::State> docs for
more on interacting directly with the IRC component.
=head4 get_irc_server
my $server_state = $core->get_irc_server( $context );
Can also be called via B<get_irc_context>.
Retrieves the appropriate L<Bot::Cobalt::IRC::Server> object from
B<<$core->Servers>>.
A server context must be specified.
See L<Bot::Cobalt::IRC::Server> for details on methods that can be called
against server context objects.
=head3 Auth-related methods
The Core provides access to a L<Bot::Cobalt::Core::ContextMeta::Auth>
object; methods can be called to determine user authorization levels.
These are the most commonly used methods; see
L<Bot::Cobalt::Core::ContextMeta> and
L<Bot::Cobalt::Core::ContextMeta::Auth> for more.
=head4 level
Retrieves the user's authorized level (or '0' for unauthorized users).
Requires a context and a nickname:
## inside a msg or command handler, f.ex:
my ($self, $core) = splice @_, 0, 2;
my $msg = ${ $_[0] };
my $context = $msg->context;
my $nick = $msg->src_nick;
my $level = $core->auth->level($context, $nick);
Auth levels are fairly flexible; it is generally a good idea for your
plugin to provide some method of configuring required access levels,
either via a configuration file or a B<Opts> directive in
C<plugins.conf>.
=head4 username
Retrieves the "username" for an authorized user (or empty list if the user
is not currently authorized).
Requires a context and a nickname, similar to L</level>:
my $username = core()->auth->username($context, $nick);
unless ($username) {
## this user isn't authorized
}
=head3 Logging
The Cobalt core provides a B<log> method that writes to the LogFile
specified in cobalt.conf (and possibly STDOUT, if running with --nodetach).
This is actually a L<Bot::Cobalt::Logger> instance, so all methods found
there
apply. Typically, plugins should log to B<info>, B<warn>, or B<debug>:
core()->log->info("An informational message");
core()->log->warn("Some error occured");
core()->log->debug("some verbose debug output for --debug");
A plugin should at least log to B<info> when it is registered or
unregistered; that is to say, inside B<Cobalt_register> and
B<Cobalt_unregister> handlers.
=head3 Timers
Core timers live in B<< core()->TimerPool >>; if need be, you can
access the timer pool directly. It is a hash keyed on timer ID.
Timer methods are provided by the L<Bot::Cobalt::Core::Role::Timers> role.
Each individual timer is a L<Bot::Cobalt::Timer> object; if you plan to
manipulate a created timer, you'll likely want to consult that POD.
Typically most plugins will only need the following functionality; this
only covers the hash-based interface to
L<Bot::Cobalt::Core::Role::Timers/timer_set>, so review the aforementioned
documentation if you'd like to use the object interface instead.
=head4 timer_set
Set up a new timer for an event or message.
## Object interface:
core()->timer_set( $timer_object );
## Hash interface:
core()->timer_set( $delay, $ev_hash );
core()->timer_set( $delay, $ev_hash, $id );
Returns the timer ID on success, boolean false on failure.
Expects at least a delay (in seconds) and a hashref specifying what to
do when the delay has elapsed.
## New 60 second 'msg' timer with a random unique ID:
## Send $string to $channel on $context
## (A triggered 'msg' timer broadcasts a 'message' event)
my $id = $core->timer_set( 60,
{
## The type of timer; 'msg', 'action' or 'event':
Type => 'msg',
## This is a 'msg' timer; we need to know what to send
## 'action' carries the same syntax
Context => $context,
Target => $channel,
Text => $string,
}
);
Here's the same timer, but using the pure object syntax:
use Bot::Cobalt::Timer;
$core->timer_set(
Bot::Cobalt::Timer->new(
core => $core,
context => $context,
target => $channel,
text => $string,
type => 'msg',
delay => 60
);
);
If no B<Type> is specified, I<event> is assumed:
## Trigger event $event in $secs with (optional) @args:
my $id = $core->timer_set( $secs,
{
Event => $event,
Args => [ @args ],
}
);
## ... same thing, but object interface:
my $id = $core->timer_set(
Bot::Cobalt::Timer->new(
core => $core,
event => $event,
args => \@args,
);
);
You can tags packages with your plugin's B<Alias>, if you'd like;
if an Alias is set, you'll be able to clear all timers by alias via
L</timer_del_alias> or retrieve them via L</timer_get_alias>:
## Alias-tagged timer
my $id = $core->timer_set( $secs,
{
Event => $event,
Args => [ @args ],
## Safely retrieve our $self object's plugin alias:
Alias => $core->get_plugin_alias( $self ),
},
);
(The L<Bot::Cobalt::Timer> object interface uses the B<alias> attribute.)
Additionally, L<Bot::Cobalt::Plugin::PluginMgr> automatically tries to clear
plugin timers for unloaded plugins; this only works for Alias-tagged timers.
Without a specified Alias, a timer is essentially considered ownerless --
it will happily fire at their scheduled time even if the issuing plugin
is gone.
By default, a random timer ID is chosen (and returned).
You can also specify an ID:
## Set a timer with specified ID 'MyTimer'
## Will overwrite any preexisting timers with the same ID
$core->timer_set(
$secs,
{ Event => $event, Args => [ @args ] },
'MyTimer'
);
(The L<Bot::Cobalt::Timer> object interface uses the B<id> attribute.)
This can be used for resetting timers you've already set; grab the ID
returned by a C<timer_set()> call and reset it to change the event or delay.
You may want C<timestr_to_secs> from L<Bot::Cobalt::Utils> for easy
conversion of human-readable strings into seconds. This is, of course,
included by default if you C<< use L<Bot::Cobalt::Common> >>.
If you need better accuracy, you'll need to use your own alarm()/delay()
calls to L<POE::Kernel>; the timer pool is checked every second or so.
Arguments specified in the B<Args> array reference or B<args> object
attribute will be relayed to plugin event handlers just like any other
event's parameters:
sub Bot_some_timed_event {
## Called by a timer_set() timer
my ($self, $core) = splice @_, 0, 2;
my $firstarg = ${ $_[0] };
my $second = ${ $_[1] };
}
=head4 timer_del
Delete a timer by ID.
my $deleted = $core->timer_del( $id );
Returns the deleted timer object, or nothing if there was no such
ID.
The returned result (if there is one) can be fed back to L</timer_set>
if needed; it will be a L<Bot::Cobalt::Timer> object:
## hang on to this timer for now:
my $postponed = $core->timer_del( $id ) ;
## . . . situation changes . . .
$postponed->delay(60);
if ( $core->timer_set( $postponed ) ) {
## readding postponed timer successful
}
=head4 timer_del_alias
Delete all timers owned by the specified alias:
my $plugin_alias = $core->plugin_get_alias( $self );
my $deleted_count = $core->timer_del_alias( $plugin_alias );
Only works for timers tagged with their Alias; see L</timer_set>.
Timers with no Alias tag are considered essentially "ownerless" and left
to their own devices; they'll fail quietly if the timed event was handled
by an unloaded plugin.
This is also called automatically by the core plugin manager
(L<Bot::Cobalt::Plugin::PluginMgr>) when a plugin is unloaded.
=head4 timer_get_alias
Find out which active timerIDs are owned by the specified alias:
my $plugin_alias = $core->plugin_get_alias( $self );
my @active_timers = $core->timer_get_alias( $plugin_alias );
=head4 timer_get
Retrieve the L<Bot::Cobalt::Timer> for this active timer (or undef if not
found).
my $this_timer = $core->timer_get($id);
=head2 Syndicated core events
These are events sent by L<Bot::Cobalt::Core> when various core states
change.
You should probably return PLUGIN_EAT_NONE on all of these, unless
you are absolutely sure of what you are doing.
=head3 Plugin related events
=head4 Bot_plugins_initialized
Broadcast when the initial plugin load has completed at start-time.
Carries no arguments.
=head4 Bot_plugin_error
Broadcast when the syndicator reports an error from a plugin.
The only argument is the error string reported by
L<POE::Component::Syndicator>.
These messages are also logged to 'warn' by default.
=head3 Timer related events
=head4 Bot_executed_timer
Broadcast whenever a timer ID has been executed.
The only argument is the timer ID.
=head4 Bot_deleted_timer
Broadcast whenever a timer ID has been deleted.
The first argument is the timer ID.
The second argument is the removed L<Bot::Cobalt::Timer> object.
=head3 Ignore related events
=head4 flood_ignore_added
Broadcast by L<Bot::Cobalt::IRC> when a temporary anti-flood ignore has
been placed.
Arguments are the server context name and the mask that was added,
respectively.
=head4 flood_ignore_deleted
Broadcast by L<Bot::Cobalt::IRC> when a temporary anti-flood ignore has
expired and been removed.
Arguments are the same as L</flood_ignore_added>.
=head1 PLUGIN DESIGN TIPS
=head2 Useful tools
=head3 Bot::Cobalt
Importing L<Bot::Cobalt> via 'use Bot::Cobalt' brings in the
L<Bot::Cobalt::Core::Sugar> functions.
These provide simple syntax sugar for accessing the L<Bot::Cobalt::Core>
singleton and common methods such as B<send_event>; consult the
L<Bot::Cobalt::Core::Sugar> documentation for details.
=head3 Bot::Cobalt::Common
L<Bot::Cobalt::Common> is a simple exporter that will pull in common constants
and utilities from L<Object::Pluggable::Constants>, L<IRC::Utils>, and
L<Bot::Cobalt::Utils>.
Additionally, C<use Bot::Cobalt::Constant> will enable the B<strict> and
B<warnings> pragmas.
This is provided as a convenience for plugin authors; rather than importing
from a goodly handful of modules, you can simply:
use Bot::Cobalt::Common;
Declaring strict and warnings explicitly are still good practice.
See L<Bot::Cobalt::Common> for details.
=head3 Bot::Cobalt::DB
L<Bot::Cobalt::DB> provides an easy object-oriented interface to storing
and retrieving Perl data structures to/from BerkeleyDB via L<DB_File>.
Useful when a plugin has some persistent data it needs to
keep track of, but storing it in memory and serializing to/from disk is
too expensive.
use Bot::Cobalt::DB;
# new object for this db, creating it if it doesn't exist:
$db = Bot::Cobalt::DB->new(
File => $some_db_path,
);
# open and lock the db:
$db->dbopen || return "database open failed!";
# 'put' some data structure in the db:
my $ref = { Some => [ 'Data', 'Structure' ] };
$db->put('MyKey', $ref);
# 'get' some other data structure:
my $other_data = $db->get('OtherKey');
# close/unlock db:
$db->dbclose;
See L<Bot::Cobalt::DB> for complete usage information.
=head3 Bot::Cobalt::Serializer
It is often useful to serialize arbitrary data structures to some
standardized format. Serialization formats such as B<JSON> and B<YAML>
are convenient for "speaking" to other networked applications, sharing
data, or saving persistent data to disk in an easily-retrievable format.
L<Bot::Cobalt> comes with a simple object oriented frontend to some common
serialization formats, as well as built-in file operations for "freezing"
and "thawing" data to/from files on disk:
use Bot::Cobalt::Serializer;
## create a JSON serializer:
my $jsify = Bot::Cobalt::Serializer->new( Format => 'JSON' );
## serialize a perl hash:
my $ref = { Some => { Deep => [ 'Structure' ] } };
my $json = $jsify->freeze($ref);
See L<Bot::Cobalt::Serializer>.
=head3 Bot::Cobalt::Utils
L<Bot::Cobalt::Utils> provides a functional-style interface to various tools
useful in effective plugin authoring.
Tools include flexible (bcrypt-enabled) password hashing and comparison
functions, string formatting with arbitrary variable replacement rules,
Cobalt-style glob syntax tools, color/format interpolation, and others.
## Import all Bot::Cobalt::Utils funcs:
use Bot::Cobalt::Utils qw/ :ALL /;
See L<Bot::Cobalt::Utils>.
=head3 IRC::Utils
L<IRC::Utils> is a very useful module covering many basic IRC-related
tasks, such as host normalization / matching and casemapping-aware IRC
uppercase/lowercase tools.
It is used extensively by both L<Bot::Cobalt> and
L<POE::Component::IRC> and therefore guaranteed to be available for use.
See L<IRC::Utils> for upstream's documentation.
=head3 Bot::Cobalt::Plugin::WWW
It's fairly common to want to make some kind of HTTP request from an
IRC bot. The most common Perl method of speaking HTTP is
L<LWP::UserAgent> -- which will block the plugin pipeline until the
request is complete.
L<Bot::Cobalt::Plugin::WWW>, if loaded, dispatches HTTP requests
asynchronously via L<POE::Component::Client::HTTP> and returns
L<HTTP::Response> responses to the plugin pipeline:
## build a request object via HTTP::Request
use HTTP::Request;
## a simple GET, see HTTP::Request docs for more info:
my $request = HTTP::Request->new( 'GET', $url );
## push it to www_request with a response event:
broadcast( 'www_request',
$request,
'myplugin_resp_recv',
## you can include a reference containing args
## (or a scalar, if you like)
##
## here's an example args arrayref telling our handler
## where to send responses:
[ $context, $channel, $nickname ],
);
## handle a response when one is received:
sub Bot_myplugin_resp_recv {
my ($self, $core) = splice @_, 0, 2;
## if the request was successful, $_[0] is a ref to the
## decoded content from HTTP::Response
## (otherwise, it is the HTTP status message)
my $content = ${ $_[0] };
## $_[1] is the HTTP::Response object, see perldoc HTTP::Response
my $response = ${ $_[1] };
## $_[2] is whatever argument ref was provided in www_request
my $argref = ${ $_[2] };
## in our example above, it was some contextual info:
my ($context, $channel, $nickname) = @$argref;
if ($response->is_success) {
## . . . do something with the response . . .
} else {
## request failed (see HTTP::Response)
}
## eat this event, we're the only handler:
return PLUGIN_EAT_ALL
}
When a response is received, it will be pushed to the plugin pipeline
as the specified SERVER event.
If the plugin is available, B<< $core->Provided->{www_request} >> will be
boolean true:
my $request = HTTP::Request->new( . . . );
if ($core->Provided->{www_request}) {
## send www_request event like above
. . .
} else {
## no async available, error out or use LWP or something:
my $ua = LWP::UserAgent->new(
timeout => 5,
max_redirect => 0,
);
my $response = $ua->request($request);
my $content = $response->content;
}
=head2 Retrieving $core
It may be necessary or convenient to use L<Bot::Cobalt::Core> methods from
outside of a syndicated event handler.
If your plugin imports L<Bot::Cobalt> via 'use Bot::Cobalt', the
C<core()> function will retrieve the instanced L<Bot::Cobalt::Core>;
for example:
core()->auth->level( . . . )
See L<Bot::Cobalt::Core::Sugar> for details on functions exported when
you 'use Bot::Cobalt'.
If you don't want to use the sugary functions and
would rather make method calls directly, L<Bot::Cobalt::Core> is an
instanced singleton; loaded plugins can always
retrieve the running L<Bot::Cobalt::Core> via the B<instance> method:
sub my_routine {
my ($self, @args) = @_;
require Bot::Cobalt::Core;
croak "No Core instance available"
unless Bot::Cobalt::Core->has_instance;
my $core = Bot::Cobalt::Core->instance;
}
=head2 Non-reloadable plugins
By default, a plugin can be unloaded/reloaded at any time, typically via
the L<Bot::Cobalt::Plugin::PluginMgr> !plugin administrative interface.
If a plugin is marked as being unreloadable, plugin managers such as the
included L<Bot::Cobalt::Plugin::PluginMgr> will recognize it as such and
refuse to unload or reload the plugin once it is loaded.
=head3 Declaring non-reloadable status
A plugin can declare itself as not being reloadable with a simple
method returning boolean true:
sub NON_RELOADABLE { 1 }
=head1 ADVANCED CONCEPTS
=head2 Breaking up lengthy loops
Cobalt operates in an event loop -- implying that any piece of
code that blocks for any significant length of time is holding up
the rest of the loop:
sub Bot_some_event {
my ($self, $core) = splice @_, 0, 2;
my @items = long_list_of_items();
BIGLOOP: for my $item (@items) {
do_work_on($item);
}
## everything else stops until BIGLOOP is done
}
Instead, you can break the loop into event handlers and yield back to
the event loop, cooperatively multitasking with other events.
The below example processes a large list of items, pushing remaining
items back to the 'worker' event handler after iterating 100 items.
sub Cobalt_register {
## ... initialization...
## ... register for myplugin_start_work, myplugin_do_work
}
## Some event that starts a long-running loop:
sub Bot_myplugin_start_work {
my ($self, $core) = splice @_, 0, 2;
my @items = long_list_of_items();
## begin _do_work
## pass our @items to it, for example:
$core->send_event( 'myplugin_do_work', [ @items ] );
return PLUGIN_EAT_ALL
}
sub Bot_myplugin_do_work {
my ($self, $core) = splice @_, 0, 2;
## our remaining items:
my $itemref = ${ $_[0] };
my @items = @$itemref;
## maximum number of elements to process before yield:
my $max_this_run = 100;
while (@items && --$max_this_run != 0) {
my $item = shift @items;
## ... do some work on $item ...
}
## if there's any items left, push them and yield:
if (@items) {
$core->send_event( 'myplugin_do_work', [ @items ] );
} else {
## no items left, we are finished
## tell pipeline we're done, perhaps:
$core->send_event( 'myplugin_finished_work' );
}
return PLUGIN_EAT_ALL
}
For more fine-grained control, consider running your own POE::Session;
see L</"Spawning your own POE::Session">, below.
=head2 Spawning your own POE::Session
There's nothing preventing you from spawning your own L<POE::Session>;
your session will run within Cobalt's L<POE::Kernel> instance and POE
event handlers will work as-normal.
Motivations for doing so include fine-grained timer control, integration
with POE bits such as the POE::Component and POE::Wheel namespaces
. . . and the fact that POE is pretty great ;-)
It's worth noting that many POE Components use B<get_active_session> to
determine where to send responses. It may sometimes be necessary to use
intermediary "proxy" methods to ensure a proper destination session is
set in the POE::Component in use.
See L<Bot::Cobalt::Plugin::WWW> source for an example of a plugin that uses
its own POE::Session and does this (when issuing HTTP requests to
L<POE::Component::Client::HTTP>).
=head2 Manipulating plugin pipeline order
L<Object::Pluggable> allows you to manipulate the plugin pipeline order;
that is to say, the order in which events will hit plugins.
For example, when writing a plugin such as an input filter, it can be useful to move
your plugin towards the top of the plugin pipeline:
## With 'use Bot::Cobalt':
core->pipeline->bump_up( plugin_alias($self) );
See L<Object::Pluggable::Pipeline> for details.
Plugin managers are not required to take any special consideration of a
plugin's previous position in the case of a plugin (re)load.
=head1 IRC CAVEATS
=head2 IRC casemapping rules
Determining whether or not nicknames and channels are equivalent on IRC
is not as easy as it looks.
Per the RFC (L<http://tools.ietf.org/html/rfc1459#section-2.2>):
the characters {}| are
considered to be the lower case equivalents of the characters []\,
respectively
This set ( {}| == []\ ) is called B<strict-rfc1459> and identified as such in
a server's I<ISUPPORT CASEMAPPING=> directive.
More often, servers use the set commonly identified as B<rfc1459>:
## rfc1459 lower->upper case change: {}|^ == []\~
$value =~ tr/a-z{}|^/A-Z[]\\~/;
Some servers may use normal ASCII case rules; they will typically announce
B<ascii> in I<CASEMAPPING=>.
L<Bot::Cobalt::IRC> will attempt to determine and save a server's CASEMAPPING value
at connect time. Some broken server configurations announce junk in
I<CASEMAPPING> and their actual valid casemapping ruleset in I<CHARSET>;
L<Bot::Cobalt::IRC> will fall back to I<CHARSET> if I<CHARSET> is a valid casemap
but I<CASEMAPPING> is invalid. If all else fails, B<rfc1459> is used.
The saved value can be used to feed C<eq_irc> and friends from L<IRC::Utils> and
determine nickname/channel equivalency.
See L</get_irc_casemap> and L<IRC::Utils>
=head2 Character encodings
IRC doesn't come with a lot of guarantees regarding character encodings.
Hopefully, you are getting either CP1252 or UTF-8.
The L<IRC::Utils> POD contains an excellent discussion of the general
problem; see L<IRC::Utils/ENCODING>.
L<IRC::Utils/decode_irc> is included if you 'use Bot::Cobalt::Common'.
=head1 SEE ALSO
L<Bot:Cobalt::IRC> covers events handled and emitted by the IRC plugin.
L<Bot::Cobalt::Manual::Plugins::Tutorial> contains a simple walk-through
tutorial on plugin writing.
L<Bot::Cobalt::Manual::Plugins::Config> describes configuration files used by
plugins.
L<Bot::Cobalt::Manual::Plugins::Dist> covers packaging your module for
installation.
L<Bot::Cobalt::Core::Sugar> describes functional sugar imported when you
C<use Bot::Cobalt;>.
Plugin authors may also be interested in using L<Bot::Cobalt::Utils>.
You can view the full documentation at
L<http://www.metacpan.org/release/Bot-Cobalt>.
=head2 Relevant CPAN documentation
L<Bot::Cobalt::Core> and L<Bot::Cobalt::IRC> are mostly a lot of sugar
over the following very useful CPAN modules:
=over
=item *
L<IRC::Utils>
=item *
L<POE::Component::IRC> and L<POE::Component::IRC::State>
=item *
L<POE::Component::Syndicator>
=back
=head1 AUTHOR
Jon Portnoy <avenj@cobaltirc.org>
http://www.cobaltirc.org
=cut