/ 
POE-Component-WWW-Pastebin-Bot-Pastebot-Create-0.001
River stage one • 2 direct dependents • 2 total dependents
/ POE::Component::WWW::Pastebin::Bot::Pastebot::Create

NAME

POE::Component::WWW::Pastebin::Bot::Pastebot::Create - non-blocking POE wrapper around WWW::Pastebin::Bot::Pastebot::Create

SYNOPSIS

use strict;
use warnings;

use POE qw(Component::WWW::Pastebin::Bot::Pastebot::Create);

my $poco = POE::Component::WWW::Pastebin::Bot::Pastebot::Create->spawn;

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

$poe_kernel->run;

sub _start {
    $poco->paste( {
            event       => 'pasted',
            content     => 'test',
            summary     => 'just testing',
            nick        => 'foos',
        }
    );
}

sub pasted {
    my $in_ref = $_[ARG0];
    if ( $in_ref->{error} ) {
        print "Got error: $in_ref->{error}\n";
    }
    else {
        print "Your paste is located on $in_ref->{uri}\n";
    }
    $poco->shutdown;
}

DESCRIPTION

The module is a POE based non-blocking wrapper around WWW::Pastebin::Bot::Pastebot::Create module which provides interface to create new pastes on pastebin sites powered by Bot::Pastebot.

CONSTRUCTOR

spawn

my $poco = POE::Component::WWW::Pastebin::Bot::Pastebot::Create->spawn;

POE::Component::WWW::Pastebin::Bot::Pastebot::Create->spawn(
    alias => 'paster',
    obj_args => { timeout => 30 },
    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::Pastebin::Bot::Pastebot::Create object. It takes a few arguments, all of which are optional. The possible arguments are as follows:

alias

->spawn( alias => 'paster' );

Optional. Specifies a POE Kernel alias for the component.

obj_args

->spawn( obj_args => { timeout => 30 } );

Optional. Takes a hashref as a value. This hashref will be dereferenced directly into WWW::Pastebin::Bot::Pastebot::Create's contructor. See documentation for WWW::Pastebin::Bot::Pastebot::Create for possible arguments.

options

->spawn(
    options => {
        trace => 1,
        default => 1,
    },
);

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

debug

->spawn(
    debug => 1
);

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

METHODS

paste

$poco->paste( {
        event       => 'event_for_output',
        content     => 'long chunk of text to paste',
        summary     => 'description of the paste',
        nick        => 'Zoffix',
        channel     => '#perl',
        _blah       => 'pooh!',
        session     => 'other',
    }
);

Takes a hashref as an argument, does not return a sensible return value. See paste 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

paste

$poe_kernel->post( paster => paste => {
        event       => 'event_for_output',
        content     => 'long chunk of text to paste',
        summary     => 'description of the paste',
        nick        => 'Zoffix',
        channel     => '#perl',
        _blah       => 'pooh!',
        session     => 'other',
    }
);

Instructs the component to create a new paste. Takes a hashref as an argument, the possible keys/value of that hashref are as follows:

event

{ event => 'results_event', }

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

content

{ content => 'long chunk to paste' }

Mandatory. Specifies the actual content of the paste you want to create.

channel

{ channel => '#perl' }

Optional. Specifies the channel to which the pastebot will announce. Valid values vary as different pastebots configured for different channels, but the value would be the same as what you'd see in the "Channel" select box on the site. Specifying empty string will result in "No channel". Defaults to: '' (no specific channel)

nick

{ nick => 'Zoffix' }

Optional. Specifies the name of the person creating the paste. Defaults to: '' (empty; no name)

summary

{ summary => 'some uber codez' }

Optional. Specifies a short summary of the paste contents. Defaults to: '' (empty; no summary)

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

{
    _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 = {
    'summary' => 'just testing',
    'content' => 'test',
    'nick' => 'foos',
    'uri' => bless( do{\(my $o = 'http://erxz.com/pb/7998')}, 'URI::http' ),
    '_blah' => 'user arg',
};

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

uri

{ 'uri' => bless( do{\(my $o = 'http://erxz.com/pb/7998')}, 'URI::http' ), }

If all worked out without errors uri key will contain a URI object pointing to a newly created paste.

error

{ error => 'Network error: 500 read timeout' }

If an error occured during pasting the error key will be present and its value will contain an explanation of the failure.

valid arguments for paste()

{
    'summary' => 'just testing',
    'content' => 'test',
    'nick' => 'foos',
}

Valid arguments to paste() event/method (i.e. the summary, content, channel and nick) will be present in output containing same values as you gave them when calling paste() event/method.

user defined

{ '_blah' => 'foos' }

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

SEE ALSO

POE, URI, WWW::Pastebin::Bot::Pastebot::Create

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-pastebin-bot-pastebot-create at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-WWW-Pastebin-Bot-Pastebot-Create. 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::Pastebin::Bot::Pastebot::Create

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.