=encoding euc-jp

=head1 NAME

=begin original

lwpcook - The libwww-perl cookbook

=end original

lwpcook - libwww-perl クックブック

=head1 DESCRIPTION

=begin original

This document contain some examples that show typical usage of the
libwww-perl library.  You should consult the documentation for the
individual modules for more detail.

=end original

この文書には、libwww-perl ライブラリの典型的な使い方を示す
いくつかのサンプルが入っています。
詳細については各モジュールの文書をご覧下さい。

=begin original

All examples should be runnable programs. You can, in most cases, test
the code sections by piping the program text directly to perl.

=end original

すべてのサンプルは実行可能なプログラムのはずです。
ほとんどの場合、プログラムテキストを perl に直接パイプすることによって
コード部分をテストすることができます。

=head1 GET

=begin original

It is very easy to use this library to just fetch documents from the
net.  The LWP::Simple module provides the get() function that return
the document specified by its URL argument:

=end original

ネットから文書を取り出すだけなら、このライブラリを使って
簡単にできます。
LWP::Simple モジュールは、URL 引数で指定された文書を返す
get() 関数を提供しています:

  use LWP::Simple;
  $doc = get 'http://search.cpan.org/dist/libwww-perl/';

=begin original

or, as a perl one-liner using the getprint() function:

=end original

あるいは、getprint() 関数を使ったperlワンライナーならば:

  perl -MLWP::Simple -e 'getprint "http://search.cpan.org/dist/libwww-perl/"'

=begin original

or, how about fetching the latest perl by running this command:

=end original

あるいは最新の perl をこのコマンドを実行して取り出すというのはどうでしょう:

  perl -MLWP::Simple -e '
    getstore "ftp://ftp.sunet.se/pub/lang/perl/CPAN/src/latest.tar.gz",
             "perl.tar.gz"'

=begin original

You will probably first want to find a CPAN site closer to you by
running something like the following command:

=end original

まずは以下のようなコマンドを実行することで、あなたに一番近い CPAN サイトを
見つけ出したいかもしれません:

  perl -MLWP::Simple -e 'getprint "http://www.cpan.org/SITES.html"'

=begin original

Enough of this simple stuff!  The LWP object oriented interface gives
you more control over the request sent to the server.  Using this
interface you have full control over headers sent and how you want to
handle the response returned.

=end original

この簡単なもので十分!
LWP オブジェクト指向インターフェースは、サーバへのリクエストをさらに
制御できます。
このインタフェースを使うと、ヘッダの送信や返されたレスポンスを
どのように扱いたいかについてすべて制御できます:

  use LWP::UserAgent;
  $ua = LWP::UserAgent->new;
  $ua->agent("$0/0.1 " . $ua->agent);
  # $ua->agent("Mozilla/8.0") # pretend we are very capable browser

  $req = HTTP::Request->new(
     GET => 'http://search.cpan.org/dist/libwww-perl/');
  $req->header('Accept' => 'text/html');

  # send request
  $res = $ua->request($req);

  # check the outcome
  if ($res->is_success) {
     print $res->decoded_content;
  }
  else {
     print "Error: " . $res->status_line . "\n";
  }

=begin original

The lwp-request program (alias GET) that is distributed with the
library can also be used to fetch documents from WWW servers.

=end original

ライブラリと一緒に配布される lwp-request プログラム（別名 GET）も、
WWW サーバからの文書取り出しに使うことができます。

=head1 HEAD

=begin original

If you just want to check if a document is present (i.e. the URL is
valid) try to run code that looks like this:

=end original

文書があるか (つまり URL が正しいか) をチェックしたいだけであれば、
以下のようなコードを実行してみてください:

  use LWP::Simple;

  if (head($url)) {
     # ok document exists
  }

=begin original

The head() function really returns a list of meta-information about
the document.  The first three values of the list returned are the
document type, the size of the document, and the age of the document.

=end original

head() 関数は実際に文書のメタ情報のリストを返します。
返されるリストの最初の三つの値は文書のタイプ、文書の
大きさ、文書の年齢 (age) です。

=begin original

More control over the request or access to all header values returned
require that you use the object oriented interface described for GET
above.  Just s/GET/HEAD/g.

=end original

リクエストをもっと制御したり、返された値のすべてのヘッダの値に
アクセスするためには、上記のGETで説明したオブジェクト指向インターフェースを
使う必要があります。
単に s/GET/HEAD/g してください。

=head1 POST

=begin original

There is no simple procedural interface for posting data to a WWW server.  You
must use the object oriented interface for this. The most common POST
operation is to access a WWW form application:

=end original

WWW にデータをポストするために、単純な手続き型のインターフェースはありません。
これにはオブジェクト指向インタフェースを使わなければなりません。
最も通常の POST 処理は WWW フォームアプリケーションにアクセスすることです:

  use LWP::UserAgent;
  $ua = LWP::UserAgent->new;

  my $req = HTTP::Request->new(
      POST => 'http://rt.cpan.org/Public/Dist/Display.html');
  $req->content_type('application/x-www-form-urlencoded');
  $req->content('Status=Active&Name=libwww-perl');

  my $res = $ua->request($req);
  print $res->as_string;

