=encoding utf-8 =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 Perl 5, 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 は Perl 5 のデファクトスタンダードな HTTP クライアントですが、クリティカルなジョブでは遅すぎますし、週末のハッキングには 複雑過ぎます。Furl はこれらの問題を解決します。楽しんで下さい! =head1 INTERFACE (インターフェース) =head2 Class Methods (クラスメソッド) =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 capture_request :Bool = false =begin original If this parameter is true, L captures raw request string. You can get it by C<< $res->captured_req_headers >> and C<< $res->captured_req_content >>. =end original このパラメータが真なら、L は生のリクエスト文字列をキャプチャします。 C<< $res->captured_req_headers >> と C<< $res->captured_req_content >> でキャプチャしたものを取得できます。 =item proxy :Str =item no_proxy :Str =item headers :ArrayRef =back =head2 Instance Methods (インスタンスメソッド) =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 (e.g. Furl::Request), but the object must implement the following methods: =end original HTTP::Request以外のオブジェクト(e.g. Furl::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; } ); =item HTTPS リクエストが警告を表示する =begin original (HTTPS requests claims warnings!) =end original =begin original When you make https requests, IO::Socket::SSL may complain about it like: =end original https リクエストをするときに、 IO::Socket::SSL が次のyおうな警告をするかもしれません: ******************************************************************* 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't 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. ******************************************************************* =begin original You should set C explicitly with Furl's C. =end original C を明示的に、Furlの C にセットすべきです。 use IO::Socket::SSL; my $ua = Furl->new( ssl_opts => { SSL_verify_mode => SSL_VERIFY_PEER(), }, }); =begin original See L for details. =end original 詳細は、Lを見てください。 =back =head1 著者 Tokuhiro Matsuno Etokuhirom@gmail.comE Fuji, Goro (gfx) =head1 謝辞 Kazuho Oku mala mattn lestrrat walf443 lestrrat audreyt =head1 参照 L 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