Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

pretty fast http client library for perl5

tag: 0.09

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.mkdn

NAME

Furl - Lightning-fast URL fetcher

SYNOPSIS

use Furl;

my $furl = Furl->new(
    agent   => 'MyGreatUA/2.0',
    timeout => 10,
);

my $res = $furl->get('http://example.com/');
die $res->status_line unless $res->is_success;
print $res->content;

my $res = $furl->post(
    'http://example.com/', # URL
    [...],                 # headers
    [ foo => 'bar' ],      # form data (HashRef/FileHandle are also okay)
);

# Accept-Encoding is supported but optional
$furl = Furl->new(
    headers => [ 'Accept-Encoding' => 'gzip' ],
);
my $body = $furl->get('http://example.com/some/compressed');

DESCRIPTION

Furl is yet another HTTP client library. LWP is the de facto standard HTTP client for Perl5, but it is too slow for some critical jobs, and too complex for weekend hacking. Furl resolves these issues. Enjoy it!

This library is an alpha software. Any API may change without notice.

INTERFACE

Class Methods

C<< Furl->new(%args | \%args) :Furl >>

Creates and returns a new Furl client with %args. Dies on errors.

%args might be:

  • agent :Str = "Furl/$VERSION"

  • timeout :Int = 10

  • max_redirects :Int = 7

  • proxy :Str

  • no_proxy :Str

  • headers :ArrayRef

Instance Methods

C<< $furl->request(%args) :Furl::Response >>

Sends an HTTP request to a specified URL and returns a instance of Furl::Response.

%args might be:

  • scheme :Str = "http"

Protocol scheme. May be http or https.

  • host :Str

Server host to connect.

You must specify at least host or url.

  • port :Int = 80

Server port to connect. The default is 80 on scheme => 'http', or 443 on scheme => 'https'.

  • path_query :Str = "/"

Path and query to request.

  • url :Str

URL to request.

You can use url instead of scheme, host, port and path_query.

  • headers :ArrayRef

HTTP request headers. e.g. headers => [ 'Accept-Encoding' => 'gzip' ].

  • content : Str | ArrayRef[Str] | HashRef[Str] | FileHandle

Content to request.

You must encode all the queries or this method will die, saying Wide character in ....

C<< $furl->get($url :Str, $headers :ArrayRef[Str] ) >>

This is an easy-to-use alias to request(), sending the GET method.

C<< $furl->head($url :Str, $headers :ArrayRef[Str] ) >>

This is an easy-to-use alias to request(), sending the HEAD method.

C<< $furl->post($url :Str, $headers :ArrayRef[Str], $content :Any) >>

This is an easy-to-use alias to request(), sending the POST method.

C<< $furl->put($url :Str, $headers :ArrayRef[Str], $content :Any) >>

This is an easy-to-use alias to request(), sending the PUT method.

C<< $furl->delete($url :Str, $headers :ArrayRef[Str] ) >>

This is an easy-to-use alias to request(), sending the DELETE method.

C<< $furl->request_with_http_request($req :HTTP::Request) >>

This is an easy-to-use alias to request() with an instance of HTTP::Request.

C<< $furl->env_proxy() >>

Loads proxy settings from $ENV{HTTP_PROXY} and $ENV{NO_PROXY}.

FAQ

  • I need more speed.

See Furl::HTTP, which provides the low level interface of Furl. It is faster than Furl.pm since Furl::HTTP does not create response objects.

  • How do you use cookie_jar?

Furl does not directly support the cookie_jar option available in LWP. You can use HTTP::Cookies, HTTP::Request, HTTP::Response like following.

my $f = Furl->new();
my $cookies = HTTP::Cookies->new();
my $req = HTTP::Request->new(...);
$cookies->add_cookie_header($req);
my $res = H$f->request_with_http_request($req)->as_http_response;
$cookies->extract_cookies($res);
# and use $res.
  • How do you limit the response content length?

You can limit the content length by callback function.

my $f = Furl->new();
my $content = '';
my $limit = 1_000_000;
my %special_headers = ('content-length' => undef);
my $res = $f->request(
    method          => 'GET',
    url             => $url,
    special_headers => \%special_headers,
    write_code      => sub {
        my ( $status, $msg, $headers, $buf ) = @_;
        if (($special_headers{'content-length'}||0) > $limit || length($content) > $limit) {
            die "over limit: $limit";
        }
        $content .= $buf;
    }
);
  • How do you display the progress bar?

    my $bar = Term::ProgressBar->new({count => 1024, ETA => 'linear'}); $bar->minor(0); $bar->max_update_rate(1);

    my $f = Furl->new(); my $content = ''; my %special_headers = ('content-length' => undef);; my $did_set_target = 0; my $received_size = 0; my $next_update = 0; $f->request( method => 'GET', url => $url, special_headers => \%special_headers, write_code => sub { my ( $status, $msg, $headers, $buf ) = @_; unless ($did_set_target) { if ( my $cl = $special_headers{'content-length'} ) { $bar->target($cl); $did_set_target++; } else { $bar->target( $received_size + 2 * length($buf) ); } } $received_size += length($buf); $content .= $buf; $next_update = $bar->update($received_size) if $received_size >= $next_update; } );

AUTHOR

Tokuhiro Matsuno

Fuji, Goro (gfx)

THANKS TO

Kazuho Oku

mala

mattn

lestrrat

walf443

SEE ALSO

LWP

Furl::HTTP

Furl::Response

LICENSE

Copyright (C) Tokuhiro Matsuno.

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

Something went wrong with that request. Please try again.