=begin original

Lazy people use the HTTP::Request::Common module to set up a suitable
POST request message (it handles all the escaping issues) and has a
suitable default for the content_type:

=end original

怠惰な人たちは適切な POST リクエストメッセージを構築するために
HTTP::Request::Common モジュールを使います
(それはすべてのエスケープ問題を扱います)、そして content_type のために
適切なデフォルトを持ちます:

  use HTTP::Request::Common qw(POST);
  use LWP::UserAgent;
  $ua = LWP::UserAgent->new;

  my $req = POST 'http://rt.cpan.org/Public/Dist/Display.html',
                [ Status => 'Active', Name => 'libwww-perl' ];

  print $ua->request($req)->as_string;

=begin original

The lwp-request program (alias POST) that is distributed with the
library can also be used for posting data.

=end original

ライブラリと一緒に配布される lwp-request プログラム (別名 POST) も、
データのポストに使うことができます。

=head1 PROXIES

=begin original

Some sites use proxies to go through fire wall machines, or just as
cache in order to improve performance.  Proxies can also be used for
accessing resources through protocols not supported directly (or
supported badly :-) by the libwww-perl library.

=end original

サイトによってはファイアーウォール機能や、単にパフォーマンスを
向上させるためのキャッシュを実現するためにプロキシを使っています。
libwww-perl ライブラリによって直接サポートされない
(あるいはうまくサポートされていない:-)) プロトコルを通してリソースに
アクセスするためにも,プロキシを使うことができます。

=begin original

You should initialize your proxy setting before you start sending
requests:

=end original

リクエスト送信を開始する前に、プロキシ設定を初期化しなければなりません:

  use LWP::UserAgent;
  $ua = LWP::UserAgent->new;
  $ua->env_proxy; # initialize from environment variables
  # or
  $ua->proxy(ftp  => 'http://proxy.myorg.com');
  $ua->proxy(wais => 'http://proxy.myorg.com');
  $ua->no_proxy(qw(no se fi));

  my $req = HTTP::Request->new(GET => 'wais://xxx.com/');
  print $ua->request($req)->as_string;

=begin original

The LWP::Simple interface will call env_proxy() for you automatically.
Applications that use the $ua->env_proxy() method will normally not
use the $ua->proxy() and $ua->no_proxy() methods.

=end original

LWP::Simple インターフェースはあなたに代わって自動的に
env_proxy() を呼びます。
$ua->env_proxy メソッドを使うアプリケーションは、通常、$ua->proxy() と
$ua->no_proxy メソッドは使いません。

=begin original

Some proxies also require that you send it a username/password in
order to let requests through.  You should be able to add the
required header, with something like this:

=end original

プロキシによっては、リクエストを通すためにユーザ名／パスワードを
送信することも要求することがあります。
以下のようにして、要求されるヘッダを追加することができます:

 use LWP::UserAgent;

 $ua = LWP::UserAgent->new;
 $ua->proxy(['http', 'ftp'] => 'http://username:password@proxy.myorg.com');

 $req = HTTP::Request->new('GET',"http://www.perl.com");

 $res = $ua->request($req);
 print $res->decoded_content if $res->is_success;

=begin original

Replace C<proxy.myorg.com>, C<username> and
C<password> with something suitable for your site.

=end original

C<proxy.myorg.com>, C<username>, C<password> をあなたのサイトに合わせて
置き換えてください。

=head1 ACCESS TO PROTECTED DOCUMENTS

(保護されている文書へのアクセス)

=begin original

Documents protected by basic authorization can easily be accessed
like this:

=end original

基本認証によって保護されている文書は以下のようにして簡単に
アクセスできます:

  use LWP::UserAgent;
  $ua = LWP::UserAgent->new;
  $req = HTTP::Request->new(GET => 'http://www.linpro.no/secret/');
  $req->authorization_basic('aas', 'mypassword');
  print $ua->request($req)->as_string;

=begin original

The other alternative is to provide a subclass of I<LWP::UserAgent> that
overrides the get_basic_credentials() method. Study the I<lwp-request>
program for an example of this.

=end original

他の方法としては、get_basic_credentials() メソッドをオーバーライドする
I<LWP::UserAgent> のサブクラスを提供することがあります。
この例として I<lwp-request> プログラムを調べてみてください。

=head1 COOKIES

(クッキー)

=begin original

Some sites like to play games with cookies.  By default LWP ignores
cookies provided by the servers it visits.  LWP will collect cookies
and respond to cookie requests if you set up a cookie jar.

=end original

クッキーをもてあそぶことを好むサイトもあります。
デフォルトでは LWP は、それが訪れたサーバから提供されるクッキーを無視します。
クッキー容器を設定しておくと、LWP はクッキーを収集して、クッキーリクエストに
応答します。

  use LWP::UserAgent;
  use HTTP::Cookies;

  $ua = LWP::UserAgent->new;
  $ua->cookie_jar(HTTP::Cookies->new(file => "lwpcookies.txt",
				     autosave => 1));

  # and then send requests just as you used to do
  $res = $ua->request(HTTP::Request->new(GET => "http://no.yahoo.com/"));
  print $res->status_line, "\n";

