模組 Marshal

編組函式庫會將 Ruby 物件集合轉換為位元組串流，讓它們可以儲存在目前作用中指令碼的外部。此資料稍後可以讀取，並重建原始物件。

編組資料會與物件資訊一起儲存主版本號碼和次要版本號碼。在正常使用下，編組只能載入使用相同主版本號碼和相等或較低次要版本號碼所寫入的資料。如果 Ruby 的「詳細」旗標已設定（通常使用 -d、-v、-w 或 –verbose），則主版本號碼和次要版本號碼必須完全相符。Marshal 版本控管與 Ruby 的版本號碼無關。您可以透過讀取編組資料的前兩個位元組來擷取版本。

str = Marshal.dump("thing")
RUBY_VERSION   #=> "1.9.0"
str[0].ord     #=> 4
str[1].ord     #=> 8

有些物件無法傾印：如果要傾印的物件包含繫結、程序或方法物件、IO 類別的執行個體，或單例物件，則會引發 TypeError。

如果您的類別有特殊序列化需求（例如，您想要以特定格式序列化），或如果它包含否則無法序列化的物件，您可以實作自己的序列化策略。

有兩種方法可以做到這一點，您的物件可以定義 marshal_dump 和 marshal_load 或 _dump 和 _load。如果兩個都已定義，marshal_dump 將優先於 _dump。marshal_dump 可能會產生較小的 Marshal 字串。

安全性考量¶ ↑

根據設計，Marshal.load 可以將載入 Ruby 程序中的幾乎任何類別反序列化。在許多情況下，如果 Marshal 資料從不受信任的來源載入，這可能會導致遠端程式碼執行。

因此，Marshal.load 不適合作為一般用途的序列化格式，您絕不應該取消編組使用者提供的輸入或其他不受信任的資料。

如果您需要反序列化不受信任的資料，請使用 JSON 或其他序列化格式，它只能載入簡單的「原始」類型，例如 String、Array、Hash 等。絕不允許使用者輸入指定要反序列化成任意類型。

marshal_dump 和 marshal_load¶ ↑

當傾印物件時，將呼叫 method marshal_dump。marshal_dump 必須傳回一個結果，其中包含 marshal_load 重建物件所需的資訊。結果可以是任何物件。

當載入使用 marshal_dump 傾印的物件時，會先配置物件，然後使用 marshal_dump 的結果呼叫 marshal_load。marshal_load 必須從結果中的資訊重新建立物件。

範例

class MyObj
  def initialize name, version, data
    @name    = name
    @version = version
    @data    = data
  end

  def marshal_dump
    [@name, @version]
  end

  def marshal_load array
    @name, @version = array
  end
end

_dump 和 _load¶ ↑

當您需要配置要自行還原的物件時，請使用 _dump 和 _load。

當傾印物件時，會使用 Integer 呼叫實例方法 _dump，它表示要傾印的物件最大深度（-1 的值表示您應該停用深度檢查）。_dump 必須傳回一個 String，其中包含重建物件所需的資訊。

類別方法 _load 應採用 String，並使用它傳回相同類別的物件。

範例

class MyObj
  def initialize name, version, data
    @name    = name
    @version = version
    @data    = data
  end

  def _dump level
    [@name, @version].join ':'
  end

  def self._load args
    new(*args.split(':'))
  end
end

由於 Marshal.dump 會輸出字串，因此您可以讓 _dump 傳回 Marshal 字串，而 _load 中的 Marshal.loaded 則用於複雜物件。