Provided by: libwww-mediawiki-client-perl_0.31-2_all 
NAME
WWW::Mediawiki::Client - module providing a VCS like to MediaWiki
SYNOPSIS
use WWW::Mediawiki::Client;
my $filename = 'Subject.wiki';
my $mvs = WWW::Mediawiki::Client->new(
host => 'www.wikitravel.org'
);
# like cvs update
$mvs->do_update($filename);
# like cvs commit
$mvs->do_commit($filename, $message);
#aliases
$mvs->do_up($filename);
$mvs->do_com($filename, $message);
DESCRIPTION
WWW::Mediawiki::Client provides a very simple cvs-like interface for Mediawiki driven
WikiWiki websites, such as <http://www.wikitravel.org|Wikitravel> or
<http://www.wikipedia.org|Wikipedia.> The interface mimics the two most basic cvs
commands: update and commit with similarly named methods. Each of these has a shorter
alias, as in cvs.
CONSTANTS
$VERSION
Update Status
STATUS_UNKNOWN
Indicates that "WWW::Mediawiki::Client" has no information about the file.
STATUS_UNCHANGED
Indicates that niether the file nor the server page have changed.
STATUS_LOCAL_ADDED
Indicates that the file is new locally, and does not exist on the server.
STATUS_LOCAL_MODIFIED
Indicates that the file has been modified locally.
STATUS_SERVER_MODIFIED
Indicates that the server page was modified, and that the modifications have been
successfully merged into the local file.
STATUS_CONFLICT
Indicates that there are conflicts in the local file resulting from a failed merge between
the server page and the local file.
Option Settings
OPT_YES
Indicates that the setting should always be applied.
OPT_NO
Indicates that the setting should never be applied.
OPT_DEFAULT
Indicates that the setting should be applied based on the user profile default on the
Wikimedia server.
OPT_KEEP
Four-state options only. Indicates that the setting should not be changed from its
current value on the server.
Mediawiki form widgets
TEXTAREA_NAME
COMMENT_NAME
EDIT_SUBMIT_NAME
EDIT_SUBMIT_VALUE
EDIT_PREVIEW_NAME
EDIT_PREVIEW_VALUE
EDIT_TIME_NAME
EDIT_TOKEN_NAME
EDIT_WATCH_NAME
EDIT_MINOR_NAME
CHECKED
UNCHECKED
USERNAME_NAME
PASSWORD_NAME
REMEMBER_NAME
LOGIN_SUBMIT_NAME
LOGIN_SUBMIT_VALUE
Files
CONFIG_FILE
.mediawiki
COOKIE_FILE
.mediawiki.cookies
SAVED_ATTRIBUTES
Controls which attributes get saved out to the config file.
CONSTRUCTORS
new
my $mvs = WWW::Mediawiki::Client->new(host = 'www.wikitravel.org');
Accepts name-value pairs which will be used as initial values for any of the fields which
have accessors below. Throws the same execptions as the accessor for any field named.
ACCESSORS
host
my $url = $mvs->host('www.wikipediea.org');
my $url = $mvs->host('www.wikitravel.org');
The "host" is the name of the Mediawiki server from which you want to obtain content, and
to which your submissions will be made. There is no default. This has to be set before
attempting to use any of the methods which attempt to access the server.
Side Effects:
Server defaults
If WWW::Mediawiki::Client knows about the path settings for the Mediawiki installation
you are trying to use then the various path fields will also be set as a side-effect.
Trailing slashes
Any trailing slashes are deleted before the value of "host" is set.
protocol
my $url = $mvs->protocol('www.wikipediea.org');
my $url = $mvs->protocol('www.wikitravel.org');
The "protocol" is the protocol used by the Mediawiki server from which you want to obtain
content, and to which your submissions will be made. It can be one of "http" or "https"
with the default value being http.
Side Effects:
Server defaults
If WWW::Mediawiki::Client knows about the settings for the Mediawiki installation you
are trying to use then the various path fields will also be set as a side-effect.
language_code
my $lang = $mvs->language_code($lang);
Most Mediawiki projects have multiple language versions. This field can be set to target
a particular language version of the project the client is set up to address. When the
"filename_to_url" and "pagename_to_url" methods encounter the text '__LANG__' in any part
of their constructed URL the "language_code" will be substituted.
"language_code" defaults to 'en'.
space_substitute
my $char = $mvs->space_substitute($char);
Mediawiki allows article names to have spaces, for instance the default Meidawiki main
page is called "Main Page". The spaces need to be converted for the URL, and to avoid the
normal but somewhat difficult to read URL escape the Mediawiki software substitutes some
other character. Wikipedia uses a '+', as in "Main+Page" and Wikitravel uses a '_' as in
"Main_page". WWW::Mediawiki::Client always writes wiki files using the '_', but converts
them to whatever the "space_substitute" is set to for the URL.
Throws:
WWW::Mediawiki::Client::URLConstructionException
escape_filenames
my $char = $mvs->escape_filenames($do_escape);
Mediawiki allows article names to be in UTF-8 and most international Wikipedias use this
feature. That leads us to UTF-8 encoded file names and not all filesystems can handle
them. So you can set this option to some true value to make all your local file names with
wiki articles URL-escaped.
wiki_path
my $path = $mvs->wiki_path($path);
"wiki_path" is the path to the php page which handles all request to edit or submit a
page, or to login. If you are using a Mediawiki site which WWW::Mediawiki::Client knows
about this will be set for you when you set the "host". Otherwise it defaults to the
'wiki/wiki.phtml' which is what you'll get if you follow the installation instructions
that some with Mediawiki.
Side effects
Leading slashes
Leading slashes in any incoming value will be stripped.
encoding
my $encoding = $mvs->encoding($encoding);
"encoding" is the charset in which the Mediawiki server expects uploaded content to be
encoded. This should be set the first time you use do_login.
username
my $url = $mvs->username($url);
The username to use if WWW::Mediawiki::Client is to log in to the Mediawiki server as a
given user.
password
my $url = $mvs->password($url);
The password to use if WWW::Mediawiki::Client is to log in to the Mediawiki server as a
given user. Note that this password is sent en clair, so it's probably not a good idea to
use an important one.
commit_message
my $msg = $mvs->commit_message($msg);
A "commit_message" must be specified before "do_commit" can be run. This will be used as
the comment when submitting pages to the Mediawiki server.
watch
my $watch = $mvs->watch($watch);
Mediawiki allows users to add a page to thier watchlist at submit time using using the
"Watch this page" checkbox. The field "watch" allows commits from this library to add or
remove the page in question to/from your watchlist.
This is a four-state option:
"OPT_YES"
Always add pages to the watchlist.
"OPT_NO"
Remove pages from the watchlist.
"OPT_KEEP"
Maintain current watched state.
"OPT_DEFAULT" (default)
Adhere to user profile default on the server. Watched pages will always remain
watched, and all other pages will be watched if the "watch all pages by default"
option is enabled in the user profile.
Throws:
WWW::Mediawiki::Client::InvalidOptionException
minor_edit
my $minor = $mvs->minor_edit($minor);
Mediawiki allows users to mark some of their edits as minor using the "This is a minor
edit" checkbox. The field "minor_edit" allows a commit from the mediawiki client to be
marked as a minor edit.
This is a three-state option:
"OPT_YES"
Always declare change as minor.
"OPT_NO"
Never declare change as minor.
"OPT_DEFAULT" (default)
Adhere to user profile default on the server. Edits will be marked as minor if the
"minor changes by default" option is enabled in the user profile.
Throws:
WWW::Mediawiki::Client::InvalidOptionException
status
my %status = $mvs->status;
This field will be empty until do_update has been called, after which it will be set to a
hash of "filename" => "status" pairs. Each "status" will be one of the following (see
CONSTANTS for discriptions):
WWW::Mediawiki::Client::STATUS_UNKNOWN;
WWW::Mediawiki::Client::STATUS_UNCHANGED;
WWW::Mediawiki::Client::STATUS_LOCAL_ADDED;
WWW::Mediawiki::Client::STATUS_LOCAL_MODIFIED;
WWW::Mediawiki::Client::STATUS_SERVER_MODIFIED;
WWW::Mediawiki::Client::STATUS_CONFLICT;
site_url DEPRICATED
my $url = $mvs->site_url($url);
The site URL is the base url for reaching the Mediawiki server who's content you wish to
edit. This field is now depricated in favor of the "host" field which is basically the
same thing without the protocol string.
Side Effects:
Server defaults
If WWW::Mediawiki::Client knows about the path settings for the Mediawiki installation
you are trying to use then the various path fields will also be set as a side-effect.
Trailing slashes
Any trailing slashes are deleted before the value of "site_url" is set.
Instance Methods
do_login
$mvs->do_login;
The "do_login" method operates like the cvs login command. The "host", "username", and
"password" attributes must be set before attempting to login. Once "do_login" has been
called successfully any successful commit from the same directory will be logged in the
Mediawiki server as having been done by "username".
Throws:
WWW::Mediawiki::Client::AuthException
WWW::Mediawiki::Client::CookieJarException
WWW::Mediawiki::Client::LoginException
WWW::Mediawiki::Client::URLConstructionException
do_li
$mvs->do_li;
An alias for "do_login".
do_update
$self->do_update($filename, ...);
The "do_update" method operates like a much-simplified version of the cvs update command.
The argument is a list of filenames, whose contents will be compared to the version on the
WikiMedia server and to a locally stored reference copy. Lines which have changed only in
the server version will be merged into the local version, while lines which have changed
in both the server and local version will be flagged as possible conflicts, and marked as
such, somewhate in the manner of cvs (actually this syntax comes from the default conflict
behavior of VCS::Lite):
********************Start of conflict 1 Insert to Primary, Insert to Secondary ************************************************************
The line as it appears on the server
****************************************************************************************************
The line as it appears locally
********************End of conflict 1********************************************************************************
After the merging, and conflict marking is complete the server version will be copied into
the reference version.
If either the reference version or the local version are empty, or if either file does not
exist they will both be created as a copy of the current server version.
Throws:
WWW::Mediawiki::Client::URLConstructionException
WWW::Mediawiki::Client::FileAccessException
WWW::Mediawiki::Client::FileTypeException
WWW::Mediawiki::Client::ServerPageException
WWW::Mediawiki::Client::AbsoluteFileNameException
do_up
An alias for "do_update".
do_commit
$self->do_commit($filename);
As with "do_update" the "do_commit" method operates like a much simplified version of the
cvs commit command. Again, the argument is a filename. In keeping with the operation of
cvs, "do_commit" does not automatically do an update, but does check the server version
against the local reference copy, throwing an error if the server version has changed,
thus forcing the user to do an update. A different error is thrown if the conflict
pattern sometimes created by "do_update" is found.
After the error checking is done the local copy is submitted to the server, and, if all
goes well, copied to the local reference version.
Throws:
WWW::Mediawiki::Client::CommitMessageException
WWW::Mediawiki::Client::ConflictsPresentException
WWW::Mediawiki::Client::FileAccessException
WWW::Mediawiki::Client::FileTypeException
WWW::Mediawiki::Client::URLConstructionException
WWW::Mediawiki::Client::UpdateNeededException
WWW::Mediawiki::Client::InvalidOptionException
do_com
This is an alias for "do_commit".
do_preview
$self->do_preview($filename);
The "do_preview" method is a non-writing version of the "do_commit" method. It uploads
the given filename to test its formatting. Its behaviour and arguments are identical to
"do_commit".
The behaviour of "do_preview" is currently based on the environment. If "MVS_BROWSER" is
set, this program (typically a web browser) will be launched on a temporary file.
Otherwise, the preview will be saved to the file specified by the "MVS_PREVIEW" variable,
or preview.html if this is unset. This behaviour is considered a prototype for future
functionality, and is "subject to change" in the near future.
Returns the name of the preview file, or undef if the file was sent to a web browser.
Throws:
WWW::Mediawiki::Client::ConflictsPresentException
WWW::Mediawiki::Client::FileAccessException
WWW::Mediawiki::Client::FileTypeException
WWW::Mediawiki::Client::URLConstructionException
WWW::Mediawiki::Client::UpdateNeededException
do_clean
$self->do_clean;
Removes all reference files under the current directory that have no corresponding Wiki
files.
Throws:
WWW::Mediawiki::Client::FileAccessException
save_state
$mvs->save_state;
Saves the current state of the wmc object in the current working directory.
Throws:
WWW::Mediawiki::Client::FileAccessException
load_state
$mvs = $mvs->load_state;
Loads the state of the wmc object from that saved in the current working directory.
Throws:
WWW::Mediawiki::Client::CorruptedConfigFileException
get_server_page
my $wikitext = $mvs->get_server_page($pagename);
Returns the wikitext of the given Mediawiki page name.
Throws:
WWW::Mediawiki::Client::ServerPageException
get_local_page
my $wikitext = $mvs->get_local_page($filename);
Returns the wikitext from the given local file;
Throws:
WWW::Mediawiki::Client::FileAccessException
WWW::Mediawiki::Client::FileTypeException
WWW::Mediawiki::Client::AbsoluteFileNameException
pagename_to_url
my $url = $mvs->pagename_to_url($pagename);
Returns the url at which a given pagename will be found on the Mediawiki server to which
this instance of points.
Throws:
WWW::Mediawiki::Client::URLConstructionException;
filename_to_pagename
my $pagename = $mvs->filname_to_pagename($filename);
Returns the cooresponding server page name given a filename.
Throws:
WWW::Mediawiki::Client::AbsoluteFileNameException
WWW::Mediawiki::Client::FileTypeException
filename_to_url
my $pagename = $mvs->filname_to_url($filename);
Returns the cooresponding server URL given a filename.
Throws:
WWW::Mediawiki::Client::AbsoluteFileNameException
WWW::Mediawiki::Client::FileTypeException
pagename_to_filename
my $filename = $mvs->pagename_to_filename($pagename);
Returns a local filename which cooresponds to the given Mediawiki page name.
url_to_filename
my $filename = $mvs->url_to_filename($url);
Returns the local filename which cooresponds to a given URL.
list_wiki_files
@filenames = $mvs->list_wiki_files;
Returns a recursive list of all wikitext files in the local repository.
BUGS
Please submit bug reports to the CPAN bug tracker at
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-Mediawiki-Client>.
DISCUSSION
There is a discussion list. You can subscribe or read the archives at:
<http://www.geekhive.net/cgi-bin/mailman/listinfo/www-mediawiki-client-l>
AUTHORS
Mark Jaroski <mark@geekhive.net>
Original author, maintainer
Mike Wesemann <mike@fhi-berlin.mpg.de>
Added support for Mediawiki 1.3.10+ edit tokens
Bernhard Kaindl <bkaindl@ffii.org>
Improved error messages.
Oleg Alexandrov <aoleg@math.ucla.edu>, Thomas Widmann <twid@bibulus.org>
Bug reports and feedback.
Adrian Irving-Beer <wisq@wisq.net>
Preview support, export support for multi-page update, more 'minor' and 'watch'
settings, and bug reports.
Nicolas Brouard <nicolas.brouard@libertysurf.fr>
Fixed content-type bug.
Alex Kapranoff <alex@kapranoff.ru>
Added "escape_filename" in order to support UTF-8 filenames on filesystems lacking
UTF-8 support.
LICENSE
Copyright (c) 2004-2006 Mark Jaroski.
This program is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.