/ 
POE-Component-WWW-PAUSE-RecentUploads-0.03
/ POE::Component::WWW::PAUSE::RecentUploads

NAME

POE::Component::WWW::PAUSE::RecentUploads - a non-blocking POE wrapper around WWW::PAUSE::RecentUploads.

SYNOPSIS

use strict;
use warnings;

use POE qw(Component::WWW::PAUSE::RecentUploads);

my $poco = POE::Component::WWW::PAUSE::RecentUploads->spawn(
    login => 'PAUSE LOGIN',
    pass  => 'PAUSE PASSWORD',
    debug => 1,
);

POE::Session->create(
    package_states => [
        main => [ qw( _start recent ) ],
    ],
);

$poe_kernel->run();

sub _start {
    $poco->fetch( { event => 'recent' } );
}

sub recent {
    my $data = $_[ARG0];
    if ( $data->{error} ) {
        print "Error while fetching recent data: $data->{error}\n";
    }
    else {
        foreach my $dist ( @{ $data->{data} || [] } ) {
            printf "%s by %s (size: %s)\n",
                    @$dist{ qw(dist name size) };
        }
    }
    $poco->shutdown;
}

Using the event based interface is also possible, of course.

DESCRIPTION

The module is a non-blocking POE wrapper around WWW::PAUSE::RecentUploads which fetches the listing of recent uploads to http://pause.perl.org

CONSTRUCTOR

my $poco = POE::Component::WWW::PAUSE::RecentUploads->spawn(
    login => 'PAUSE LOGIN',     # mandatory
    pass  => 'PAUSE PASSWORD',  # mandatory
);

POE::Component::WWW::PAUSE::RecentUploads->spawn(
    login => 'PAUSE LOGIN',     # mandatory
    pass  => 'PAUSE PASSWORD',  # mandatory
    alias => 'recent',          # all the rest are optional
    debug   => 1,               
    ua_args => {                
        timeout => 10,
        agent   => 'RecentUA',
        # other LWP::UserAgent's constructor arguments can go here
    },
    options => {
        debug => 1, # POE::Session create() may go here.
    },
);

Spawns a new POE::Component::WWW::PAUSE::RecentUploads component and returns a reference to it, but you don't have to keep it if you set the optional alias argument. Takes a single argument which is a hashref of options. Two of them, login and password are mandatory, the rest is optional. The possible keys/values are as follows:

login

{ login => 'PAUSE LOGIN' }

Mandatory. Must contain your http://pause.perl.org login.

pass

{ login => 'PAUSE LOGIN' }

Mandatory. Must contain your http://pause.perl.org password.

alias

{ alias => 'recent' }

Optional. Specifies the component's POE::Session alias of the component.

debug

Optional. =head2 ua_args

{ debug   => 1 }

Optional. When set to a true value will make the component emit some debuging info. Defaults to false.

options

{
    options => {
        trace   => 1,
        default => 1,
    }
}

A hashref of POE Session options to pass to the component's session.

METHODS

These are the object-oriented methods of the component.

fetch

$poco->fetch( { event => 'recent' } );
   
$poco->fetch(   {
        event   => 'recent', # the only mandatory argument
        login   => 'other_login', # this and below is optional
        pass    => 'other_pass',
        session => 'other_session',
        ua_args => {
            timeout => 10, # default timeout is 30.
            argent  => 'LolFetcher',
        },
        _user1  => 'random',
        _cow    => 'meow',
    }
);

Instructs the component to fetch information about recent PAUSE uploads. See fetch event description below for more information.

session_id

my $fetcher_id = $poco->session_id;

Takes no arguments. Returns POE Session ID of the component.

shutdown

$poco->shutdown;

Takes no arguments. Shuts the component down.

ACCEPTED EVENTS

The interaction with the component is also possible via event based interface. The following events are accepted by the component:

fetch

$poe_kernel->post( recent => fetch => {
        event   => 'event_where_to_send_output', # mandatory,
        session => 'some_session', # this and everything below is...
                                   # ...optional
        login   => 'some_other_login',
        pass    => 'some_other_password',
        ua_args => {
            timeout => 10, # defaults to 30
            agent   => 'SomeUA',
            # the rest of LWP::UserAgent contructor arguments
        },
        _user_defined => 'foo',
        _cow_said     => 'meow',
    }
);

Takes one argument which is a hashref with the following keys:

event

{ event   => 'event_where_to_send_output' }

Mandatory. The name of the event which to send when output is ready. See OUTPUT section for its format.

