.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Furl 3pm"
.TH Furl 3pm "2019-03-21" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Furl \- Lightning\-fast URL fetcher
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Furl;
\&
\&    my $furl = Furl\->new(
\&        agent   => \*(AqMyGreatUA/2.0\*(Aq,
\&        timeout => 10,
\&    );
\&
\&    my $res = $furl\->get(\*(Aqhttp://example.com/\*(Aq);
\&    die $res\->status_line unless $res\->is_success;
\&    print $res\->content;
\&
\&    my $res = $furl\->post(
\&        \*(Aqhttp://example.com/\*(Aq, # URL
\&        [...],                 # headers
\&        [ foo => \*(Aqbar\*(Aq ],      # form data (HashRef/FileHandle are also okay)
\&    );
\&
\&    # Accept\-Encoding is supported but optional
\&    $furl = Furl\->new(
\&        headers => [ \*(AqAccept\-Encoding\*(Aq => \*(Aqgzip\*(Aq ],
\&    );
\&    my $body = $furl\->get(\*(Aqhttp://example.com/some/compressed\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Furl is yet another \s-1HTTP\s0 client library. \s-1LWP\s0 is the de facto standard \s-1HTTP\s0
client for Perl 5, but it is too slow for some critical jobs, and too complex
for weekend hacking. Furl resolves these issues. Enjoy it!
.SH "INTERFACE"
.IX Header "INTERFACE"
.SS "Class Methods"
.IX Subsection "Class Methods"
\fI\f(CI\*(C`Furl\->new(%args | \e%args) :Furl\*(C'\fI\fR
.IX Subsection "Furl->new(%args | %args) :Furl"
.PP
Creates and returns a new Furl client with \fI\f(CI%args\fI\fR. Dies on errors.
.PP
\&\fI\f(CI%args\fI\fR might be:
.ie n .IP "agent :Str = ""Furl/$VERSION""" 4
.el .IP "agent :Str = ``Furl/$VERSION''" 4
.IX Item "agent :Str = Furl/$VERSION"
.PD 0
.IP "timeout :Int = 10" 4
.IX Item "timeout :Int = 10"
.IP "max_redirects :Int = 7" 4
.IX Item "max_redirects :Int = 7"
.IP "capture_request :Bool = false" 4
.IX Item "capture_request :Bool = false"
.PD
If this parameter is true, Furl::HTTP captures raw request string.
You can get it by \f(CW\*(C`$res\->captured_req_headers\*(C'\fR and \f(CW\*(C`$res\->captured_req_content\*(C'\fR.
.IP "proxy :Str" 4
.IX Item "proxy :Str"
.PD 0
.IP "no_proxy :Str" 4
.IX Item "no_proxy :Str"
.IP "headers :ArrayRef" 4
.IX Item "headers :ArrayRef"
.IP "cookie_jar :Object" 4
.IX Item "cookie_jar :Object"
.PD
(\s-1EXPERIMENTAL\s0)
.Sp
An instance of HTTP::CookieJar or equivalent class that supports the add and cookie_header methods
.SS "Instance Methods"
.IX Subsection "Instance Methods"
\fI\f(CI\*(C`$furl\->request([$request,] %args) :Furl::Response\*(C'\fI\fR
.IX Subsection "$furl->request([$request,] %args) :Furl::Response"
.PP
Sends an \s-1HTTP\s0 request to a specified \s-1URL\s0 and returns a instance of Furl::Response.
.PP
\&\fI\f(CI%args\fI\fR might be:
.ie n .IP "scheme :Str = ""http""" 4
.el .IP "scheme :Str = ``http''" 4
.IX Item "scheme :Str = http"
Protocol scheme. May be \f(CW\*(C`http\*(C'\fR or \f(CW\*(C`https\*(C'\fR.
.IP "host :Str" 4
.IX Item "host :Str"
Server host to connect.
.Sp
You must specify at least \f(CW\*(C`host\*(C'\fR or \f(CW\*(C`url\*(C'\fR.
.IP "port :Int = 80" 4
.IX Item "port :Int = 80"
Server port to connect. The default is 80 on \f(CW\*(C`scheme => \*(Aqhttp\*(Aq\*(C'\fR,
or 443 on \f(CW\*(C`scheme => \*(Aqhttps\*(Aq\*(C'\fR.
.ie n .IP "path_query :Str = ""/""" 4
.el .IP "path_query :Str = ``/''" 4
.IX Item "path_query :Str = /"
Path and query to request.
.IP "url :Str" 4
.IX Item "url :Str"
\&\s-1URL\s0 to request.
.Sp
You can use \f(CW\*(C`url\*(C'\fR instead of \f(CW\*(C`scheme\*(C'\fR, \f(CW\*(C`host\*(C'\fR, \f(CW\*(C`port\*(C'\fR and \f(CW\*(C`path_query\*(C'\fR.
.IP "headers :ArrayRef" 4
.IX Item "headers :ArrayRef"
\&\s-1HTTP\s0 request headers. e.g. \f(CW\*(C`headers => [ \*(AqAccept\-Encoding\*(Aq => \*(Aqgzip\*(Aq ]\*(C'\fR.
.IP "content : Str | ArrayRef[Str] | HashRef[Str] | FileHandle" 4
.IX Item "content : Str | ArrayRef[Str] | HashRef[Str] | FileHandle"
Content to request.
.PP
If the number of arguments is an odd number, this method assumes that the
first argument is an instance of \f(CW\*(C`HTTP::Request\*(C'\fR. Remaining arguments
can be any of the previously describe values (but currently there's no
way to really utilize them, so don't use it)
.PP
.Vb 2
\&    my $req = HTTP::Request\->new(...);
\&    my $res = $furl\->request($req);
.Ve
.PP
You can also specify an object other than HTTP::Request (e.g. Furl::Request),
but the object must implement the following methods:
.IP "uri" 4
.IX Item "uri"
.PD 0
.IP "method" 4
.IX Item "method"
.IP "content" 4
.IX Item "content"
.IP "headers" 4
.IX Item "headers"
.PD
.PP
These must return the same type of values as their counterparts in
\&\f(CW\*(C`HTTP::Request\*(C'\fR.
.PP
You must encode all the queries or this method will die, saying
\&\f(CW\*(C`Wide character in ...\*(C'\fR.
.PP
\fI\f(CI\*(C`$furl\->get($url :Str, $headers :ArrayRef[Str] )\*(C'\fI\fR
.IX Subsection "$furl->get($url :Str, $headers :ArrayRef[Str] )"
.PP
This is an easy-to-use alias to \f(CW\*(C`request()\*(C'\fR, sending the \f(CW\*(C`GET\*(C'\fR method.
.PP
\fI\f(CI\*(C`$furl\->head($url :Str, $headers :ArrayRef[Str] )\*(C'\fI\fR
.IX Subsection "$furl->head($url :Str, $headers :ArrayRef[Str] )"
.PP
This is an easy-to-use alias to \f(CW\*(C`request()\*(C'\fR, sending the \f(CW\*(C`HEAD\*(C'\fR method.
.PP
\fI\f(CI\*(C`$furl\->post($url :Str, $headers :ArrayRef[Str], $content :Any)\*(C'\fI\fR
.IX Subsection "$furl->post($url :Str, $headers :ArrayRef[Str], $content :Any)"
.PP
This is an easy-to-use alias to \f(CW\*(C`request()\*(C'\fR, sending the \f(CW\*(C`POST\*(C'\fR method.
.PP
\fI\f(CI\*(C`$furl\->put($url :Str, $headers :ArrayRef[Str], $content :Any)\*(C'\fI\fR
.IX Subsection "$furl->put($url :Str, $headers :ArrayRef[Str], $content :Any)"
.PP
This is an easy-to-use alias to \f(CW\*(C`request()\*(C'\fR, sending the \f(CW\*(C`PUT\*(C'\fR method.
.PP
\fI\f(CI\*(C`$furl\->delete($url :Str, $headers :ArrayRef[Str] )\*(C'\fI\fR
.IX Subsection "$furl->delete($url :Str, $headers :ArrayRef[Str] )"
.PP
This is an easy-to-use alias to \f(CW\*(C`request()\*(C'\fR, sending the \f(CW\*(C`DELETE\*(C'\fR method.
.PP
\fI\f(CI\*(C`$furl\->env_proxy()\*(C'\fI\fR
.IX Subsection "$furl->env_proxy()"
.PP
Loads proxy settings from \f(CW$ENV{HTTP_PROXY}\fR and \f(CW$ENV{NO_PROXY}\fR.
.SH "TIPS"
.IX Header "TIPS"
.IP "IO::Socket::SSL preloading" 4
.IX Item "IO::Socket::SSL preloading"
Furl interprets the \f(CW\*(C`timoeut\*(C'\fR argument as the maximum time the module is permitted to spend before returning an error.
.Sp
The module also lazy-loads IO::Socket::SSL when an \s-1HTTPS\s0 request is being issued for the first time. Loading the module usually takes ~0.1 seconds.
.Sp
The time spent for loading the \s-1SSL\s0 module may become an issue in case you want to impose a very small timeout value for connection establishment. In such case, users are advised to preload the \s-1SSL\s0 module explicitly.
.SH "FAQ"
.IX Header "FAQ"
.IP "Does Furl depends on \s-1XS\s0 modules?" 4
.IX Item "Does Furl depends on XS modules?"
No. Although some optional features require \s-1XS\s0 modules, basic features are
available without \s-1XS\s0 modules.
.Sp
Note that Furl requires HTTP::Parser::XS, which seems an \s-1XS\s0 module
but includes a pure Perl backend, HTTP::Parser::XS::PP.
.IP "I need more speed." 4
.IX Item "I need more speed."
See Furl::HTTP, which provides the low level interface of Furl.
It is faster than \f(CW\*(C`Furl.pm\*(C'\fR since Furl::HTTP does not create response objects.
.IP "How do you use cookie_jar?" 4
.IX Item "How do you use cookie_jar?"
Furl does not directly support the cookie_jar option available in \s-1LWP.\s0 You can use HTTP::Cookies, HTTP::Request, HTTP::Response like following.
.Sp
.Vb 8
\&    my $f = Furl\->new();
\&    my $cookies = HTTP::Cookies\->new();
\&    my $req = HTTP::Request\->new(...);
\&    $cookies\->add_cookie_header($req);
\&    my $res = $f\->request($req)\->as_http_response;
\&    $res\->request($req);
\&    $cookies\->extract_cookies($res);
\&    # and use $res.
.Ve
.IP "How do you limit the response content length?" 4
.IX Item "How do you limit the response content length?"
You can limit the content length by callback function.
.Sp
.Vb 10
\&    my $f = Furl\->new();
\&    my $content = \*(Aq\*(Aq;
\&    my $limit = 1_000_000;
\&    my %special_headers = (\*(Aqcontent\-length\*(Aq => undef);
\&    my $res = $f\->request(
\&        method          => \*(AqGET\*(Aq,
\&        url             => $url,
\&        special_headers => \e%special_headers,
\&        write_code      => sub {
\&            my ( $status, $msg, $headers, $buf ) = @_;
\&            if (($special_headers{\*(Aqcontent\-length\*(Aq}||0) > $limit || length($content) > $limit) {
\&                die "over limit: $limit";
\&            }
\&            $content .= $buf;
\&        }
\&    );
.Ve
.IP "How do you display the progress bar?" 4
.IX Item "How do you display the progress bar?"
.Vb 3
\&    my $bar = Term::ProgressBar\->new({count => 1024, ETA => \*(Aqlinear\*(Aq});
\&    $bar\->minor(0);
\&    $bar\->max_update_rate(1);
\&
\&    my $f = Furl\->new();
\&    my $content = \*(Aq\*(Aq;
\&    my %special_headers = (\*(Aqcontent\-length\*(Aq => undef);;
\&    my $did_set_target = 0;
\&    my $received_size = 0;
\&    my $next_update  = 0;
\&    $f\->request(
\&        method          => \*(AqGET\*(Aq,
\&        url             => $url,
\&        special_headers => \e%special_headers,
\&        write_code      => sub {
\&            my ( $status, $msg, $headers, $buf ) = @_;
\&            unless ($did_set_target) {
\&                if ( my $cl = $special_headers{\*(Aqcontent\-length\*(Aq} ) {
\&                    $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;
\&        }
\&    );
.Ve
.IP "\s-1HTTPS\s0 requests claims warnings!" 4
.IX Item "HTTPS requests claims warnings!"
When you make https requests, IO::Socket::SSL may complain about it like:
.Sp
.Vb 8
\&    *******************************************************************
\&     Using the default of SSL_verify_mode of SSL_VERIFY_NONE for client
\&     is depreciated! Please set SSL_verify_mode to SSL_VERIFY_PEER
\&     together with SSL_ca_file|SSL_ca_path for verification.
\&     If you really don\*(Aqt want to verify the certificate and keep the
\&     connection open to Man\-In\-The\-Middle attacks please set
\&     SSL_verify_mode explicitly to SSL_VERIFY_NONE in your application.
\&    *******************************************************************
.Ve
.Sp
You should set \f(CW\*(C`SSL_verify_mode\*(C'\fR explicitly with Furl's \f(CW\*(C`ssl_opts\*(C'\fR.
.Sp
.Vb 1
\&    use IO::Socket::SSL;
\&
\&    my $ua = Furl\->new(
\&        ssl_opts => {
\&            SSL_verify_mode => SSL_VERIFY_PEER(),
\&        },
\&    );
.Ve
.Sp
See IO::Socket::SSL for details.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tokuhiro Matsuno <tokuhirom@gmail.com>
.PP
Fuji, Goro (gfx)
.SH "THANKS TO"
.IX Header "THANKS TO"
Kazuho Oku
.PP
mala
.PP
mattn
.PP
lestrrat
.PP
walf443
.PP
lestrrat
.PP
audreyt
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1LWP\s0
.PP
IO::Socket::SSL
.PP
Furl::HTTP
.PP
Furl::Response
.SH "LICENSE"
.IX Header "LICENSE"
Copyright (C) Tokuhiro Matsuno.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.