Page Top

NAME

WWW::Mechanize - Perlオブジェクト中のハンディWebブラウザ

Page Top

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 $

Page Top

SYNOPSIS

WWW::Mechanize、あるいは縮めて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アプリケーションのテストにも良くあいます。Test::HTML::Lint モジュールなど、Test::*の内の一つを使えば、取得したコンテンツを チェックし、testコールへの入力に使うことができます。

    use Test::More;
    like( $a->content(), qr/$expected/, "Got expected content" );

ページ取得を行う度にそのURLはスタックに保持され、これを前後に移動 することができます。

    $a->back();

ページ取得の過程をよりうまくコントロールしようと思ったら、以下の メソッドを使うことができます。follow_linkとsubmit_formは、 つまるところこれらの高レベルのラッパーです。

    $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 );

LWP::UserAgentのサブクラスであり、 LWP::UserAgentのどのメソッドも利用可能です。

    $a->add_header($name => $value);

Page Top

重要なリンク

Page Top

この他のドキュメント

Spidering Hacks, by Kevin Hemenway and Tara Calishain

O'Reilly(http://www.oreilly.com/catalog/spiderhks/)刊の Spidering Hacksはscreen-scrapingとspideringについてもっと知りたい 人にとってすばらしい本です。

この本にはAndy Lesterによる3つのMech-specificハックがあります:

  1. WWW::Mechanize 101
  2. Downloading Images from Webshots
  3. Archiving Yahoo! Groups Messages with WWW::Yahoo::Groups

Chris Elthekの2つのMechハックがあります:

  1. Scraping with WWW::Mechanize
  2. Scraping TV Listings

Web上のリソース

Page Top

コンストラクタと開始

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が認識できるパラメータです。 これらはLWP::UserAgentが認識するパラメータには含まれていません。

$a->agent_alias( $alias )

実際にユーザーが渡した文字列からバージョンなどを拡張したものをuser agentに設定します。$aliasには以下のうち一つを使用できます。

すると、最も関連深いものの一つに置き換えられます。例えば、

    $a->agent_alias( 'Windows IE 6' );

ではUser-Agentは以下に設定されます。

    Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)

適切な別名の一覧はknown_agent_aliases()から返されます。

known_agent_aliases()

Mechが知っている全てのエージェントの別名のリストを返します。

Page Top

ページ取得メソッド

$a->get($url)

URL/URIを与えられると、それを取得します。HTTP::Response オブジェクトが帰り値です。$urlは適切に整形されたURL文字列か、 URIオブジェクトです。

この結果はagentオブジェクトに内部的に保持されますが、それを知っている 必要はありません。以下にリストされているアクセッサを使うだけです。 内部の詮索はしないように祈りますし、サブジェクトは将来変更されます。

get()はLWP::UserAgentのメソッドをよりよい振る舞いをするように オーバーライドしたバージョンです。これは

    $mech->get( $url, ":content_file"=>$tempfile );

のようなことを可能にしますし、このパラメータが適当にフィルタされて 取得されることとみなして構いません。

$a->reload()

ブラウザのリロードボタンのように振舞います: 現在のリクエストを 再実行します。

リロードによるHTTP::Responseオブジェクトか、まだリクエストが実行 されていない時は現在のリクエストがない時にはundefを返します。

$a->back()

ブラウザの``back''ボタンを叩くのと等価です。前のページに戻ります。 過去の最初のページに戻りたくはありませんか？（実際、それが可能だと したらそうするでしょう？）

Page Top

リンク追跡メソッド

$a->follow_link(...)

そのページの指定されたリンクをたどります。find_link()で使うのと 同じパラメータを使い、それにマッチするものを指定します。

以下がその例です:

リンクが見つかれば、GETメソッドの実行結果（HTTP::Response オブジェクト）が返されます。ページ内にリンクがないか、または指定された リンクが見つからなかった時は、undefを返します。

このメソッドは、将来の開発では使用されない$a->follow()の置き 換えにあたります。

