argra****@users*****
argra****@users*****
2010年 7月 3日 (土) 03:24:23 JST
Index: docs/modules/libwww-perl-5.813/lwpcook.pod diff -u /dev/null docs/modules/libwww-perl-5.813/lwpcook.pod:1.1 --- /dev/null Sat Jul 3 03:24:23 2010 +++ docs/modules/libwww-perl-5.813/lwpcook.pod Sat Jul 3 03:24:22 2010 @@ -0,0 +1,553 @@ + +=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:passw****@proxy*****'); + + $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 will collect cookies +and respond to cookie requests if you set up a cookie jar. +(TBT) + + 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 <GCD00****@nifty*****> (5.48) +Updated: Kentaro SHIRAKATA <argra****@ub32*****> (5.813) + +=end meta +