view release on metacpan or  search on metacpan

lib/App/RoboBot/Plugin/Bot/Alarm.pm  view on Meta::CPAN

package App::RoboBot::Plugin::Bot::Alarm;
$App::RoboBot::Plugin::Bot::Alarm::VERSION = '4.004';
use v5.20;

use namespace::autoclean;

use Moose;
use MooseX::SetOnce;

use AnyEvent;
use Data::Dumper;
use JSON;
use Scalar::Util qw( blessed );

use App::RoboBot::Channel;
use App::RoboBot::Message;
use App::RoboBot::Parser;
use App::RoboBot::Response;

extends 'App::RoboBot::Plugin';

=head1 bot.alarm

Exports functions for setting and modifying alarms, which can trigger messages
at specified times or intervals.

In addition to the exported functions, this module maintains a collection of
persistent AnyEvent timer objects which are used to fire the alarm messages
asynchronously from any regular message processing.

=cut

has '+name' => (
    default => 'Bot::Alarm',
);

has '+description' => (
    default => 'Exports functions for setting and modifying alarms, which can trigger messages at specified times or intervals.',
);

=head2 set-alarm

=head3 Description

Creates a new alarm in the current channel. The only required parameters are an
alarm name and its first occurrence. An optional message may be included, which
will be echoed whenever the alarm fires. Its length and formatting are limited
only by the features of the network on which the alarm was set (e.g. IRC will
generally be a couple hundred characters or less of plain text, whereas Slack
would allow several KB of text with formatting).

Alternately, the message may be given as a quoted expression, which will be
stored and evaluated anew with each occurrence of the alarm. These expressions
will not receive any arguments, but they may interact with global variables
defined within the same network on which the alarm is created. Because the
alarms trigger in an anonymous context (i.e. they are not responses to an
individual user's message), functions which assume a user will either fail or
behave oddly.

Unquoted expressions will be evaluated once at the time of alarm creation, and
that result will simply be echoed each time the alarm triggers. You must quote
the expression if you wish it to be evaluated on each alarm occurrence.

The initial date and time of the alarm, specified with ``:first`` must be a
valid ISO8601 formatted timestamp. The timezone is optional and will default to