The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Bot-NotSoBasicBot-0.02
++
/ Bot::NotSoBasicBot

NAME

Bot::NotSoBasicBot - Builts on Bot::BasicBot, adding a little extra functionality for convenience.

VERSION

Version 0.02

SYNOPSIS

Bot::NotSoBasicBot adds some functionality and convenience to the already pretty fantastic Bot::BasicBot. Chief among those new features is the ability to set mode on channels, so you can make your own modbots, like Bot::Roberts, which is itself derived from Bot::NotSoBasicBot. It can also start from a configuration file, allowing you to write bot scripts that need no modification at all to run in different environments.

Its use is even simpler than Bot::BasicBot.

    use Bot::NotSoBasicBot;

    my $bot = Bot::NotSoBasicBot->new("my.conf");
    $bot->run();

Now, Bot::NotSoBasicBot alone will not do very much at all of any interest. You'll want to subclass it. For better functionality right out of the box, see Bot::Listener and Bot::Roberts in this distribution.

FUNCTIONS

new ($configfile) (or nothing)

Bot::NotSoBasicBot uses Config::Auto to parse a configuration file. If you don't give new() a filename, it will let Config::Auto figure it out for you. This might work, or might have hilarious consequences.

Once the configuration is read, the munge_config class function is called so you can preprocess your configuration before it's used to initiate the bot. This means that if you need to do something funky to derive nick, server, and/or channels, do it there.

munge_config ($config) CLASS METHOD

The munge_config method is called before the object is initialized, so it's a class method, not an object method. This may be confusing.

logline ($channel, $what_said)

The logline function provides a central transcripting location. Debugging logs can easily be kept separate from transcripts of the channels your bot is listening to. You'll probably want to override it, as its standard implementation just uses BasicBot's log function, which writes to stderr.

announce ($channel, $what_to_say)

The announce function says something on the channel listed, and simultaneously logs it to the transcript.

say_discreetly ($channel, $who, $what_to_say)

The say_discreetly function says something to a user by PM if given a user; otherwise, announces it on the channel.

reply ($channel, $mode, $who, $what_to_say)

The reply function takes the modes generated by said below and either announces a reply or says it discreetly.

said ($message)

The said function is just the usual Bot::BasicBot hook for incoming messages. The default implementation logs the transcript, then calls a respond hook unique to Bot::NotSoBasicBot after organizing the input a little for you.

Before logging the transcript, it calls a "remember" function that can be overridden if the bot needs a memory of things that have been said. Only things said in public are remembered.

remember ($channel, $who, $what)

The remember hook is called to allow the bot to keep track of things people have said. Since most bots don't need this, the default does nothing and you can usually ignore it.

emoted ($message)

The emoted function is the Bot::BasicBot hook for incoming emoted messages. The default logs the transcript in normal emote format, then calls respond with mode 'emoted'.

respond ($channel, $mode, $who, $message)

The respond function is a hook you can override to respond to things said to the bot.

$mode takes values 'general' for things said on the channel, 'emoted' for things emoted on the channel (if you care), 'addressed' for things said to the bot on the channel with "Nick:" addressing, and 'private' for things addressed to the bot on PM.

users ($channel)

The users function calls Bot::BasicBot's channel_data function to retrieve the list of users on the channel. If called in list context, it returns the list of users; if called in scalar context, a hashref mapping user names onto hashrefs of 'voice' and 'op' flags for each user (i.e. the same thing channel_data returns).

This allows us to say e.g. foreach my $u in $self-users()>. Isn't that easy?

mode ($modestrings)

The mode function performs a mode command on the channel of your choice. No matter how many strings you give it, it will just join them all together to form a mode command.

join ($channel)

The join function attempts to join a channel. Note that this won't affect $self->{config}->{channels}.

tick()

The default tick handler makes sure it's called every second to service the event queue.

schedule($time, $event)

Bot::NotSoBasicBot uses Event::Schedule to maintain a queue of events to be executed at specific times. This allows us to schedule something to be done a minute after a given response, for instance, without worrying about how it will work.

$time is the number of seconds to wait until executing the event; $event is a coderef to a (usually anonymous) procedure to be called with no parameters. To call something with parameters, enclose it in an anonymous procedure to form a closure, e.g.

   $self->schedule (60, sub { $self->announce ($channel, "Did you forget about me?") });

AUTHOR

Michael Roberts, <michael at vivtek.com>

BUGS

Please report any bugs or feature requests to bug-bot-notsobasicbot at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Bot-NotSoBasicBot. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Bot::NotSoBasicBot

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2010 Michael Roberts, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.