WWW::Mechanize 覚書

perldoc WWW::Mechanize の読書メモです

概論
コンストラクタ
PAGE-FETCHING METHODS
STATUS METHODS
CONTENT-HANDLING METHODS
LINK METHODS
IMAGE METHODS
FORM METHODS
MISCELLANEOUS METHODS
OVERRIDDEN LWP::UserAgent METHODS
DEPRECATED METHODS
INTERNAL-ONLY METHODS
WWW::MECHANIZE'S SUBVERSION REPOSITORY
OTHER DOCUMENTATION
ARTICLES ABOUT WWW::MECHANIZE
REQUESTS & BUGS

概論

LWP::UserAgent のサブクラスとして実装され、LWP::UserAgent のメソッドは全部使える。

WWW::Mechanize::FAQ なんてのがある

コンストラクタ

my $mech = WWW::Mechanize->new()

WWW::Mechanize のコンストラクタは、LWP::UserAgent のしてくれることに加えて、User-Agent to とクッキージャーを、↓のような具合にセットアップしてくれる

agent => "WWW-Mechanize/#.##"
cookie_jar => {}    # an empty, memory-only HTTP::Cookies object

ユーザーエージェントを変更するなら

my $mech = WWW::Mechanize->new( agent=>"wonderbot 1.01" );

クッキーを有効にしないんだったら

my $mech = WWW::Mechanize->new( cookie_jar => undef );

この他に、LWP::UserAgent にはない以下のパラメータを設定できる

autocheck => [0|1] ::

個々のリクエストが成功したかチェック
エラー発生時にはエラー
デフォールトはオフ

onwarn => \&func() ::

警告時の関数の指定

onerror => \&func() ::

die 時の関数の指定

quiet => [0|1] ::

警告を出力しない

stack_depth => $value ::

ページスタックの深さを指定
デフォールト値は 0 で無制限
WWW::Mechanize がメモリを食いすぎるようだったら 1 にセットする

$mech->agent_alias( $alias ) ::

よく使うエージェントを簡易な別名でセット
使える別名は以下の通り
- Windows IE 6
- Windows Mozilla
- Mac Safari
- Mac Mozilla
- Linux Mozilla
- Linux Konqueror
known_agent_aliases() は使える別名のリストを返す
$mech->agent_alias( ’Windows IE 6’ ); で、下の値がセットされる

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

PAGE-FETCHING METHODS

$mech->get( $url )

URL をフェッチして HTTP::Response オブジェクトを返す
引数 URI は、文字列、URI オブジェクトまたは WWW::Mechanize::Link オブジェクト

$mech->reload()

リロードボタンを押した時の様に振舞う
返り値は HTTP::Response オブジェクトまたは undef

$mech->back()

バックボタンに同じ

STATUS METHODS

$mech->success()

リクエストが成功したかどうかのブール値を返す
リクエストが発行されていない場合は false
"$mech->res->is_success". とするのと同じ

$mech->uri()

現在 URI を返す

$mech->response() / $mech->res()

現在レスポンスを返す
返り値は HTTP::Response オブジェクト
"$mech->response()" と同義

$mech->status()

Returns the HTTP status code of the response.

$mech->ct()

Returns the content type of the response.

$mech->base()

Returns the base URI for the current response

$mech->forms()

リストコンテキストでは、最後にフェッチしたページのフォームのリストを返す
スカラコンテキストでは、フォームを格納する配列へのリファレンスを返す
フォームは HTML::Form のオブジェクト

$mech->current_form()

Returns the current form as an HTML::Form object. I’d call this "form()" except tha

$mech->links()

リストコンテキストでは、現在ページ上のリンクのリストを返す
スカラコンテキストでは、現在ページ上のリンクを格納した配列へのリファレンスを返す
これらリンクは WWW::Mechanize::Link のオブジェクト

$mech->is_html()

コンテンツが HTML かどうかの述語
HTTP ヘッダをみて判断

$mech->title()

タイトルタグのコンテンツを返す
構文解析には HTML::HeadParser を使っている
HTML じゃなかったら undef を返す

CONTENT-HANDLING METHODS

