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

VERSION
    This documentation describes version 0.03

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;

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

  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.

  processor
    This is a stub and it might go away in the future. It does takes the
    content retrieved (see: retrieve) from the URL parameter provided to 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*.

DIAGNOSTICS
    * Unable to authenticate, username and password not valid credentials
    * Both username and password is required for authentication
        If you want to use authentication you have to provide both username
        and password.

    * Unable to retrieve base URL: $@
        The base URL provided to retrieve gives an error.

        Please see: http://search.cpan.org/perldoc?HTTP%3A%3AResponse or
        http://search.cpan.org/~gaas/libwww-perl/lib/HTTP/Status.pm

        Test the URL in your browser to investigate.

    * Unable to retrieve URL: $@
        The base URL provided to retrieve gives an error.

        Please see: http://search.cpan.org/perldoc?HTTP%3A%3AResponse or
        http://search.cpan.org/~gaas/libwww-perl/lib/HTTP/Status.pm

        Test the URL in your browser to investigate.

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

DEPENDENCIES
    * WWW::Mechanize
    * Carp

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/perlcriticrc

    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:

    * email: `bug-www-dandomain at rt.cpan.org'
    * HTTP: http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-DanDomain

DEVELOPMENT
    * Subversion repository: http://logicLAB.jira.com/svn/DAND

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
    * http://www.dandomain.dk

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

        perldoc WWW::DanDomain

    You can also look for information at:

    * Official Wiki
        http://logiclab.jira.com/wiki/display/DAND/Home+-+WWW-DanDomain

    * AnnoCPAN: Annotated CPAN documentation
        http://annocpan.org/dist/WWW-DanDomain

    * CPAN Ratings
        http://cpanratings.perl.org/d/WWW-DanDomain

    * RT: CPAN's request tracker
        http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-DanDomain

    * Search CPAN
        http://search.cpan.org/dist/WWW-DanDomain

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.
    * Steen Schnack, who understand the power and flexibility of computer
    programming and custom solutions and who gave me the assignment.

LICENSE AND COPYRIGHT
    Copyright 2009-2010 jonasbn, all rights reserved.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

