Why not adopt me?

This distribution is up for adoption! If you're interested then please contact the PAUSE module admins via email.

NAME

POE::Component::WWW::CPANRatings::RSS - non-blocking wrapper around WWW::CPANRatings::RSS

SYNOPSIS

    use strict;
    use warnings;

    use POE qw(Component::WWW::CPANRatings::RSS);

    my $poco = POE::Component::WWW::CPANRatings::RSS->spawn;

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

    my $Count = 0;

    $poe_kernel->run;

    sub _start {
        $poco->fetch( {
                event   => 'ratings',
                unique  => 1,
                repeat  => 10,
            }
        );
    }

    sub ratings {
        my $in_ref = $_[ARG0];
        if ( $in_ref->{error} ) {
            print "ERROR: $in_ref->{error}\n\n";
        }
        else {
            print "New reviews:\n";
            for ( @{ $in_ref->{ratings} } ) {
                printf "%s - %s stars - by %s\n--- %s ---\nsee %s\n\n\n",
                    @$_{ qw/dist rating creator comment link/ };
            }
        }
    }

Using event based interface is also possible of course.

DESCRIPTION

The module is a non-blocking wrapper around WWW::CPANRatings::RSS which provides interface to fetch data from the RSS feed on http://cpanratings.perl.org/

CONSTRUCTOR

`spawn`

    my $poco = POE::Component::WWW::CPANRatings::RSS->spawn;

    POE::Component::WWW::CPANRatings::RSS->spawn(
        alias => 'cpan_ratings',
        ua    => {
            timeout => 30,
        },
        options => {
            debug => 1,
            trace => 1,
            # POE::Session arguments for the component
        },
        debug => 1, # output some debug info
    );

The spawn method returns a POE::Component::WWW::CPANRatings::RSS object. It takes a few arguments, all of which are optional. The possible arguments are as follows:

`alias`

    ->spawn( alias => 'cpan_ratings' );

Optional. Specifies a POE Kernel alias for the component.

`ua`

    ua => {
        timeout => 30,
    },

Optional. Takes a hashref as a value. That hashref will be directly dereferenced into LWP::UserAgent's constructor. See LWP::UserAgent documentation for possible keys/values. Defaults to: { timeout => 30 }

`options`

    ->spawn(
        options => {
            trace => 1,
            default => 1,
        },
    );

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

`debug`

    ->spawn(
        debug => 1
    );

When set to a true value turns on output of debug messages. Defaults to: 0.

METHODS

`fetch`

    $poco->fetch( {
            event       => 'event_for_output',
            unique      => 1,
            repeat      => 60,
            repeat_name => 'foos',
            file        => 'cpan_ratings.store',
            _blah       => 'pooh!',
            session     => 'other',
        }
    );

Takes a hashref as an argument, does not return a sensible return value. See fetch event's description for more information.

`stop_repeat`

    $poco->stop_repeat('GENERAL');

Takes one mandatory argument which is the name of the repeat to clear, this will be whatever was set in repeat_name argument of fetch() event/method. See stop_repeat event description for details.

`session_id`

    my $poco_id = $poco->session_id;

Takes no arguments. Returns component's session ID.

`shutdown`

    $poco->shutdown;

Takes no arguments. Shuts down the component.

ACCEPTED EVENTS

`fetch`

    $poe_kernel->post( cpan_ratings => fetch => {
            event       => 'event_for_output',
            unique      => 1,
            repeat      => 60,
            repeat_name => 'foos',
            file        => 'cpan_ratings.store',
            _blah       => 'pooh!',
            session     => 'other',
        }
    );

Instructs the component to fetch RSS feed from http://cpanratings.perl.org/. Takes a hashref as an argument, the possible keys/value of that hashref are as follows:

`event`

    { event => 'results_event', }

Mandatory. Specifies the name of the event to emit when results are ready. See OUTPUT section for more information.

`unique`

    { unique => 1, }

Optional. Takes either true or false values. When set to a true value will instruct the component to report only the reviews which it hasn't reported yet (basically a call to fetch_unique() in WWW::CPANRatings::RSS). Defaults to: 0

`repeat`

    { repeat => 60, }

Optional. Takes a positive integer as a value. When specified will instruct the component to repeat the fetch of info every repeat seconds. This generally makes sense to use along with unique argument. By default is not specified.

`repeat_name`

    { repeat_name => 'foos', }