=begin original

As you visit sites that send you cookies to keep, then the file
F<lwpcookies.txt"> will grow.

=end original

保存するようにクッキーを送信するサイトに訪れるにつれて、ファイル
F<lwpcookies.txt> が大きくなります。

=head1 HTTPS

=begin original

URLs with https scheme are accessed in exactly the same way as with
http scheme, provided that an SSL interface module for LWP has been
properly installed (see the F<README.SSL> file found in the
libwww-perl distribution for more details).  If no SSL interface is
installed for LWP to use, then you will get "501 Protocol scheme
'https' is not supported" errors when accessing such URLs.

=end original

https 機能を持つ URL は http 機能を持つものと全く同じようにアクセスされます。
それは適切にインストールされている LWP のための SSL インタフェース
モジュールにより提供されます (詳細は libwww-perl ディストリビューションに
含まれている F<README.SSL> ファイルをご覧下さい)。
LWP のための SSL インタフェースが利用できなければ、そのような URL に
アクセスすると、"501 Protocol scheme 'https' is not supported" エラーに
なります。

=begin original

Here's an example of fetching and printing a WWW page using SSL:

=end original

以下に SSL を使っている WWW ページの取り出しと出力の例を示します:

  use LWP::UserAgent;

  my $ua = LWP::UserAgent->new;
  my $req = HTTP::Request->new(GET => 'https://www.helsinki.fi/');
  my $res = $ua->request($req);
  if ($res->is_success) {
      print $res->as_string;
  }
  else {
      print "Failed: ", $res->status_line, "\n";
  }

=head1 MIRRORING

(ミラーリング)

=begin original

If you want to mirror documents from a WWW server, then try to run
code similar to this at regular intervals:

=end original

WWW サーバから文書をミラーしたければ、定期的に以下のようなコードを
実行してみてください:

  use LWP::Simple;

  %mirrors = (
     'http://www.sn.no/'                       => 'sn.html',
     'http://www.perl.com/'                    => 'perl.html',
     'http://search.cpan.org/distlibwww-perl/' => 'lwp.html',
     'gopher://gopher.sn.no/'                  => 'gopher.html',
  );

  while (($url, $localfile) = each(%mirrors)) {
     mirror($url, $localfile);
  }

=begin original

Or, as a perl one-liner:

=end original

もしくは perl ワンライナーとして：

  perl -MLWP::Simple -e 'mirror("http://www.perl.com/", "perl.html")';

=begin original

The document will not be transferred unless it has been updated.

=end original

更新されていなければ、文書は転送されません。

=head1 LARGE DOCUMENTS

(巨大な文書)

=begin original

If the document you want to fetch is too large to be kept in memory,
then you have two alternatives.  You can instruct the library to write
the document content to a file (second $ua->request() argument is a file
name):

=end original

取り出したい文書がメモリに入りきらないほど大きければ、
二つの代替案があります。
文書内容をファイルに書きこむようライブラリに
指示できます ($ua->request() の 2 番目の引数はファイル名になります):

  use LWP::UserAgent;
  $ua = LWP::UserAgent->new;

  my $req = HTTP::Request->new(GET =>
     'http://www.cpan.org/authors/Gisle_Aas/libwww-perl-6.02.tar.gz');
  $res = $ua->request($req, "libwww-perl.tar.gz");
  if ($res->is_success) {
     print "ok\n";
  }
  else {
     print $res->status_line, "\n";
  }


=begin original

Or you can process the document as it arrives (second $ua->request()
argument is a code reference):

=end original

あるいは、文書が届いたときに処理することができます
($ua->request() の 2 番目の引数はコードリファレンスになります):

  use LWP::UserAgent;
  $ua = LWP::UserAgent->new;
  $URL = 'ftp://ftp.unit.no/pub/rfc/rfc-index.txt';

  my $expected_length;
  my $bytes_received = 0;
  my $res =
     $ua->request(HTTP::Request->new(GET => $URL),
               sub {
                   my($chunk, $res) = @_;
                   $bytes_received += length($chunk);
	           unless (defined $expected_length) {
	              $expected_length = $res->content_length || 0;
                   }
		   if ($expected_length) {
		        printf STDERR "%d%% - ",
	                          100 * $bytes_received / $expected_length;
                   }
	           print STDERR "$bytes_received bytes received\n";

                   # XXX Should really do something with the chunk itself
	           # print $chunk;
               });
   print $res->status_line, "\n";

=head1 COPYRIGHT

Copyright 1996-2001, Gisle Aas

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

=begin meta

Translate: Hippo2000 <GCD00051@nifty.ne.jp> (5.48)
Update: SHIRAKATA Kentaro <argrath@ub32.org> (5.813-)
Status: completed

=end meta