Page Top

フォームフィールド入力メソッド

$a->form_number($number)

ページ中のnumber番目のフォームを副手順でfield()や click()で呼び出す際のターゲットとして選択します。返り値も選択 されたフォームです。選択されたものが存在しない場合には、ワーニングを 出し、undefを返します。フォームは1番からインデックスが付けられるので 最初のフォームは0ではなく、1です。

$a->form_name($name)

フォームを名前で選択します。ページ上にその名前のフォームが複数ある 時は、そのうち最初のものが選択され、ワーニングが生成されます。 通常はフォームそれ自体を、見つからなかった時にはundefを返します。

この機能はlibwww-perl 5.69以降を必要としますのでご注意ください。

$a->field($name, $value, $number)

フィールド名を受け取り、指定された値をそこにセットします。これは 現在のフォーム（form()で設定されたものか、デフォルトである ページ内の最初のフォーム）に適用されます。

オプションの$numberパラメータは、2つ以上の同じ名前のフィールドが ある時に、それらを区別するのに使われます。フィールドは1から番号が ふられます。

$a->set_fields( $name => $value ... )

このメソッドはフォームの複数のフィールドを設定します。これはフィールド 名と値のペアのリストを引数に取ります。もし同じ名前のフィールドが複数 あれば、そのうち最初に見つかったものに値がセットされます。この複製 されたフィールドのいずれかを選択したいときは、値として、値と番号の 2つの要素をもつ無名配列を使用します。

        # set the second foo field
        $a->set_fields( $name => [ 'foo', 2 ] ) ;

フィールドは1から番号がふられます。

これは現在のフォーム（form()で設定されたものか、デフォルトである ページ内の最初のフォーム）に適用されます。

$a->tick( $name, $value [, $set] )

現在のフォーム中の、その名前と値を持つ最初のチェックボックスに '印を 付け(Ticks)' ます。その値を持つ名前月のチェックボックスがない時は dieします。オプションの三番目の引数でFalseの値を渡すと、チェック ボックスは印がはずされます。

$a->untick($name, $value)

チェックボックスの印をはずします。tick($name,$value,undef)の短い 書き方です。

Page Top

フォーム送信メソッド

$a->click( $button [, $x, $y] )

ボタンをクリックする効果を持ちます。最初の引数は、クリックするボタンの 名前です。2番目と3番目の（オプションの）引数ではクリックする(x,y) 座標を指定できます。

フォーム上にボタンが一つしかなければ、引数なしで$a->click()と するだけで、そのボタンをクリックしたことになります。

HTTP::Responseオブジェクトを返します。

$a->submit()

ボタンをクリックしないまま、そのページをsubmitします。実際には、どの ボタンもクリックされなかったことになります。

これは$a->click("submit")のシノニムとして使用されてきましたが、 今後、いずれかのバージョンでなくなるでしょう。

$a->submit_form( ... )

このメソッドは、直前に取得したページのフォームを選択し、フィールドを 埋め、それをsubmitするためのものです。これはform_number/form_name、 set_fields、clickメソッドを一つの高レベルの呼び出しに結合したものです。 これの引数はkey/valueの組み合わせのリストで、そのいずれもオプション です。

フォームが選択されていない時は、最初に見つかったフォームが使用 されます。

buttonが渡されなかった時は、代わりにsubmit()メソッドが使われ ます。

HTTP::Responseオブジェクトを返します。

Page Top

ステータスメソッド

$a->success()

最後のリクエストが成功したか否かをtrue(1)かfalse(0)で返します。まだ リクエストを実行していなければ、falseを返します。

これは$a->res->is_successをラップする便利な関数です。

$a->uri()

現在のURIを返します。

$a->response() or $a->res()

現在のレスポンスをHTTP::Responseオブジェクトとして返します。

$a->response()の短縮形です。

$a->status()

レスポンス中のHTTPステータスコードを返します。

$a->ct()

