Mechanize::History

一般的な Web ブラウザにおけるアクセス履歴とファイルキャッシュをひとまとめにしたようなクラスです。
Mechanize が取得したファイルやページのオブジェクトが、アクセス時の URL に関連付けられて丸ごと格納されています。

通常は Mechanize#history でアクセス履歴配列として利用するか、Mechanize#visited_page で URL を指定してページを抽出します。ユーザーがこのクラスのメソッドを直接利用することはあまりありません。
いちおう配列を継承してはいるのですが、独自内部インデックスとの齟齬が起きるので配列由来のメソッドの使用はお勧めできません。

Mechanize の履歴は役割的にはキャッシュで、 URL の他に取得したファイル本体（とパースした Nokogiri オブジェクトと Page オブジェクト）を全てメモリ内に保持しています（{uri1 => page1, uri2 => page2} のようなイメージ）。大量の URL や巨大なファイル群にアクセスすることが事前にわかっている場合は、履歴の最大数を Mechanize#max_history= で適当な数に設定しておくことをお勧めします。妥当な動作をする履歴の最低値は 1 です。

通常の Web ブラウザのようにキャッシュ相当をディスク上に書き出して運用するようなことはできません。
巨大なファイルを「少しずつ読み捨てながらパースする」というようなこともできません。
巨大なファイルを取得した場合は必ず同じだけの（HTML だった場合はパース済みオブジェクトのぶん倍以上の）メモリを占有します。
履歴を 0 に設定した場合は、履歴オブジェクトへの登録自体は行われなくなりますが

Mechanize#page つまり agent.page が常に nil を返す
If-Modified-Since 用の時刻が取れないので 304 かどうかチェックできない
click したり相対 URL を get してもリファラが送られない
- ただし、submit や post のリファラは履歴とは無関係に必ず送られる
履歴の配列から参照されないだけで、最新ファイルと HTML パース内容をメモリ内で保持すること自体は必ず行われる

というめんどくさい動作になります。

new - Mechanize::History オブジェクトを生成する
max_size= - アクセス履歴兼キャッシュの最大保持数を整数で指定
max_size - アクセス履歴兼キャッシュの最大保持数を整数で返す
push - アクセス履歴兼キャッシュにページを登録する
<< - alias #push
visited? - URL がアクセス履歴兼キャッシュに存在するかどうかを真偽で返す
visited_page - アクセス履歴兼キャッシュから該当 URL のページを取り出して返す
clear - アクセス履歴兼キャッシュを全て削除する
shift - 一番古い履歴をひとつアクセス履歴兼キャッシュから削除する
pop - 最新の履歴をひとつアクセス履歴兼キャッシュから削除する

Mechanize::History.new(max_size=nil)

Mechanize::History オブジェクトを生成します。ユーザーが使用することはありません。
引数の max_size は #max_size の初期値になります。

max_size=(size)

アクセス履歴上限を返す #max_size の返り値を size に変更します。
ページのオブジェクトの数を整数か nil で設定します。
Mechanize#max_history= から呼ばれているメソッドです。通常は Mechanize#max_history= を使用してください。

max_size

アクセス履歴として保持してもよい、ページのオブジェクトの数を整数か nil で返します。
Mechanize#max_history から呼ばれているメソッドです。通常は Mechanize#max_history を使用してください。
nil は無限に保持することを表します。

push(page, url=nil)

ページのオブジェクトを履歴兼キャッシュに追加します。追加の終わった Mechanize::History オブジェクトを返します。
第 1引数 page は Mechanize::Page か Mechanize::File オブジェクトです。
第 2引数 url は登録に使用する URL を表す文字列か URI オブジェクトです。無指定だった場合は page の uri メソッドの返り値（Mechanize::File#uri）が流用されます。
追加後の履歴の大きさが #max_size よりも大きい場合は、#shift メソッドで先頭から同数になるまで削除されます。

<<

alias #push

visited?(url)

履歴兼キャッシュが url に関するページを含んでいれば true を、そうでなければ false を返します。
Mechanize#visited? から呼ばれているメソッドです。通常は Mechanize#visited? を使用してください。

visited_page(url)

履歴兼キャッシュが url に関するページを含んでいれば抽出して返します。存在しなければ nil を返します。
Mechanize#visited_page から呼ばれているメソッドです。通常は Mechanize#visited_page を使用してください。

clear

キャッシュに追加されたページと履歴用内部インデックスを全て削除します。空になった History オブジェクトを返します。

shift

履歴に登録されている一番古いオブジェクトをひとつ削除し、それを返します。ユーザーが使用することはありません。
履歴が空だった場合は nil を返します。

pop

履歴に登録されている一番新しいオブジェクトをひとつ削除し、それを返します。ユーザーが使用することはありません。
履歴が空だった場合は nil を返します。
多くの場合、現在のページが削除され、ひとつ履歴が詰まります。Mechanize#back から呼ばれているメソッドです。通常は Mechanize#back を使用してください。