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| ... } -> JSON::CoderRuby 4.0 から[permalink][rdoc][edit]

自身を初期化します。

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

ブロックを指定すると、上記のような JSON にネイティブ対応していない型のオブジェクトを生成しようとしたときにそのブロックが呼び出されます。ブロックには対象のオブジェクトが渡され、 JSON にネイティブ対応した値(文字列など)を返す必要があります。ブロックの戻り値もネイティブ対応していない型であった場合はエラーになります。

[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

インスタンスメソッド

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 にブロックも指定されていなかった場合に発生します。

例

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

要約

目次

特異メソッド

インスタンスメソッド