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
that of the server on which the bot is running if omitted. It must also be a
date and time in the future.

Alarms may be set to recur by specifying an interval with ``:recurring``. The
format of the interval (shockingly!) matches that of the interval type in
PostgreSQL. Before the alarm is created, a test is performed to ensure that the
alarm will not fire too often, as a small measure to prevent abuse. The alarm
creation will be rejected if it will emit messages more than a few times an
hour.

An exclusion pattern may also be specified with ``:exclude``. Any timestamps
from the recurrence interval that match the exclusion patterns will be skipped.
The format of the is a comma-separated list of ``<field>=<regular expression>``
and may use any of the PostgreSQL ``to_char(...)`` formatting fields.

=head3 Usage

<alarm name> :first <ISO8601> [:recurring <interval>] [:exclude <pattern>] [<message or quoted expression>]

=head3 Examples

    (set-alarm daily-standup
      :first     "2016-04-25 10:00:00 US/Eastern"
      :recurring "1 day"