Zoffix Znet

NAME

POE::Component::IRC::Plugin::WWW::CPANRatings::RSS - announce CPAN ratings on IRC from RSS feed on http://cpanratings.perl.org/

SYNOPSIS

    #!/usr/bin/env perl

    use strict;
    use warnings;

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

    my $irc = POE::Component::IRC->spawn(
        nick        => 'CPANRatings',
        server      => 'irc.freenode.net',
        port        => 6667,
        ircname     => 'CPAN Ratings Bot',
    );

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

    $poe_kernel->run;

    sub irc_cpanratings {
        my $in_ref = $_[ARG0];
        use Data::Dumper;
        print Dumper $in_ref;
    }

    sub _start {
        $irc->yield( register => 'all' );

        $irc->plugin_add(
            'cpan_ratings' =>
                POE::Component::IRC::Plugin::WWW::CPANRatings::RSS->new(
                    channels => [ '#zofbot' ],
                )
        );

        $irc->yield( connect => {} );
    }

    sub irc_001 {
        $irc->yield( join => '#zofbot' );
    }


    * CPANRatings rating: String-String - ●○○○○ - by BKB [ http://cpanratings.perl.org/#4476 ]
    * CPANRatings rating: IWL - ●○○○○ - by BKB [ http://cpanratings.perl.org/#4474 ]
    * CPANRatings rating: String - ●○○○○ - by BKB [ http://cpanratings.perl.org/#4472 ]
    * CPANRatings rating: String-Buffer - ●○○○○ - by BKB [ http://cpanratings.perl.org/#4470 ]
    * CPANRatings rating: String-Strip - ●○○○○ - by BKB [ http://cpanratings.perl.org/#4468 ]
    * CPANRatings rating: Acme-Monta - N/A - by BKB [ http://cpanratings.perl.org/#4466 ]

DESCRIPTION

The module is POE::Component::IRC plugin which uses POE::Component::IRC::Plugin for its base, thus can be loaded with plugin_add() method. The module provides means to announce new reviews posted to http://cpanratings.perl.org/

CONSTRUCTOR

new

    # plain
    $irc->plugin_add(
        'cpan_ratings' =>
            POE::Component::IRC::Plugin::WWW::CPANRatings::RSS->new(
                channels => [ '#zofbot' ],
            )
    );

    # juicy
        $irc->plugin_add(
            'cpan_ratings' =>
                POE::Component::IRC::Plugin::WWW::CPANRatings::RSS->new(
                    channels    => [ '#zofbot' ],
                    rate        => 60;
                    ua          => { timeout => 30 },
                    file        => 'cpan_ratings.rss.storable',
                    format      => 'rating: {:dist:} - {:rating:} - by {:creator:} [ {:link:} ]',
                    max_ratings => 10,
                    response_event => 'irc_cpanratings';
                    auto        => 1,
                    utf         => 1,
                )
        );

Constructs and returns a POE::Component::IRC::Plugin::WWW::CPANRatings::RSS object suitable to be fed to POE::Component::IRC's plugin_add() method. All of which are optional. You can change all of the arguments dynamically by accessing them as keys in a hashref of the plugin object: $plug->{rate} = 1000; Possible arguments are as follows

channels

    ->new( channels => [ '#zofbot' ], );

Semi-mandatory, not specifying this argument will render the plugin useless when auto option is turned on, however you can still listen to the events emited by the plugin. Takes an arrayref as a value which must contain the channels where the plugin will announce new ratings.

rate

    ->new( rate => 360, );

Optional. Takes a positive integer as a value which specifies the interval of rate seconds between the checks for new ratings. Defaults to: 60

ua

    ->new( ua => { timeout => 30 } );

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

file

    ->new( file => 'cpan_ratings.rss.storable' );

Optional. Plugin stores already reported reviews/ratings into a file. Using the file argument, which takes a scalar as a value, you can specify the file name for storage. Defaults to: cpan_ratings.rss.storable

format

    ->new( format => 'rating: {:dist:} - {:rating:} - by {:creator:} [ {:link:} ]', );

Optional. When auto argument (see below) is set to a true value the plugin will announce new reviews into the channels. The format argument, which takes a string as a value, specifies the format of the output. Currently all the announcing is done via /me, let me know if you want that configurable. Special character sequences in the format string will be replaced with respective data bits in the following fashion:

    {:dist:}        - name of the distribution
    {:rating:}      - either the number or the stars (see C<utf>) rating
    {:creator:}     - name of the creator of the review
    {:link:}        - link to the review

The special sequences can be used any number of times if you so desire. The format argument defaults to: <'rating: {:dist:} - {:rating:} - by {:creator:} [ {:link:} ]'>

max_ratings

    ->new( max_ratings => 5 );

Optional. The max_ratings takes a positive integer as a value and specifies the maximum number of ratings/reviews to report at a time. Anything over that limit won't be reported at all; considering those reviews don't pop up like mushrooms this shouldn't be a problem. Defaults to: 5

response_event

    ->new( response_event => 'irc_cpanratings' );

Optional. During its operation, the plugin will emit an event every time the data is fetched. The response_event specifies the name of the event to emit. Defaults to: irc_cpanratings

auto

    ->new( auto => 1 );

Optional. Takes either true or false values. When set to a true value plugin will auto-announce new reviews into all the channels specified in channels argument. Defaults to: 1

utf

    ->new( utf => 1 );

Optional. Takes either true or false values. When set to a true value will use UTF-8 circles to represent the given rating (that is what will replace the {:rating:} sequence in the format argument). When set to a false value will use simple numbers. Defaults to: 1

EMITED EVENTS

    $VAR1 = {
        'rate' => 60,
        'ratings' => [
            {
                'link' => 'http://cpanratings.perl.org/#4452',
                'comment' => 'One of the most useful Acme modules ever! Simply fantastic to show off without losing more than 5 seconds, a real masterpiece of meta-art. I\'d suggest ...',
                'creator' => 'Flavio Poletti',
                'dist' => 'Acme-EyeDrops',
                'rating' => '5'
            },
        ],
        'file' => 'cpan_ratings.rss.storable'
    };

The event handler setup to handle the response_event, which defaults to irc_cpanratings, will receive input on every fetch, thus every rate (see CONSTRUCTOR) seconds. The input will come in a form of a hashref in $_[ARG0]. The keys/values of that hashref are as follows.

ratings

    'ratings' => [
        {
            'link' => 'http://cpanratings.perl.org/#4452',
            'comment' => 'One of the most useful Acme modules ever! Simply fantastic to show off without losing more than 5 seconds, a real masterpiece of meta-art. I\'d suggest ...',
            'creator' => 'Flavio Poletti',
            'dist' => 'Acme-EyeDrops',
            'rating' => '5'
        },
    ],

The ratings key will contain a (possibly empty) arrayref of hashrefs where each hashrefs represents a new review. See WWW::CPANRatings::RSS's fetch() method of explaination of each of the keys/values of those hashrefs.

error

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

If an error occured the error key will be present and its value, which will be a scalar, will contain the description of the error.

rate

    'rate' => 60

The rate key will contain the rate (in seconds) at which the plugin fetches new data.

file

    'file' => 'cpan_ratings.rss.storable'

The file key will contain the filename of the file where the plugin stores already reported reviews.

EXAMPLES

The examples/ directory of this distribution contains ratings_bot.pl which is a fully working CPAN Ratings announcing IRC bot.

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