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

aliases: JSON::Ext::Generator::State

要約

Ruby オブジェクトから JSON 形式の文字列を生成する間、 JSON 形式の文字列を生成するための設定を保持しておくために使用するクラスです。

実体は JSON::Ext::Generator::State であり、JSON::State はそれを指す別名(定数)です。そのため、生成したインスタンスの class メソッドや inspect の結果には JSON::Ext::Generator::State と表示されます。

特異メソッド

default_sort_keys_proc=(prc)Ruby 4.1 から[permalink][rdoc][edit]

sort_keys= に真を指定したときに使用する、デフォルトの並べ替え用 Proc を設定します。

[PARAM] prc:: ハッシュを引数に取り、並べ替えたハッシュを返す Proc を指定します。
[EXCEPTION] TypeError:: prc が Proc でない場合に発生します。

例

require "json"

JSON::State.default_sort_keys_proc = ->(hash) { hash.sort.to_h }
state = JSON::State.new(sort_keys: true)
p JSON.generate({b: 1, a: 2}, state) # => "{\"a\":2,\"b\":1}"

[SEE_ALSO] JSON::State#sort_keys=

from_state(options) -> JSON::StateRuby 1.9.3 から[permalink][rdoc][edit]

与えられた options によって生成した JSON::State のインスタンスを返します。

[PARAM] options:: JSON::State のインスタンスか、ハッシュを指定します。
[RETURN]: options がハッシュである場合は、それによって初期化した JSON::State を返します。options が JSON::State のインスタンスである場合は単に options を返します。いずれでも無い場合は、何も設定されていない JSON::State のインスタンスを返します。

例 Hash を指定

require "json"

json_state = JSON::State.from_state(indent: "\t")
json_state.class  # => JSON::Ext::Generator::State
json_state.indent # => "\t"

例 JSON::State を指定

require "json"

json_state = JSON::State.from_state(indent: "\t")
# JSON を出力する何らかの処理を実行する
same = JSON::State.from_state(json_state)
same.equal?(json_state) # => true
same.class               # => JSON::Ext::Generator::State
same.indent              # => "\t"

generate(obj, options, io) -> String | IORuby 3.4 から[permalink][rdoc][edit]

obj と options から一時的な JSON::State を作成し、それを使って obj から JSON 形式の文字列を生成します。

[PARAM] obj:: JSON 形式の文字列に変換するオブジェクトを指定します。
[PARAM] options:: JSON::State.new に指定するのと同様のオプションをハッシュで指定します。 nil を指定した場合、オプション無しで初期化した JSON::State を使用します。
[PARAM] io:: 生成した文字列の書き込み先を、write メソッドを持つオブジェクトで指定します。 nil を指定した場合は、生成した文字列をそのまま返します。
[RETURN]: io を指定しなかった場合は生成した JSON 形式の文字列を返します。 io を指定した場合は、そこに書き込んだ上で io を返します。

例

require "json"

p JSON::State.generate({b: 1, a: 2}, nil, nil) # => "{\"b\":1,\"a\":2}"
p JSON::State.generate({b: 1, a: 2}, {indent: "  ", object_nl: "\n"}, nil)
# => "{\n  \"b\":1,\n  \"a\":2\n}"

[SEE_ALSO] JSON::State.new, JSON::State#generate

new(options = {}) -> JSON::StateRuby 1.9.3 から[permalink][rdoc][edit]

自身を初期化します。

[PARAM] options:: ハッシュを指定します。指定可能なオプションは以下の通りです。

:indent

インデントに使用する文字列を指定します。デフォルトは空文字列です。

:space

JSON 形式の文字列のトークン間に挿入する文字列を指定します。デフォルトは空文字列です。

:space_before

JSON 形式の文字列中で JavaScript のオブジェクトを表す部分にある ':' の前に挿入する文字列をセットします。デフォルトは空文字列です。

:object_nl

JSON 形式の文字列中に現れる JavaScript のオブジェクトの行末に挿入する文字列を指定します。デフォルトは空文字列です。

:array_nl

JSON 形式の文字列中に現れる JavaScript の配列の行末に挿入する文字列を指定します。デフォルトは空文字列です。

:check_circular

真を指定した場合、生成するオブジェクトの循環をチェックします。この動作がデフォルトです。

:allow_nan

