Perlwikibot/Printable version

From Wikibooks, open books for an open world
Jump to navigation Jump to search


The current, editable version of this book is available in Wikibooks, the open-content textbooks collection, at

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


Original author(s)ST47
Developer(s)The Perlwikibot team
Initial releaseAugust 25, 2007
Stable release5.5.7 / Nov 2013
Written inPerl
LicenseGNU General Public License

What is this thing?[edit | edit source]

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

Does that mean you're trying to make pywikibot obsolete?[edit | edit source]

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?[edit | edit source]

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[edit | edit source]

  • 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[edit | edit source]

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

Installation[edit | edit source]

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 test
sudo make install

Development versions[edit | edit source]

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

 git clone

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

Who wrote perlwikibot?[edit | edit source]

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

Can I help?[edit | edit source]

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


Introduction[edit | edit source]

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[edit | edit source]

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

Comments[edit | edit source]

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

sub foo {
    my $param = shift; # Take the first param
    my @args = @_;     # Take the remaining elements, if any
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[edit | edit source]

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[edit | edit source]

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


Installation[edit | edit source]

There are two ways to install MediaWiki::Bot.

Using CPAN shell (recommended)[edit | edit source]

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[edit | edit source]

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 perlwikibot‐at‐ with the complete output of the test suite and ask for advice.

Dependencies[edit | edit source]

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