Ruby Mechanize wiki (ja)

HTML 以外を Mechanize で取得したあと、最終的にデータが格納されるクラスです。HTML の場合は Mechanize::Page が使用されます。
ファイル本文や URI、アクセス時の HTTP レスポンスヘッダなどを保持しています。
このオブジェクトに格納されているデータは Mechanize が解釈し終わったあとのものなので、内容を変更しても Mechanize の動作に影響を与えることができません。Mechanize の解釈を変えたい場合は Mechanize#post_connect_hooks で送信直後の HTTP レスポンスに直接割り込む必要があります。

Mechanize::Page へ継承されています。Mechanize::PluggableParser を自作する際にも使用します。

---

• new - Mechanize::File オブジェクトを生成する
• uri - サーバにアクセスした際の URI を返す
• uri= - サーバにアクセスした際の URI を事後で書き換える
• response - サーバからのレスポンスヘッダを返す
• response= - サーバからのレスポンスヘッダを事後で書き換える
• body - サーバから取得したファイル内容を返す
• body= - サーバから取得したファイル内容を事後で置き換える
• code - ファイル取得時の HTTP リザルトコード数字文字列を返す
• code= - ファイル取得時の HTTP リザルトコード数字文字列を事後で書き換える
• filename - 保存メソッドでのデフォルトで使用されるファイルパスを返す
• filename= - 保存メソッドでのデフォルトで使用されるファイルパスを指定する
• header - alias #response
• content - alias #body
• save_as - ファイル内容をディスクに保存する
• save - alias #save_as

---

HTML 以外のファイルを表す Mechanize::File オブジェクトを生成します。

file = Mechanize::File.new(URI.parse('http://www.example.com/'){
                           {'content-type' => 'image/jpeg'},
                           File.open('hoge.jpg'){|f| f.read},
                           '200')
# http://www.example.com/ から取得したファイルだとみなして履歴に登録
agent.__send__(:add_to_history, file)

ユーザーが使用することはあまりありません。一応、「空のページ」等の作成のために使用することはあります。
第 1引数 uri はページ（というか、ファイル）の場所を表す URL を表す Ruby 標準の URI オブジェクトです。文字列は動作しません。
第 2引数 response はサーバからの受信ヘッダを表す小文字キー Hash か Mechanize::Headers です。本来 Net::HTTPResponse のヘッダが使われる場所なので、ヘッダ名のキーは小文字にしておいてください。Mechanize::Page とは違い Mechanize でこの値を使用することはありません。外部利用する機会がないことがわかっているなら空の Hash {} で構いません。
第 3引数 body はサーバからのレスポンスボディです。gzip 展開済みでヘッダなどのない「ファイル」本体の文字列を指定します。
第 4引数 code はサーバからのレスポンスコードの数値文字列です。通常は '200' です。Mechanize はこの値を利用しないので、nil のままでも動作はします。
ブロックを取ることもでき、生成された File オブジェクトが渡されます。ブロックの返り値は、渡された File オブジェクトと同一です。

このファイルを取得した際の最終的な URI オブジェクトを返します。
デフォルトは Mechanize::File.new の引数で、Mechanize#get などでアクセスし終わった URL を表す Ruby 標準の URI オブジェクトです。
必ず絶対 URI です。GET したときのクエリパラメータは URI#query 部に含まれています。

このファイルを取得した際の最終的な URI オブジェクトを返す #uri を再設定します。
ページを取得した際の GET のクエリパラメータは URI#query 部に含められていなければなりません。あまり使用する機会のないメソッドだと思われます。

サーバから送られてきた HTTP レスポンスヘッダを Mechanize::Headers オブジェクトで返します。
デフォルトは Mechanize::File.new の第 2引数で、サーバアクセス時の Net::HTTPResponse#each を Mechanize::Headers に登録したものです。読むぶんにはおおむね Hash のように振舞うので、Hash だとみなして構いません。
サーバへ送った HTTP リクエストヘッダを得たい場合は Mechanize#log で送信後にログ出力させるか、Mechanize#pre_connect_hooks で送信直前のデータにアクセスする必要があります。

サーバから送られてきた HTTP レスポンスヘッダを返す #response の返り値を変更します。
設定を行わなかった場合は #response の値が使用されます。小文字キーの Hash か Mechanize::Headers で再設定してください。

サーバから取得したファイル内容を文字列で返します。
デフォルトは Mechanize::File.new の引数で、gzip 展開後のレスポンスボディです。
Ruby1.9 での Encoding は Net::HTTPResponse 依存です。おそらくは ASCII-8BIT です。
何らかの理由で「gzip 展開前の生のレスポンスボディ」が必要な場合は Mechanize::Chain::BodyDecodingHandler? あたりに割り込んでください。また、Mechanize#gzip_enabled= で false を指定すると、リクエストヘッダから gzip が抜けて Accept-Encoding: identity だけになります。

サーバから取得して gzip 展開済みのファイル内容を返す #body の返り値を、引数の文字列で置き換えます。
Ruby1.9 での Encoding は ASCII-8BIT が期待されています。

このファイルをサーバから取得した際のリザルトコードを3桁の数字の文字列で返します。
デフォルトは Mechanize::File.new の引数で、アクセス時の Net::HTTPResponse#code の値です。普通に取得できていれば "200" のはずです。
200 OK や 404 Not Found の "200" や "404" です。
File オブジェクトが確定してから再設定することは無いと思うのですが、#code= で書き換えが可能です。

このファイルをサーバから取得した際のリザルトコードを返す #code の返り値を、3桁の数字の文字列で再設定します。
通常は使用することのないメソッドだと思われます。

#save_as で引数なしのときに使用される保存用ファイルパスを返します。
デフォルトは Content-Disposition ヘッダの値か、#uri のファイル名っぽい部分を参考にしたファイル名です。
再設定は #filename= で行います。#save_as で必ず引数指定するようにしても構いません。

自動保存用ファイルパスを返す #filename の返り値を文字列で設定します。
直接 File.open に渡されるので、open が解釈可能な文字列を引数に指定してください。
ファイル保存を（save_asで）行わないのなら放置しても構いません。

alias #response

alias #body

#body をバイナリモードでファイルに保存します。
保存したファイルのバイト数が返ります。
以下の動作をメソッドひとつで行うものです。

filepath = filepath ? filepath : file.filename
::File.open(filepath, 'wb'){|f| f.write(file.body)}

引数でファイルパスを指定しなかった場合は #filename の値が使用されます（Content-Dispositionヘッダの危険性に注意）。#filename のパスにすでに同名のファイルが存在している場合は、被らなくなるまで末尾に「.数字」が付加され、上書きが回避されます。数字は 1始まりです。
引数でファイルパスを指定した場合は、この上書き回避処理は行われません。既に存在するファイルは破壊され、新たに #body の内容のファイルが作成されます。
#filename= で filepath 相当を設定してから引数なしの save_as を起動すると、Content-Disposition の危険性を回避しつつ、上書きの危険性も回避できます。が、若干面倒です。上書き回避処理を設定で追加できると便利なのですが。

alias #save_as