module Marshal

[edit]

要約

Ruby オブジェクトをファイル(または文字列)に書き出したり、読み戻したりする機能を提供するモジュール。

大部分のクラスのインスタンスを書き出す事ができますが、書き出しの不可能なクラスも存在します(Marshal.#dump を参照)。

ここで「マーシャルデータ」と言う用語は、Marshal.#dump が出力する文字列を指すものとします。

目次

モジュール関数
定数

モジュール関数

dump(obj, port, limit = -1) -> IO[permalink][rdoc][edit]
dump(obj, limit = -1) -> String

obj を指定された出力先に再帰的に出力します。

ファイルに書き出せないオブジェクトをファイルに書き出そうとすると例外 TypeError が発生します。ファイルに書き出せないオブジェクトは以下の通りです。

また、これらのオブジェクトを間接的に指すオブジェクトなども書き出せません。例えば、デフォルト値を求めるブロックを持った Hash は Proc を間接的に指していることになります。 

例

p Marshal.dump(Hash.new {})
# => -:1:in `dump': cannot dump hash with default proc (TypeError)

マーシャルの動作を任意に定義することもできます。

[PARAM] obj:
ダンプする対象のオブジェクトを指定します。
[PARAM] port:
IO かそのサブクラスのインスタンスを指定します。
[PARAM] limit:
指定した場合、limit 段以上深くリンクしたオブジェクトをダンプできません。負の limit を指定すると深さチェックを行いません。デフォルトは -1 です。
[RETURN]
port を省略すると、obj をダンプした String を返します。 port を指定すると port を返します。
[EXCEPTION] TypeError:
ファイルに書き出せないオブジェクトをファイルに書きだそうとした場合に発生します。
[EXCEPTION] ArgumentError:
名前の付いていない Class や Module オブジェクトをダンプしようとした場合に発生します。
[EXCEPTION] ArgumentError:
limit 段以上深くリンクしたオブジェクトをダンプしようとした場合に発生します。

[SEE_ALSO] Object#marshal_dump, Object#marshal_load

load(port, proc = nil) -> object[permalink][rdoc][edit]
restore(port, proc = nil) -> object

port からマーシャルデータを読み込んで、元のオブジェクトと同じ状態をもつオブジェクトを生成します。

proc として手続きオブジェクトが与えられた場合には読み込んだオブジェクトを引数にその手続きを呼び出します。 

例

str = Marshal.dump(["a", 1, 10 ** 10, 1.0, :foo])
p Marshal.load(str, proc {|obj| p obj})

# => "a"
#    1
#    10000000000
#    1.0
#    :foo
#    ["a", 1, 10000000000, 1.0, :foo]
#    ["a", 1, 10000000000, 1.0, :foo]
[PARAM] port:
String か IO (またはそのサブクラス)のインスタンスを指定します。
[PARAM] proc:
手続きオブジェクト。Proc
[EXCEPTION] TypeError:
メジャーバージョンが異なるか、バージョンの大きなマーシャルデータを読み込んだ場合に発生します。

定数

MAJOR_VERSION -> Integer[permalink][rdoc][edit]
MINOR_VERSION -> Integer

Marshal.#dump が出力するデータフォーマットのバージョン番号です。

Marshal.#load は、メジャーバージョンが異なるか、バージョンの大きなマーシャルデータを読み込んだとき例外 TypeError を発生させます。

マイナーバージョンが古いだけのフォーマットは読み込み可能ですが、 $VERBOSE = true のときには警告メッセージが出力されます

マーシャルされたデータのバージョン番号は以下のようにして取得することができます。 

例

obj = Object.new
major, minor = Marshal.dump(obj).unpack("cc")
p [major, minor]
# => [4, 8]