コンテンツが html じゃなかったら、以下のメソッドでは何も起らない。(将来的には変更の予定がある)

$mech->content(...)

基本的には $mech->response()->content() と同義

$mech->content( format => "text" ) ::

HTML のマークアップを除去してテキスト版のコンテンツを返す
これを使うには HTML::TreeBuilder が必要

$mech->content( base_href => [$base_href|undef] ) ::

ヘッダに

を追加

$base_href を与えないと $mech->base() の値を使う

LINK METHODS

$mech->links

現在ページのリンクのリストを返す
リンクは WWW::Mechanize::Link object
リストコンテキストでは、リンクのリストを返す
スカラコンテキストでは、リンクを格納する配列へのリファレンスを返す

$mech->follow_link(...)

指定されたリンクを辿る

下は三番目の"download というリンクを辿る例"
```
$mech->follow_link( text => "download", n => 3 );
```

URL に download が含まれる最初のリンクを辿る例

$mech->follow_link( url_regex => qr/download/i );
$mech->follow_link( url_regex => qr/(?i:download)/ ); # こちらでも同じ

ページの三番目のリンクを辿る
```
$mech->follow_link( n => 3 );
```

成功したら GET メソッドの結果を HTTP::Response オブジェクトとして返す
ページにリンクがなかったり GET できなかったら undef を返す
このメソッドは廃止予定の $mech->follow() メソッドを置き換えるものである。

$mech->find_link()

リンクを見付けるメソッド
WWW::Mechanize::Link オブジェクトを返す
失敗すれば undef を返す
url をみつけて get しにいくんなら follow_link() を使うべき

"text > 'string'," :: - リンクのテキストが 'string'に正確にマッチ <pre class"example"> $mech->find_link( text => "download" );

"text_regex > qr/regex/," :: - 正規表現が、リンクテキストにマッチ <pre class"example"> $mech->find_link( text_regex => qr/download/i );

リンクテキストはトリムされていることに注意

"url

> 'string'," ::
 - url が string にマッチ

"url_regex

> qr/regex/," ::

url が正規表現にマッチ

"url_abs > string" :: - abs_url が string にマッチ "url_abs_regex> regex" ::

abs_url が正規表現にマッチ

"name > string" :: - name が string にマッチ "name_regex> regex" ::

name が regex にマッチ

"tag > string" :: "tag_regex> regex" ::

タグとその属性でチェックする場合は $mech-find_link() : link format の項参照
```
$mech->find_link( tag_regex => qr/^(a|frame)$/ );
```
$mech-find_link() : link format>.

これらで n を指定しないとデフォールト値の 1 が使われ、最初のマッチが拾われる。

複数の指定を同時に行なうと and になる。

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

返り値は、WWW::Mechanize::Link オブジェクトの配列へのリファレンスになる。

$mech->find_all_links( ... )

マッチしたすべてのリンクを返す
マッチの指定は find_link() メソッドと一緒
返り値のリンクは WWW::Mechanize::Link のオブジェクト
リストコンテキストではリンクのリストを返す
スカラコンテキストでは、配列へのリファレンスを返す
パラメタなしで呼んだときは、ページ上のすべてのリンクを返す

IMAGE METHODS

$mech->images

現在ページのすべてのイメージを返す
返り値のイメージは、WWW::Mechanize::Image オブジェクト
リストコンテキストではイメージのリストを返す
スカラコンテキストでは、配列へのリファレンスを返す

$mech->find_image()

find_link() 同様 alt,url rul_abs,tag に対して、文字列または正規表現のマッチで拾うことができる
n も find_link() 同様デフォは 1 で最初にマッチしたものを拾う

複数のパターンを指定すると and になるのも同じ

$mech->find_image( image => "News", url_regex => qr/cnn\.com/ );

$mech->find_all_images( ... )

条件に適合するすべてのイメージを拾うには、こちらを使う

FORM METHODS

$mech->forms

現在ページのフォームのリストを返す
フォームはHTML::Form オブジェクト
リストコンテキストでは、リスト
スカラコンテキストでは、配列のリファレンス

$mech->form_number($number)

