名前¶

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

このライブラリは ベータソフトウェアです。予告なくAPIが変更されるかも知れません。

インターフェース¶

クラスメソッド¶

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

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

%args は:

agent :Str = "Furl/$VERSION"

timeout :Int = 10

max_redirects :Int = 7

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以外のオブジェクトも指定できますが、指定するオブジェクトは 以下のメソッドを実装していなくてはいけません。

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

著者¶

Tokuhiro Matsuno <tokuhirom AAJKLFJEF GMAIL COM>

Fuji, Goro (gfx)

謝辞¶

Kazuho Oku

mala

mattn

lestrrat

walf443

lestrrat

参照¶

LWP

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.