view release on metacpan or  search on metacpan

lib/Bot/Backbone/SendPolicy/MinimumRepeatInterval.pm  view on Meta::CPAN

            $send{allow} = 0
                if $self->has_queue 
               and $after / $self->interval > $self->queue_length;
        }
    }

    $self->set_last_send_times($key, [ $last_send, $orig_send ]) if $save;
    return \%send;
}

__PACKAGE__->meta->make_immutable;

__END__

=pod

=encoding UTF-8

=head1 NAME

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

=head1 VERSION

version 0.161950

=head1 SYNOPSIS

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

=head1 DESCRIPTION

This send policy will prevent a particular message text from being sent more frequently than the permitted L</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 Wi...

=head1 ATTRIBUTES

=head2 interval

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

=head2 queue_length

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

=head2 discard

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

=head2 lingering_interval

The L</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 accord...

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 attemp...

=head2 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 conveni...

The given subroutine will be passed a single argument, the options hash reference sent to L</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 subro...

=head2 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 L<JSON> or L<YAML> or L<MongoDB> or L<Storable> or whatever you like and load it again, if you want the bot's C<send_cache> to survive restarts. However, the structure itself should be considered opaque ...

=head1 METHODS

=head2 purge_send_cache

  $self->purge_send_cache;

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

=head2 allow_send

This applies the send policy to the message.

=head1 AUTHOR

Andrew Sterling Hanenkamp <hanenkamp@cpan.org>

=head1 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.

=cut