レスポンスのコンテントタイプを返します。

$a->base()

現在のレスポンスのベースURIを返します。

$a->content()

レスポンスのコンテントを返します。

$a->forms()

リストコンテキストで呼ばれたときは、最後に取得したページ内で見つかった フォームのリストを返します。スカラーコンテキストのときは、これらの フォームの配列リファレンスを返します。これで返されるフォームはいずれも HTML::Formオブジェクトです。

$a->current_form()

現在のフォームをHTML::Formオブジェクトとして返します。私は form()が既に存在してcurrent_formがセットされている場合を除いては こちらのform()を呼んでいます。

$a->links()

リストコンテキストで呼ばれたときは、最後に取得したページ内で見つかった リンクのリストを返します。スカラーコンテキストのときは、これらの リンクの配列リファレンスを返します。これで返されるリンクはいずれも WWW::Mechanize::Linkオブジェクトです。

$a->is_html()

現在のコンテントがHTMLか否かをHTTPヘッダーを元に判断して、trueまたは falseを返します。

$a->title()

HTML::HeadParserの解析結果を元に、<TITLE>タグの内容を返します。 コンテントがHTMLではない場合はundefを返します。

Page Top

コンテントハンドリングメソッド

$a->find_link()

このメソッドは現在取得されているページ内のリンクを検索します。これは そのリンクについて記述しているWWW::Mechanize::Linkオブジェクトを 返します。（きっとURLの記述より、こちらに魅力を覚えるでしょう。） リンクが見つからなかったときにはundefを返します。

URL部分を取り出し、get()メソッドに渡すことができます。もしこれを したいのであれば、直接follow_link()メソッドを呼ぶのも良い でしょう。これは、自動的にget()を実行します。

<FRAME SRC="...">タグはHTMLとして解析され、リンクとして扱われ ますので、このメソッドを使えることを覚えておいてください。

以下のkey/valueの組み合わせを一つまたは複数渡すことで、リンクを選択 することができます:

nが指定されなかった場合、デフォルトは1です。したがって、もし一切 パラメータを指定しなかった場合には、このメソッドはデフォルトで ページ中の最初のリンクを検索します。

複数のテキストまたはURLパラメータを指定でき、これらはすべてand条件 として扱われることを覚えておいてください。例えば、テキストが``News''で、 URLに``cnn.com''を含む最初のリンクを探すには、以下のようにします:

    $a->find_link( text => "News", url_regex => qr/cnn\.com/ );

$a->find_link(): link format

$self->content中のリンクに対応するWWW::Mechanize::Link オブジェクトをすべて含んだ配列リファレンスが返り値です。

リンクは、以下から取得されます:

<A HREF=...>
<AREA HREF=...>
<FRAME SRC=...>
<IFRAME SRC=...>

$a->find_all_links( ... )

判定基準にマッチするすべてのリンクを返します。このメソッドへのリンク の判定基準の指定方法は、find_link()と同じです。すべてのリンクは WWW::Mechanize::Linkとして返されます。

リストコンテキストでは、find_all_links()はリンクのリストを返します。 そうでなければ、リンクのリストへのリファレンスを返します。

find_all_links()をパラメータなしで呼ぶと、ページ中のすべての リンクが返されます。

Page Top

その他のメソッド

$a->add_header(name => $value)

WWW::MechanizeエージェントがWebページを取得する際に常に使用する ヘッダーをセットします。これはエージェントオブジェクトではなく （こうしてしまうと、back()でこれを設定する以前まで戻るとセットした 内容は無効になってしまいます）、全てのヘッダーがセットされている ハッシュ値の%WWW::Mechanize::headers中に保持されます。 もしそうしたければ、直接この値を操作することもできます: add_header()メソッドは最も標準的なヘッダー追加に便利な関数を提供するに 過ぎません。

$a->quiet(true/false)

