oracular (3) WWW::Mediawiki::Client.3pm.gz

Provided by: libwww-mediawiki-client-perl_0.31-2.2_all bug

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.