Why not adopt me?
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.