名前¶

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

インターフェース¶

クラスメソッド¶

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

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

%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¶

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

%args は:

scheme :Str = "http"

Protocol scheme. May be http or https.

プロトコロスキーマ。http か https でしょう。

host :Str

Server host to connect.

接続するサーバホスト。

You must specify at least host or url.

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

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.

schema、host、port、path_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.

リクエストする内容。

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

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

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

uri

method

content

headers

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

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

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

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

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

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

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

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

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

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

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

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

$furl->env_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::Cookies、 HTTP::Request、 HTTP::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.