modules/libwww-perl-5.813/lwpcook.pod


=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://www.linpro.no/lwp/';

=begin original

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

=end original

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

  perl -MLWP::Simple -e 'getprint "http://www.linpro.no/lwp/"'

=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.perl.com/perl/CPAN/CPAN.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://www.linpro.no/lwp');
  $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() 関数は本当にドキュメントのメタ情報のリストを返します。
返されるリストの最初の3つの値はドキュメントのタイプ、ドキュメントの
大きさ、ドキュメントの年齢 (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://www.perl.com/cgi-bin/BugGlimpse');
  $req->content_type('application/x-www-form-urlencoded');
  $req->content('match=www&errors=0');

  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://www.perl.com/cgi-bin/BugGlimpse',
                [ search => 'www', errors => 0 ];

  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://www.yahoo.no"));
  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://www.sn.no/libwww-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 transfered 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.linpro.no/lwp/libwww-perl-5.46.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

Translated: Hippo2000 <GCD00051@nifty.ne.jp> (5.48)
Updated: Kentaro SHIRAKATA <argrath@ub32.org> (5.813)

=end meta
