/ 
Plient-0.03
River stage zero No dependents
/ Plient

NAME

Plient - the uniform way to use curl, wget, LWP, HTTP::Lite, etc.

SYNOPSIS

use Plient qw/plient plient_support/;
my $content = plient( 'get', 'http://cpan.org' );      # get http://cpan.org

if ( plient_support( 'http', 'post' ) ) {
    my $content = plient(
        'post',
        'http://foo.com',
        {
            body => {
                title => 'foo',
                body  => 'bar',
            }
        }
    );
}

# or if ( my $http_post = plient_support( 'http', 'post' ) ) { my $content = $http_post->( 'http://foo.com', { body => { title => 'foo', body => 'bar', } } ); }

DESCRIPTION

Plient is a wrapper to clients like curl, wget, LWP and HTTP::Lite, aiming to supply a uniform way for users.

It's intended to use in situations where you don't want to bind your applications to one specific client. e.g. forcing users to install curl even when some of them already have wget installed.

Plient will try its best to use clients available.

Plient is a very young project, only a subset of HTTP functionality is implemented currently.

INTERFACE

plient( $method, $uri, $args )

accessing $uri with the specified $method and $args.

return the content server returns unless $args->{output_file} is set, in which case return 1 to indicate success.

$method: for HTTP(S), can be 'get', 'post', 'head', etc.

$uri: e.g. http://cpan.org

$args: hashref, useful keys are:

output_file

the file path returned content from server will be written to. if this option is set, plient() will return 1 if with success.

user and password

for HTTP(S), these will be used to set Authorization header

auth_method

currently, only 'Basic' is supported, default is 'Basic'

content_type

for HTTP(S), specify the Contnet-Type of post data. availables are 'urlencoded' and 'form-data'. default is 'urlencoded'.

headers

hashref, this will be sent as HTTP(S) headers. e.g. { 'User-Agent' => 'plient/0.01' }

body

hashref or arrayref, this will be sent as HTTP(S) post data. e.g. { title => 'foo', body => 'bar', foo => [ 'bar', 'baz' ], file1 => { file => '/path/to/file' }, }

if one value is hashref with file key, it's interpreted as a file upload

plient_support( $protocol, $method, $args )

test if we have $protocol's $method support in current environment. returns the subroutine that can be called like a currying plient(), e.g. the following 2 ways of 'GET' http://cpan.org are equivalent:

my $content = plient('get', 'http://cpan.org');
# ditto using plient_support
my $http_get = plient_support('http', 'get');
if ($http_get) {
    my $content = $http_get->('http://cpan.org');
}

currently $args is not used, we may use it later, e.g. to test if support Digest Authentication.

ENV FOR USERS

PLIENT_DEBUG

show more debug info if this it true.

PLIENT_CURL

curl's path, if not specified, use the one `which curl` returns

PLIENT_CURL_CONFIG

curl-config's path, if not specified, use the one `which curl-config` returns

PLIENT_WGET

wget's path, if not specified, use the one `which wget` returns

PLIENT_HANDLER_PREFERENCE

preference of handlers, format is:

PROTOCOL1:HANDLER1,HANDLER2;PROTOCOL2:HANDLER3,...

e.g. http:HTTPLite,curl,wget;https:curl,wget

default is equal to(not set in this env actually):

http:curl,wget,HTTPLite,LWP;https:curl,wget,LWP

Plient will try the listed one by one to get the first competent one to handle the ongoing request. but if none was found, it will try the other handlers not listed.

ENV FOR DEVELOPERS

PLIENT_HANDLER_PREFERENCE_STRICT

Plient will try other handlers that are not listed in PLIENT_HANDLER_PREFERENCE if all the listed ones can't handle the ongoing request.

if this is true, Plient won't try in this situation, instead, it will die directly.

used in Plient's tests.

PLIENT_TEST_PLACKUP_WAIT

seconds we wait after starting plackup in tests. by default it's 1 second. it can be decimal, e.g. 0.3

this waiting time is to make sure plack is really started.

PLIENT_BUNDLE_MODE

used in plient-make-bundle only, end users shouldn't touch this.

DEPENDENCIES

None.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

AUTHOR

sunnavy <sunnavy@bestpractical.com>

LICENCE AND COPYRIGHT

Copyright 2010-2011 Best Practical Solutions.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.