view release on metacpan or  search on metacpan

lib/Dokuwiki/RPC/XML/Client.pm  view on Meta::CPAN

=head1 the C<reach> constructor

to use the C<RPC::XML::Client::new> constructor directly, you have to remember the url of the RPC server 
and how to setup a cookie file so you stay connected after the 
L<dokuwiki.login|https://www.dokuwiki.org/devel:xmlrpc#dokuwikilogin>) was called. 

So, as explained in
L<http://stackoverflow.com/questions/16572903/logging-into-dokuwiki-using-perls-rpcxmlclient-or-alternately-how-can-i-re>, 
calling the constructor would be: 

    my $client =
        RPC::XML::Client->new
        ('http://example.com/wikiname/lib/exe/xmlrpc.php'
        , useragent => [ cookie_jar => { file => "$ENV{HOME}/.cookies.txt" }] );

But you don't want to write it down? don't you? L<Dokuwiki::RPC::XML::Client> comes with a
wrapper called C<reach $class $url %options>; possible calls are

        Dokuwiki::RPC::XML::Client->reach
        ('http://example.com/wikiname/' );

        Dokuwiki::RPC::XML::Client->reach
        ( base => 'http://example.com/wikiname/' );

        Dokuwiki::RPC::XML::Client->reach
        ( url => 'http://example.com/wikiname/lib/exe/xmlrpc.php' );

        Dokuwiki::RPC::XML::Client->reach
        ('http://example.com/wikiname/'
        , file => '/tmp/dokukookies.txt' );

=head1 METHODS, INTROSPECTION

C<%Dokuwiki::RPC::XML::Client::API> is a hash where keys are the
C<Dokuwiki::RPC::XML::Client> methods and values are the Dokuwiki XML-RPC
methods. So you can have the list of the mapped functions with:

    perl -MDokuwiki::RPC::XML::Client -E'
        say for keys %Dokuwiki::RPC::XML::Client::API 

but please refer to the 
L<dokuwiki xml-rpc page|https://www.dokuwiki.org/devel:xmlrpc> for more details.

=head1 A REAL WORLD EXAMPLE USING C<~/.netrc>

getting the login and password from C<STDIN>, C<@ARGV> or hardcoded in your
source file is B<always> a bad idea. so this is an example to get things done
using the god damn old and good C<~/.netrc> file.

    use Dokuwiki::RPC::XML::Client;
    use Modern::Perl;
    use Net::Netrc;
    my $base = 'https://example.com/';
    my $host = 'company';

    my $wiki =
        Dokuwiki::RPC::XML::Client 
        -> reach('https://wiki.example.com/');

    my $credentials = Net::Netrc->lookup($host)
        or die "please add a fake $host machine in your ~/.netrc";

    my ( $l, $p ) = $credentials->lpa;

    $wiki->login( $l, $p )->value 
        or die "can't authenticate with $l";

    say $wiki->getVersion->value;

=head1 FUTURE

i'm still experimenting to make my mind up about the right way to do it. it would
be nice to have both a raw C<RPC::XML::Client> as a singleton. then we could have
something usable in both way

    use aliased qw<Dokuwiki::RPC::XML::Client::Singleton D>;
    D::netrc 'unistra';
    D::login 'https://di.u-strasbg.fr';
    say "connected to dokuwiki version ". D::getVersion;
    say for grep /^metiers:/, ids_of D::getAllPages; 

or

    use Dokuwiki::RPC::XML::Client::Singleton ':all';
    netrc 'unistra';
    login 'https://di.u-strasbg.fr';
    say "connected to dokuwiki version ". getVersion;
    say for grep /^metiers:/, ids_of getAllPages;

=cut