/ 
WWW-DanDomain-0.08
River stage zero No dependents
/ WWW::DanDomain

NAME

WWW::DanDomain - class to assist in interacting with DanDomain admin interface

VERSION

This documentation describes version 0.08

SYNOPSIS

The module lets the user interact with DanDomains administrative web interface. This can be used for automating tasks of processing data exports etc.

use WWW::DanDomain;

#All mandatory parameters
#Please note DanDomain can be configured to use authorization on IP
#meaning authentication is unnessesary
my $wd = WWW::DanDomain->new({
    url => 'http://www.billigespil.dk/admin/edbpriser-export.asp',
});

#With optional authentication credentials
my $wd = WWW::DanDomain->new({
    username => 'topshop',
    password => 'topsecret',
    url => 'http://www.billigespil.dk/admin/edbpriser-export.asp',
});

#with verbosity enabled
my $wd = WWW::DanDomain->new({
    username => 'topshop',
    password => 'topsecret',
    url      => 'http://www.billigespil.dk/admin/edbpriser-export.asp',
    verbose  => 1,
});

#With caching
my $wd = WWW::DanDomain->new({
    username => 'topshop',
    password => 'topsecret',
    url      => 'http://www.billigespil.dk/admin/edbpriser-export.asp',
    cache    => 1,
});


#With custom WWW::Mechanize object
use WWW::Mechanize;

my $mech = WWW::Mechanize->new(agent => 'MEGAnice bot');

my $wd = WWW::DanDomain->new({
    username => 'topshop',
    password => 'topsecret',
    url      => 'http://www.billigespil.dk/admin/edbpriser-export.asp',
    mech     => $mech,
});


#The intended use
package My::WWW::DanDomain::Subclass;

sub processor {
    my ( $self, $content ) = @_;

    #Note the lines terminations are Windows CRLF
    my @lines = split /\r\n/, $$content;

    ...

    }
}


#Using your new class
my $my = My::WWW::DanDomain::Subclass->new({
    username => 'topshop',
    password => 'topsecret',
    url      => 'http://www.billigespil.dk/admin/edbpriser-export.asp',
});

my $content = $my->retrieve();

print $$content;


#Using a processor implemented as a code reference
$wd = WWW::DanDomain->new({
    username  => 'topshop',
    password  => 'topsecret',
    url       => 'http://www.billigespil.dk/admin/edbpriser-export.asp',
    processor => sub {
        ${$_[0]} =~ s/test/fest/;
        return $_[0];
    },
});


#Implementing a processor class
my $processor = MY::Processor->new();

$processor->can('process');

$wd = WWW::DanDomain->new({
    username  => 'topshop',
    password  => 'topsecret',
    url       => 'http://www.billigespil.dk/admin/edbpriser-export.asp',
    processor => $processor,
});

my $content = $wd->retrieve();

print ${$content};

DESCRIPTION

This module is a simple wrapper around WWW::Mechanize it assists the user in getting going with automating tasks related to the DanDomain administrative web interface.

Such as:

  • manipulating data exports (removing, adjusting, calculating, adding columns)

  • filling in missing data (combining data)

  • converting formats (from CSV to XML, JSON, CSV, whatever)

METHODS

new

This is the constructor.

The constructor takes a hash reference as input. The hash reference should contain keys according to the following conventions:

  • username, optional username credential to access DanDomain

  • password, optional password credential to access DanDomain

  • url, the mandatory URL to retrieve data from ("retrieve")

  • mech, a WWW::Mechanize object if you have a pre instantiated object or some other object implementing the the same API as WWW::Mechanize.

    The parameter is optional.

    See also cache parameter below for an example.

  • verbose, a flag for indicating verbosity, default is 0 (disabled), the parameter is optional

  • cache, usage of a cache meaning that we internally use WWW::Mechanize::Cached instead of WWW::Mechanize.

    The parameter is optional

  • processor

    This parameter can be used of you do not want to implement a subclass of WWW::DanDomain.

    The processor parameter can either be:

    • an object implementing a "proces" method, with the following profile:

      proces(\$content);

    • a code reference with the same profile, adhering to the following example:

      sub { return ${$_[0]} };

