• NAME
• SYNOPSIS
• DESCRIPTION
• CONSTANTS
  • • $VERSION
  • Update Status
    • STATUS_UNKNOWN
    • STATUS_UNCHANGED
    • STATUS_LOCAL_ADDED
    • STATUS_LOCAL_MODIFIED
    • STATUS_SERVER_MODIFIED
    • STATUS_CONFLICT
  • Option Settings
    • OPT_YES
    • OPT_NO
    • OPT_DEFAULT
    • OPT_KEEP
  • 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
    • COOKIE_FILE
    • SAVED_ATTRIBUTES
• CONSTRUCTORS
  • new
• ACCESSORS
  • host
  • protocol
  • language_code
  • space_substitute
  • escape_filenames
  • wiki_path
  • encoding
  • username
  • password
  • commit_message
  • watch
  • minor_edit
  • status
  • site_url DEPRICATED
• Instance Methods
  • do_login
  • do_li
  • do_update
  • do_up
  • do_commit
  • do_com
  • do_preview
  • do_clean
  • save_state
  • load_state
  • get_server_page
  • get_local_page
  • pagename_to_url
  • filename_to_pagename
  • filename_to_url
  • pagename_to_filename
  • url_to_filename
  • list_wiki_files
• BUGS
• DISCUSSION
• AUTHORS
• LICENSE

NAME

WWW::Mediawiki::Client

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.