File Coverage

blib/lib/MediaWiki/EditFramework.pm

Criterion	Covered	Total	%
statement	28	43	65.1
branch	2	10	20.0
condition	0	3	0.0
subroutine	9	13	69.2
pod	6	6	100.0
total	45	75	60.0

=head1 NAME

MediaWiki::EditFramework - a framework for editing MediaWiki pages.

=head1 SYNOPSIS

 use MediaWiki::EditFramework;

 my $wiki = MediaWiki::EditFramework->new('example.com', 'wiki');
 my $page = $wiki->get_page('Main_Page');
 my $text = $page->get_text;
 $text =~ s/old thing/new update/g;
 $page->edit($text, 'update page');

=head2 DESCRIPTION

This is a higher level framework for editing MediaWiki pages.  It depends on
another module for lower level API access, and doesn't provide functionality
unrelated to editing.  By using a higher-level abstraction layer in scripts,
it becomes simpler to change out backend modules as needed.

This is the framework that I've been using for the past few years to run an
archiving bot.  The main features that it has over lower-level frameworks
are:

=over

=item *

Pages are represented as objects.

This allows the page to store additional information, such as the last
updated timestamp when they were retrieved.  The timestamp is then passed
back to the server when the page is edited, to allow it to properly detect
edit conflicts.

=item *

The module supports specified a write_prefix, which is appended to pages
titles when editing a page.

This makes it easier to create a test mode for a bot script.  By specifying
the write prefix in your own user space, the bot will retrieve the normal
pages, but the modifications will be written to user space so you can review
them without impacting others.

=back

=cut

package MediaWiki::EditFramework;

use strict;
use warnings;

use Carp;
use MediaWiki::API;
use Data::Dumper;
use MediaWiki::EditFramework::Page;
use strict;

our $VERSION = '0.02';
our $ABSTRACT = 'framework for editing MediaWiki pages';

=head2 CONSTRUCTOR

=over

=item B(I,I)

Create a new instance pointing to the specified I and I (default
I).  The underling API object points to http://I/I/api.php.

=back

=head2 METHODS

=over

=cut

sub new ($;$$) {
    my ($class,$site,$path)=@_;
    my $mw = MediaWiki::API->new();
    if (defined $site) {
	$path = 'w' unless defined $path;
	$mw->{config}->{api_url} = "http://$site/$path/api.php";
    }
    #$mw->{ua}->cookie_jar({file=>"$ENV{HOME}/.cookies.txt", autosave=>1});
    bless {0=>$mw, write_prefix=>''}, $class;
}

=item B(I)

Passes I to L's I method, to store cookies
for a persistent login.

=cut

sub cookie_jar( $$ ) {
    #temporary method for persistent login.
    my $self = shift;
    my $file = shift;
    $self->{0}{ua}->cookie_jar($file, autosave=>1);
}

=item B(I,I)

Log in the specified I.

=cut

sub login ($$$) {
    my ($self,$user,$pass) = @_;
    my $mw = $self->{0};

    my $state = $mw->api({ action=>'query', meta=>'userinfo', });

    if (
	 ! exists $state->{query}{userinfo}{anon}
	and
	$state->{query}{userinfo}{name} eq $user
	){
	warn "already logged in as $user";
    } else {
	$mw->login( { lgname => $user, lgpassword => $pass } )
	    or confess $mw->{error}->{code} . ': ' .
	    Dumper($mw->{error}->{details});
    }
}


=item B(I) </td>
</tr>

<tr>
<td  class="h" >
<a name="134">134</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">   </td>
</tr>

<tr>
<td  class="h" >
<a name="135">135</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> Get the wiki page with the specified I<TITLE>.  Returns an instance of </td>
</tr>

<tr>
<td  class="h" >
<a name="136">136</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> L<MediaWiki::EditFramework::Page>, which has methods to get/edit the page text. </td>
</tr>

<tr>
<td  class="h" >
<a name="137">137</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">   </td>
</tr>

<tr>
<td  class="h" >
<a name="138">138</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> =cut </td>
</tr>

<tr>
<td  class="h" >
<a name="139">139</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">   </td>
</tr>

<tr>
<td  class="h" >
<a name="140">140</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> sub get_page( $$ ) { </td>
</tr>

<tr>
<td  class="h" >
<a name="141">141</a>
</td>

<td  class="c3" >

2

</td>

<td >

 

</td>

<td >

 

</td>

<td  class="c3" >
 <a href="blib-lib-MediaWiki-EditFramework-pm--subroutine.html#141-1"> 
2
 </a> 
</td>

<td  class="c3" >
 <a href="blib-lib-MediaWiki-EditFramework-pm--subroutine.html#141-1"> 
1
 </a> 
</td>

<td >

19

</td>

<td class="s">     MediaWiki::EditFramework::Page->new(@_); </td>
</tr>

<tr>
<td  class="h" >
<a name="142">142</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> }; </td>
</tr>

<tr>
<td  class="h" >
<a name="143">143</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">   </td>
</tr>

<tr>
<td  class="h" >
<a name="144">144</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> =item B<create_page>(I<TITLE>) </td>
</tr>

<tr>
<td  class="h" >
<a name="145">145</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">   </td>
</tr>

<tr>
<td  class="h" >
<a name="146">146</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> Get the wiki page with the specified I<TITLE>; then croak if it already </td>
</tr>

<tr>
<td  class="h" >
<a name="147">147</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> exists. </td>
</tr>

<tr>
<td  class="h" >
<a name="148">148</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">   </td>
</tr>

<tr>
<td  class="h" >
<a name="149">149</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> =cut </td>
</tr>

