Why not adopt me?

This distribution is up for adoption! If you're interested then please contact the PAUSE module admins via email.

NAME

POE::Component::IRC::Plugin::AlarmClock - IRC alarm clock plugin

SYNOPSIS

    use strict;
    use warnings;

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

    my $irc = POE::Component::IRC->spawn(
        nick        => 'AlarmClockBot',
        server      => 'irc.freenode.net',
        port        => 6667,
        ircname     => 'AlarmClock bot',
        plugin_debug => 1,
    );

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

    $poe_kernel->run;

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

        $irc->plugin_add(
            'AlarmClock' =>
                POE::Component::IRC::Plugin::AlarmClock->new
        );

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

    sub irc_001 {
        $irc->yield( join => '#zofbot' );
    }

    [18:13:23] <Zoffix> AlarmClockBot, alarm set 50
    [18:13:23] <AlarmClockBot> Alarm will ring in 50 second(s)

    [18:13:25] <Zoffix> AlarmClockBot, alarm set 10m
    [18:13:25] <AlarmClockBot> Alarm will ring in 10 minute(s)

    [18:13:28] <Zoffix> AlarmClockBot, alarm set 1h
    [18:13:28] <AlarmClockBot> Alarm will ring in 1 hour(s)

    [18:13:30] <Zoffix> AlarmClockBot, alarm list
    [18:13:30] -AlarmClockBot- [ 0 - 43 second(s) -  ] [ 1 - 9 minute(s)
                and 55 second(s) -  ] [ 2 - 59 minute(s) and 58 second(s) -  ]

    [18:13:33] <Zoffix> AlarmClockBot, alarm del 2
    [18:13:33] -AlarmClockBot- Deleted alarm 2 [] which would have rang in
                59 minute(s) and 55 second(s)

    [18:13:52] <Zoffix> AlarmClockBot, alarm set 10s Check your stove!
    [18:13:52] <AlarmClockBot> Alarm will ring in 10 second(s)

    [18:13:56] <Zoffix> AlarmClockBot, alarm list
    [18:13:56] -AlarmClockBot- [ 2 - 6 second(s) - Check your stove! ] [ 0
                - 17 second(s) -  ] [ 1 - 9 minute(s) and 29 second(s) -  ]

    [18:14:02] <AlarmClockBot> Zoffix, alarm rang Check your stove!
    [18:14:13] <AlarmClockBot> Zoffix, alarm rang

    [18:14:16] <Zoffix> AlarmClockBot, alarm list
    [18:14:16] -AlarmClockBot- [ 1 - 9 minute(s) and 9 second(s) -  ]

    [18:14:20] <Zoffix> AlarmClockBot, alarm del 1
    [18:14:20] -AlarmClockBot- Deleted alarm 1 [] which would have rang in
                9 minute(s) and 5 second(s)

    [18:14:22] <Zoffix> AlarmClockBot, alarm del 10
    [18:14:22] -AlarmClockBot- You don't have any alarms set

    [18:14:35] <Zoffix> AlarmClockBot, alarm set 1h
    [18:14:35] <AlarmClockBot> Alarm will ring in 1 hour(s)
    [18:14:36] <Zoffix> AlarmClockBot, alarm set 1h
    [18:14:36] <AlarmClockBot> Alarm will ring in 1 hour(s)
    [18:14:36] <Zoffix> AlarmClockBot, alarm set 1h
    [18:14:36] <AlarmClockBot> Alarm will ring in 1 hour(s)
    [18:14:36] <Zoffix> AlarmClockBot, alarm set 1h
    [18:14:36] <AlarmClockBot> Alarm will ring in 1 hour(s)
    [18:14:36] <Zoffix> AlarmClockBot, alarm set 1h
    [18:14:36] <AlarmClockBot> Alarm will ring in 1 hour(s)
    [18:14:37] <Zoffix> AlarmClockBot, alarm set 1h
    [18:14:37] <AlarmClockBot> Alarm will ring in 1 hour(s)
    [18:14:37] <Zoffix> AlarmClockBot, alarm set 1h

    [18:14:38] <AlarmClockBot> Sorry but you may not set any more alarms. Clear your old ones or wait for them to ring

    [18:15:18] <Zoffix> AlarmClockBot, alarm blah
    [18:15:18] <AlarmClockBot> Invalid command in alarm plugin

DESCRIPTION

This module is a POE::Component::IRC plugin which uses POE::Component::IRC::Plugin for its base. It provides interface to to remind forgetful users of some evens as an alarm clock. It accepts input from public channel events, /notice messages as well as /msg (private messages); although that can be configured at will.

COMMANDS/FUNCTIONALITY

See end of SYNOPSIS section for examples.

After stripping the trigger (see constructor description) the plugin will look for several commands to decide how to act.

If input matches /^(?:set|start)\s+(\d+[smh]?)\s*(.+)?/xi the alarm will be set to ring in said amount of seconds, minutes or hours and an optional "alarm message" can be added at the end to remind the user why the alarm was set. Note: if your program shuts down all alarms are cleared.