順番でフォームを指定
フォームがなければ undef
最初のフォームのインデクスは 1 でゼロではない

$mech->form_name($name)

名前でフォームを選ぶ
マッチする最初のフォームを返す
libwww-perl が必要

$mech->field( $name, $value, $number )
$mech->field( $name, \@values, $number )

現在フォームのフィールドに値をセットする
対象フォームは form() メソッドで選択しなければ最初のフォーム
オプショナルな $number 引数を与えたときは、同名の何番目のフィールドかの指定
- ここにフィールドは 1 から数える

$mech->select($name, $value)
$mech->select($name, \@values)

名前 $name の selectエレメントに値をセット
成功したら 1 を返し、失敗したら undef を返す

$mech->set_fields( $name > $value ... ) :: - 一度に現在フォームの複数のフィールドに値をセットする - 同名のフィールドが複数あれば、最初にみつかったものにセットする - 複数の同名フィールドに値をセットする時は下のように無名配列をつかう <pre class"example"> $mech->set_fields( $name => [ 'foo', 2 ] ) ;

フィールドは 1 から数える

$mech->set_visible( @criteria )

名前を指定せずに visible なフィールドに順に値を埋めていく
最初の画面がユーザ名とパスワードを聞いてくるなら次のようにすればいい
```
$mech->set_visible( $username, $password ) ;
```
これは visible なフィールドにのみ作用する
@criteria の値は、フィールド値か、フィールド指定子
- フィールド値はスカラ
- フィールド指定子は、入力フィールドのタイプとその値
  - 最初のラジオボタンに値を指定する例
```
$mech->set_visible( [ radio => "KCRW" ] ) ;
```
    with

フィールド値と、フィールド指定子は一緒に使える

$mech->set_visible( "fred", "secret", [ option => "Checking" ] ) ;

ここで使えるフィールド型は

"text", "password", "hidden",
"textarea", "file", "image", "submit", "radio", "checkbox" and
"option".

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

名前と値で指定した最初のチェックボックスをチェックする
名前がマッチしなかったら die する
オプショナルな第三引数に false を与えると、チェックボックスをアンチェックにする

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

チェックボックスをアンチェックにする

$mech->value( $name, $number )

名前が $name なフィールドの値を返す
オプショナルな第二引数で、同名な名前の何番目かを指定
- ここに順番は 1 から数える

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

カレントフォームのボタンをクリック
第一引数はボタンの名前
オプショナルな第二、第三引数は、クリック位置
フォームにひとつしかボタンがなかったら、引数なしでボタンクリック
返り値は HTTP::Response object.

$mech->click_button( ... )

ボタンをクリック
引数は、key/value 対のリスト name > name :: 現在フォームの名前が name な奴をクリック number> n :: 現在フォームのn番目をクリック
1 から数える
value > value :: 現在フォームの値が value な奴をクリック input> $inputobject :: $inputobject が参照するボタンをクリック
- インプットオブジェクトは HTML::Form::SubmitInput のインスタンス
  - 下のようにしてゲットする
```
$mech->current_form()->find_input(undef, "submit")
```

x => x =item * y > y :: クリック座標

$mech->submit() :: - クリックせずにページを送信 - かつて下と同義で使われたが、もう使われない <pre class"example"> $mech->click("submit")"

$mech->submit_form( ... )

現在ページよりフォームを選び、フィールドに値をセットして送信
form_number/form_name, set_fields を組み合わせた高級メソッド
引数は以下のkey/value 対で、すべてオプショナル

form_number => n
n 番目のフォームを選ぶ
- 値が省略されたら、現在フォーム
form_name => name
名前でフォームを選ぶ
fields => fields
フィールドの値をセットする
fields はハッシュリファレンス)
button => button
クリック
x => x, y => y
座標を指定してクリック
フォームが選択されていなかったら最初のフォームが選ばれる
ボタンが渡されてなかったら送信ボタン
返り値は HTTP::Response object.

MISCELLANEOUS METHODS

$mech->add_header( name > $value [, name > $value... ] )

HTTP ヘッダの追加もしくは削除

$mech->add_header( Encoding => 'text/klingon' );