session

{ session => 'other_session_alias' }

{ session => $other_session_ID }

{ session => $other_session_ref }

Optional. Specifies an alternative POE Session to send the output to. Accepts either session alias, session ID or session reference. Defaults to the current session.

login

{ login   => 'some_other_login' }

Optional.Using login argument you may override the PAUSE login you've specified in the constructor. Defaults to contructor's login value.

pass

{ pass    => 'some_other_password' }

Optional. Using pass argument you may override the PAUSE password you've specified in the constructor. Defaults to contructor's pass value.

ua_args

{
    ua_args => {
        timeout => 10, # defaults to 30
        agent   => 'SomeUA',
        # the rest of LWP::UserAgent contructor arguments
    },
}

Optional. The ua_args key takes a hashref as a value which should contain the arguments which will be passed to LWP::UserAgent contructor. Note: all arguments will default to whatever LWP::UserAgent default contructor arguments are except for the timeout, which will default to 30 seconds.

user defined arguments

{
    _user_var    => 'foos',
    _another_one => 'bars',
    _some_other  => 'beers',
}

Optional. Any keys beginning with the _ (underscore) will be present in the output intact. If where option (see below) is specified, any arguments will also be present in the result of "finished downloading" event.

shutdown

$poe_kernel->post( recent => 'shutdown' );

Takes no arguments, instructs the component to shut itself down.

OUTPUT

$VAR1 = {
      'data' => [
                  {
                    'name' => 'CJUKUO',
                    'dist' => 'AIIA-GMT-0.01',
                    'size' => '33428b'
                  },
                  {
                    'name' => 'DOMQ',
                    'dist' => 'Alien-Selenium-0.07',
                    'size' => '1640987b'
                  },
                # more of these here
        ],
        '_secret' => 'value',
}

The event handler set up to listen for the event, name of which you've specified in the event argument of fetch event/method will recieve the results in ARG0 in the form of a hashref with one or more of the keys presented below. Note: the uploads stick around for quite some time in the list on PAUSE, thus you are likely to get several "dists" reported as recent by this component if you are fetching the list often enough. If your goal is to report any new uploads to PAUSE you may want to use POE::Component::WWW::PAUSE::RecentUploads::Tail instead. The keys of the output hashref are as follows:

data

{
    'data' => [
            {
            'name' => 'CJUKUO',
            'dist' => 'AIIA-GMT-0.01',
            'size' => '33428b'
            },
            {
            'name' => 'DOMQ',
            'dist' => 'Alien-Selenium-0.07',
            'size' => '1640987b'
            },
        # more of these here
    ],
}

Unless an error occured, the data key will be present and the value of it will be an arrayref of hashrefs representing recent uploads to PAUSE. The keys of those hashrefs are as follows:

name

{ 'name' => 'CJUKUO' }

The author ID of the upload. Note: often ID will show up on PAUSE a bit later than the upload itself. If author's ID is missing the component will ignore this upload and will report it later.

dist

{ 'dist' => 'Alien-Selenium-0.07' }

The name of the distro (or file if you prefer) that was uploaded.

size

{ 'size' => '1640987b' }

The size of the uploaded file. The value will also contain the unit of measure.

error

{ 'error' => '401 Authorization Required' }

If an error occured the error key will be present and will contain the description of the error.

user defined arguments

{
    _user_var    => 'foos',
    _another_one => 'bars',
    _some_other  => 'beers',
}

Optional. Any keys beginning with the _ (underscore) will be present in the output intact.

SEE ALSO

POE, WWW::PAUSE::RecentUploads, POE::Component::WWW::PAUSE::RecentUploads::Tail, LWP::UserAgent, http://pause.perl.org

PREREQUISITES

This module requires the following modules/version for proper operation:

Carp                      => 1.04,
POE                       => 0.9999,
POE::Wheel::Run           => 1.2179,
POE::Filter::Reference    => 1.2187,
POE::Filter::Line         => 1.1920,
WWW::PAUSE::RecentUploads => 0.01,

Not tested with earlier versions of those modules.

AUTHOR

Zoffix Znet, <zoffix at cpan.org> (http://zoffix.com, http://haslayout.net)

BUGS

Please report any bugs or feature requests to bug-poe-component-www-pause-recentuploads at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-WWW-PAUSE-RecentUploads. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

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

perldoc POE::Component::WWW::PAUSE::RecentUploads

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2008 Zoffix Znet, all rights reserved.

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