/ 
Bot-Backbone-0.161950
River stage two • 8 direct dependents • 10 total dependents
/ Bot::Backbone::SendPolicy

NAME

Bot::Backbone::SendPolicy - Define policies to prevent flooding and other bot no-nos

VERSION

version 0.161950

SYNOPSIS

package MyBot;
use v5.14;
use Bot::Backbone;

# This policy prevents the bot from sending more than once every 1.5 seconds
send_policy no_flooding => (
    MinimumInterval => { interval => 1.5 },
);

# This policy does the same, but discards messages coming too fast
send_policy no_flooding_with_prejedice => (
    MinimumInterval => { interval => 1.5, discard => 1 };
);

# This policy discards messages repeated within 5 minutes
send_policy dont_repeat_yourself => (
    MinimumRepeatInterval => { interval => 5*60, discard => 1 };
);

service jabber_chat => (
    service => 'JabberChat',
    # your other settings...
    send_policy => 'no_flooding',
);

service group_foo => (
    service => 'GroupChat',
    chat    => 'jabber_chat',
    group   => 'foo',
    # your other settings...
    send_policy => 'no_flooding_with_prejudice',
);

# Policy that is shared
my $do_not_repeat = [ 
    Bot::Backbone::SendPolicy::MinimumRepeatInterval->new(
        interval => 300, # 5 * 60
        discar   => 1,
    ),
];

service wikipedia => (
    service => '.Wikipedia',
    chat    => 'group_foo',
    # your other settings...
    send_policies => $do_not_repeat,
);

service google_search => (
    service => 'GoogleSearch',
    chat    => 'group_foo',
    # your other settings...
    send_policies => $do_not_repeat,
);

DESCRIPTION

Bots are fun and all, but they can easily become annoying. These controls for preventing a bot from sending too often or repeating itself too frequently can help to minimize that annoyance.

The purpose of the send policy framework is to allow the bot maintainer to set policies against any service that may call send_message. The policy set against that service may delay any message being sent, cause a message to be discarded, or alter the message.

The framework is designed to be extensible with a couple very useful policies being provided with the backbone framework.

See Bot::Backbone::SendPolicy::MinimumInterval and Bot::Backbone::SendPolicy::MinimumRepeatInterval. See Bot::Backbone and Bot::Backbone::Service for more information on how send policies are defined and applied.

The rest of this docuemntation describes how to build a send policy implementation.

ATTRIBUTES

bot

This is a back reference to the bot.

REQUIRED METHODS

allow_send

my $send_policy = $policy->allow_send({
    text => 'some message',
    ...
});

Given a set of options passed to the send_message method of Bot::Backbone::Service::Role::Chat, return a hash reference containing the instrucitons on what to do with that message. The allow_send method may also modify the passed in options to alter the message being posted.

The result may contain the following keys:

allow

This is a boolean value. If true, the message will be delivered to the chat. If it is false, the message is immediately discarded.

This must be set. If not set, an exception will be thrown.

after

This is a numeric value that contains a number of fractional sections to wait utnil the message should be delivered. The message will be put on hold and then delivered after that amount of wait time has passed.

AUTHOR

Andrew Sterling Hanenkamp <hanenkamp@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by Qubling Software LLC.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.