=encoding utf8 =head1 名前 =begin original Furl - Lightning-fast URL fetcher =end original Furl - 軽量で速い URL fetcher =head1 概要 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'); =head1 説明 =begin original 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! =end original Furlはもう一つのHTTPクライアントライブラリです。LWPはPerl5のデファクトスタンダードな HTTPクライアントですが、クリティカルなジョブでは遅すぎますし、週末のハッキングには 複雑過ぎます。Furlはこれらの問題を解決します。楽しんで下さい! =begin original This library is an B software. Any API may change without notice. =end original このライブラリは B<ベータ>ソフトウェアです。予告なくAPIが変更されるかも知れません。 =head1 インターフェース =head2 クラスメソッド =head3 C<< Furl->new(%args | \%args) :Furl >> =begin original Creates and returns a new Furl client with I<%args>. Dies on errors. =end original I<%args>で新しいFurlクライアントを作ります。エラーがあれば死にます。 =begin original I<%args> might be: =end original I<%args> は: =over =item agent :Str = "Furl/$VERSION" =item timeout :Int = 10 =item max_redirects :Int = 7 =item proxy :Str =item no_proxy :Str =item headers :ArrayRef =back =head2 インスタンスメソッド =head3 C<< $furl->request([$request,] %args) :Furl::Response >> =begin original Sends an HTTP request to a specified URL and returns a instance of L. =end original HTTPリクエストを指定のURLに送り、Lのインスタンスを返します。 =begin original I<%args> might be: =end original I<%args> は: =over =item scheme :Str = "http" =begin original Protocol scheme. May be C or C. =end original プロトコロスキーマ。C か C でしょう。 =item host :Str =begin original Server host to connect. =end original 接続するサーバホスト。 =begin original You must specify at least C or C. =end original C か Cのいずれかを指定しなければいけません。 =item port :Int = 80 =begin original Server port to connect. The default is 80 on C<< scheme => 'http' >>, or 443 on C<< scheme => 'https' >>. =end original 接続するサーバのポート。デフォルトは、C<< schema => 'http' >>なら80で、 C<< scheme => 'https' >>なら、443です。 =item path_query :Str = "/" =begin original Path and query to request. =end original リクエストするパスとクエリ。 =item url :Str =begin original URL to request. =end original リクエストするURL。 =begin original You can use C instead of C, C, C and C. =end original C、C、C、Cを指定する代わりにCを使えます。 =item headers :ArrayRef =begin original HTTP request headers. e.g. C<< headers => [ 'Accept-Encoding' => 'gzip' ] >>. =end original HTTPリクエストヘッダ。例 C<< headers => [ 'Accept-Encoding' => 'gzip' ] >>. =item content : Str | ArrayRef[Str] | HashRef[Str] | FileHandle =begin original Content to request. =end original リクエストする内容。 =back =begin original If the number of arguments is an odd number, this method assumes that the first argument is an instance of C. 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) =end original 引数の数が奇数の場合、このメソッドは最初の引数を Cのインスタンスと 想定します。残りの引数は先に説明したいずれの値も取れます(ですが、今の所, それらの値は実際には役にたちません。ですので、使わないで下さい)。 my $req = HTTP::Request->new(...); my $res = $furl->request($req); =begin original You can also specify an object other than HTTP::Request, but the object must implement the following methods: =end original HTTP::Request以外のオブジェクトも指定できますが、指定するオブジェクトは 以下のメソッドを実装していなくてはいけません。 =over 4 =item uri =item method =item content =item headers =back =begin original These must return the same type of values as their counterparts in C. =end original Cにあるメソッドと同じタイプの値を返さなくては行けません。 =begin original You must encode all the queries or this method will die, saying C. =end original すべてのクエリをエンコードする必要があります。さもなくば、C を吐いて死にます。 =head3 C<< $furl->get($url :Str, $headers :ArrayRef[Str] ) >> =begin original This is an easy-to-use alias to C, sending the C method. =end original C簡単に使うためのエイリアスです。Cメソッドを送ります。 =head3 C<< $furl->head($url :Str, $headers :ArrayRef[Str] ) >> =begin original This is an easy-to-use alias to C, sending the C method. =end original C簡単に使うためのエイリアスです。Cメソッドを送ります。 =head3 C<< $furl->post($url :Str, $headers :ArrayRef[Str], $content :Any) >> =begin original This is an easy-to-use alias to C, sending the C method. =end original C簡単に使うためのエイリアスです。Cメソッドを送ります。 =head3 C<< $furl->put($url :Str, $headers :ArrayRef[Str], $content :Any) >> =begin original This is an easy-to-use alias to C, sending the C method. =end original C簡単に使うためのエイリアスです。Cメソッドを送ります。 =head3 C<< $furl->delete($url :Str, $headers :ArrayRef[Str] ) >> =begin original This is an easy-to-use alias to C, sending the C method. =end original C簡単に使うためのエイリアスです。Cメソッドを送ります。 =head3 C<< $furl->env_proxy() >> =begin original Loads proxy settings from C<< $ENV{HTTP_PROXY} >> and C<< $ENV{NO_PROXY} >>. =end original C<< $ENV{HTTP_PROXY} >> と C<< $ENV{NO_PROXY} >> からプロキシ設定を読みこみます。 =head1 FAQ =over 4 =item FurlはXSモジュールに依存しますか? =begin original (Does Furl depends on XS modules?) =end original =begin original No. Although some optional features require XS modules, basic features are available without XS modules. =end original いいえ、いくつかのオプショナルな機能はXSモジュールを必要としますが、 基本的な機能はXSモジュールなしに使えます。 =begin original Note that Furl requires HTTP::Parser::XS, which seems an XS module but includes a pure Perl backend, HTTP::Parser::XS::PP. =end original FurlはHTTP::Parser::XSを必要とします。これはXSモジュールのようですが、 pure PerlのバックエンドであるHTTP::Parser::XS::PPを含んでいます。 =item もっとスピードが必要です。 =begin original (I need more speed.) =end original =begin original See L, which provides the low level interface of L. It is faster than C since L does not create response objects. =end original L を見てください。Lの低レベルのインターフェースを提供しています。 Lはレスポンスオブジェクトを作らないのでCより速いです。 =item cookie_jar を使うには? =begin original (How do you use cookie_jar?) =end original =begin original Furl does not directly support the cookie_jar option available in LWP. You can use L, L, L like following. =end original Furl はLWPで使えるcookie_jarオプションを直接にはサポートしません。 L、 L、 Lを使って 以下のようにできます。 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; $res->request($req); $cookies->extract_cookies($res); # and use $res. =item コンテントレングスをどのように制限できますか? =begin original (How do you limit the response content length?) =end original =begin original You can limit the content length by callback function. =end original コールバック関数を使ってコンテントレングスを制限できます。 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; } ); =item プログレスバーを表示できますか? =begin original (How do you display the progress bar?) =end original 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; } ); =back =head1 著者 Tokuhiro Matsuno Etokuhirom AAJKLFJEF GMAIL COME Fuji, Goro (gfx) =head1 謝辞 Kazuho Oku mala mattn lestrrat walf443 lestrrat =head1 参照 L L L =head1 ライセンス Copyright (C) Tokuhiro Matsuno. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut