=encoding utf8 =head1 NAME WWW::Mechanize - Perlオブジェクト中のハンディWebブラウザ =head1 VERSION Version 0.70 $Header: /cvsroot/www-mechanize/www-mechanize/lib/WWW/Mechanize.pm,v 1.92 2003/12/01 05:46:55 petdance Exp $ =head1 SYNOPSIS C、あるいは縮めてMechはWebサイトとのやりとりの自動化を 助けます。これはリンク先やフォームデータの送信を含む、複数のページの取得を サポートします。取得したページはそれぞれ解析され、そのリンクやフォームが 抽出されます。リンクやフォームを選択し、フォームを埋め、次のページを取得 することが可能です。Mechは訪れたURLの履歴を保持しますので、これを問い あわせたり再訪することも可能です。 use WWW::Mechanize; my $a = WWW::Mechanize->new(); $a->get( $url ); $a->follow_link( n => 3 ); $a->follow_link( text_regex => qr/download this/i ); $a->follow_link( url => 'http://host.com/index.html' ); $a->submit_form( form_number => 3, fields => { username => 'yourname', password => 'dummy', } ); $a->submit_form( form_name => 'search', fields => { query => 'pot of gold', }, button => 'Search Now' ); MechはWebアプリケーションのテストにも良くあいます。L モジュールなど、Test::*の内の一つを使えば、取得したコンテンツを チェックし、testコールへの入力に使うことができます。 use Test::More; like( $a->content(), qr/$expected/, "Got expected content" ); ページ取得を行う度にそのURLはスタックに保持され、これを前後に移動 することができます。 $a->back(); ページ取得の過程をよりうまくコントロールしようと思ったら、以下の メソッドを使うことができます。CとCは、 つまるところこれらの高レベルのラッパーです。 $a->follow( $link ); $a->find_link( n => $number ); $a->form_number( $number ); $a->form_name( $name ); $a->field( $name, $value ); $a->set_fields( %field_values ); $a->click( $button ); LはまさしくLのサブクラスであり、 Lのどのメソッドも利用可能です。 $a->add_header($name => $value); =head1 重要なリンク =over 4 =item * L CPANのMechanizeのドキュメントページ。 =item * L Mechanizeにはバグと機能向上のRTキューがあります。もしあなたの抱えて いるバグが未報告のものであれば"Report bug"をクリックしてください。 =back =head1 この他のドキュメント =head2 I, by Kevin Hemenway and Tara Calishain O'Reilly(L)刊の Iはscreen-scrapingとspideringについてもっと知りたい 人にとってすばらしい本です。 この本にはAndy Lesterによる3つのMech-specificハックがあります: =over 4 =item 21 WWW::Mechanize 101 =item 36 Downloading Images from Webshots =item 44 Archiving Yahoo! Groups Messages with WWW::Yahoo::Groups =item =back Chris Elthekの2つのMechハックがあります: =over 4 =item 22 Scraping with WWW::Mechanize =item 73 Scraping TV Listings =back =head2 Web上のリソース =over 4 =item * WWW::Mechanize Development mailing list Sourceforgeによって配信されており、Mechへの貢献者たちが様々なことを 話し合う場になっています。 L =item * LWP mailing list LWPメーリングリストはLに あり、WWW::Mechanize開発リストよりも一般的でユーザー主導になっています。 LWPはMechの基盤ですから、これはMechユーザーにとって良いリストです。 =item * L 手当たり次第にユーザから投稿されたサンプル群で、Mechanizeディストリ ビューションに含まれています。 =item * L テレビ番組表をWWW::Mechanizeを使ってスクラップすることについての Chris Ballの記事です。 =item * L Yahoo Newsの画像のスクラップについてのRandal Schwartzの記事です。 これは既に古くなっています: 彼はマッチするリンクを探すのにリンクリストを 歩きまわりましたが、これの発行時にCメソッドがあれば その必要はなかったでしょう。 =item * L WWW::Mechanize on the Perl Advent Calendar, by Mark Fowler. =back =head1 コンストラクタと開始 =head2 C<< new() >> WWW::Mechanizeの新規オブジェクトを生成し、返します。 以下ではこのオブジェクトを'agent'と呼びます。 my $a = WWW::Mechanize->new() WWW::Mechanizeのコンストラクタは、LWP::UserAgentのコンストラクタへの パラメータのうち2つを上書きします。 agent => "WWW-Mechanize/#.##" cookie_jar => {} # an empty, memory-only HTTP::Cookies object コンストラクタにパラメータを渡すことで、この上書き値を変更することが できます。以下のようになります: my $a = WWW::Mechanize->new( agent=>"wonderbot 1.01" ); cookie jarでのオーバーヘッドを避けたい時や、botにcookieを受け入れ させたくない時は、明示的にこれを禁止します。こんな感じです: my $a = WWW::Mechanize->new( cookie_jar => undef ); 以下はWWW::Mechanizeが認識できるパラメータです。 これらはLが認識するパラメータには含まれていません。 =over 4 =item * C<< autocheck => [0|1] >> ここのリクエストについてそれが成功していそうか否かをチェックします。 これはあなたが自分でマニュアルでチェックすることによるトラブルを防ぎ ます。エラーが見つかれば、それはワーニングではなくエラーになります。 デフォルトはオフです。 =item * C<< onwarn => \&func() >> C<< L::carp >>のようなC互換の、ワーニングを表示する必要が あるときに呼び出される関数へのリファレンスです。 ここにCが設定されると、ワーニングはまったく表示されなくなります。 とはいえ、その振る舞いを制御するのにCを使うよりは良いでしょう。 この値が渡されなければ、MechはLがインストールされていれば Cを、そうでなければCを使用します。 =item * C<< onerror => \&func() >> C<< L::croak >>のようなC互換の、知恵意的なエラーが発生した 際に呼び出される関数へのリファレンスです。 ここにCが設定されると、エラーはまったく表示されなくなります。 この値が渡されなければ、MechはLがインストールされていれば Cを、そうでなければCを使用します。 =item * C<< quiet => [0|1] >> ワーニングを出しません。C<< quiet => 1 >>に設定するのと、 C<< $agent->quiet(1) >>を呼び出すのは同じです。デフォルトではオフです。 =back =head2 C<< $a->agent_alias( $alias ) >> 実際にユーザーが渡した文字列からバージョンなどを拡張したものをuser agentに設定します。I<$alias>には以下のうち一つを使用できます。 =over 4 =item * Windows IE 6 =item * Windows Mozilla =item * Mac Safari =item * Mac Mozilla =item * Linux Mozilla =item * Linux Konqueror =back すると、最も関連深いものの一つに置き換えられます。例えば、 $a->agent_alias( 'Windows IE 6' ); ではUser-Agentは以下に設定されます。 Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1) 適切な別名の一覧はCから返されます。 =head2 C Mechが知っている全てのエージェントの別名のリストを返します。 =head1 ページ取得メソッド =head2 C<< $a->get($url) >> URL/URIを与えられると、それを取得します。L オブジェクトが帰り値です。I<$url>は適切に整形されたURL文字列か、 Lオブジェクトです。 この結果はagentオブジェクトに内部的に保持されますが、それを知っている 必要はありません。以下にリストされているアクセッサを使うだけです。 内部の詮索はしないように祈りますし、サブジェクトは将来変更されます。 CはLのメソッドをよりよい振る舞いをするように オーバーライドしたバージョンです。これは $mech->get( $url, ":content_file"=>$tempfile ); のようなことを可能にしますし、このパラメータが適当にフィルタされて 取得されることとみなして構いません。 =head2 C<< $a->reload() >> ブラウザのリロードボタンのように振舞います: 現在のリクエストを 再実行します。 リロードによるLオブジェクトか、まだリクエストが実行 されていない時は現在のリクエストがない時にはCを返します。 =head2 C<< $a->back() >> ブラウザの"back"ボタンを叩くのと等価です。前のページに戻ります。 過去の最初のページに戻りたくはありませんか？（実際、それが可能だと したらそうするでしょう？） =head1 リンク追跡メソッド =head2 C<< $a->follow_link(...) >> そのページの指定されたリンクをたどります。C>で使うのと 同じパラメータを使い、それにマッチするものを指定します。 以下がその例です: =over 4 =item * "download"と名づけられた3番目のリンク $a->follow_link( text => "download", n => 3 ); =item * 大文字小文字を区別せず、"download"をURL中に含む最初のリンク: $a->follow_link( url_regex => qr/download/i ); または $a->follow_link( url_regex => qr/(?i:download)/ ); =item * ページ内の3番目のリンク $a->follow_link( n => 3 ); =back リンクが見つかれば、GETメソッドの実行結果（HTTP::Response オブジェクト）が返されます。ページ内にリンクがないか、または指定された リンクが見つからなかった時は、undefを返します。 このメソッドは、将来の開発では使用されないC<< $a->follow() >>の置き 換えにあたります。 =head1 フォームフィールド入力メソッド =head2 C<< $a->form_number($number) >> ページ中のI番目のフォームを副手順でC>や C>で呼び出す際のターゲットとして選択します。返り値も選択 されたフォームです。選択されたものが存在しない場合には、ワーニングを 出し、undefを返します。フォームは1番からインデックスが付けられるので 最初のフォームは0ではなく、1です。 =head2 C<< $a->form_name($name) >> フォームを名前で選択します。ページ上にその名前のフォームが複数ある 時は、そのうち最初のものが選択され、ワーニングが生成されます。 通常はフォームそれ自体を、見つからなかった時にはundefを返します。 この機能はlibwww-perl 5.69以降を必要としますのでご注意ください。 =head2 C<< $a->field($name, $value, $number) >> フィールド名を受け取り、指定された値をそこにセットします。これは 現在のフォーム（C>で設定されたものか、デフォルトである ページ内の最初のフォーム）に適用されます。 オプションのI<$number>パラメータは、2つ以上の同じ名前のフィールドが ある時に、それらを区別するのに使われます。フィールドは1から番号が ふられます。 =head2 C<< $a->set_fields( $name => $value ... ) >> このメソッドはフォームの複数のフィールドを設定します。これはフィールド 名と値のペアのリストを引数に取ります。もし同じ名前のフィールドが複数 あれば、そのうち最初に見つかったものに値がセットされます。この複製 されたフィールドのいずれかを選択したいときは、値として、値と番号の 2つの要素をもつ無名配列を使用します。 # set the second foo field $a->set_fields( $name => [ 'foo', 2 ] ) ; フィールドは1から番号がふられます。 これは現在のフォーム（C>で設定されたものか、デフォルトである ページ内の最初のフォーム）に適用されます。 =head2 C<< $a->tick( $name, $value [, $set] ) >> 現在のフォーム中の、その名前と値を持つ最初のチェックボックスに '印を 付け(Ticks)' ます。その値を持つ名前月のチェックボックスがない時は dieします。オプションの三番目の引数でFalseの値を渡すと、チェック ボックスは印がはずされます。 =head2 C<< $a->untick($name, $value) >> チェックボックスの印をはずします。Cの短い 書き方です。 =head1 フォーム送信メソッド =head2 C<< $a->click( $button [, $x, $y] ) >> ボタンをクリックする効果を持ちます。最初の引数は、クリックするボタンの 名前です。2番目と3番目の（オプションの）引数ではクリックする(x,y) 座標を指定できます。 フォーム上にボタンが一つしかなければ、引数なしでC<< $a->click() >>と するだけで、そのボタンをクリックしたことになります。 Lオブジェクトを返します。 =head2 C<< $a->submit() >> ボタンをクリックしないまま、そのページをsubmitします。実際には、どの ボタンもクリックされなかったことになります。 これはC<< $a->click("submit") >>のシノニムとして使用されてきましたが、 今後、いずれかのバージョンでなくなるでしょう。 =head2 C<< $a->submit_form( ... ) >> このメソッドは、直前に取得したページのフォームを選択し、フィールドを 埋め、それをsubmitするためのものです。これはform_number/form_name、 set_fields、clickメソッドを一つの高レベルの呼び出しに結合したものです。 これの引数はkey/valueの組み合わせのリストで、そのいずれもオプション です。 =over 4 =item * form_number => n I番目のフォームを選択します（C>を呼びます）。この パラメータが指定されなかった場合、現在選択されているフォームが使用 されます。 =item * form_name => name Iと名づけられたフォームを使用します（C>を呼び ます）。 =item * fields => fields Iハッシュリファレンスの値でフィールド値をセットします （C>を呼びます）。 =item * button => button I