If input matches /\b(list|show)\b/i. Then plugin will list all active alarms (if any) for this user. The format of the output is [ $alarm_id - $when_will_it_ring - $alarm_message ]. In other words, the output [ 0 - 43 second(s) - foos ] [ 1 - 9 minute(s) and 55 second(s) - ] means the user has two active alarms. Alarm number 0 will ring in 43 seconds and was set with a message foos. Alarm number 1 will ring in 9 minutes, 55 seconds and does not have any message associated with it. You may use these alarm IDs (numbers) to clear the alarms.

If input matches /^(?:del(?:ete)?|rem(?:ove)?)\s+(\d)/i then alarm with ID number provided will be cleared. The alarm ID numbers can be obtained via list/show command.

NOTE ON MESSAGE TYPES

The alarm can be set via public message, private message or notice message. When it "rings" the user will be notified via the same kind of message which was used to set the alarm.

The output of list and delete command is always sent via notice messages. And if you don't like this fact, feel free to set auto constructor's option to a false value and make output yourself.

CONSTRUCTOR

`new`

    # plain and simple
    $irc->plugin_add(
        'AlarmClock' => POE::Component::IRC::Plugin::AlarmClock->new
    );

    # juicy flavor
    $irc->plugin_add(
        'AlarmClock' =>
            POE::Component::IRC::Plugin::AlarmClock->new(
                auto             => 1,
                max_alarms       => 5,
                response_event   => 'irc_alarm_clock',
                banned           => [ qr/aol\.com$/i ],
                root             => [ qr/mah.net$/i ],
                addressed        => 1,
                trigger          => qr/^alarm\s+(?=\S)/i,
                listen_for_input => [ qw(public notice privmsg) ],
                eat              => 1,
                debug            => 0,
            )
    );

The new() method constructs and returns a new POE::Component::IRC::Plugin::AlarmClock object suitable to be fed to POE::Component::IRC's plugin_add method. The constructor takes a few arguments, but all of them are optional. Note: all these arguments can be set dynamically by setting values to keys of your plugin's object. In other words, if you want to ban some user on the fly you would do push @{ $your_plugin_object->{banned} }, 'user!ident@host';. The possible arguments/values are as follows (their names are case insensitive):

`auto`

    ->new( auto => 0 );

Optional. Takes either true or false values, specifies whether or not the plugin should auto respond to requests. When the auto argument is set to a true value plugin will respond to the requesting person with the results automatically. When the auto argument is set to a false value plugin will not respond and you will have to listen to the events emitted by the plugin to retrieve the results (see EMITTED EVENTS section and response_event argument for details). Defaults to: 1.

`max_alarms`

    ->new( max_alarms => 5 );

Optional. Takes a positive integer as a value which specifies the maximum number of active alarms each user may have. In other words if max_alarms is set to 5 and user sets 5 alarms he or she will have to wait until at least one of them rings (or will have to delete at least one of them) before he or she would be able to set any more alarms. Defaults to: 5

`response_event`

    ->new( response_event => 'event_name_to_receive_results' );

Optional. Takes a scalar string specifying the name of the event to emit when the results of the request are ready. See EMITTED EVENTS section for more information. Defaults to: irc_alarm_clock

`banned`

    ->new( banned => [ qr/aol\.com$/i ] );

Optional. Takes an arrayref of regexes as a value. If the usermask of the person (or thing) making the request matches any of the regexes listed in the banned arrayref, plugin will ignore the request. Defaults to: [] (no bans are set).

`root`

    ->new( root => [ qr/\Qjust.me.and.my.friend.net\E$/i ] );

Optional. As opposed to banned argument, the root argument allows access only to people whose usermasks match any of the regexen you specify in the arrayref the argument takes as a value. By default: it is not specified. Note: as opposed to banned specifying an empty arrayref to root argument will restrict access to everyone.

`trigger`

    ->new( trigger => qr/^alarm\s+(?=\S)/i );

Optional. Takes a regex as an argument. Messages matching this regex will be considered as requests. See also addressed option below which is enabled by default. Note: the trigger will be removed from the message, therefore make sure your trigger doesn't match the actual data that needs to be processed. Defaults to: qr/^alarm\s+(?=\S)/i

`addressed`

    ->new( addressed => 1 );

Optional. Takes either true or false values. When set to a true value all the public messages must be addressed to the bot. In other words, if your bot's nickname is Nick and your trigger is qr/^trig\s+/ you would make the request by saying Nick, trig set 10. When addressed mode is turned on, the bot's nickname, including any whitespace and common punctuation character will be removed before matching the trigger (see above). When addressed argument it set to a false value, public messages will only have to match trigger regex in order to make a request. Note: this argument has no effect on /notice and /msg requests. Defaults to: 1

`listen_for_input`

    ->new( listen_for_input => [ qw(public  notice  privmsg) ] );

Optional. Takes an arrayref as a value which can contain any of the three elements, namely public, notice and privmsg which indicate which kind of input plugin should respond to. When the arrayref contains public element, plugin will respond to requests sent from messages in public channels (see addressed argument above for specifics). When the arrayref contains notice element plugin will respond to requests sent to it via /notice messages. When the arrayref contains privmsg element, the plugin will respond to requests sent to it via /msg (private messages). You can specify any of these. In other words, setting ( listen_for_input = [ qr(notice privmsg) ] )> will enable functionality only via /notice and /msg messages. Defaults to: [ qw(public notice privmsg) ]

