Perlwikibot

The current, editable version of this book is available in Wikibooks, the open-content textbooks collection, at
https://en.wikibooks.org/wiki/Perlwikibot

Permission is granted to copy, distribute, and/or modify this document under the terms of the Creative Commons Attribution-ShareAlike 3.0 License.

Overview

Perlwikibot
Original author(s)	ST47
Developer(s)	The Perlwikibot team
Initial release	August 25, 2007
Stable release	5.5.7 / Nov 2013
Written in	Perl
License	GNU General Public License
Website	http://perlwikipedia.googlecode.com

What is this thing?

Perlwikibot is a bot framework, similar to Pywikibot, except it's written in Perl.

Does that mean you're trying to make pywikibot obsolete?

Of course not! Pywikibot is a valuable bot framework (the Tawkerbot2 code, as well as most major bots, are written using it), however, if Perl coders are confined to using Python, they can't customize and extend the code to fit their needs. With an open-source framework written in their "native language," they'll be able to better write bots in a language that they are comfortable with, and even customize the framework to fit needs it wasn't originally imagined for.

How complete is perlwikipedia?

Perlwikibot is almost completely cross-wiki, so you can write bots for virtually any MediaWiki wiki with it. As of version 5.005007, Perlwikibot does not support WikiData-specific queries or edits.

Editing and querying wikis

Retrieve the wikitext of articles, sections, and old revisions
Edit pages
Retrieve the history of articles
Revert to old revisions of articles (manually, with undo, or with rollback)
Retrieve the Recent Changes log
Retrieve backlinks and transclusions
Purge page caches
Retrieve a listing of all pages in a category
Run linksearches

Admin functions

Deleting and undeleting pages
Blocking and unblocking users
Protecting and unprotecting pages
Performing transwiki imports (XML upload is in the works)

Installation

The latest stable version can be installed from CPAN:

user@host:~$ cpan
cpan> install MediaWiki::Bot
...

Or download from [1] and install it like you would any other Perl module:

perl Makefile.PL
make
make test
sudo make install

Development versions

The latest unstable source code can be acquired from the github repo.

 git clone https://github.com/MediaWiki-Bot/MediaWiki-Bot.git

Unlike pywikibot, we do not recommend using the unstable source tree for production.

Who wrote perlwikibot?

perlwikibot is maintained by ST47, Shadow1, Jmax-, Oleg Alexandrov, and Mike.lifeguard.

Can I help?

Sure! Check out the OpenHatch page for ways to get started, or jump into the list of issues and start hacking!

Contributing

Introduction

Perlwikibot is an open-source project which aims to create a complete framework for rapidly creating and deploying computer programs which can perform common repetitive tasks on MediaWiki wikis. These clients are typically called 'bots' - hence the project name.

You can help fix bugs or add new functionality to the framework. The code is licensed under the GNU General Public License. In short, this means anyone may use the code for any purpose, including commercial use, and including making and distributing modified versions so long as they provide attribution and all derivative versions are also licensed under the GPL.

Code style

Perl code is hard enough to read already, so try to make an effort to write readable code.

Comments

Comments should be included wherever the code does something that isn't obvious.

bad

sub foo {
    my $param = shift; # Take the first param
    my @args = @_;     # Take the remaining elements, if any
}

good

sub bar {
    my $param = shift; # The page to edit
    my @args  = @_;    # Contains any other settings (for example, whether to mark the edit as minor)
}

Perltidy

Perltidy is a code indenter and formatter. You can use it to help clean up your Perl code. For perlwikibot, use:

-syn    # Syntax check input and output
-b      # Backup and modify in-place
-l=78   # Max line width is 78 cols
-i=4    # Indent level is 4 cols
-ci=4   # Continuation indent is 4 cols
-vt=0   # Minimum vertical tightness
-vtc=0  # Minimum vertical tightness closing
-cti=0  # No extra indentation for closing brackets
-pt=2   # Maximum parenthesis tightness
-sbt=2  # Maximum square bracket tightness
-bt=1   # Medium brace tightness
-nsfs   # No space before semicolons
-nolq   # Don't outdent long quoted strings
-boc    # Break at old comma breakpoints
-bbs    # Blank line before subs
-sot    # Stack opening tokens
-sct    # Stack closing tokens
-bbao   # Break before all operators

You can put this in .perltidyrc, and they'll be used every time you use perltidy. Put the file in your working directory to apply only to that directory, or in your $HOME to use the settings for everything.

Alternatively, set each option as a command line option to perltidy:

user@host:~$ perltidy -syn -b -l=78 ...

Committing

Mike pushes his git repo to github; to contribute, make a fork, make your changes, and make a new pull request.

Installing

Installation

There are two ways to install MediaWiki::Bot.

Using CPAN shell (recommended)

If you use the CPAN shell to install MediaWiki::Bot, the entire process is automated:

   user@host:~$ sudo -i
   root@host:~# cpan
   cpan> install MediaWiki::Bot
   ...

You might have CPAN configured such that you don't need to become root initially.

Manual

Otherwise, you can install it manually. First install the dependencies (listed below), then install MediaWiki::Bot. To install this module type the following in the root directory or a checkout from SVN or an unpacked tarball:

  user@host:~$ perl Makefile.PL
  user@host:~$ make
  user@host:~$ make test
  user@host:~$ sudo make install

You might use other methods to become root instead of sudo.

The test scripts included with MediaWiki::Bot require a working internet connection. If the test suite fails, it might be safe to install the module anyway. When in doubt, email perlwikibotgooglegroups.com with the complete output of the test suite and ask for advice.

Dependencies

This module requires these other modules and libraries:

WWW::Mechanize
HTML::Entities
URI::Escape
XML::Simple
Carp
Encode
MediaWiki::API
Module::Pluggable
Crypt::SSLeay
Digest::MD5