WWW::Pastebin::PastebinCom::Create(3)

NAME
WWW::Pastebin::PastebinCom::Create - paste to <http://pastebin.com> from Perl.

SYNOPSIS
    use strict;
    use warnings;

    use WWW::Pastebin::PastebinCom::Create;

    my $paste = WWW::Pastebin::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::Pastebin::PastebinCom::Create->new;

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

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

Constructs and returns a brand new yummy juicy WWW::Pastebin::PastebinCom::Create object. Takes two arguments, 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::Pastebin::PastebinCom::Create"'s "timeout" argument is set to as well as "agent" argument is set to mimic Firefox.

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',
        subdomain => 'subdomain',
        private  => 0,
    ) 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".

"subdomain"

    subdomain => 'private_domain'

Optional. Allows one to paste into a so called "private" pastebin with a personal domain name. Takes the domain name.

"uri"

    uri => 'http://private_domain.pastebin.com/'

DEPRECATED. use "subdomain".

  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::Pastebin::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::Pastebin::PastebinCom::Create object is overloaded so instead of calling "paste_uri" method you could simply interpolate the WWW::Pastebin::PastebinCom::Create object. For example:

    my $paster = WWW::Pastebin::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>, <http://mind-power-book.com/>)

Patches by Diab Jerius (DJERIUS)

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

You can also look for information at:

•   RT: CPAN's request tracker

    <http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-Pastebin-PastebinCom-Create>

•   AnnoCPAN: Annotated CPAN documentation

    <http://annocpan.org/dist/WWW-Pastebin-PastebinCom-Create>

•   CPAN Ratings

    <http://cpanratings.perl.org/d/WWW-Pastebin-PastebinCom-Create>

•   Search CPAN

    <http://search.cpan.org/dist/WWW-Pastebin-PastebinCom-Create>

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.