/ 
POE-Component-WWW-PastebinCom-Retrieve-0.002
/ POE::Component::WWW::PastebinCom::Retrieve

NAME

POE::Component::WWW::PastebinCom::Retrieve - non-blocking wrapper around WWW::PastebinCom::Retrieve

SYNOPSIS

use strict;
use warnings;

use POE qw(Component::WWW::PastebinCom::Retrieve);

my $poco = POE::Component::WWW::PastebinCom::Retrieve->spawn;

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

$poe_kernel->run;

sub _start {
    $poco->retrieve( {
            id    => 'http://pastebin.com/m73779e58',
            event => 'retrieved',
        }
    );
}

sub retrieved {
    my $in = $_[ARG0];
    if ( $in->{error} ) {
        print "Got an error: $in->{error}\n";
    }
    else {
        print "Paste $in->{id} is:\n$in->{content}\n";
    }
    $poco->shutdown;
}

Using event based interface is also possible of course.

DESCRIPTION

The module is a non-blocking wrapper around WWW::PastebinCom::Retrieve which provides interface to retrieve pastes from http://pastebin.com

CONSTRUCTOR

spawn

my $poco = POE::Component::WWW::PastebinCom::Retrieve->spawn;

POE::Component::WWW::PastebinCom::Retrieve->spawn(
    alias => 'paster',
    timeout => 10,
    # or:  ua => LWP::UserAgent->new( timeout => 10, agent => 'blah),
    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::PastebinCom::Retrieve object. It takes a few arguments, all of which are optional. The possible arguments are as follows:

alias

POE::Component::WWW::PastebinCom::Retrieve->spawn(
    alias => 'paster'
);

Optional. Specifies a POE Kernel alias for the component.

timeout

->spawn( timeout => 10 );

Optional. Specifies the timeout argument of LWP::UserAgent's constructor, which is used for pasting. Defaults to: 30 seconds.

ua

->spawn( ua => LWP::UserAgent->new( agent => 'Foos!' ) );

Optional. If the timeout argument is not enough for your needs of mutilating the LWP::UserAgent object used for retrieving the pastes, feel free to specify the ua argument which takes an LWP::UserAgent object as a value. Note: the timeout argument to the constructor will not do anything if you specify the ua argument as well. Defaults to: plain boring default LWP::UserAgent object with timeout argument set to whatever POE::Component::WWW::PastebinCom::Retrieve's timeout argument is set to as well as agent argument is set to mimic Firefox.

options

my $poco = POE::Component::WWW::PastebinCom::Retrieve->spawn(
    options => {
        trace => 1,
        default => 1,
    },
);

Optioanl. A hashref of POE Session options to pass to the component's session.

debug

my $poco = POE::Component::WWW::PastebinCom::Retrieve->spawn(
    debug => 1
);

When set to a true value turns on output of debug messages. Defaults to: 0.

METHODS

retrieve

$poco->retrieve( {
        event => 'event_for_output',
        id    => 'http://pastebin.com/m73779e58',
        # or just 'm73779e58',
        _blah => 'pooh!',
        session => 'other',
    }
);

Takes a hashref as an argument, does not return a sensible return value. See retrieve event's description for more information.

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

retrieve

$poe_kernel->post( paster => retrieve => {
        event => 'event_for_output',
        id    => 'http://pastebin.com/m73779e58',
        # or just 'm73779e58',
        _blah => 'pooh!',
        session => 'other',
    }
);

event

{ event => 'results_event', }

Mandatory. Specifies the name of the event to emit when results are ready. See OUTPUT section for more information.

id

{ id => 'http://pastebin.com/m73779e58' }

{ id => 'm73779e58' }

Mandatory. As a value takes a full URI to the paste you want to retrieve or just its ID.

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.

shutdown

$poe_kernel->post( paster => 'shutdown' );

Takes no arguments. Tells the component to shut itself down.

OUTPUT

$VAR1 = {
    'id'  => 'http://pastebin.com/m73779e58',
    'content' => 'blah blah',
}

The event handler set up to handle the event which you've specified in the event argument to retrieve() method/event will recieve input in the $_[ARG0] in a form of a hashref. The possible keys/value of that hashref are as follows:

content

If the paste was retrieved successfully the content key will contain the content of the paste as its value.

error

If there was some problem while retrieving your paste the content key will not be present and the error key will be present instead and will contain a human parsable description of the error.

id

The id key will contain whatever you've specified as an id argument to retrieve() event/method.

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

Any arguments beginning with _ (underscore) passed into the retrieve() event/method will be present intact in the result.

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-pastebincom-retrieve at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-WWW-PastebinCom-Retrieve. 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::PastebinCom::Retrieve

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.