値に undef を与えると、そのヘッダはその後のリクエストすべてから削除
- リファラを送らないようにする例
```
$mech->add_header( Referer => undef );
```
ヘッダを除くにはこれよりも delete_header メソッドを使うべし
返り値は、追加された name/value 対の数

$mech->delete_header( name [, name ... ] )

HTTPヘッダからの削除

    # Don't send a Referer for this URL
    $mech->add_header( Referer => undef );

    # Get the URL
    $mech->get( $url );

    # Back to the default behavior
    $mech->delete_header( 'Referer' );

$mech->quiet(true/false)

ワーニング表示の抑制

    $mech->quiet(0); # turns on warnings (the default)
    $mech->quiet(1); # turns off warnings
    $mech->quiet();  # returns the current quietness status

$mech->stack_depth($value)

ページスタックの深さの参照・設定
0 だったら、すべてのページを保持

$mech->save_content( $filename )

コンテンツ($mech->content)をファイルにセーブ
既存のファイルだったら上書き

OVERRIDDEN LWP::UserAgent METHODS

redirect_ok()
$mech->request( $request [, $arg [, $size]])

リクエストの実行
WWW::Mechanize を使っていたら使わない筈

$mech->update_html( $html )

カレントのページを $html と置き換える
ページの検証なんかするときに便利鴨

DEPRECATED METHODS

トバス

INTERNAL-ONLY METHODS

トバス

WWW::MECHANIZE'S SUBVERSION REPOSITORY

http://svn.perl.org/modules/www-mechanize

ARTICLES ABOUT WWW::MECHANIZE

* <http://www.oreilly.com/catalog/googlehks2/chapter/hack84.pdf>
    Leland Johnson's hack #84 in Google Hacks, 2nd Edition is an exam-
    ple of a production script that uses WWW::Mechanize and
    HTML::TableContentParser. It takes in keywords and returns the
    estimated price of these keywords on Google's AdWords program.

* <http://www.perl.com/pub/a/2004/06/04/recorder.html>
    Linda Julien writes about using HTTP::Recorder to create WWW::Mech-
    anize scripts.

* <http://www.developer.com/lang/other/article.php/3454041>
    Jason Gilmore's article on using WWW::Mechanize for scraping sales
    information from Amazon and eBay.

* <http://www.perl.com/pub/a/2003/01/22/mechanize.html>
    Chris Ball's article about using WWW::Mechanize for scraping TV
    listings.

* <http://www.stonehenge.com/merlyn/LinuxMag/col47.html>
    Randal Schwartz's article on scraping Yahoo News for images.  It's
    already out of date: He manually walks the list of links hunting
    for matches, which wouldn't have been necessary if the
    "find_link()" method existed at press time.

* <http://www.perladvent.org/2002/16th/>
    WWW::Mechanize on the Perl Advent Calendar, by Mark Fowler.

* <http://www.linux-magazin.de/Artikel/ausgabe/2004/03/perl/perl.html>
    Michael Schilli's article on Mech and WWW::Mechanize::Shell for the
    German magazine Linux Magazin.

Other modules that use Mechanize

Here are modules that use or subclass Mechanize.  Let me know of any
others:

* Finance::Bank::LloydsTSB
* HTTP::Recorder
    Acts as a proxy for web interaction, and then generates WWW::Mecha-
    nize scripts.

* Win32::IE::Mechanize
    Just like Mech, but using Microsoft Internet Explorer to do the
    work.

* WWW::Bugzilla
* WWW::CheckSite
* WWW::Google::Groups
* WWW::Hotmail
* WWW::Mechanize::Cached
* WWW::Mechanize::FormFiller
* WWW::Mechanize::Shell
* WWW::Mechanize::Sleepy
* WWW::Mechanize::SpamCop
* WWW::Mechanize::Timed
* WWW::SourceForge
* WWW::Yahoo::Groups

REQUESTS & BUGS

bug-tracking system: http://rt.cpan.org/
email: bug-WWW-Mechanize@rt.cpan.org
RT queue: http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-Mechanize

連絡先:webadmin.itsumi@gmail.com