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

NAME

Bot::Backbone::SendPolicy::MinimumRepeatInterval - Prevent any message from being repeated too often

VERSION

version 0.142220

SYNOPSIS

send_policy dont_repeat_yourself => (
    MinimumRepeatInterval => {
        interval        => 5 * 60,
        discard         => 1,
        linger_interval => 60 * 60,
    },
);

DESCRIPTION

This send policy will prevent a particular message text from being sent more frequently than the permitted "interval".

For example, suppose you have a service which does a Wikipedia lookup each time someone uses a WikiWord and states the link and first sentence from the article. It would be terribly annoying if, during a heated discussion of this article, when the WikiWord were repeated often, if that resulted in the bot posting and re-posting that sentence and link over and over again. With this policy in place, you don't have to worry about that happening.

ATTRIBUTES

interval

This is the length of time in fractional seconds during which the bot is not permitted to repeat any particular message.

queue_length

This is the maximum number of messages that will be queued for later display before the messages will be discarded. If "discard" is set to false, it is recommended that you set this value to something reasonable.

discard

When set to a true value, any messasge sent too soon will be discarded immediately. The default is false.

lingering_interval

The "interval" determines how long the bot must wait before sending a duplicate message text. The lingering interval allows the normal interval to be extended with each new attempt to send the duplicate message text. The extension will occur according to the usual interval, but will not be extended being the values set in fractional seconds on the lingering_interval.

For example, suppose you have interval set to 5 seconds and lingering interval set to 20 seconds. The bot tries to send the message "blah" and then tries again 3 seconds later and then again 6 seconds after the original. Both of these followup attempts will blocked. Assume this continues at 3 second intervals for 60 seconds. All the messages will be blocked except that first message, the message coming at 21 seconds and 42 seconds.

cache_key

The documentation in this module fudges a little in how this works. It's actually more flexible than it might seem. Normally, this send policy works based upon the actual message text sent by the user. However, in some cases this might not be convenient. In case you want to make the send policy depend on some other aspect of the message other than the message text, just replace the default cache_key with a new subroutine.

The given subroutine will be passed a single argument, the options hash reference sent to "allow_send". It must return a string (i.e., whatever is returned will be stringified). That string will be used as the cache key.

This is an advanced feature. If you can't think of a reason why you'd want to use it, you probably don't want to. This is why the rest of the documentation will assumes the message text, but it's really caching according to whatever this little subroutine returns.

send_cache

This is the actual structure used to determine how recently a particular message text was last sent. Each time the send policy is called, it will be purged of any keys that are no longer relevant.

It should be safe to save this structure using JSON or YAML or MongoDB or Storable or whatever you like and load it again, if you want the bot's send_cache to survive restarts. However, the structure itself should be considered opaque and might change in a future release of Bot::Backbone. It may even be removed altogether in a future release since there are lots of handy caching tools on the CPAN that might be used in place of this manual one.

METHODS

purge_send_cache

$self->purge_send_cache;

This method may go away in a future release depending on the fate of "send_cache". In the meantime, however, this method is used clear the send_cache of expired cache keys.

allow_send

This applies the send policy to the message.

AUTHOR

Andrew Sterling Hanenkamp <hanenkamp@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 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.