retrieve

Parameters:

  • a hash reference, the reference can be populated with statistic information based on the lineprocessing ("processor") initiated from "retrieve".

The method returns a scalar reference to a string containing the content retrieved from the URL provided to the contructor ("new"). If the "processor" method is overwritten you can manipulate the content prior to being returned.

process

Takes the content retrieved (see: "retrieve") from the URL parameter provided to the constructor (see: "new"). You can overwrite the behaviour via the constructor (see: "new").

Parameters:

  • a scalar reference to a string to be processed line by line

The stub does however not do anything, but it returns the scalar reference untouched.

processor

This is a wrapper for "process", provided for backwards compatibility.

DIAGNOSTICS

CONFIGURATION AND ENVIRONMENT

The module requires Internet access to make sense and an account with DanDomain with username and password is required.

DEPENDENCIES

TEST AND QUALITY

The tests are based on Test::MockObject::Extends and example data are mocked dummy data. Please see the TODO section.

The test suite uses the following environment variables as flags:

TEST_AUTHOR, to test prerequisites, using Test::Prereq
TEST_CRITIC, to do a static analysis of the code, using Perl::Critic, see also QUALITY AND CODING STANDARD

TEST COVERAGE

The following data are based on an analysis created using Devel::Cover and the distributions own test suite, instantiated the following way.

% ./Build testcover --verbose

---------------------------- ------ ------ ------ ------ ------ ------ ------
File                           stmt   bran   cond    sub    pod   time  total
---------------------------- ------ ------ ------ ------ ------ ------ ------
blib/lib/WWW/DanDomain.pm     100.0  100.0  100.0  100.0  100.0  100.0  100.0
Total                         100.0  100.0  100.0  100.0  100.0  100.0  100.0
---------------------------- ------ ------ ------ ------ ------ ------ ------

Please note the report is based on version 0.03 of WWW::DanDomain

QUALITY AND CODING STANDARD

The code passes Perl::Critic tests a severity: 1 (brutal)

The following policies have been disabled:

Perl::Critic::Policy::InputOutput::RequireBracedFileHandleWithPrint

Perl::Critic resource file, can be located in the t/ directory of the distribution t/perlcritic.rc

Perl::Tidy resource file, can be obtained from the original author

BUGS AND LIMITATIONS

No known bugs at this time.

BUG REPORTING

Please report any bugs or feature requests via:

DEVELOPMENT

TODO

  • Most of the work is done in the classes inheriting from this class, there could however be work to do in the maintenance area, making this class more informative if failing

  • I would like to add some integration test scripts so I can see that the package works with real data apart from the mock.

SEE ALSO

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc WWW::DanDomain

You can also look for information at:

AUTHOR

  • jonasbn, <jonasbn at cpan.org>

MOTIVATION

This module grew out of a small script using WWW::Mechanize to fetch some data from a website and changing it to satisfy the client utilizing the data.

More a more scripts where based on the original script giving a lot of redundant code. Finally I refactored the lot to use some common code base.

After some time I refactored to an object oriented structure making it even easier to maintain and adding more clients. This made the actual connectivity into a package (this package) letting it loose as open source.

ACKNOWLEDGEMENTS

  • Andy Lester (petdance) the author of WWW::Mechanize and WWW::Mechanize:Cached, this module makes easy things easy and hard things possible.

  • Iain Truskett, the author of WWW::Mechanize and WWW::Mechanize:Cached

  • Steen Schnack, who understand the power and flexibility of computer programming and custom solutions and who gave me the assignment.

  • Slaven Rezic, for his CPAN testers work and assistance in pointing out an issue with release 0.03

LICENSE AND COPYRIGHT

WWW-DanDomain and related modules are (C) by Jonas B. Nielsen, (jonasbn) 2009-2014

WWW-DanDomain and related modules are released under the artistic license 2.0