User:AnomieBOT/source/d/Trial.pm

package d::Trial;

use utf8;
use strict;
use AnomieBOT::API;
use POSIX;
AnomieBOT::API::load('d::Talk');

use vars qw/@ISA/;
@ISA=qw/d::Talk/;

=pod

=head1 NAME

d::Trial - AnomieBOT trial utility decorator

=head1 SYNOPSIS

 use AnomieBOT::API;

 $api = new AnomieBOT::API('conf.ini', 1);
 $api->decorators(qw/d::Trial/);

=head1 DESCRIPTION

C<d::Trial> contains utility functions for use by an AnomieBOT task in trial.
When "d::Trial" is used as a decorator on the API object, the following methods
are available.

In addition, all A<d::Talk> methods are also available, as this decorator uses
them internally.

=head1 METHODS PROVIDED

=over

=item $api->check_trial( $until, $brfa )

Checks if the current timestamp is past the C<$until> timestamp. If not,
returns false; if so, whines to the bot talk page and returns a scalar ref that
should be dereferenced and returned.

=cut

sub check_trial {
    my $api=shift;
    my $until=shift;
    my $brfa=shift;

    return 0 if time<$until;
    my $res=$api->whine("Trial complete!", "This task was in trial until ".POSIX::strftime("%F %T (UTC)", gmtime $until).", which has now passed. Please stop the task and report the completion of the trial at [[Wikipedia:Bots/Requests for approval/$brfa]]. Thanks.", Summary => "Trial complete!");
    return (($res->{'code'} eq 'success')?\undef:\60);
}

=pod

=item $api->trial_complete( $brfa )

Whines to the bot talk page and returns a value that should be returned.

=cut

sub trial_complete {
    my $api=shift;
    my $brfa=shift;

    my $res=$api->whine("Trial complete!", "This trial for this task is now complete. Please stop the task and report the completion of the trial at [[Wikipedia:Bots/Requests for approval/$brfa]]. Thanks.", Summary => "Trial complete!");
    return (($res->{'code'} eq 'success')?undef:60);
}

1;

=pod

=back

=head1 COPYRIGHT

Copyright 2008–2013 Anomie

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