真を指定した場合、JSON::NaN, JSON::Infinity, JSON::MinusInfinity を生成することを許すようになります。偽を指定した場合、これらの値を生成しようとすると例外が発生します。デフォルトは偽です。

:ascii_only

真を指定した場合、ASCII 文字列のみを用いて JSON 形式の文字列を生成します。デフォルトは偽です。

:buffer_initial_length

JSON 形式の文字列を生成する際に使用する内部バッファの初期の長さを指定します。デフォルトは 1024 です。

例 Hash を指定

require "json"

json_state = JSON::State.new(indent: "\t")
json_state.class  # => JSON::Ext::Generator::State
json_state.indent # => "\t"

例 JSON::State を指定

require "json"

json_state = JSON::State.new(indent: "\t")
copy = JSON::State.new(json_state)
copy.class  # => JSON::Ext::Generator::State
copy.indent # => "\t"

インスタンスメソッド

self[name] -> objectRuby 2.1.0 から[permalink][rdoc][edit]

name という名前のメソッドを呼び出し、その戻り値を返します。

このメソッドは非推奨です(json 2.16.0 から)。json 3.0.0 で削除される予定で、代わりの手段として JSON::Coder が挙げられています。

self[name] = valueRuby 2.1.0 から[permalink][rdoc][edit]

属性 name に value をセットします。

このメソッドは非推奨です(json 2.16.0 から)。json 3.0.0 で削除される予定で、代わりの手段として JSON::Coder が挙げられています。

allow_nan? -> boolRuby 1.9.3 から[permalink][rdoc][edit]

allow_nan=(enable)Ruby 3.4 から

NaN, Infinity, -Infinity を生成できる場合、allow_nan? は真を返します。そうでない場合は偽を返します。

allow_nan= は、NaN, Infinity, -Infinity を生成できるかどうかを設定します。

[PARAM] enable:: 真を指定すると NaN, Infinity, -Infinity を生成できるようにします。偽を指定すると生成できないようにします。

例

require "json"

json_state = JSON::State.new({})
json_state.allow_nan? # => false
json_state = JSON::State.new(allow_nan: true)
json_state.allow_nan? # => true

例 allow_nan= を使う

require "json"

json_state = JSON::State.new(allow_nan: true)
p json_state.allow_nan? # => true
json_state.allow_nan = false
p json_state.allow_nan? # => false

[SEE_ALSO] [RFC4627]

array_nl -> StringRuby 1.9.3 から[permalink][rdoc][edit]

JSON の配列の後に出力する文字列を返します。

例

require "json"

json_state = JSON::State.new({})
json_state.array_nl # => ""
json_state = JSON::State.new(array_nl: "\n")
json_state.array_nl # => "\n"

array_nl=(str)Ruby 1.9.3 から[permalink][rdoc][edit]

JSON の配列の後に出力する文字列をセットします。

例

require "json"

json_state = JSON::State.new({})
json_state.array_nl        # => ""
json_state.array_nl = "\n"
json_state.array_nl        # => "\n"

as_json -> Proc | nilRuby 4.0 から[permalink][rdoc][edit]

as_json=(prc)

strict? が真のとき、そのままでは JSON 形式の文字列に変換できないオブジェクトを変換するために使用する Proc を取得・設定します。

設定した Proc は、変換できないオブジェクトが現れるたびに、そのオブジェクトと、それがハッシュのキーとして使われているかどうかを表す真偽値の 2 引数で呼び出されます。 Proc の返り値が、代わりに JSON 形式の文字列への変換に使われます。

[PARAM] prc:: 変換できないオブジェクトを変換するための Proc を指定します。

例

require "json"

state = JSON::State.new(strict: true, as_json: ->(obj, is_key) { obj.to_s })
p state.as_json.class             # => Proc
p JSON.generate([1, 2..3], state) # => "[1,\"2..3\"]"

[SEE_ALSO] JSON::State#strict

ascii_only? -> boolRuby 2.1.0 から[permalink][rdoc][edit]

ascii_only=(enable)Ruby 3.4 から

ASCII 文字列のみを用いて JSON 形式の文字列を生成する場合に ascii_only? は真を返します。そうでない場合に偽を返します。

ascii_only= は、ASCII 文字列のみを用いて JSON 形式の文字列を生成するかどうかを設定します。

[PARAM] enable:: 真を指定すると ASCII 文字列のみを生成するようになります。偽を指定すると、ASCII 以外の文字列もそのまま生成するようになります。

例

require "json"

