Furl-3.00 > Furl
Furl-3.00
Other versions:
Furl-3.01
Furl-0.24

名前

Furl - Lightning-fast URL fetcher

Furl - 軽量で速い URL fetcher

概要

    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');

説明

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!

Furl はもう一つの HTTP クライアントライブラリです。LWP は Perl 5 のデファクトスタンダードな HTTP クライアントですが、クリティカルなジョブでは遅すぎますし、週末のハッキングには 複雑過ぎます。Furl はこれらの問題を解決します。楽しんで下さい!

インターフェース

クラスメソッド

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

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

%args で新しい Furl クライアントを作ります。エラーがあれば死にます。

%args might be:

%args は:

agent :Str = "Furl/$VERSION"
timeout :Int = 10
max_redirects :Int = 7
capture_request :Bool = false

If this parameter is true, Furl::HTTP captures raw request string. You can get it by $res->captured_req_headers and $res->captured_req_content.

このパラメータが真なら、Furl::HTTP は生のリクエスト文字列をキャプチャします。 $res->captured_req_headers$res->captured_req_content でキャプチャしたものを取得できます。

proxy :Str
no_proxy :Str
headers :ArrayRef

インスタンスメソッド

$furl->request([$request,] %args) :Furl::Response

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

HTTPリクエストを指定のURLに送り、Furl::Responseのインスタンスを返します。

%args might be:

%args は:

scheme :Str = "http"

Protocol scheme. May be http or https.

プロトコロスキーマ。httphttps でしょう。

host :Str

Server host to connect.

接続するサーバホスト。

You must specify at least host or url.

hosturlのいずれかを指定しなければいけません。

port :Int = 80

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

接続するサーバのポート。デフォルトは、schema => 'http'なら80で、 scheme => 'https'なら、443です。

path_query :Str = "/"

Path and query to request.

リクエストするパスとクエリ。

url :Str

URL to request.

リクエストするURL。

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

schemahostportpath_queryを指定する代わりにurlを使えます。

headers :ArrayRef

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

HTTPリクエストヘッダ。例 headers => [ 'Accept-Encoding' => 'gzip' ].

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

Content to request.

リクエストする内容。

If the number of arguments is an odd number, this method assumes that the first argument is an instance of HTTP::Request. 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)

引数の数が奇数の場合、このメソッドは最初の引数を HTTP::Requestのインスタンスと 想定します。残りの引数は先に説明したいずれの値も取れます(ですが、今の所, それらの値は実際には役にたちません。ですので、使わないで下さい)。

    my $req = HTTP::Request->new(...);
    my $res = $furl->request($req);

You can also specify an object other than HTTP::Request (e.g. Furl::Request), but the object must implement the following methods:

HTTP::Request以外のオブジェクト(e.g. Furl::Request)も指定できますが、 指定するオブジェクトは以下のメソッドを実装していなくてはいけません。

uri
method
content
headers

These must return the same type of values as their counterparts in HTTP::Request.

HTTP::Requestにあるメソッドと同じタイプの値を返さなくては行けません。

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

すべてのクエリをエンコードする必要があります。さもなくば、Wide character in ... を吐いて死にます。

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

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

request()簡単に使うためのエイリアスです。GETメソッドを送ります。

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

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

request()簡単に使うためのエイリアスです。HEDメソッドを送ります。

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

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

request()簡単に使うためのエイリアスです。POSTメソッドを送ります。

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

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

request()簡単に使うためのエイリアスです。PUTメソッドを送ります。

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

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

request()簡単に使うためのエイリアスです。DELETEメソッドを送ります。

$furl->env_proxy()

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

$ENV{HTTP_PROXY}$ENV{NO_PROXY} からプロキシ設定を読みこみます。

FAQ

FurlはXSモジュールに依存しますか?

(Does Furl depends on XS modules?)

No. Although some optional features require XS modules, basic features are available without XS modules.

いいえ、いくつかのオプショナルな機能はXSモジュールを必要としますが、 基本的な機能はXSモジュールなしに使えます。

Note that Furl requires HTTP::Parser::XS, which seems an XS module but includes a pure Perl backend, HTTP::Parser::XS::PP.

FurlはHTTP::Parser::XSを必要とします。これはXSモジュールのようですが、 pure PerlのバックエンドであるHTTP::Parser::XS::PPを含んでいます。

もっとスピードが必要です。

(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.

Furl::HTTP を見てください。Furlの低レベルのインターフェースを提供しています。 Furl::HTTPはレスポンスオブジェクトを作らないのでFurl.pmより速いです。

cookie_jar を使うには?

(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.

Furl はLWPで使えるcookie_jarオプションを直接にはサポートしません。 HTTP::CookiesHTTP::RequestHTTP::Responseを使って 以下のようにできます。

    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.
コンテントレングスをどのように制限できますか?

(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;
        }
    );
HTTPS リクエストが警告を表示する

(HTTPS requests claims warnings!)

When you make https requests, IO::Socket::SSL may complain about it like:

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.
    *******************************************************************

You should set SSL_verify_mode explicitly with Furl's ssl_opts.

SSL_verify_mode を明示的に、Furlの ssl_opts にセットすべきです。

    use IO::Socket::SSL;

    my $ua = Furl->new(
        ssl_opts => {
            SSL_verify_mode => SSL_VERIFY_PEER(),
        },
    });

See IO::Socket::SSL for details.

詳細は、IO::Socket::SSLを見てください。

著者

Tokuhiro Matsuno <tokuhirom@gmail.com> Fuji, Goro (gfx)

謝辞

Kazuho Oku

mala

mattn

lestrrat

walf443

lestrrat

audreyt

参照

LWP

IO::Socket::SSL

Furl::HTTP

Furl::Response

ライセンス

Copyright (C) Tokuhiro Matsuno.

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