class JSON::Coder (Ruby 4.0 リファレンスマニュアル)

要約

JSON のエンコード(シリアライズ)・デコード(パース)の設定をひとつのオブジェクトにまとめ、再利用可能にするためのクラスです。

JSON?.generate, JSON?.parse のようなモジュール関数はプロセス全体で設定を共有しますが、 JSON::Coder を使うとライブラリやアプリケーションごとに独立した設定(オプションや、 JSON にネイティブ対応していない型の変換方法)を持つことができます。

JSON::State の #[], #[]= メソッドの代替の手段として、 JSON::Coder の使用が案内されています。

例

require "json"
require "time"

module MyApp
  API_JSON_CODER = JSON::Coder.new do |object|
    case object
    when Time
      object.iso8601(3)
    else
      object # 未対応の型。ブロックの戻り値も JSON にネイティブ対応していなければエラーになる
    end
  end
end

t = Time.utc(2025, 1, 21, 8, 41, 44, 286_000)
p MyApp::API_JSON_CODER.dump(t) # => "\"2025-01-21T08:41:44.286Z\""

特異メソッド

new(options = nil) {|object, is_key| ... } -> JSON::CoderRuby 4.0 から[permalink][rdoc][edit]

自身を初期化します。

options には、JSON 形式の文字列を生成する際(JSON?.generate)とパースする際(JSON?.parse)の両方に使われるオプションをハッシュで指定します。ただし、生成に関しては常に strict: true を指定した場合と同様に扱われます。すなわち、文字列・シンボル・整数・浮動小数点数・配列・ハッシュ・true・false・nil 以外のオブジェクトを変換しようとすると、ブロックが指定されていない限り JSON::GeneratorError が発生します。

ブロックを指定すると、上記のような JSON にネイティブ対応していない型のオブジェクトを生成しようとしたときにそのブロックが呼び出されます。ブロックには対象のオブジェクトと、それがハッシュのキーとして使われているかどうかを表す真偽値が渡されます。ブロックの返り値が、そのオブジェクトの代わりに変換されます。返り値の中にさらにネイティブ対応していないオブジェクトが含まれていれば、それに対してもブロックが呼び出されます。JSON::Fragment を返すと、その内容がそのまま挿入されます。ハッシュのキーに対する返り値は String か Symbol でなければなりません。不正なエンコーディングの文字列や、ASCII 以外のバイトを含む BINARY(ASCII-8BIT)エンコーディングの文字列に対してもブロックが呼び出されます。ブロックの返り値もネイティブ対応していない型であった場合は JSON::GeneratorError が発生します。

[PARAM] options:: ハッシュを指定します。指定可能なオプションは JSON?.generate, JSON?.parse を参照してください。

例 options はパースと生成の両方に適用される

require "json"

coder = JSON::Coder.new(symbolize_names: true)
p coder.load('{"name":"Ruby","version":"3.4"}') # => {name: "Ruby", version: "3.4"}
p coder.dump(name: "Ruby", version: "3.4")       # => "{\"name\":\"Ruby\",\"version\":\"3.4\"}"

例ブロックを指定しない場合、未対応の型はエラーになる

require "json"

coder = JSON::Coder.new
begin
  coder.dump(1..3)
rescue JSON::GeneratorError => e
  p e.message # => "Range not allowed in JSON"
end

例ハッシュのキーと値でブロックの引数が異なる

require "json"

coder = JSON::Coder.new do |object, is_key|
  is_key ? object.to_s : object.to_a
end
p coder.dump({1..2 => 3..4, "k" => 5..6}) # => "{\"1..2\":[3,4],\"k\":[5,6]}"

例 JSON::Fragment で生成済みの JSON を埋め込む

require "json"

cached = '{"id":1,"name":"Ruby"}'
coder = JSON::Coder.new { |object| JSON::Fragment.new(cached) }
p coder.dump({"item" => Object.new}) # => "{\"item\":{\"id\":1,\"name\":\"Ruby\"}}"

[SEE_ALSO] JSON::State#as_json=, JSON::State#strict=

インスタンスメソッド

dump(object) -> StringRuby 4.0 から[permalink][rdoc][edit]

dump(object, io) -> IO

generate(object) -> String

generate(object, io) -> IO

object を JSON 形式の文字列に変換します。

io を指定した場合は、生成した JSON 形式の文字列を io に書き込み、io 自身を返します。指定しない場合は、生成した文字列を返します。

generate は dump の別名です。

[PARAM] object:: JSON 形式の文字列に変換するオブジェクトを指定します。
[PARAM] io:: IO のように write メソッドを実装しているオブジェクトを指定します。
[EXCEPTION] JSON::GeneratorError:: object(またはその内部の値)が JSON にネイティブ対応しておらず、JSON::Coder.new にブロックも指定されていなかった場合や、ブロックの返り値も JSON にネイティブ対応していなかった場合に発生します。

例

require "json"

coder = JSON::Coder.new
p coder.dump({ "name" => "Ruby" }) # => "{\"name\":\"Ruby\"}"
p coder.generate({ "name" => "Ruby" }) # => "{\"name\":\"Ruby\"}"

load(source) -> objectRuby 4.0 から[permalink][rdoc][edit]

parse(source) -> object

source を Ruby のオブジェクトに変換します。

parse は load の別名です。

[PARAM] source:: JSON 形式の文字列を指定します。
[EXCEPTION] JSON::ParserError:: source が正しい JSON 形式の文字列ではない場合に発生します。

例

require "json"

coder = JSON::Coder.new
p coder.load('{"name":"Ruby"}')  # => {"name" => "Ruby"}
p coder.parse('{"name":"Ruby"}') # => {"name" => "Ruby"}

load_file(path) -> objectRuby 4.0 から[permalink][rdoc][edit]

path で指定したファイルの中身を JSON 形式の文字列として読み込み、 Ruby のオブジェクトに変換します。

[PARAM] path:: 読み込む JSON ファイルのパスを指定します。

例

require "json"
require "tempfile"

coder = JSON::Coder.new
Tempfile.create(["sample", ".json"]) do |f|
  f.write(coder.dump({ "name" => "Ruby" }))
  f.flush
  p coder.load_file(f.path) # => {"name" => "Ruby"}
end

要約

目次

特異メソッド

インスタンスメソッド