NAME

POE::Component::IRC::Plugin::Thanks - make witty responses to "thank you"s

SYNOPSIS

    use strict;
    use warnings;

    use POE qw(Component::IRC  Component::IRC::Plugin::Thanks);

    my $irc = POE::Component::IRC->spawn(
            nick    => 'ThankBot',
            server  => 'irc.freenode.net',
            port    => 6667,
            ircname => 'Silly Thankie bot',
    ) or die "Oh noes :( $!";

    POE::Session->create(
        package_states => [
            main => [ qw( _start irc_001 ) ],
        ],
    );

    $poe_kernel->run();

    sub _start {
        $irc->yield( register => 'all' );

        # register our plugin
        $irc->plugin_add( 'Thanks' => POE::Component::IRC::Plugin::Thanks->new );

        $irc->yield( connect => { } );
        undef;
    }

    sub irc_001 {
        my ( $kernel, $sender ) = @_[ KERNEL, SENDER ];
        $kernel->post( $sender => join => '#zofbot' )
        undef;
    }

CONSTRUCTOR

    # vanilla plugin
    $irc->plugin_add( 'Thanks' => POE::Component::IRC::Plugin::Thanks->new );

    # juicy flavor
    $irc->plugin_add(
        'Thanks' => POE::Component::IRC::Plugin::Thanks->new(
            trigger => qr/^\s*(?:thanks|thank you)/i,
            respond => 1,
            thanks_event => 'thanks_response',
            messages => [       # discard default messages and use these
                'response 1',
                'response 2',
            ],
            extra_messages => [ # add these to the default messages
                'response 1',
                'response 2',
            ],
            bans => [ qr/^Spammer/i, qr/spam[.]net$/i ],
        )
    );

The constructor returns a POE::Component::IRC::Plugin object suitable for consumption by POE::Component::IRC plugin_add() method. It takes a few arguments but all of them are optional. The possible arguments are:

trigger

    ->new( trigger => qr/^\s*(?:thanks|thank you)/i );

Takes a regex as an argument. Specifies what messages to consider to be "thank you" messages. In other words, messages that match trigger will generate a random "thank you" response from this plugin. Defaults to: qr/ ^ (?:thank s? (?: \s* you )? | th?a?nx | thx | tyvm )/xi

respond

    ->new( respond => 0 );

The respond argument controls whether or not the plugin should auto respond to the person thanking us. If set to a false value plugin will not auto respond and only the thanks_event (see below) will be sent out. If set to a true value plugin will respond to the person and send the event.

thanks_event

    ->new( thanks_event => 'thanks_response' );

Whenever the bot is addressed and the message matches the trigger (see above) the plugin will send out the event specified by thanks_event. See EMITTED EVENTS section below for more information.

messages

    ->new(
           messages => [
                'response 1',
                'response 2',
            ],
    );

Plugin has a set of predefined "thank you" responses which are listed in the DEFAULT RESPONSES section below. If you wish, you can specify your own set using the messages argument which takes an arrayref of messages. Defaults to: the responses listed in the DEFAULT RESPONSES section below.

extra_messages

    ->new(
            extra_messages => [ # add these to the default messages
                'response 1',
                'response 2',
            ],
    );

The same as messages argument (see above) except the messages listed in extra_messages will be appended to messages listed in messages argument. In other words, if you want to add a few responses to the default responses you don't have to redefine every default response in messages argument, but instead just list your extra messages in extra_messages argument. Default to: nothing (obviously).

bans

    ->new( bans => [ qr/^Spammer/i, qr/spam[.]net$/i ] );

The bans key takes an arrayref as an argument with regex objects as elements of that arrayref. If plugin receives input from a user who's mask matches any of the regexes specified in bans key, plugin will ignore that user. Defaults to: empty, no bans are set.

eat

    ->new( eat => 0 );

If set to a false value plugin will return a PCI_EAT_NONE after responding with a "thank you" message. If eat is set to a true value, plugin will return a PCI_EAT_ALL after responding with a "thank you" message. See POE::Component::IRC::Plugin documentation for more information if you are interested. Defaults to: 1

DEFAULT RESPONSES

The plugin has a set of defined "thank you" responses, which are what is the default of messages argument of the constructor. See messages and extra_messages arguments to the constructor if you wish to change the default responses in any way. I am very open to new additions of messages to the default list, feel free to suggest some witty responses. The following arrayref is the default value of messages argument if the constructor:

    [
         q|You are welcome!|,
         q|That will be $50... CASH!|,
         q|yeah, yeah, that's what you all say...|,
         q|No problema :)|,
         q|can you help _me_ now?|,
         q|FYI, thanking the bot says a lot about your mental state!|,
         q|It's ok, I'm just a bot, no need for "thank you"s.|,
         q|No, no, thank YOU|,
    ]

EMITTED EVENTS

Whenever the plugin responds with a "thank you" response. The plugin emits an event, name of which is specified by the <thanks_event> argument to the constructor.

By setting respond in the constructor to a false value you may generate responses yourself whenever you receive the thanks_event.

The event handler which is handling this event will receive a hashref in its ARG0 argument. The hashref will have the following keys/values:

    {
        who => 'Zoffix!zoffix@unaffiliated/zoffix',
        channel => '#zofbot',
        what => '_ZofBot, thanks!',
        response => 'No, no, thank YOU'
    }

who

    { who => 'Zoffix!zoffix@unaffiliated/zoffix' }

The mask of the person who thanked us.

channel

    { channel => '#zofbot' }

The channel where the message originated.

what

    { what => '_ZofBot, thanks!' }

The content of the message.

response

    { response => 'No, no, thank YOU' }

The randomly generated "thank you" response.

REPOSITORY

Fork this module on GitHub: https://github.com/zoffixznet/POE-Component-IRC-PluginBundle-Toys

BUGS

To report bugs or request features, please use https://github.com/zoffixznet/POE-Component-IRC-PluginBundle-Toys/issues

If you can't access GitHub, you can email your request to bug-POE-Component-IRC-PluginBundle-Toys at rt.cpan.org

AUTHOR

Zoffix Znet <zoffix at cpan.org> (http://zoffix.com/, http://haslayout.net/)

LICENSE

You can use and distribute this module under the same terms as Perl itself. See the LICENSE file included in this distribution for complete details.