Zoffix Znet > POE-Component-WWW-CPANRatings-RSS-0.0101 > POE::Component::WWW::CPANRatings::RSS

Download:
POE-Component-WWW-CPANRatings-RSS-0.0101.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.0101   Source  

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.

SEE ALSO ^

POE, WWW::CPANRatings::RSS

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:

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.

syntax highlighting: