Mechanize::CookieJar

「クッキーの入れ物」（Cookie Jar）として振舞うクラスです。受け取ったクッキーをドメイン内のパス内の名前ごとに Mechanize::Cookie オブジェクトにして格納しています。
クッキーのドメイン管理や期限切れチェック、送信と受信は Mechanize が自動で行っているので、ユーザーがこのクラスのメソッドを利用する機会はそう多くはありません。いくつかメソッドが定義されていますが、ほとんどは Mechanize が内部で使用しているだけのものです。

#save_as メソッドで Mechanize オブジェクトが現在保持している全てのクッキーを YAML 形式で保存することができます。読み込みたいときは #load メソッドです。

Mechanize は HTTP ヘッダの Cookie: ヘッダと同様に HTML の meta 要素の cookie も解釈します。拒否することも由来を区別することもできません。HTML のクッキーを読み込んだあとに HTTP のクッキーを読み込みます。name が重複した場合は HTTP のほうのクッキーで上書きされます。

Mechanize はクロスドメインクッキーインジェクション等に対して特に対処を行っていません。.co.jp というクッキーも普通に保持して使用してしまうので、（Mechanize の用途的にあまりありえないと思うのですが）不審なクッキーを発行するような怪しいサイトへのアクセスと普通なサイトへのアクセスを混ぜて行う場合には注意をしてください。

new - Mechanize::CookieJar オブジェクトを生成する
jar - 登録されているクッキーを内部状態のまま全て返す
add - クッキーをひとつ登録する
cookies - URL に関する有効なクッキーを全て返す
empty? - URL に関する有効なクッキーが存在しないことについて真偽で返す
to_a - 現在保持する全てのクッキーを期限切れも含めて配列にして返す
save_as - 現在保持する全てのクッキーをテキストでファイルに保存する
load - Mechanizeが保存したクッキーファイルを読み込む
clear! - 登録されているクッキーを全て削除する
load_cookiestxt - cookies.txt形式のクッキーファイルを読み込んで登録する
dump_cookiestxt - cookies.txt形式のテキストとして書き出す

Mechanize::CookieJar.new

Mechanize::CookieJar オブジェクトを生成します。ユーザーが使用することはありません。

jar

登録されているクッキーを内部の状態のまま Hash で返します。クッキーが何もない状態では空の Hash の {} を返します。

{'domain1' => 
  {'Path1' => 
    {'name1' => MechanizeCookie1,
     'name2' => MechanizeCookie2}.
   'Path2' => ...,
  }
}

という、対象クッキーオブジェクトの domain と path と name を入れ子キーにして本体の Mechanize::Cookie を格納する、という構造になっています（Mechanize::Cookie は name ごとに作成されています）。
返り値の Hash を直接変更することはあまりお勧めしません。

add(uri, cookie)

Mechanize::Cookie オブジェクト cookie を uri に関連付けて登録します。このメソッドをユーザーが使用することは通常ありません。クッキーの手動登録の方法は Mechanize::Cookie を参照してください。
cookie を返します。
第 1引数の uri は Ruby 標準の URI オブジェクトです。uri.host は cookie.domain に含まれていなければなりません。
第 2引数の cookie は Mechanize::Cookie オブジェクトです。
大文字小文字無関係のドメイン名 Mechanize::Cookie#domain と大文字小文字区別するパス名 Mechanize::Cookie#path とクッキーに記述されていた名前 Mechanize::Cookie#name の 3つで区別されます。domain と path と name を持つクッキーが既に存在していた場合、引数の cookie で上書きされます。
もし、既に登録されているクッキーで期限切れのものがあれば、cookie の登録後にチェックされ、メソッドの引数とは無関係に全て削除されます。

cookies(uri)

引数 uri の uri.host と uri.path に関するクッキーのうち、期限切れでない Mechanize::Cookie オブジェクトを全て配列にして返します。
uri に該当するクッキーがない場合や、全て期限切れだった場合は空の配列 [] を返します。
uri.host はクッキーのドメイン名 Mechanize::Cookie#domain と、uri.path はクッキーのパス名 Mechanize::Cookie#path と比較チェックされます。uri.host は大文字小文字が区別されませんが、 uri.path は大文字小文字が区別されます。。
検索時に全クッキーの期限切れチェックと削除が行われるので、期限切れのクッキーが存在した場合は uri と無関係でも削除されます。無関係な期限切れのクッキーを削除したくない場合は #jar の返り値から直接 Mechanize::Cookie オブジェクトを取り出してください。

empty?(uri)

URL の host と path に関するクッキーが存在しないか、存在していても全て期限切れであった場合に true を返します（区別できません）。
期限切れでないものが存在した場合は false を返します。
#cookies メソッドに uri を渡した結果の配列の大きさをチェックしています（配列に中身があれば false）。uri の扱いと期限切れクッキー全削除の挙動はそちらを参照してください。

to_a

オブジェクトが現在保持する全ての Mechanize::Cookie オブジェクトを、期限切れ状態のものも含め全て抽出して配列にして返します。
クッキーがひとつもなかった場合は空の配列 [] が返ります。
期限切れチェックなどは行われません。

save_as(path)

save_as(path, :cookiestxt)

このオブジェクトが現在保持する Mechanize::Cookie オブジェクトを、期限切れ状態のものも含め全て YAML 形式でファイルに書き出します。保存したファイルのバイト数が返ります。

agent.get(uri)
...
agent.cookie_jar.save_as('mech_cookie.yaml')

クッキーがひとつもなかった場合は空っぽの Hash を示す YAML が書かれた数バイトのファイルができます。
第 1引数の path は保存先ファイルのパス文字列です。File.open に渡せる文字列を指定してください。#jar の返り値が YAML.dump されたものがファイルにテキストモードで保存されます（'wb'ではなく'w'）。
第 2引数を空にする（か :yaml というSymbolを指定する）と YAML 形式で保存されます。:cookiestxt という Symbol を指定すると Firefox2 の cookies.txt 形式（連綿と続く古いMozilla形式）で書き出すことができます（#dump_cookiestxt を参照）。

保存されたファイルは #load で読み込むことができ、 YAML 形式の場合は #jar 全体と置き換わります。
第 2引数に #load で読み込んだとき、元々の #jar は破壊されず個々に上書きされます。
この動作が意図的な使い分けなのかどうかはよくわかりません。Firefox3 の cookies.sqlite ファイルに保存することはこのメソッドではできません。なんとかして SQLite3 でアクセスしてください。

load(path)

load(path, :cookiestxt)

ファイルから #save_as などによって YAML 形式で保存されたクッキーデータを読み込んで、現在の #jar をそのまま置き換えます。新しい #jar の中身が返ります。

agent = Mechanize.new
agent.cookie_jar.load('mech_cookie.yaml')
agent.get(site_top)
site_login(agent) if agent.page.body =~ /ようこそゲストさん/u
...

機械的に置き換わるので、既に保持しているクッキーと混在させたい場合は事前に退避しておいてから何らかの手段でマージしてください。
path は読み込むファイルのパス文字列です（::File.open(path) として渡されます）。
第 2引数に :cookiestxt という Symbol を指定すると Firefox2 の cookies.txt 形式のファイルも読み込むことができます。#load_cookiestxt を参照してください。この場合はクッキーは慎重に上書きされ、元からあったクッキーは破壊されません。
Firefox3 の cookies.sqlite ファイルを読み込むことはできません。RubyのMechanizeでFirefox3のクッキーをsqlite3使って読んでみるを参照してください。