NAME
MediaWiki - OOP MediaWiki engine client
SYNOPSIS
use MediaWiki;
$c = MediaWiki->new;
$c->setup("config.ini");
$whoami = $c->user();
$text = $c->text("page_name_here");
$c->text("page_name_here", "some new text");
$c->refresh_messages();
$msg = $c->message("MediaWiki_message_name");
die unless $c->exists("page_name");
my($articles_p, $subcats_p) = $c->readcat("category_name");
$c->upload("image_name", `cat myfoto.jpg`, "some notes", $force);
$c->block("VasyaPupkin", "2 days");
$c->unblock("VasyaPupkin");
$c->{summary} = "Automatic auto-replacements 1.2";
$c->{minor} = 1;
$c->{watch} = 1;
$pg = $c->random();
$pg = $c->get("page_name");
$pg = $c->get("page_name", "");
$pg = $c->get("page_name", "rw");
$pg->load();
$pg->save();
$pg->prepare();
$text = $pg->oldid($old_version_id);
$text = $pg->content();
$title = $pg->title();
$pg->delete();
$pg->restore();
$pg->protect();
$pg->protect($edit_protection);
$pg->protect($edit_protection, $move_protection);
$pg->move("new_name");
$pg->watch();
$pg->unwatch();
$pg->upload(`cat myfoto.jpg`, "some notes", $force);
$pg->block("2 days");
$pg->unblock();
$pg->history(sub { my $edit_p = shift; } );
$pg->history_clear();
my $edit_p = $pg->last_edit;
$pg->markpatrolled();
$pg->revert();
$pg->{history_step} = 10;
$pg->replace(sub { my $text_p = shift; } );
$pg->remove("some_regex_here");
$pg->remove_template("template_name");
$pg->{content} = "new text";
$pg->{summary} = "do something strange";
$pg->{minor} = 0;
$pg->{watch} = 1;Functions and options
Client object (MediaWiki) functions
MediaWiki->new()
Performs basic initialization of the client structure. Returns client object.
$c->setup([ $ini_file_name ])
Reads configuration file in INI format; also performs login if username and password are specified. If file name is omited, "~/.bot.ini is used.
Configuration file can use [bot], [wiki] and [tmp] sections. Keys 'user' and 'pass' in 'bot' section specify login information. 'wiki' section must have 'host' and 'path' keys (for example, host may be 'en.wikipedia.org' and path may be 'w') which specify path to index.php script. There is also optional parameter in 'wiki' scope, 'special', which should contain localized name of 'Special' namespace (only if default value is being overwritten). This is needed for image upload feature. Section 'tmp' and key 'msgcache' specify path to the MediaWiki messages cache.
$c->login([$user [, $password]])
Performs login if no login information was specified in configuration. Called automatically from setup().
$c->user()
Returns username from configuration file or makes a dummy edit in wiki sandbox to get client IP from page history. Note: no result caching is done.
$c->text( $page_name [, $new_text ])
If $new_text is specified, replaces content of $page_name article with $new_text. Returns current revision text otherwise.
$c->refresh_messages()
Downloads all MediaWiki messages and saves to messages cache.
$c->message($message_name)
Returns message from cache or undef it cache entry not exists. When no cache is present at all this functions downloads only one message (but caches it).
$c->exists($page_name)
Returns true value if page exists.
$c->readcat($category_name);
Returns two array references, first with names of all articles, second with names of all subcategories (without 'Category:' namespace prefix).
$c->upload($image_name, $content [, $description [, $force]]);
Uploads an image with name 'Image:$image_name' and with content $content. If description is not specified, empty string will be used. Force flag may be set to 1 to disable warnings. Currently warnings are not handled properly (see "LIMITATIONS"), so force=1 is recommended. That's not default because each rewriting of the image creates new version, no matter are there any differences or not. If you never rewrite image, feel free to set $force to 1.
$c->filepath($image_name)
Returns direct URL for downloading raw image $image_name or undef if image not exists.
$c->download($image_name)
Returns content of $image_name image or undef if not exists.
$c->block($user_name, $block_time)
Blocks specified user from editing. Block time should be in format [0-9]+ (seconds|minutes|hours|days|months|years) or in ctime format.
Note: this operation requires sysop rights.
$c->unblock($user_name)
Unblocks specified user.
Note: this operation requires sysop rights.
$c->random()
Returns page handle for random article (page in namespace 0).
$c->get($page [, $mode])
Returns page handle for specified article. Mode parameter may be "", "r", "w" or "rw" (default "r"). If there is no 'r' in mode, no page content will be fetched.
If there is 'w' flag, page is loaded in Prepared Load Mode. There're some options in edit form required for saving page. When using prepared loading, text is fetched from edit form (not from raw page) with this values. This reduces traffic usage. For normal editing, edit form is loaded before saving.
Note: prepared mode is toggled off after first saving.
Client object (MediaWiki) options
$c->{minor}
If not set, default value for account will be used. If set to 0, major edits are made, it set to 1 - minor edits.
$c->{watch}
If set to 1, edited pages will be included to watch list. If not set, account default will be used; 0 disables adding to list.
$c->{summary}
Short description used by default for all edits.
Page object (MediaWiki::page) functions
$pg->load()
Loads page content.
$pg->save()
Saves changes to this page.
$pg->prepare()
Performs prepared load (do not use this function directly).
$pg->content()
Returns page content.
$pg->oldid($id)
Returns content of an old revision.
$pg->title()
Returns page title.
$pg->delete()
Deletes this page.
Note: this operation requires sysop rights.
$pg->restore()
Restores recently deleted page.
Note: this operation requires sysop rights.
$pg->protect([$edit_mode [, $move_mode]])
Protects page from edits and/or moves. Protection modes: 2 - for sysop only, 1 - for registered users only, 0 - default, means no protection. If no parameters specified, protects against anonymous edits. If only first parameter specified, move mode will be set to same value.
In order to unprotect page, use $pg-protect(0)>.
$pg->move($new_name)
Renames page setting new title to $new_name and creating redirect in place of old article. This is only possible if target article not exists or is redirect without non-redirect versions.
$pg->watch([$unwatch])
Adds page to watch list. If $unwatch is set, removes page from watch list
$pg->unwatch()
Synonym for $pg->watch(1)
$pg->upload($content, [, $description [, $force]])
See $c->upload
$pg->filepath()
See $c->filepath
$pg->download()
See $c->download()
$pg->block($block_time)
See $c->block
$pg->unblock()
See $c->unblock
$pg->history(&cb)
Iterates callback through page history. One parameter is passed, edit info (this is hash reference). Callback should return undef to continue listing of true value to stop it. Returns this true value or undef if all edits listed without interrupting.
Hash reference has the following keys: page - pointer to page handler ($pg) oldid - revision identifier (may be used in call to $pg->oldid()) user - username or ip anon - is 1 if 'user' contains IP address minor - is 1 if this is minor edit comment - contains short comment section - contains section name (so-called autocomment) time - edit time (in format 'HH:MM') date - edit date (in format 'D MONTH YYYY') datetime - contains time and date separated by ', '
Note: this function used the same history cache as last_edit(), revert() etc.
$pg->history_clear()
Clear history cache. This is done automatically when page is modified.
$pg->last_edit()
Return structure of the last edit
$pg->markpatrolled()
Mark latest revision of this page as checked by administrator. This is experimental option and may not present in many MediaWiki installations.
Note: this operation requires sysop rights.
$pg->revert()
Reverts all changes made by last user who edited this page. This functions not uses admin quick-revert interface and can be run by anybody.
Note: MediaWiki message 'Revertpage' will be used as summary.
$pg->replace(&cb)
This is most common implementation of replacements bot. It splits wiki-code to parts which may and which should not be affected (for example, inside pre/nowiki/math tags) and runs callback for each allowed part. Callback gets pointer to text as parameter and may change it (and may not change). If text was not change after work of all callbacks, it will not be saved (this is checked at client-side - that reduces traffic usage).
Note: If page has '{{NO_BOT_TEXT_PROCESSING}}' template, no changes will be done.
$pg->remove($regex)
This function removes all matches against regex specified.
$pg->remove_template($template_name)
This function is wrapper for remove. It removes all matches of template specified.
Page object (MediaWiki::page) options
$pg->{content}
Raw page content. This is needed to set new content for article.
$pg->{minor}
See $c->{minor} - local setting (only for this page handle).
$pg->{watch}
See $c->{watch} - local setting (only for this page handle).
$pg->{summary}
See $c->{summary} - local setting (only for this page handle).
$pg->{history_step}
Number of edits fetched in one time. This field can be used for task-related optimization (increasing it decrease traffic usage and servers load). Default 50.
EXAMPLE
All examples start with
use MediaWiki;
my $c = MediaWiki->new();
$c->setup();Very easy example: creating prepared articles
opendir D, "articles";
while(defined ($file = readdir(D)))
{
if(($file =~ s/\.txt$//) == 1)
{
my $text;
open F, "$file.txt";
read F, $text, -s F;
close F;
$c->text($file, $text);
}
}
closedir D;Easy example: replacements bot
for(my $i = 0; $i < 10000; $i ++)
{
my $pg = $c->random();
$pg->replace(\&my_replacements);
}More complex example: anti-vandalism bot
$c->{summary} = "Vandalism: blanking more than 5 times";
my %users = (); my %articles = ();
while(1)
{
my $pg = $c->random();
if($pg->content() eq '')
{
my $e = $pg->last_edit;
$blanker = $e->{user};
$pg->revert();
$e = $pg->last_edit;
if($e->{user} eq $blanker) # Only author
{
$pg->{content} .= "{{db-author}}"; # Delete note for admins
$pg->{summary} = "+ {{db-author}}"
$pg->save();
}
else
{
$users{$blanker} = 1 + (exists $users{$blanker} ? $users{$blanker} : 0);
if($users{$blanker} > 5)
{
$c->block($blanker, "1 hour");
delete $users{$blanker};
}
}
}
}LIMITATIONS
- No advanced errors handling available (only true/false return values). Image upload warnings are not being checked.
AUTHOR
Edward Chernenko <edwardspec@gmail.com>
COPYRIGHT
Copyright (C) 2006 Edward Chernenko. This program is protected by Artistic License and can be used and/or distributed by the same rules as perl. All right reserved.