json_state = JSON::State.new(ascii_only: true)
p JSON.generate(["日本語"], json_state) # => "[\"\\u65e5\\u672c\\u8a9e\"]"
json_state.ascii_only = false
p JSON.generate(["日本語"], json_state) # => "[\"日本語\"]"

buffer_initial_length -> IntegerRuby 2.1.0 から[permalink][rdoc][edit]

現在のバッファの初期の長さを整数で返します。

buffer_initial_length=(length)Ruby 2.1.0 から[permalink][rdoc][edit]

バッファの初期の長さを length にセットします。length が 0 より大きい場合のみ値がセットされ、それ以外の場合は値は変更されません。

check_circular? -> boolRuby 1.9.3 から[permalink][rdoc][edit]

循環参照のチェックを行う場合は、真を返します。そうでない場合は偽を返します。

例ネストをチェックするケース

require "json"

a = [[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[0]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
s = JSON.state.new
begin
  JSON.generate(a, s)
rescue JSON::NestingError => e
  [e, s.max_nesting, s.check_circular?] # => [#<JSON::NestingError: nesting of 100 is too deep>, 100, true]
end

例ネストをチェックしないケース

require "json"

a = [[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[0]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]
s2 = JSON.state.new(max_nesting: 0)
json = JSON.generate(a, s2)
[json, s2.max_nesting, s2.check_circular?] # => ["[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[0]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]", 0, false]

configure(options = {}) -> selfRuby 1.9.3 から[permalink][rdoc][edit]

merge(options = {}) -> selfRuby 2.1.0 から

与えられたハッシュで自身を設定します。

オプションで使用するハッシュのキーについては JSON::State.new を参照してください。

[PARAM] options:: このオブジェクトの設定をするためのハッシュを指定します。

例

require "json"

json_state = JSON::State.new(indent: "\t")
json_state.indent # => "\t"
p JSON.generate({key1: "value1", key2: "value2"}, json_state)
# => "{\t\"key1\":\"value1\",\t\"key2\":\"value2\"}"

json_state.configure(indent: "  ")
json_state.indent # => "  "
p JSON.generate({key1: "value1", key2: "value2"}, json_state)
# => "{  \"key1\":\"value1\",  \"key2\":\"value2\"}"

[SEE_ALSO] JSON::State.new

depth -> IntegerRuby 2.1.0 から[permalink][rdoc][edit]

現在のデータ構造のネストの深さを整数で返します。

depth=(depth)Ruby 2.1.0 から[permalink][rdoc][edit]

データ構造のネストの深さの現在値を整数 depth にセットします。インデントを伴う生成では、この深さを起点として出力されます。ネストの深さの上限(JSON::State#max_nesting)とは別の値です。

generate(obj) -> StringRuby 2.1.0 から[permalink][rdoc][edit]

オブジェクト obj から有効な JSON 形式の文字列を生成し、その結果を返します。有効な JSON 形式の文字列を生成できない場合は、JSON::GeneratorError 例外が発生します。

indent -> StringRuby 1.9.3 から[permalink][rdoc][edit]

インデントに使用する文字列を返します。

例

require "json"

json_state = JSON::State.new(indent: "\t")
json_state.indent # => "\t"
p JSON.generate({key1: "value1", key2: "value2"}, json_state)
# => "{\t\"key1\":\"value1\",\t\"key2\":\"value2\"}"

indent=(string)Ruby 1.9.3 から[permalink][rdoc][edit]

インデントに使用する文字列をセットします。

[PARAM] string:: インデントに使用する文字列を指定します。

例

require "json"

json_state = JSON::State.new(indent: "\t")
json_state.indent # => "\t"
p JSON.generate({key1: "value1", key2: "value2"}, json_state)
# => "{\t\"key1\":\"value1\",\t\"key2\":\"value2\"}"
json_state.indent = "  "
p JSON.generate({key1: "value1", key2: "value2"}, json_state)
# => "{  \"key1\":\"value1\",  \"key2\":\"value2\"}"

max_nesting -> IntegerRuby 1.9.3 から[permalink][rdoc][edit]

生成される JSON 形式の文字列のネストの深さの最大値を返します。

この値がゼロである場合は、ネストの深さのチェックを行いません。

例ネストの深さチェックを行う

require "json"

json_state = JSON::State.new(max_nesting: 2)
json_state.max_nesting            # => 2
JSON.generate([[]], json_state)
JSON.generate([[[]]], json_state) # ~> JSON::NestingError

例ネストの深さチェックを行わない

require "json"

json_state = JSON::State.new(max_nesting: 0)
json_state.max_nesting            # => 0
JSON.generate([[[[[[[[[[]]]]]]]]]], json_state)

max_nesting=(depth)Ruby 1.9.3 から[permalink][rdoc][edit]

生成される JSON 形式の文字列のネストの深さの最大値をセットします。

この値にゼロをセットすると、ネストの深さのチェックを行いません。

例

require "json"

json_state = JSON::State.new(max_nesting: 2)
json_state.max_nesting            # => 2
JSON.generate([[]], json_state)
json_state.max_nesting = 3
json_state.max_nesting            # => 3
JSON.generate([[[[]]]], json_state) # ~> JSON::NestingError

object_nl -> StringRuby 1.9.3 から[permalink][rdoc][edit]

JSON 形式の文字列中に現れる JavaScript のオブジェクトの行末に挿入する文字列を返します。

例

require "json"

json_state = JSON::State.new(object_nl: "")
json_state.object_nl             # => ""
puts JSON.generate([1, 2, { name: "tanaka", age: 19 }], json_state)
# => [1,2,{"name":"tanaka","age":19}]

json_state = JSON::State.new(object_nl: "\n")
json_state.object_nl             # => "\n"
puts JSON.generate([1, 2, { name: "tanaka", age: 19 }], json_state)

# => [1,2,{
#    "name":"tanaka",
#    "age":19
#    }]

object_nl=(string)Ruby 1.9.3 から[permalink][rdoc][edit]

JSON 形式の文字列中に現れる JavaScript のオブジェクトの行末に挿入する文字列をセットします。

[PARAM] string:: JSON 形式の文字列中に現れる JavaScript のオブジェクトの行末に挿入する文字列を指定します。

例

require "json"

json_state = JSON::State.new(object_nl: "")
json_state.object_nl             # => ""
puts JSON.generate([1, 2, { name: "tanaka", age: 19 }], json_state)
# => [1,2,{"name":"tanaka","age":19}]

json_state.object_nl = "\n"
json_state.object_nl             # => "\n"
puts JSON.generate([1, 2, { name: "tanaka", age: 19 }], json_state)
 # => [1,2,{
#    "name":"tanaka",
#    "age":19
#    }]

script_safe -> boolRuby 3.3 から[permalink][rdoc][edit]

script_safe? -> bool

script_safe=(enable)

生成する JSON 形式の文字列中のスラッシュ(/)をエスケープするかどうかを取得・設定します。真を指定すると、スラッシュを \/ としてエスケープします。

Ruby 3.3 以降は、スラッシュに加えて U+2028, U+2029 もエスケープするようになりました。 escape_slash, escape_slash?, escape_slash= は、この設定が script_safe という名前になる前から使われている別名です。Ruby 4.1 で削除されます。

[PARAM] enable:: 真を指定するとエスケープを有効にします。偽を指定すると無効にします。

例

require "json"

state = JSON::State.new(script_safe: true)
p state.script_safe?            # => true
p JSON.generate(["a/b"], state) # => "[\"a\\/b\"]"

sort_keys -> bool | ProcRuby 4.1 から[permalink][rdoc][edit]

sort_keys=(value)

生成する JSON 形式の文字列で、オブジェクト(ハッシュ)のキーを並べ替えるかどうかを取得・設定します。

value に真を指定すると、キーを昇順に並べ替えます。Proc を指定すると、ハッシュ全体を引数としてその Proc を呼び出し、返り値のハッシュをそのままの順序で使用します。これにより任意の並べ替えができます。偽を指定すると並べ替えを行いません(デフォルト)。

[PARAM] value:: 真偽値または Proc を指定します。
[EXCEPTION] TypeError:: value が真偽値でも Proc でもない場合に発生します。

例

require "json"

state = JSON::State.new(sort_keys: true)
p JSON.generate({b: 1, a: 2}, state) # => "{\"a\":2,\"b\":1}"

state2 = JSON::State.new(sort_keys: ->(hash) { hash.sort_by { |k, v| -v }.to_h })
p JSON.generate({a: 1, b: 2}, state2) # => "{\"b\":2,\"a\":1}"

[SEE_ALSO] JSON::State.default_sort_keys_proc=

space -> StringRuby 1.9.3 から[permalink][rdoc][edit]

JSON 形式の文字列のトークン間に挿入する文字列を返します。

例

require "json"

json_state = JSON::State.new(space: "")
json_state.space             # => ""
puts JSON.generate([1, 2, { name: "tanaka", age: 19 }], json_state)
# => [1,2,{"name":"tanaka","age":19}]

json_state = JSON::State.new(space: "\t")
json_state.space             # => "\t"
puts JSON.generate([1, 2, { name: "tanaka", age: 19 }], json_state)
# => [1,2,{"name":  "tanaka","age": 19}]

space=(string)Ruby 1.9.3 から[permalink][rdoc][edit]

JSON 形式の文字列のトークン間に挿入する文字列をセットします。

[PARAM] string:: JSON 形式の文字列のトークン間に挿入する文字列を指定します。

例

require "json"

json_state = JSON::State.new(space: "")
json_state.space             # => ""
puts JSON.generate([1, 2, { name: "tanaka", age: 19 }], json_state)
# => [1,2,{"name":"tanaka","age":19}]

json_state.space = "\t"
json_state.space             # => "\t"
puts JSON.generate([1, 2, { name: "tanaka", age: 19 }], json_state)
# => [1,2,{"name":  "tanaka","age": 19}]

space_before -> StringRuby 1.9.3 から[permalink][rdoc][edit]

JSON 形式の文字列中で JavaScript のオブジェクトを表す部分にある ':' の前に挿入する文字列を返します。

例

require "json"

json_state = JSON::State.new(space_before: "")
json_state.space_before             # => ""
puts JSON.generate([1, 2, { name: "tanaka", age: 19 }], json_state)
# => [1,2,{"name":"tanaka","age":19}]

json_state = JSON::State.new(space_before: " ")
json_state.space_before             # => " "
puts JSON.generate([1, 2, { name: "tanaka", age: 19 }], json_state)
# => [1,2,{"name" :"tanaka","age" :19}]

space_before=(string)Ruby 1.9.3 から[permalink][rdoc][edit]

JSON 形式の文字列中で JavaScript のオブジェクトを表す部分にある ':' の前に挿入する文字列をセットします。

[PARAM] string:: JSON 形式の文字列中で JavaScript のオブジェクトを表す部分にある ':' の前に挿入する文字列をセットします。

例

require "json"

json_state = JSON::State.new(space_before: "")
json_state.space_before             # => ""
puts JSON.generate([1, 2, { name: "tanaka", age: 19 }], json_state)
# => [1,2,{"name":"tanaka","age":19}]

json_state.space_before = " "
json_state.space_before             # => " "
puts JSON.generate([1, 2, { name: "tanaka", age: 19 }], json_state)
# => [1,2,{"name" :"tanaka","age" :19}]

strict -> boolRuby 3.3 から[permalink][rdoc][edit]

strict? -> bool

strict=(enable)

JSON 形式で表現できない型のオブジェクトが現れたときの挙動を取得・設定します。

偽の場合(デフォルト)、JSON 形式で表現できない型のオブジェクトは文字列に変換されて出力されます。真の場合、そのようなオブジェクトが現れると JSON::GeneratorError が発生します。

[PARAM] enable:: 真を指定すると、JSON 形式で表現できない型のオブジェクトが現れたときに例外を発生させるようになります。
[EXCEPTION] JSON::GeneratorError:: strict? が真の状態で、JSON 形式で表現できない型のオブジェクトを変換しようとした場合に発生します。

例

require "json"

state = JSON::State.new(strict: true)
p state.strict?                            # => true
begin
  JSON.generate([Object.new], state)
rescue JSON::GeneratorError => e
  p e.message # => "Object not allowed in JSON"
end

[SEE_ALSO] JSON::State#as_json=

to_h -> HashRuby 1.9.3 から[permalink][rdoc][edit]

to_hash -> HashRuby 2.1.0 から

自身をハッシュに変換します。

例

require "json"
require "pp"

json_state = JSON::State.new
pp json_state.to_h

# => {:indent=>"",
#     :space=>"",
#     :space_before=>"",
#     :object_nl=>"",
#     :array_nl=>"",
#     :allow_nan=>false,
#     :ascii_only=>false,
#     :max_nesting=>100,
#     :depth=>0,
#     :buffer_initial_length=>1024}

要約

目次

特異メソッド

インスタンスメソッド