画面へのワーニングを抑制することができます。

    $a->quiet(0); # ワーニングを有効にします (デフォルト)
    $a->quiet(1); # ワーニングを無効にします
    $a->quiet();  # 現在のquiet設定状態を返します

Page Top

LWP::UserAgentメソッドのオーバーライド

$a->redirect_ok()

LWP::UserAgentのredirect_ok()をオーバーライドしたバージョンです。 このメソッドはリダイレクションを追跡すべきか否かを判定するために 使われます。

$a->request( $request [, $arg [, $size]])

LWP::UserAgentのrequest()をオーバーライドしたバージョンです。 現在のリクエストを実行します。通常は、WWW::Mechanizeを使っていれば、 このようなレベルで作業し様とはまったく思わないでしょうから、こう すべきでしょう

$requestが修正されていることは覚えておいてください。

HTTP::Responseオブジェクトを返します。

$a->_parse_html()

HTMLドキュメントから得られるフォームとリンクを初期化する内部メソッド です。もしサブクラスでこれをオーバーライドしたり、複数回これを呼び出し たくなったら、どうぞそうしてください。

_make_request()

WWW::Mechanize::Cachedのように、サブクラスでリクエストを中断させる のに便利なメソッドです。

Page Top

使用が推奨されないメソッド

このメソッドはより正しく柔軟なメソッドで置き換えられています。そちら 代わりにお使いください。

$a->follow($string|$num)

非推奨になっており、より柔軟なfollow_link()を使うことが 勧められます。

リンクを追跡します。文字列を与えれば、そのテキストがこの文字列にマッチ する最初のリンクが追跡されます。番号を与えれば、ページ中の $num番目のリンクになります。リンクは0から始まることに注意して ください。

ページ中にリンクが見つかればtrueを、そうでなければundefを返します。

$a->form($number|$name)

非推奨になっており、form_name()またはform_number()を 使うことが勧められます。

渡されたのが数字だけの文字列か否かによって、フォームを番号または名前で 選択します。これは、もし数字だけの名前をもつフォームがあった場合に、 このメソッドは正しく動かないかも知れないことを意味しています。

Page Top

内部使用限定のメソッド

これらのメソッドは内部でのみ使われます。これらについて知る必要は多分 ないでしょう。

$a->_reset_page()

ページを解析した際のガラクタのような内部フィールドをリセットします。

$a->_extract_links()

Webページの今テントからリンクを抽出するもので、WWW::Mechanize::Link の{links}プロパティを一般化します。

$a->_push_page_stack() and $a->_pop_page_stack()

エージェントは訪れたページをスタックしており、BACKの際など必要になった 時にはこれで取り出します。

現在のページは新しいページを取得する前にスタックに追加されなければ いけませんし、BACKが発生した際にはスタックから取り出されなければ いけません。

どちらも引数を与えられても、$aオブジェクトを操作します。

Page Top

参照

サンプルコードについてはWWW::Mechanize::Examplesも参照してください。 WWW::Mechanize::ShellはMechanizeを よりスクリプティングツールとしてふさわしいものにするアドオンです。

その他のMechanizeを使用するモジュール

以下はMechanizeを使用しているかサブクラスになっているモジュールの リストです。他にあれば教えてください:

Page Top

要望とバグ

要望や示唆、バグ（ヤバッ！）は http://rt.cpan.org/ のRTバグ トラッキングシステムか、 bug-WWW-Mechanize@rt.cpan.org へのemailで 報告してください。これは私が追跡するのを簡単にしてくれます。

http://rt.cpan.org/NoAuth/Bugs.html はMechanize へのRTキューです。あなたのバグが既に報告されていないか見るにはこちらを チェックしてください。

Page Top

Author

Copyright 2003 Andy Lester <andy@petdance.com>

Artistic Licenseに基づきリリースされています。 Kirrily RobertのすばらしいWWW::Automateパッケージをベースにしました。

Page Top

DOCUMENT TRANSLATION

Makio Tsukamoto, tsukamoto@gmail.com

Page Top

This document is hosted by