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 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) 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, "" (, ) 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 . 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: * RT: CPAN's request tracker * AnnoCPAN: Annotated CPAN documentation * CPAN Ratings * Search CPAN 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.