=head1 NAME

POE::Component::IRC::Plugin::Trac::RSS - A POE::Component::IRC plugin that provides RSS headline retrieval.

=head1 SYNOPSIS

  use strict;
  use warnings;
  use POE qw(Component::IRC Component::IRC::Plugin::Trac::RSS);

  my $nickname = 'TracRSS' . $$;
  my $ircname = 'TracRSS Name';
  my $ircserver = 'irc.nnnnn.net';
  my $port = 6667;
  my $channel = '#channel';
  my $rss_url = 'http://';
  my $rss_username = 'username';
  my $rss_password = 'password';

  my $irc = POE::Component::IRC->spawn(
        nick => $nickname,
        server => $ircserver,
        port => $port,
        ircname => $ircname,
        debug => 0,
        plugin_debug => 1,
        options => { trace => 0 },
  ) or die "Oh noooo! $!";

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

  $poe_kernel->run();
  exit 0;

  sub _start {
    # Create and load our plugin
    $irc->plugin_add( 'TracRSS' =>
        POE::Component::IRC::Plugin::Trac::RSS->new() );

    $irc->yield( register => 'all' );
    $irc->yield( connect => { } );
    undef;
  }

  sub irc_001 {
    $irc->yield( join => $channel );
    undef;
  }

  sub irc_join {
    my ($kernel,$sender,$channel) = @_[KERNEL,SENDER,ARG1];
    print STDERR "$channel $rss_url\n";
    $kernel->yield( 'get_tracrss', { url => $rss_url, username => $rss_username, password => $rss_password, _channel => $channel } );
    undef;
  }

  sub irc_tracrss_items {
    my ($kernel,$sender,$args) = @_[KERNEL,SENDER,ARG0];
    my $channel = delete $args->{_channel};
    $kernel->post( $sender, 'privmsg', $channel, join(' ', @_[ARG1..$#_] ) );
    undef;
  }

=head1 DESCRIPTION

POE::Component::IRC::Plugin::Trac::RSS, is a L<POE::Component::IRC> plugin that provides
a mechanism for retrieving Trac/RSS headlines from given URLs.

=head1 CONSTRUCTOR

=over 

=item new

Creates a new plugin object. Takes the following optional arguments:

  'http_alias', you may provide the alias of an existing POE::Component::Client::HTTP 
		component that the plugin will use instead of spawning it's own;
  'follow_redirects', this argument is passed to PoCoCl::HTTP to inform it how to deal with
		following redirects, default is 2;

=back

=head1 INPUT EVENTS

The plugin registers the following state handler within your session:

=over

=item get_trac_rss

Takes a hashref as an argument with the following keys:

  'url', the RSS based url to retrieve items for;
  'username', Username to login in trac.
  'password', Password to login in trac.

You may pass arbitary key/value pairs, but the keys must be prefixed with an underscore.

=back

=head1 OUTPUT

The following irc event is generated with the result of a 'get_headline' command:

=over

=item irc_tracrss_items

Has the following parameters:

  'ARG0', the original hashref that was passed;
  'ARG1' .. $#_, RSS headline item titles;

=item irc_tracrss_error

Has the following parameters:

  'ARG0', the original hashref that was passed;
  'ARG1', the error text;

=back

=head1 AUTHOR

Thiago Berlitz Rondon

=head1 LICENSE

Copyright C<(c)> Thiago Berlitz Rondon

This module may be used, modified, and distributed under the same terms as Perl itself. Please see the license that came with your Perl distribution for details.

=head1 SEE ALSO

L<POE::Component::IRC>