User:AnomieBOT/source/d/Talk.pm

package d::Talk;

use utf8;
use strict;
use AnomieBOT::API;

=pod

=head1 NAME

d::Talk - AnomieBOT talkpage utility decorator

=head1 SYNOPSIS

 use AnomieBOT::API;

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

=head1 DESCRIPTION

C<d::Talk> contains various talk page related utility functions for use by an
AnomieBOT task. When "d::Talk" is used as a decorator on the API object, the
following methods are available.

=head1 METHODS PROVIDED

=over

=item $api->whine( $title, $msg )

=item $api->whine( $title, $msg, %options )

If a section with the specified title doesn't exist on the specified page,
create one with the specified C<$msg>. Additional options are:

=over

=item Summary

Edit summary, instead of the default "I<Name> needs human assistance"

=item Pagename

Page to post the message to, instead of the bot's talk page.

=item NoSmallPrint

If true, the small print at the end of the message will be omitted.

=item NoSig

If true, no signature will be appended. You should probably have included the
sig in the message.

=back

Additionally, any options accepted by C<< $api->edittoken() >> are accepted.

This may return anything returnable by C<< $api->edittoken() >> or
C<< $api->edit() >>.

=cut

sub whine {
    my ($api, $title, $msg, %options)=@_;

    $options{'Summary'}=$api->user.' needs human assistance' unless exists($options{'Summary'});
    $options{'Pagename'}='User talk:'.$api->user unless exists($options{'Pagename'});
    $options{'NoSmallPrint'}=0 unless exists($options{'NoSmallPrint'});
    $options{'NoSig'}=0 unless exists($options{'NoSig'});

    my $tok=$api->edittoken($options{'Pagename'}, %options);
    return $tok if($tok->{'code'} ne 'success');
    $title=$api->task.': '.$title;
    $msg.=' ' unless $msg=~/\s$/;
    unless($options{'NoSmallPrint'}){
        $msg.='<small>When you have fixed this issue, please change the section title (e.g. append " - Fixed") or remove this section completely. I will repost the notice if the page is still broken or is re-broken.';
        $msg.=' If you have any questions or comments that my operator should see, please <span class="plainlinks">[https://en.wikipedia.org/w/index.php?title={{subst:FULLPAGENAMEE:User talk:'.$api->user.'}}&action=edit&section=new&preloadtitle=Talkback&preload=Template:Talkback/preload_page&preview=yes#Talkback post a notice]</span> to [[User talk:'.$api->user.']].' if $options{'Pagename'} ne 'User talk:'.$api->user;
        $msg.=' Thanks!</small> ';
    }
    $msg.='~~~~' unless $options{'NoSig'};
    my $txt;
    if(exists($tok->{'missing'})){
        $txt='';
    } else {
        $txt=$tok->{'revisions'}[0]{'slots'}{'main'}{'*'};
        $txt=~s/\s+$//;
        $txt.="\n\n";
        return $tok if(index($txt, "== $title ==")>=0);
    }
    return $api->edit($tok, "$txt== $title ==\n$msg\n", "/* $title */ ".$options{'Summary'}, 0, 0);
}

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.