=encoding euc-jp =head1 NAME WWW::Mechanize - Perlオブジェクト中のハンディWebブラウザ =head1 VERSION Version 1.02 $Header: /cvsroot/www-mechanize/www-mechanize/lib/WWW/Mechanize.pm,v 1.129 2004/04/10 05:30:10 petdance Exp $ =head1 SYNOPSIS C、あるいは縮めてMechはWebサイトとのやりとりの自動化を 助けます。これはリンク先やフォームデータの送信を含む、複数のページの取得を サポートします。取得したページはそれぞれ解析され、そのリンクやフォームが 抽出されます。リンクやフォームを選択し、フォームを埋め、次のページを取得 することが可能です。Mechは訪れたURLの履歴を保持しますので、これを問い あわせたり再訪することも可能です。 use WWW::Mechanize; my $mech = WWW::Mechanize->new(); $mech->get( $url ); $mech->follow_link( n => 3 ); $mech->follow_link( text_regex => qr/download this/i ); $mech->follow_link( url => 'http://host.com/index.html' ); $mech->submit_form( form_number => 3, fields => { username => 'yourname', password => 'dummy', } ); $mech->submit_form( form_name => 'search', fields => { query => 'pot of gold', }, button => 'Search Now' ); MechはWebアプリケーションのテストにも良くあいます。L モジュールなど、Test::*の内の一つを使えば、取得したコンテンツを チェックし、testコールへの入力に使うことができます。 use Test::More; like( $mech->content(), qr/$expected/, "Got expected content" ); ページ取得を行う度にそのURLはスタックに保持され、これを前後に移動 することができます。 $mech->back(); ページ取得の過程をよりうまくコントロールしようと思ったら、以下の メソッドを使うことができます。CとCは、 つまるところこれらの高レベルのラッパーです。 $mech->follow( $link ); $mech->find_link( n => $number ); $mech->form_number( $number ); $mech->form_name( $name ); $mech->field( $name, $value ); $mech->set_fields( %field_values ); $mech->set_visible( @criteria ); $mech->click( $button ); LはまさしくLのサブクラスであり、 Lのどのメソッドも利用可能です。 $mech->add_header($name => $value); =head1 重要なリンク =over 4 =item * L CPANのMechanizeのドキュメントページ。 =item * L Mechanizeにはバグと機能向上のRTキューがあります。もしあなたの抱えて いるバグが未報告のものであれば"Report bug"をクリックしてください。 =back =head1 コンストラクタと開始 =head2 new() WWW::Mechanizeの新規オブジェクトを生成し、返します。 以下ではこのオブジェクトを'agent'と呼びます。 my $mech = WWW::Mechanize->new() WWW::Mechanizeのコンストラクタは、LWP::UserAgentのコンストラクタへの パラメータのうち2つを上書きします。 agent => "WWW-Mechanize/#.##" cookie_jar => {} # an empty, memory-only HTTP::Cookies object コンストラクタにパラメータを渡すことで、この上書き値を変更することが できます。以下のようになります: my $mech = WWW::Mechanize->new( agent=>"wonderbot 1.01" ); cookie jarでのオーバーヘッドを避けたい時や、botにcookieを受け入れ させたくない時は、明示的にこれを禁止します。こんな感じです: my $mech = 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 $mech->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 すると、最も関連深いものの一つに置き換えられます。例えば、 $mech->agent_alias( 'Windows IE 6' ); ではUser-Agentは以下に設定されます。 Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1) 適切な別名の一覧はCから返されます。 =head2 C Mechが知っている全てのエージェントの別名のリストを返します。 =head1 ページ取得メソッド =head2 $mech->get($url) URL/URIを与えられると、それを取得します。L オブジェクトが帰り値です。I<$url>は適切に整形されたURL文字列か、 Lオブジェクトです。 この結果はagentオブジェクトに内部的に保持されますが、それを知っている 必要はありません。以下にリストされているアクセッサを使うだけです。 内部の詮索はしないように祈りますし、サブジェクトは将来変更されます。 CはLのメソッドをよりよい振る舞いをするように オーバーライドしたバージョンです。これは $mech->get( $url, ":content_file"=>$tempfile ); のようなことを可能にしますし、このパラメータが適当にフィルタされて 取得されることとみなして構いません。 =head2 $mech->reload() ブラウザのリロードボタンのように振舞います: 現在のリクエストを 再実行します。 リロードによるLオブジェクトか、まだリクエストが実行 されていない時は現在のリクエストがない時にはCを返します。 =head2 $mech->back() ブラウザの"back"ボタンを叩くのと等価です。前のページに戻ります。 過去の最初のページに戻りたくはありませんか?(実際、それが可能だと したらそうするでしょう?) =head1 リンク追跡メソッド =head2 $mech->follow_link(...) そのページの指定されたリンクをたどります。C>で使うのと 同じパラメータを使い、それにマッチするものを指定します。 以下がその例です: =over 4 =item * "download"と名づけられた3番目のリンク $mech->follow_link( text => "download", n => 3 ); =item * 大文字小文字を区別せず、"download"をURL中に含む最初のリンク: $mech->follow_link( url_regex => qr/download/i ); または $mech->follow_link( url_regex => qr/(?i:download)/ ); =item * ページ内の3番目のリンク $mech->follow_link( n => 3 ); =back リンクが見つかれば、GETメソッドの実行結果(HTTP::Response オブジェクト)が返されます。ページ内にリンクがないか、または指定された リンクが見つからなかった時は、undefを返します。 このメソッドは、将来の開発では使用されないC<< $mech->follow() >>の置き 換えにあたります。 =head1 フォームフィールド入力メソッド =head2 $mech->form_number($number) ページ中のI番目のフォームを副手順でC>や C>で呼び出す際のターゲットとして選択します。返り値も選択 されたフォームです。選択されたものが存在しない場合には、ワーニングを 出し、undefを返します。フォームは1番からインデックスが付けられるので 最初のフォームは0ではなく、1です。 =head2 $mech->form_name($name) フォームを名前で選択します。ページ上にその名前のフォームが複数ある 時は、そのうち最初のものが選択され、ワーニングが生成されます。 通常はフォームそれ自体を、見つからなかった時にはundefを返します。 この機能はlibwww-perl 5.69以降を必要としますのでご注意ください。 =head2 $mech->field( $name, $value, $number ) =head2 $mech->field( $name, \@values, $number ) フィールド名を受け取り、指定された値をそこにセットします。これは 現在のフォーム(C>で設定されたものか、デフォルトである ページ内の最初のフォーム)に適用されます。 オプションのI<$number>パラメータは、2つ以上の同じ名前のフィールドが ある時に、それらを区別するのに使われます。フィールドは1から番号が ふられます。 =head2 $mech->set_fields( $name => $value ... ) このメソッドはフォームの複数のフィールドを設定します。これはフィールド 名と値のペアのリストを引数に取ります。もし同じ名前のフィールドが複数 あれば、そのうち最初に見つかったものに値がセットされます。この複製 されたフィールドのいずれかを選択したいときは、値として、値と番号の 2つの要素をもつ無名配列を使用します。 # set the second foo field $mech->set_fields( $name => [ 'foo', 2 ] ) ; フィールドは1から番号がふられます。 これは現在のフォーム(C>で設定されたものか、デフォルトである ページ内の最初のフォーム)に適用されます。 =head2 $mech->set_visible( @criteria ) このメソッドはフォームフィールドを、そのフィールド名を知る必要なく セットします。したがって、もしユーザー名とパスワードを要求するログイン 画面があるなら、そのフィールド名を知るためにフォームを取得してソース から調査する(あるいはWWW::Mechanizeといっしょにインストールされる Fを使う)必要はありません; こう命じるだけで $mech->set_visible( $username, $password ) ; これにしたがって、1番目と2番目のフィールドがセットされます。この メソッドは、可視(visible)フィールドのみに働くので、set_Iと 呼ばれます; 不可視(hidden)のフォームインプットは無視されます。 フィールドの順番はHTMLソース中に出てくる順番と同じで、多くの場合は ページ上で見える順番と同じですが、テーブルを使ったクリエイティブな デザインでは異なることがあることは警告しておきます。 C<@criteria>の個々の要素はフィールド値またはフィールド指定値です。 フィールド値はスカラです。フィールド指定値では値をセットしたい フィールドのI<タイプ>を指定でき、二つの要素をもつ配列リファレンスで 表わされます。したがって、最初のラジオボタンを次のように指定できます $mech->set_visible( [ radio => "KCRW" ] ) ; フィールド値とフィールド指定値は混在させることができ、したがって $mech->set_visible( "fred", "secret", [ option => "Checking" ] ) ; は1、2番目のフィールドを"fred"と"secret"に、そしてI<次の>C