Hippo2000 (2000/7/28)
LWPモジュール群のドキュメントなのです。はっきり言ってよくわかっていませんが...(^^:::。
ブラウザだけがWWWクライアントだけではないですよということで。
作者はGisle Aasさんです。メールで許可をいただきました。関連のHTTPモジュール群、URIモジュールもよろしく。
なおLWPモジュールには以下のサブクラスがあります。
| クラス名 | 説 明 |
|---|---|
| LWP::Debug | libwww-perl ライブラリのためのデバッグ・ルーチン |
| LWP::MediaTypes | ファイルまたはURLのためのメディアタイプを答える |
| LWP::MemberMixin | クラスに入ったメンバーアクセス |
| LWP::Protocol | LWPプロトコルの基本クラス |
| LWP::RobotUA | Webロボットのためのクラス |
| LWP::Simple | 手続き型LWPインターフェース |
| LWP::UserAgent | WWW ユーザ・エージェント クラス |
そのほか関連するモジュールもよろしく。
| クラス名 | 説 明 |
|---|---|
| lwpcook | libwww-perl クックブック。libwww-perlの使い方を説明しています。 |
| HTTP | HTTP::*モジュール群 |
| URI | URI::*モジュール群 |
| Crypt::SSLeay | LWP httpsサポートを提供するOpenSSL と SSLeay とのつなぎ |
2001/6/21：山宮隆さんからの指摘を受けて、余分な「；」を削除しました。
LWP - PerlでのWWWアクセスのためのライブラリ
use LWP; print "This is libwww-perl-$LWP::VERSION\n";
Libwww-perl はWorld-Wide Webへの簡単で一貫性のあるプログラミング･インターフェース(API)を提供するPerlモジュールの集まりです。WWWクライアントを書くことが出来るクラスと関数を提供することを目標にしています。そのためlibwww-perl はWWWクライアントライブラリです。ライブラリはもっと汎用的に使われるモジュールも入っています。
このライブラリのほとんどのモジュールはオブジェクト指向です。リクエストを送信し、WWWサーバからレスポンスを受信するユーザ・エージェント(user agent)は、すべてオブジェクトによって表されます。これによりこれらのサービスへの単純で強力なインターフェースを実現ます。このインターフェースはあなたの必要のために拡張したりカスタマイズすることが簡単でしょう。
このライブラリの主な機能を以下に示します：
libwww-perはHTTP式通信(HTTP style communication)をベースにしています。このセクションでは、それがどういう意味かを説明します。
まずはHTTP仕様のドキュメント<URL:http://www.w3.org/pub/WWW/Protocols/>からの引用から始めましょう：
HTTPプロトコルはリクエスト／レスポンス パラダイムをベースにしています。クライアントはサーバと接続を確立し、リクエスト・メソッド、URIそしてプロトコル・バージョン、その後にリクエスト修飾子、クライアント情報、もしあればボディ内容が入ったMIMEライクなメッセージといった形式でサーバにリクエストを送信します。サーバはメッセージのプロトコル・バージョン、成功あるいはエラーコードが入ったステータス行、その後ろにサーバ情報、エンティティ・メタ情報、もしあればボディ内容が入ったMIMEライクなメッセージでレスポンスします。
これがlibwww-perl に意味することは、通信はこれらのステップで行われるということです：まずrequestオブジェクトが生成され、構成設定されます。そしてこのオブジェクトはサーバに渡され、戻りで検査することが出来るresponseオブジェクトを取得します。リクエストは常に前のリクエストとは独立しています。つまりサービスはステートレスです。同じ単純なモデルがアクセスしたいすべての種類のサービスに使われます。
例えば、リモートのファイル・サーバからドキュメントを取り出したいならば、そのドキュメントの名前が入ったリクエストを送信すると、レスポンスにそのドキュメントそのものが入っているでしょう。もし検索エンジンにアクセスすれば、リクエストの内容には問い合わせパラメータが入り、レスポンスには問い合わせ結果が入るでしょう。ある人にメール・メッセージを送信したければ、メッセージが入ったリクエスト・オブジェクトをメール・サーバに送信すると、レスポンス・オブジェクトにはそのメッセージが受信され受取人にフォワードされたことを教えてくれる受取通知が入るでしょう。
それくらい単純なのです！
libwww-perl リクエスト(request)オブジェクトはHTTP::Requestというクラスを持ちます。クラス名の前にHTTP::がついているということは、通信のHTTPモデルを使っているということを暗示しているだけです。それは、このリクエストを渡そうそするサービスの種類を制限しません。例えばftpやgopherサービスにも、そしてローカルなファイル・システムにもHTTP::Requestを送信します。
Requestオブジェクトの主な属性は以下の通りです：
ibwww-perl レスポンス（response）オブジェクトはHTTP::Responseというクラス名を持ちます。このクラスのオブジェクト主な属性は以下の通りです：
すべてのありうるcode値を直接我々のプログラムで扱いたくないので、libwww-perl responseオブジェクトは、これがどんな種類のレスポンスかを問い合わせるために使うことが出来るメソッドを持っています。最もよく使われるレスポンス分類メソッドは以下の通りです：
リクエスト(request)オブジェクトを作成したとします。レスポンス（response)を受信するため実際には何をするでしょうか？
答えはそれをユーザー・エージェント（user agent）オブジェクトに渡します。このオブジェクトは（下位レベルの通信やエラーの取り扱いなど）しなけれならないすべてのことに注意し、レスポンス（response)オブジェクトを返します。ユーザー・エージェントはネットワークでのアプリケーションを表し、リクエスト(request)を受け付け、レスポンス（response)を返すことができるインタフェースを提供します。
ユーザー・エージェントはあなたのアプリケーション・コードとネットワークの間のインターフェース層です。このインタフェースを通して、ネットワーク上のさまざまなサービスにアクセスすることができます。
ユーザ・エージェントのためのlibwww-perl クラス名はLWP::UserAgentです。通信したいすべてのlibwww-perlアプリケーションは、このクラスのオブジェクトを少なくとも１つ作成しなければなりません。このオブジェクトにより提供される主なメソッドはrequest()です。このメソッドはHTTP::Requestオブジェクトを引数として取り、（最終的に）HTTP::Responseオブジェクトを返します。
ユーザ・エージェントは他に、ネットワークやアプリケーションとどのように相互に影響しあうかを構成設定させる多くの属性を持っています。
多くのアプリケーションはネットワークとどのようにやりとりするかを、さらに制御することを望みます。そしてこれはLWP::UserAgentをサブクラス化することによって実現します。ライブラリにはサブクラスとして、ロボット・アプリケーションのためにLWP::RobotUAが入っています。
この例は、ユーザ・エージェント(user agent)、リクエスト（request)、そしてレスポンス（response)が、実際のperlコードではどのように表されるかを示します：
# ユーザ・エージェント オブジェクトを作成します
use LWP::UserAgent;
$ua = new LWP::UserAgent;
$ua->agent("AgentName/0.1 " . $ua->agent);
# リクエストを作成します
my $req = new HTTP::Request 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);
# レスポンスの結果をチェックします
if ($res->is_success) {
print $res->content;
} else {
print "Bad luck this time\n";
}
アプリケーションが起動されたとき、$uaが一度作られます。新しいリクエスト・オブジェクトは通常リクエストを送信するたびに作成されます。
このセクションでは各種のプロトコル機構とそれぞれにヘッダが使われるかもしれないHTTP式・メソッドについて説明します。
すべてのリクエストに、リクエストがネットワーク層に渡される前に、"User-Agent"ヘッダが追加され、$ua->agent属性から初期化されます。同じ方法で、"From"ヘッダは$ua->from属性から初期化されます。
すべてのレスポンスに、ライブラリは"Client-Date"と呼ばれるヘッダを追加します。このヘッダはレスポンスがアプリケーションにより受信された時刻を保持します。ヘッダの形式と意味はサーバにより作成される"Date"ヘッダと同じです。他にも"Client-XXX"というヘッダに出会うかもしれません。それらはライブラリにより内部で生成され、サーバから受信されていません。
HTTPリクエストは単純にHTTPサーバに渡され、それが何をするかを判断します。ほとんどのサーバは通常の"GET"、"HEAD"、"POST"、"PUT"の他にメソッドを実装しませんが、CGIスクリプトが好きなメソッドを実装するかもしれません。
サーバが利用できなければ、ライブラリは内部でエラーレスポンスを生成します。
このライブラリは自動的にネットワークを越えて送信する前に、HTTPリクエストに"Host"と"Content-Length"ヘッダを追加します。
GETリクエストでは、条件をつけたリクエストを行うために"If-Modified-Since"ヘッダを追加したいかもしれません。
POSTリクエストでは、"Content-Type"ヘッダを追加しなければなりません。HTML<FORM>扱いをエミュレートしようとするとき、"Content-Type"ヘッダの値は"application/x-www-form-urlencoded"にしなければなりません。この例についてはlwpcookをご覧下さい。
libwww-perl HTTP 実装は現在HTTP/1.0プロトコルをサポートしています。HTTP/0.9サーバも正しく扱われます。
このライブラリはHTTPを通してプロキシー・サーバにアクセスすることも可能にしています。つまりHTTPプロトコル・モジュールを通してすべてのタイプのリクエストをフォワードするために設定できるということです。これのドキュメントについてはLWP::UserAgent をご覧下さい。
HTTPSリクエストは、ネットスケープにより開発されたSSLプロトコルを使った暗号化されたネットワーク接続によるHTTPリクエストです。HTTPリクエストについての上記のすべてがHTTPSリクエストにも当てはまります。さらにライブラリはレスポンスにヘッダ"Client-SSL-Cipher"、"Client-SSL-Cert-Subject" そして "Client-SSL-Cert-Issuer"を追加します。これらのヘッダは使われた暗号化方法とサーバ所有者の名前を表します。
リクエストにはサーバ認証の内容による条件付のリクエストを行うためにヘッダ"If-SSL-Cert-Subject"を入れることが出来ます。認証サブジェクト(cerificate subject)が合わなければ、サーバにはリクエストが送られず、内部的に作成されたエラーレスポンスが返されます。"If-SSL-Cert-Subject"ヘッダの値はPerl正規表現として解釈されます。
このライブラリは現在GET、HEADそしてPUTリクエストをサポートします。GETはFTPサーバからファイルやディレクトリ一覧を取り出します。PUTはファイルをftpサーバに格納します。
加えてユーザ名、パスワードを欲しがるサーバのためにftpアカウントを指定することが出来ます。これはリクエストのなかの"Account"ヘッダが入ることによって指定されます。
ユーザ名／パスワードは基本認証を使いながら指定したり、URLでエンコードされたりすることが出来ます。ログインが失敗すると"WWW-Authenticate: Basic"でUNAUTHORIZEDレスポンスを返し、HTTPのための基本認証のように扱うことが出来ます。
このライブラリはURLで"typ=a"パラメータを指定することにより、ftp ASCII転送モードをサポートします。
ディレクトリ一覧はデフォルトでは内容メディア型が"text/ftp-dir-listing"としてレポートさながら、返され、（ftpサーバから返されたまま）処理されません。File::Listringモジュールはこれらのディレクトリ一覧の解析のためのメソッドを提供します。
ftpモジュールはディレクトリ一覧をHTMLに変換することも出来ます。そしてこれは標準のHTTPコンテント・ネゴシエーション機構を通して要求されることも出来ます。（こうしたければリクエストに"Accept: text/html"ヘッダを追加してください）
通常のファイル取り出しでは、"Content-Type"はファイル名の拡張しに基づいて答えられます。LWP::MediaTypes.をご覧下さい。
"If-Modified-Since"リクエスト・ヘッダがMDTMコマンドを実装しているサーバのために働きます。しかしながらこれはおそらくディレクトリ一覧には働かないでしょう。
例：
$req = HTTP::Request->new(GET => 'ftp://me:passwd@ftp.some.where.com/'); $req->header(Accept => "text/html, */*;q=0.1");
USENET NewsシステムへのアクセスはNNTPプロトコルを通して実装されます。newsサーバの名前はNNTP_SERVER環境変数から取得され、デフォルトは"news"です。news:URLでNNTPサーバのホスト名を指定することは出来ません。
このライブラリはNNTPプロトコルを通してnews記事を取り出すためのGETとHEADをサポートします。（驚くべきことに！）POSTメソッドを使ってnewsgroupに記事をポストすることもできます。
newsgroupへのGETはまだ実装されていません。
例：
$req = HTTP::Request->new(GET => 'news:abc1234@a.sn.no');
$req = HTTP::Request->new(POST => 'news:comp.lang.perl.test');
$req->header(Subject => 'This is a test',
From => 'me@some.where.org');
$req->content(<<EOT);
This is the content of the message that we are sending to
the world.
EOT
このライブラリはgopherリクエストのためのGETとHEADメソッドをサポートします。すべてのリクエスト・ヘッダの値は無視されます。HEADはごまかして、サーバと話することすらなくレスポンスを返します。
Gopher メニューは常にHTMLに変換されます。
レスポンスの"Content-Type"はリクエストURLパスそれ自身にエンコードされたドキュメント・タイプから生成されます。
例：
$req = HTTP::Request->new(GET => 'gopher://gopher.sn.no/');
このライブラリはfileリクエストのためにGETとhEADヘソッドをサポートしています。"If-Modified-Since" ヘッダがサポートされています。他のすべてのヘッダは無視されます。file URLのhostコンポーネントは空であるか"localhost"に設定されていなければなりません。他のhostはすべてエラーとして扱われます。
ディレクトリは常にHTMLドキュメントに変換されます。通常のファイルでは、レスポンスの中の"Content-Type"と"Content-Encoding"はファイル拡張子を元にして答えられます。
例：
$req = HTTP::Request->new(GET => 'file:/etc/passwd');
このライブラリを使って、メールメッセージを送信（つまり"POST")することができます。リクエストに指定されたすべてのヘッダはメール・システムに渡されます。"To"ヘッダはURLでのメール・アドレスで初期化されます。
例：
$req = HTTP::Request->new(POST => 'mailto:libwww@perl.ord');
$req->header(Subject => "subscribe");
$req->content("Please subscribe me to the libwww-perl mailing list!\n");
以下の表はこのライブラリによって提供されるクラスの簡単な概略を示します。インデントはクラスの継承を示します。
LWP::MemberMixin -- Perl5クラスのメンバー変数へのアクセス
LWP::UserAgent -- WWW ユーザ・エージェントクラス
LWP::RobotUA -- ロボット(robot)アプリケーションを開発するとき
LWP::Protocol -- 様々なプロトコル機能へのインターフェース
LWP::Protocol::http -- http:// アクセス
LWP::Protocol::file -- file:// アクセス
LWP::Protocol::ftp -- ftp:// アクセス
...
LWP::Authen::Basic -- 401と407レスポンスの取り扱い LWP::Authen::Digest
HTTP::Headers -- MIME/RFC822スタイル・ヘッダ ( HTTP::Messageによって使われる) HTTP::Message -- HTTP式・メッセージ HTTP::Request -- HTTPリクエスト HTTP::Response -- HTTPレスポンス HTTP::Daemon -- HTTPサーバクラス
WWW::RobotRules -- robots.txtファイルの解析 WWW::RobotRules::AnyDBM_File -- 永続化RobotRules
以下のモジュールは様々な関数と定義を提供します。
LWP -- このファイル。ライブラリ･バージョン番号とドキュメント LWP::MediaTypes -- MIME タイプ設定(text/html など) LWP::Debug -- デバッグ・ログ出力モジュール LWP::Simple -- 一般的な機能のための簡略化された手続き型インターフェース HTTP::Status -- HTTP ステータス・コード (200 OK など) HTTP::Date -- HTTP日付フォーマットのための日付解析モジュール HTTP::Negotiate -- HTTPコンテント・ネゴシエーション計算 File::Listing -- ディレクトリ一覧の解析
すべてのモジュールにはそれが提供しているインターフェースについての詳細な情報がはいっています。lwpcook マニュアルページはライブラリの典型的な利用法の例が入ったlibwww-perl cookbook です。スクリプトlwp-request、lwp-rgetそしてlwp-mirrorがどのように実行されているかを見るのもよいでしょう。
ライブラリは同時に複数のリクエストをまだ扱えません。また何が残っているかはTODOファイルをチェックしてください。
（原文のまま）
This package owes a lot in motivation, design, and code, to the libwww-perl library for Perl 4, maintained by Roy Fielding <fielding@ics.uci.edu>.
That package used work from Alberto Accomazzi, James Casey, Brooks Cutter, Martijn Koster, Oscar Nierstrasz, Mel Melchner, Gertjan van Oosten, Jared Rhine, Jack Shirazi, Gene Spafford, Marc VanHeyningen, Steven E. Brenner, Marion Hakanson, Waldemar Kebsch, Tony Sanders, and Larry Wall; see the libwww-perl-0.40 library for details.
The primary architect for this Perl 5 library is Martijn Koster and Gisle Aas, with lots of help from Graham Barr, Tim Bunce, Andreas Koenig, Jared Rhine, and Jack Shirazi.
（原文のまま）
Copyright 1995-2000, Gisle Aas Copyright 1995, Martijn Koster
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
このライブラリの最新バージョンは以下の場所の他にCPANからも利用できます：
http://www.linpro.no/lwp/
このプログラムについて議論する一番よい場所は<libwww@perl.org> メーリング・リストです。
ご意見、ご質問はこちらの掲示板で受け付けています。
またメールは河馬屋(Nifty)にお願いします。