# Perlwikibot/Printable version

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

# Overview
## 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:
Or download from and install it like you would any other Perl module:

### Development versions

The latest unstable source code can be acquired from the github repo.
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.

#### good
### Perltidy

Perltidy is a code indenter and formatter. You can use it to help clean up your Perl code. For perlwikibot, use:
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:

## 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:
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:
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