<tr>
<td  class="h" >
<a name="150">150</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">   </td>
</tr>

<tr>
<td  class="h" >
<a name="151">151</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> sub create_page( $$ ) { </td>
</tr>

<tr>
<td  class="h" >
<a name="152">152</a>
</td>

<td  class="c0" >

0

</td>

<td >

 

</td>

<td >

 

</td>

<td  class="c0" >
 <a href="blib-lib-MediaWiki-EditFramework-pm--subroutine.html#152-1"> 
0
 </a> 
</td>

<td  class="c3" >
 <a href="blib-lib-MediaWiki-EditFramework-pm--subroutine.html#152-1"> 
1
 </a> 
</td>

<td >

 

</td>

<td class="s">     my $page = MediaWiki::EditFramework::Page->new(@_); </td>
</tr>

<tr>
<td  class="h" >
<a name="153">153</a>
</td>

<td  class="c0" >

0

</td>

<td  class="c0" >
 <a href="blib-lib-MediaWiki-EditFramework-pm--branch.html#153-1"> 
  0
 </a> 
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">     croak "$_[1]: exists" if $page->exists; </td>
</tr>

<tr>
<td  class="h" >
<a name="154">154</a>
</td>

<td  class="c0" >

0

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">     return $page; </td>
</tr>

<tr>
<td  class="h" >
<a name="155">155</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> }; </td>
</tr>

<tr>
<td  class="h" >
<a name="156">156</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">   </td>
</tr>

<tr>
<td  class="h" >
<a name="157">157</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> =item B<write_prefix>(I<PREFIX>) </td>
</tr>

<tr>
<td  class="h" >
<a name="158">158</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">   </td>
</tr>

<tr>
<td  class="h" >
<a name="159">159</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> When writing pages, prepend the specified I<PREFIX> to the page title. </td>
</tr>

<tr>
<td  class="h" >
<a name="160">160</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">   </td>
</tr>

<tr>
<td  class="h" >
<a name="161">161</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> This makes it easier to create a test mode for a bot script.  By specifying </td>
</tr>

<tr>
<td  class="h" >
<a name="162">162</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> the write prefix in your own user space, the bot will retrieve the normal </td>
</tr>

<tr>
<td  class="h" >
<a name="163">163</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> pages, but the modifications will be written to user space so you can review </td>
</tr>

<tr>
<td  class="h" >
<a name="164">164</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> them without impacting others. </td>
</tr>

<tr>
<td  class="h" >
<a name="165">165</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">   </td>
</tr>

<tr>
<td  class="h" >
<a name="166">166</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> =cut </td>
</tr>

<tr>
<td  class="h" >
<a name="167">167</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">   </td>
</tr>

<tr>
<td  class="h" >
<a name="168">168</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> sub write_prefix { </td>
</tr>

<tr>
<td  class="h" >
<a name="169">169</a>
</td>

<td  class="c0" >

0

</td>

<td >

 

</td>

<td >

 

</td>

<td  class="c0" >
 <a href="blib-lib-MediaWiki-EditFramework-pm--subroutine.html#169-1"> 
0
 </a> 
</td>

<td  class="c3" >
 <a href="blib-lib-MediaWiki-EditFramework-pm--subroutine.html#169-1"> 
1
 </a> 
</td>

<td >

 

</td>

<td class="s">     my $self = shift; </td>
</tr>

<tr>
<td  class="h" >
<a name="170">170</a>
</td>

<td  class="c0" >

0

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">     my $prefix = shift; </td>
</tr>

<tr>
<td  class="h" >
<a name="171">171</a>
</td>

<td  class="c0" >

0

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">     $self->{write_prefix} = $prefix; </td>
</tr>

<tr>
<td  class="h" >
<a name="172">172</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> } </td>
</tr>

<tr>
<td  class="h" >
<a name="173">173</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">   </td>
</tr>

<tr>
<td  class="h" >
<a name="174">174</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> =back </td>
</tr>

<tr>
<td  class="h" >
<a name="175">175</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">   </td>
</tr>

<tr>
<td  class="h" >
<a name="176">176</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> =head1 SEE ALSO </td>
</tr>

<tr>
<td  class="h" >
<a name="177">177</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">   </td>
</tr>

<tr>
<td  class="h" >
<a name="178">178</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> L<MediaWiki::API> </td>
</tr>

<tr>
<td  class="h" >
<a name="179">179</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">   </td>
</tr>

<tr>
<td  class="h" >
<a name="180">180</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> =head1 COPYRIGHT </td>
</tr>

<tr>
<td  class="h" >
<a name="181">181</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">   </td>
</tr>

<tr>
<td  class="h" >
<a name="182">182</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> Copyright (C) 2012 by Steve Sanbeg </td>
</tr>

<tr>
<td  class="h" >
<a name="183">183</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">   </td>
</tr>

<tr>
<td  class="h" >
<a name="184">184</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> This library is free software; you can redistribute it and/or modify </td>
</tr>

<tr>
<td  class="h" >
<a name="185">185</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> it under the same terms as Perl itself, either Perl version 5.10.1 or, </td>
</tr>

<tr>
<td  class="h" >
<a name="186">186</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> at your option, any later version of Perl 5 you may have available. </td>
</tr>

<tr>
<td  class="h" >
<a name="187">187</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">   </td>
</tr>

<tr>
<td  class="h" >
<a name="188">188</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> =cut </td>
</tr>

<tr>
<td  class="h" >
<a name="189">189</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s">   </td>
</tr>

<tr>
<td  class="h" >
<a name="190">190</a>
</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td >

 

</td>

<td class="s"> 1; </td>
</tr>

</table>

</body>
</html>