/ 
POE-Component-IRC-Plugin-PAUSE-RecentUploads-0.03
/ POE::Component::IRC::Plugin::PAUSE::RecentUploads

NAME

POE::Component::IRC::Plugin::PAUSE::RecentUploads - PoCo::IRC plugin for reporting recent uploads to "/pause.perl.org" in http::

SYNOPSIS

use strict;
use warnings;

use POE::Component::IRC;
use POE::Component::IRC::Plugin::PAUSE::RecentUploads;

my @Channels = ( '#zofbot', '#other_channel' );

my $irc = POE::Component::IRC->spawn( 
        nick    => 'PAUSEBot',
        server  => 'irc.freenode.net',
        port    => 6667,
        ircname => 'PAUSE recent upload reporter',
) or die "Oh noes :( $!";

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


$poe_kernel->run();

sub _start {
    $irc->yield( register => 'all' );
    
    # register our plugin
    $irc->plugin_add(
        'PAUSE' => 
            POE::Component::IRC::Plugin::PAUSE::RecentUploads->new(
                login => 'PAUSE_LOGIN',
                pass  => 'PAUSE_PASS',
                interval => 600,
                channels => \@Channels,
            )
    );
    
    $irc->yield( connect => { } );
    undef;
}

sub irc_001 {
    my ( $kernel, $sender ) = @_[ KERNEL, SENDER ];
    $kernel->post( $sender => join => $_ )
        for @Channels;

    undef;
}

DESCRIPTION

The module provides a POE::Component::IRC plugin using POE::Component::IRC::Plugin which reports recent uploads to PAUSE (http://pause.perl.org)

CONTRUCTOR

$irc->plugin_add(
    'PAUSE' => 
        POE::Component::IRC::Plugin::PAUSE::RecentUploads->new(
            login => 'PAUSE_LOGIN',
            pass  => 'PAUSE_PASS',
            interval => 600,
            channels => \@Channels,
            flood_limit => 5,
        )
);

The contructor takes a few arguments which specify the behaviour of the plugin. Three arguments, login, pass and channels are mandatory the rest are optional. The contructor returns a POE::Component::IRC::Plugin object suitable for consumtion with POE::Component::IRC plugin_add() method. The accepted arguments are as follows:

login

->new( login => 'PAUSE_LOGIN' )

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

pass

->new( pass => 'PAUSE_PASS' )

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

channels

->new( channels => \@Channels )

->new( channels => [ '#just_pause', '#reports' ] )

Mandatory. Takes an arrayref as a value which should contain the channels in which the plugin should report new uploads (see also quiet option)

interval

{ interval  => 600 }

Optional. Specifies the interval in seconds between requests to PAUSE for fresh list. If specified to 0 will make the component only fire a single shot request without setting any interval. Defaults to: 600 (10 minutes)

loud_format

->new( loud_format => 'ACTION upload: [[:dist:]] by [[:name:]]' )

->new( loud_format => '[[:name:]] uploaded [[:dist:]] (size: [[:size:]])' )

Optional. If automatic reporting is turned on (see quiet option) The loud_format takes a scalar that specifies the format of the report message. There are three special sequences in the format which will be replaced with data before being sent out, those are as follows:

flood_format

->new( flood_format  => 'ACTION Total of [[:total:]] uploads were uploaded' );

Optional. When when flood_limit is in effect (see below) and the total number of the uploads is exceeded, the flood_format message will sent. The special string [[:total:]] will be replaced by the total number of uploads found. Defaults to: ACTION Total of [[:total:]] uploads were uploaded.

[[:dist:]]

Will be replaced with the uploaded distribution name

[[:name:]]

Will be replaced with the PAUSE ID of the author of the upload

[[:size:]]

Will be replaced with the size of the upload

The replacement will replace any number of each of the formats so feel free to be redundant at will. Default format is: 'ACTION upload: [[:dist:]] by [[:name:]]'

message_type

->new( message_type  => 'ctcp' )

->new( message_type  => 'privmsg' )

Optional. In addition to loud_format you may specify the type of messages the reports will be sent in. For example, setting message_type to ctcp and adding ACTION into loud_format would make the plugin reports via as a /me command, and setting message_type to privmsg would make the plugin "speak" the format normally into the channels. Defaults to: ctcp

Even though it's untested you could possibly set user nicks as channels (see above) and send notice's. However, in that case you'd probably would want to set quiet option (see below) and listen to the events the plugin emits.

quiet

->new( quiet => 1 )

Optional. When quiet option is set to a true value the plugin will not do the "reports" (see message_type and loud_format options above). It will only emit the two type of events (see below). Defaults to: 0

flood_limit

->new( flood_limit => 5 );

Optional. The flood_limit prevents channel floods when quiet option is set to a false value (its the default). If after fetching a new list of uploads, the number of uploads exceeds the number specified in flood_limit, the plugin will respond only with the total number of uploads. You can still get the details via the sent out event (see EMITED EVENTS section). If flood_limit is set to undef no flood protection will be in effect. Defaults to: undef (no flood protection).

fetched_event

->new( fetched_event => 'pause_uploads_list_event' )

Optional. Specifies the name of the event to emit after fetching the list of uploads (see EMITED EVENTS section for details). Defaults to: pause_uploads_list

report_event

->new( report_event  => 'pause_new_uploads_event' )

Optional. Specifies the name of the event to emit when a fetched list contains uploads which haven't been reported before. Defaults to: pause_new_uploads

store

{ store => 'storage_file.data' }

{ store => '/tmp/storage_file.data' }

Optional. Specifies the filename of the file where we are going to store the already reported modules. Defaults to: pause_recent.data in the current directory.

ua_args

->new(
    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.

debug

->new( debug => 1 )

Optional. When set to a true value will make the plugin print out some debug messages. Defaults to: 0

EMITED EVENTS

Even though in most cases setting up the plugin with format and ctcp will suffice for the operation of the plugin you also have an option of listening to the two events it emits. The event names are specified by fetched_event and report_event options to the constructor (see above).

fetched_event

The fetched_event will be emitted every time the plugin accesses http://pause.perl.org for a fresh list of uploads. This will be emited every interval seconds (see contructor's interval option above). The input will be in ARG0 and will be exactly the same as in POE::Component::WWW::PAUSE::RecentUploads::Tail output. See EMITED EVENTS section in POE::Component::WWW::PAUSE::RecentUploads::Tail documentation for the format of ARG0

report_event

The report_event will be emitted every time the plugin discovers a new upload to http://pause.perl.org. This will be emited every time a "loud" version of the plugin would send out reports ( see quiet, loud_format and message_type options to the contructor). If the "loud" version doesn't satisfy your needs you can easily turn the quiet option to the constructor on and use a handler for this event to handle the reports.

The input will be in ARG0 and will be exactly the same as in POE::Component::WWW::PAUSE::RecentUploads::Tail output. See EMITED EVENTS section in POE::Component::WWW::PAUSE::RecentUploads::Tail documentation for the format of ARG0

SEE ALSO

POE, POE::Component::IRC, POE::Component::IRC::Plugin, POE::Component::WWW::PAUSE::RecentUploads::Tail

PREREQUISITES

For healthy operation this module requires you to have the following modules/versions:

Carp                                             => 1.04,
POE                                              => 0.9999,
POE::Component::IRC::Plugin                      => 0.09,
POE::Component::WWW::PAUSE::RecentUploads::Tail  => 0.01,

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-pause-recentuploads at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-IRC-Plugin-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::IRC::Plugin::PAUSE::RecentUploads

You can also look for information at:

ACKNOWLEDGEMENTS

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.