/ 
WWW-PastebinCom-Create-0.001
/ WWW::PastebinCom::Create

NAME

WWW::PastebinCom::Create - paste to http://pastebin.com from Perl.

SYNOPSIS

use strict;
use warnings;

use WWW::PastebinCom::Create;

my $paste = WWW::PastebinCom::Create->new;

$paste->paste( text => 'lots and lost of text to paste' )
    or die "Error: " . $paste->error;

print "Your paste can be found on $paste\n";

DESCRIPTION

The module provides means of pasting large texts into http://pastebin.com pastebin site.

CONSTRUCTOR

new

my $paste = WWW::PastebinCom::Create->new;

my $paste = WWW::PastebinCom::Create->new(
    timeout => 10,
);

my $paste = WWW::PastebinCom::Create->new(
    ua => LWP::UserAgent->new(
        timeout => 10,
        agent   => 'PasterUA',
    ),
);

Constructs and returns a brand new yummy juicy WWW::PastebinCom::Create object. Takes two argument, both are optional. Possible arguments are as follows:

timeout

->new( timeout => 10 );

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

ua

->new( 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 pasting, 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 WWW::PastebinCom::Create's timeout argument is set to.

METHODS

paste

$paste->paste( text => 'long long text' )
    or die "Failed to paste: " . $paste->error;

my $paste_uri = $paste->paste(
    text => 'long long text',
    format => 'perl',
    poster => 'Zoffix',
    expiry => 'm',
) or die "Failed to paste: " . $paste->error;

Instructs the object to pastebin some text. If pasting succeeded returns a URI pointing to your paste, otherwise returns either undef or an empty list (depending on the context) and the reason for the failure will be avalable via error() method (see below).

Note: you don't have to store the return value. There is a paste_uri() method as well as overloaded construct; see paste_uri() method's description below.

Takes one mandatory and three optional arguments which are as follows:

text

->paste( text => 'long long long long text to paste' );

Mandatory. The text argument must contain the text to paste. If text's value is undefined the paste() method will return either undef or an empty list (depending on the context) and the error() method will contain a message about undefined text.

format

->paste( text => 'foo', format => 'perl' );

Optional. Specifies the format of the paste to enable specific syntax highlights on http://pastebin.com. The list of possible values is very long, see get_valid_formats() method below for information on how to obtain possible valid values for the format argument. Defaults to: text (plain text paste).

poster

->paste( text => 'foo', poster => 'Zoffix Znet' );

Optional. Specifies the name of the person pasting the text. Defaults to: empty string, which leads to Anonymous apearing on http://pastebin.com

expiry

->paste( text => 'foo', expiry => 'f' );

Optional. Specifies when the paste should expire. Defaults to: d (expire the paste in one day). Takes three possible values:

d

When expiry is set to value d, the paste will expire in one day.

m

When expiry is set to value m, the paste will expire in one month.

f

When expiry is set to value f, the paste will (should) stick around "forever".

error

$paste->paste( text => 'foos' )
    or die "Error: " . $paste->error;

If the paste() method failed to paste your text for any reason (including your text being undefined) it will return either undef or an empty list depending on the context. When that happens you will be able to find out the reason of the error via error() method. Returns a scalar containing human readable message describing the error. Takes no arguments.

paste_uri (and overloads)

print "You can find your pasted text on " . $paste->paste_uri . "\n";

# or by interpolating the WWW::PastebinCom::Create object directly:
print "You can find your pasted text on $paste\n";

Takes no arguments. Returns a URI pointing to the http://pastebin.com page containing the text you have pasted. If you call this method before pasting anything or if paste() method failed the paste_uri will return either undef or an empty list depending on the context.

Note: the WWW::PastebinCom::Create object is overloaded so instead of calling paste_uri method you could simply interpolate the WWW::PastebinCom::Create object. For example:

my $paster = WWW::PastebinCom::Create->new;
$paster->paste( text => 'long text' )
    or die "Failed to paste: " . $paster->error;
    
print "Your paste is located on $paster\n";

get_valid_formats

my $valid_formats_hashref = $paste->get_valid_formats;

Takes no arguments. Returns a hashref, keys of which will be valid values of the format argument to paste() method and values of which will be explanation of semi-cryptic codes.

AUTHOR

Zoffix Znet, <zoffix at cpan.org> (http://zoffix.com, http://haslayout.net)

BUGS

Please report any bugs or feature requests to bug-www-pastebincom-create at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-PastebinCom-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 WWW::PastebinCom::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.