`eat`

    ->new( eat => 0 );

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

`debug`

    ->new( debug => 1 );

Optional. Takes either a true or false value. When debug argument is set to a true value some debugging information will be printed out. When debug argument is set to a false value no debug info will be printed. Defaults to: 0.

EMITTED EVENTS

`response_event`

    $VAR1 = {
        'out' => 'Alarm will ring in 1 hour(s)',
        'who' => 'Zoffix!Zoffix@i.love.debian.org',
        'what' => 'set 1h',
        'type' => 'public',
        'channel' => '#zofbot',
        'set' => 1,
        'message' => 'AlarmClockBot, alarm set 1h'
    };

    $VAR1 = {
        'out' => '[ 2 - 6 second(s) - Check your stove! ] [ 0 - 17 second(s) -  ] [ 1 - 9 minute(s) and 29 second(s) -  ]',
        'who' => 'Zoffix!Zoffix@i.love.debian.org',
        'what' => 'list',
        'type' => 'notice',
        'channel' => '#zofbot',
        'list' => 1,
        'message' => 'AlarmClockBot, alarm list'
    };

    $VAR1 = {
        'out' => 'Deleted alarm 1 [] which would have rang in 9 minute(s) and 5 second(s)',
        'who' => 'Zoffix!Zoffix@i.love.debian.org',
        'what' => 'del 1',
        'type' => 'notice',
        'channel' => '#zofbot',
        'del' => 1,
        'message' => 'AlarmClockBot, alarm del 1'
    };

    $VAR1 = {
          'out' => 'Zoffix, alarm rang ',
          'who' => 'Zoffix!Zoffix@i.love.debian.org',
          'rang' => 1,
          'channel' => '#zofbot',
          'type' => 'public'
    };

    $VAR1 = {
        'out' => 'Invalid command in alarm plugin',
        'who' => 'Zoffix!Zoffix@i.love.debian.org',
        'what' => 'blah',
        'type' => 'public',
        'channel' => '#zofbot',
        'invalid' => 1,
        'message' => 'AlarmClockBot, alarm blah'
    };

The event handler set up to handle the event, name of which you've specified in the response_event argument to the constructor (it defaults to irc_alarm_clock) will receive input every time alarm rings, new alarms is set, user asks to list active alarms, user deletes the alarm or user uses an invalid command for the alarm plugin. The input will come in $_[ARG0] in a form of a hashref. The above Dumper output shows possible variations of keys. The keys/values are as follows:

`out`

    { 'out' => 'Deleted alarm 1 [] which would have rang in 9 minute(s) and 5 second(s)', }

The out key will contain the message which was (would have been) sent to IRC.

`who`

    { 'who' => 'Zoffix!Zoffix@i.love.debian.org', }

The who key will contain the user mask of the user who sent the request or in case of "alarm rang" type of event - the user to whom the alarm belongs.

`what`

    { 'what' => 'set 1h', }

The what key will contain user's message after stripping the trigger (see CONSTRUCTOR).

`message`

    { 'message' => 'AlarmClockBot, alarm set 1h' }

The message key will contain the actual message which the user sent; that is before the trigger is stripped.

`type`

    { 'type' => 'public', }

The type key will contain the "type" of the message the user have sent. This will be either public, privmsg or notice. In case of the "alarm rang" type of event the type key will contain the type of message which was used to set this alarm.

`channel`

    { 'channel' => '#zofbot', }

The channel key will contain the name of the channel where the message originated. This will only make sense if type key contains public.

`set`, `list`, `del`, `rang` and `invalid`

The set, list, del, rang and invalid keys indicate the type of the event. That is if this event was generated by the user setting the alarm, the set key will be present. If user used an invalid command the invalid key will be present. If this even was generated by alarm ringing then rang key will be present. The list and del keys will be present for user listing alarms and deleting them respectively. The value of these keys will always be 1.

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.

To install POE::Component::IRC::PluginBundle::Toys, copy and paste the appropriate command in to your terminal.

cpanm

cpanm POE::Component::IRC::PluginBundle::Toys

CPAN shell

perl -MCPAN -e shell
install POE::Component::IRC::PluginBundle::Toys

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

Why not adopt me?

NAME

SYNOPSIS

DESCRIPTION

COMMANDS/FUNCTIONALITY

NOTE ON MESSAGE TYPES

CONSTRUCTOR

new

auto

max_alarms

response_event

banned

root

trigger

addressed

listen_for_input

eat

debug

EMITTED EVENTS

response_event

out

who

what

message

type

channel

set, list, del, rang and invalid

REPOSITORY

BUGS

AUTHOR

LICENSE

Module Install Instructions

`new`

`auto`

`max_alarms`

`response_event`

`banned`

`root`

`trigger`

`addressed`

`listen_for_input`

`eat`

`debug`

`response_event`

`out`

`who`

`what`

`message`

`type`

`channel`

`set`, `list`, `del`, `rang` and `invalid`