Optional. When repeat is set, specifies a name for the "alarm". You can use this name in the stop_repeat() event/method. Defaults to: GENERAL

`file`

    { file => 'cpan_ratings.store', }

Optional. When unique option is turned on, the component will store already reported reviews in a file. You can specify the name of the file with file argument. Defaults to: cpan_ratings.rss.storable

`session`

    { session => 'other' }

    { session => $other_session_reference }

    { session => $other_session_ID }

Optional. Takes either an alias, reference or an ID of an alternative session to send output to.

user defined

    {
        _user    => 'random',
        _another => 'more',
    }

Optional. Any keys starting with _ (underscore) will not affect the component and will be passed back in the result intact.

`stop_repeat`

    $poe_kernel->post( cpan_ratings => stop_repeat => 'GENERAL');

Takes one mandatory argument which is the name of the repeat to clear, this will be whatever was set in repeat_name argument of fetch() event/method. Instructs the component to stop repeating the fetch request. Using this event/method you can stop the request which was set when the repeat argument was specified to the fetch event/method.

`shutdown`

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

Takes no arguments. Tells the component to shut itself down.

OUTPUT

    $VAR1 = {
        'unique' => 1,
        'ratings' => [
            {
                'link' => 'http://cpanratings.perl.org/#4446',
                'comment' => 'This module has failed on all swf\'s ive tried it on.  All attempts at transcoding has resulted in contentless flv that will not play.
',
                'creator' => 'Dave Williams',
                'dist' => 'FLV-Info',
                'rating' => '1'
            }
        ],
        'file' => 'foo.file.store',
        'repeat' => 10,
        '_user'  => 'defined variable',
    };

The event handler set up to handle the event which you've specified in the event argument to fetch() method/event will recieve input in the $_[ARG0] in a form of a hashref. The possible keys/value of that hashref are as follows:

`ratings`

    'ratings' => [
        {
            'link' => 'http://cpanratings.perl.org/#4446',
            'comment' => 'This module has failed on all swf\'s ive tried it on.  All attempts at transcoding has resulted in contentless flv that will not play.
',
            'creator' => 'Dave Williams',
            'dist' => 'FLV-Info',
            'rating' => '1'
        }
    ],

The ratings key will contain a (possibly empty) arrayref of hashrefs, each hashref represents a review. See documentation for fetch() and fetch_unqiue() methods in WWW::CPANRatings::RSS for description of each of the keys in those hashrefs.

`error`

    'error' => 'Network error: 500 Timeout',

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

arguments passed to `fetch`

    {
        'unique' => 1,
        'file' => 'foo.file.store',
        'repeat' => 10
    }

The unique, file, repeat and repeat_name will be present in the result intact.

user defined

    { '_blah' => 'foos' }

Any arguments beginning with _ (underscore) passed into the EXAMPLE() event/method will be present intact in the result.

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-cpanratings-rss at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-WWW-CPANRatings-RSS. 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::CPANRatings::RSS

You can also look for information at:

RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Component-WWW-CPANRatings-RSS
AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/POE-Component-WWW-CPANRatings-RSS
CPAN Ratings

http://cpanratings.perl.org/d/POE-Component-WWW-CPANRatings-RSS
Search CPAN

http://search.cpan.org/dist/POE-Component-WWW-CPANRatings-RSS

COPYRIGHT & LICENSE

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

To install POE::Component::WWW::CPANRatings::RSS, copy and paste the appropriate command in to your terminal.

cpanm

cpanm POE::Component::WWW::CPANRatings::RSS

CPAN shell

perl -MCPAN -e shell
install POE::Component::WWW::CPANRatings::RSS

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

Why not adopt me?

NAME

SYNOPSIS

DESCRIPTION

CONSTRUCTOR

spawn

alias

ua

options

debug

METHODS

fetch

stop_repeat

session_id

shutdown

ACCEPTED EVENTS

fetch

event

unique

repeat

repeat_name

file

session

user defined

stop_repeat

shutdown

OUTPUT

ratings

error

arguments passed to fetch

user defined

SEE ALSO

AUTHOR

BUGS

SUPPORT

COPYRIGHT & LICENSE

Module Install Instructions

`spawn`

`alias`

`ua`

`options`

`debug`

`fetch`

`stop_repeat`

`session_id`

`shutdown`

`fetch`

`event`

`unique`

`repeat`

`repeat_name`

`file`

`session`

`stop_repeat`

`shutdown`

`ratings`

`error`

arguments passed to `fetch`