=head1 NAME

WWW::TWikiClient - WWW::Mechanize-based client to access a TWiki.

=head1 SYNOPSIS

 # use
 use WWW::TWikiClient; 
 my $client = new WWW::TWikiClient;

 # authentication
 $client->auth_user           ("TWikiUserName");
 $client->auth_passwd         ("secretpasswd");

 # handling locks
 $client->override_locks      (0);  # default 0,
                                    # set to 1 if locked topics
                                    # should be "edited anyway"

 # base config
 $client->bin_url             ('http://twiki.org/cgi-bin/');
 $client->current_default_web ('Sandbox'); # used if not contained in topic
 $client->current_topic       ('SandBox32');

 # read and save appended text
 my $topic_content = $client->read_topic;
 $client->save_topic ($topic_content . "\n\n*TWikiClient was here.*\n\n");

 # attach a file
 $client->current_topic ('SandBox32');
 $client->attach_to_topic ("/home/ss5/tmp/image.jpg", "nice photo", 1, 1);


=head1 ABOUT

This class is derived from WWW::Mechanize for easy remote controlling
a TWiki based website. It was originally developed to migrate from a
VQWiki to TWiki.

After it lived some time under the Acme::PM::Dresden namespace I made
it an extra distribution because it seems to be useful for others.

It was originally developed during the same time when
WWW:Mechanize::TWiki appeared. I watched that other module for some
time but my WWW::TWikiClient follows a more explicit implementation
approach that worked better for me.

There are many TWikis with many different skins out there. TWikiClient
tries to work quite generically. I mostly developed it with TWikis
version 01Sep2004 (Cairo release) using the I<PatternSkin> but I also
did some tests against some other skins and twiki versions:

   * Beijing release (01Feb2003)
      * default skin (with only preview button in topic edit)
   * Cairo release (01Sep2004)
      * default skin (with several buttons in topic edit)
      * BlueSkin (the old version, probably 0.4)
      * PatternSkin
   * Dakar release 4.0.2
      * Reported to run, not tested by myself

See L<http://twiki.org/> for more information about TWiki.

See the example scripts in eg/ for more complex usage.

=head1 METHODS

WWW::TWikiClient inherits from L<WWW::Mechanize|WWW::Mechanize>. See
there for more methods.

=head2 new

Constructor. Takes an argument hash:

=over 4

=item bin_url

The base URL, where the twiki binaries are reached,
e.g. "http://twiki.org/cgi-bin/". 

=item current_default_web

The web that is used if topics are given without web prefix.  Compare
"Main.WebHome" vs. "WebHome"; set current_default_web("Main") for the
latter case.

=item current_topic

The topic that is used if not given to functions. That makes it easier
to set the topic and then call C<read_topic> and C<save_topic> with
just content params.

=item auth_user

Set your TWiki username here.

=item auth_passwd

Set your TWiki password here.

=item override_locks

If the topic is locked during C<save_topic>, this option decides
whether the TWiki link "Edit anyway" is used and the lock is ignored.

Please note, that a lock means, that another user edits the topic just
in this moment and his later save will throw away your changes.

=item verbose

If set to a true value, then some messages or warnings are printed to
STDERR, e.g., if a topic is locked. Default is 0.

=back

=head2 pre_init

Called before params are taken over. I mostly use it for setting
default values in derived clases.

=head2 post_init

Called after params are taken over. I mostly use it for forcing values
(and ignoring params) in derived clases.

=head2 get_basic_credentials

Overwritten function to provide username and password, that were set
via C<auth_user> and C<auth_passwd>.

=head2 htmlparse_extract_single_textarea

Auxiliary function to extract the nameless textarea in "raw text"
view.

=head2 _htmlparse_get_text

Auxiliary function within
L<htmlparse_extract_single_textarea|htmlparse_extract_single_textarea>.

=head2 $url = _make_url ($cmd, $topic, $optional_tail);

Auxiliary function. Constructs URL from class param C<bin_url>, $cmd
(view, edit, ...) and topic name. If topic name doesn't contain a web
prefix (eg., the "Main." in "Main.WebHome"), then the class param
C<current_default_web> is used.

=head2 $client->edit_press_cancel;

Cancels edit of C<current_topic>.

=head2 my $rawcontent = $client->read_topic ($optional_topic_name);

Returns the raw topic content. Uses C<current_topic> if no
C<$optional_topic_name> given.

=head2 my $success = save_topic ($rawcontent, $optional_topic_name);

Writes the string $rawcontent into the topic. Old content is
overwritten, so if you just want to append, use C<read_topic> and
concatenate. Uses C<current_topic> if no C<$optional_topic_name>
given.

=head2 attach_to_topic ($local_filename, $comment, $create_link_flag, $hide_file, $optional_topic_name);

Attaches (uploads) a local file to the topic. Uses C<current_topic> if
no C<$optional_topic_name> given.

C<$local_filename> should be a full path and filename.

C<$comment> is the created text near the image.

If C<$create_link_flag> is a true value, "images will be displayed,
for other attachments a link will be created". (quoted from the TWiki
description).

If C<$hide_file> is a true value, "attachments will not be shown in
topic view page". (quoted from the TWiki description).

=head1 SKIN OVERRIDABLE METHODS

Some behaviour might be skin dependent. The potential skin specific
behaviour is sourced out into methods so that they are overridable in
a class for a particular skin.

=head2 _skin_regex_authentication_failed

I sourced out some regexes that might be skin dependend. If you have
another skin, you should only need to subclass and overwrite the
_skin_*() methods.

This regex is for matching "authentication failed" page.

=head2 _skin_regex_topic_locked

This regex is for matching "topic locked" page.

=head2 _skin_regex_topic_locked_edit_anyway

This regex is for finding the "Edit anyway" link in the "topic locked"
page.

=head1 AUXILIARY METHODS

=head2 _save_topic_Save

Does the real "Save" from the topic edit page. It simply submits the
form and look whether the next page looks like a preview page, in
which case it simply submits again.

=head2 _save_topic_handle_locks

Checks for lock and overrides ot if C<override_locks> is set.

=head1 AUTHOR

Steffen Schwigon <schwigon@cpan.org>

=head1 LICENSE

  Copyright (c) 2006. Steffen Schwigon
  All rights reserved. You can redistribute and/or modify
  this bundle under the same terms as Perl itself.