Ruby 4.1 リファレンスマニュアル

module JSON

[edit]

要約

JSON (JavaScript Object Notation) を扱うためのモジュールです。

目次

特異メソッド
モジュール関数
定数

特異メソッド

self[object, options] -> objectRuby 1.9.3 から[permalink][rdoc][edit]

文字列のように扱えるデータを受け取った場合は Ruby のオブジェクトに変換して返します。そうでない場合は JSON に変換して返します。

[PARAM] object:
任意のオブジェクト指定可能です。
[PARAM] options:
JSON?.parse, JSON?.generate の説明を参照してください。
例 
require "json"
string=<<JSON
{ "a":1, "b":2, "c":3 }
JSON
hash = { a: 1, b: 2, c: 3 }

p JSON[string].class                 # => Hash
p JSON[string]                       # => {"a" => 1, "b" => 2, "c" => 3}
p JSON[string, symbolize_names: true]  # => {a: 1, b: 2, c: 3}
p JSON[hash].class                   # => String
p JSON[hash]                         # => "{\"a\":1,\"b\":2,\"c\":3}"

[SEE_ALSO] JSON?.parse, JSON?.generate

generator -> JSON::Ext::GeneratorRuby 1.9.3 から[permalink][rdoc][edit]

JSON ライブラリがジェネレータとして使用するモジュールを返します。

parser -> JSON::Ext::ParserRuby 1.9.3 から[permalink][rdoc][edit]

JSON ライブラリがパーサとして使用するクラスを返します。

例 
require "json"

p JSON.parser # => JSON::Ext::Parser
state -> JSON::Ext::Generator::StateRuby 1.9.3 から[permalink][rdoc][edit]

JSON ライブラリがジェネレータの状態を表すクラスとして使用するクラスを返します。

例 
require "json"

p JSON.state # => JSON::Ext::Generator::State

モジュール関数

dump(object, io = nil, limit = nil, options = nil) -> String | IORuby 1.9.3 から[permalink][rdoc][edit]

与えられたオブジェクトを JSON 形式の文字列に変換してダンプします。

与えられたオブジェクトを引数として JSON?.generate を呼び出します。

[PARAM] object:
ダンプするオブジェクトを指定します。
[PARAM] io:
IO のように write メソッドを実装しているオブジェクトを指定します。
[PARAM] limit:
指定した場合、limit 段以上深くリンクしたオブジェクトをダンプできません。 limit は非推奨です。代わりに options の :max_nesting を指定してください。
[PARAM] options:
JSON?.generate と同じオプションをハッシュで指定します。キーワード引数の形でも指定できます。 rfc8785: true を指定した場合は、allow_nan を偽として扱います。
[EXCEPTION] JSON::NestingError:
オブジェクトのネストの深さが limit または :max_nesting を越えた場合に発生します。
例 
require "json"

p JSON.dump({ name: "tanaka", age: 19 }) # => "{\"name\":\"tanaka\",\"age\":19}"
例 
require "json"

File.open("test.txt", "w") do |f|
  p JSON.dump([[[[[[[[[[]]]]]]]]]], f, 10) # => #<File:test.txt>
  JSON.dump([[[[[[[[[[[]]]]]]]]]]], f, 10) # ~> nesting of 11 is too deep. Did you try to serialize objects with circular references? (JSON::NestingError)
end

[SEE_ALSO] Marshal, Marshal?.dump

generate(object, state = nil) -> StringRuby 1.9.3 から[permalink][rdoc][edit]

与えられたオブジェクトを一行の JSON 形式の文字列に変換して返します。

デフォルトでは、サイズが最小となる JSON 形式の文字列を生成します。また、循環参照のチェックを行います。JSON::NaN, JSON::Infinity, JSON::MinusInfinity を生成することもありません。

[PARAM] object:
JSON 形式の文字列に変換するオブジェクトを指定します。
[PARAM] state:
JSON::State または、to_hash や to_h メソッドでハッシュに変換可能なオブジェクトを指定できます。ハッシュを使用する場合指定可能なオプションは以下の通りです。
:indent

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

:space

a string that is put after, a : or , delimiter (default: '')

:space_before

a string that is put before a : pair delimiter (default: '')

:object_nl

a string that is put at the end of a JSON object (default: '')

:array_nl

a string that is put at the end of a JSON array (default: '')

:check_circular

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

:allow_nan

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

:max_nesting

入れ子になっているデータの最大の深さを指定します。偽を指定すると深さのチェックを行いません。デフォルトは 100 です。

:ascii_only

真を指定すると、ASCII 以外の文字を \uXXXX の形式にエスケープします。デフォルトは偽です。

:script_safe

真を指定すると、/ を \/ に、U+2028・U+2029 を \u2028・\u2029 にエスケープし、 JavaScript に埋め込んでも安全な JSON 形式の文字列を生成します。デフォルトは偽です。

:strict

真を指定すると、nil・true・false・Integer・Float・String・Array・Hash 以外のオブジェクトを to_json や to_s で変換せず、JSON::GeneratorError を発生させます。 Symbol は文字列として変換します。デフォルトは偽です。

:allow_duplicate_key

真を指定すると、キーを文字列に変換した結果が重複するハッシュ({foo: 1, "foo" => 2} など)をそのまま出力します。デフォルトは偽で、この場合は JSON::GeneratorError が発生します。

:sort_keys

真を指定すると、オブジェクト(ハッシュ)のキーを昇順に並べ替えます。 Proc を指定すると、その Proc で並べ替えます。詳しくは JSON::State#sort_keys= を参照してください。デフォルトは偽です。

:rfc8785

真を指定すると、[RFC8785] の JSON Canonicalization Scheme に従って正規化した JSON 形式の文字列を生成します。詳しくは JSON::State#rfc8785= を参照してください。デフォルトは偽です。

[EXCEPTION] JSON::GeneratorError:
JSON::NaN, JSON::Infinity,JSON::MinusInfinity を生成しようとした場合に発生します。
[EXCEPTION] JSON::CircularDatastructure:
与えられたオブジェクトが循環参照を持つ場合に発生します。
[EXCEPTION] JSON::GeneratorError:
:allow_duplicate_key が偽の場合(デフォルト)に、キーを文字列に変換した結果が重複するハッシュを変換しようとすると発生します。
[EXCEPTION] JSON::GeneratorError:
ASCII 以外のバイトを含む BINARY(ASCII-8BIT)エンコーディングの文字列を変換しようとすると発生します。
例 
require "json"

p JSON.generate([1, 2, { name: "tanaka", age: 19 }])
# => "[1,2,{\"name\":\"tanaka\",\"age\":19}]"
json_state = JSON::State.new(space: " ")
p JSON.generate([1, 2, { name: "tanaka", age: 19 }], json_state)
# => "[1,2,{\"name\": \"tanaka\",\"age\": 19}]"
例 キーの重複と BINARY 文字列 
require "json"

JSON.generate({foo: 1, "foo" => 2})                            # ~> detected duplicate key "foo" in {foo: 1, "foo" => 2} (JSON::GeneratorError)
JSON.generate({foo: 1, "foo" => 2}, allow_duplicate_key: true) # => "{\"foo\":1,\"foo\":2}"
JSON.generate(["é".b])                                         # ~> "\xC3" from ASCII-8BIT to UTF-8 (JSON::GeneratorError)

[SEE_ALSO] JSON::State, JSON?.pretty_generate

load(source, proc = nil, allow_blank: true, **options) -> objectRuby 1.9.3 から[permalink][rdoc][edit]

与えられた JSON 形式の文字列を Ruby オブジェクトとしてロードして返します。

JSON?.parse との違いは、load は信頼できる入力源を読み込むための簡易メソッドである点です。 source には JSON 形式の文字列だけでなく、to_str, to_io, read のいずれかに応答するオブジェクト (File などの IO や、パスを表すオブジェクトなど) も指定でき、その内容を読み込んだ上で内部的に JSON?.parse を呼び出します。

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

オプションはキーワード引数で指定します。 proc の位置にハッシュを渡してもオプションとしては扱われず、Hash#to_proc で変換した手続きとして各値に適用されます。 

require 'json'
  
str=<<JSON
[1,2,3]
JSON
  
p JSON.load(str) # => [1,2,3]
p JSON.load(str, proc{|v| p v }) # => [1,2,3]
# 以下が表示される
# 1
# 2
# 3
# [1,2,3]
  
str=<<JSON
{ "a":1, "b":2, "c":3 }
JSON
  
p JSON.load(str) # => {"a" => 1, "b" => 2, "c" => 3}
p JSON.load(str, proc{|v| p v }) # => {"a" => 1, "b" => 2, "c" => 3}
# 以下が表示される
# "a"
# 1
# "b"
# 2
# "c"
# 3
# {"a" => 1, "b" => 2, "c" => 3}
[PARAM] source:
JSON 形式の文字列を指定します。他には、to_str, to_io, read メソッドを持つオブジェクトも指定可能です。
[PARAM] proc:
Proc オブジェクトを指定します。
[PARAM] allow_blank:
真を指定すると、source が nil または空文字列の場合に nil を返します。偽を指定すると、source が nil の場合は TypeError が、空文字列の場合は JSON::ParserError が発生します。デフォルトは真です。
[PARAM] options:
その他のオプションをキーワード引数で指定します。指定可能なオプションは以下の通りです。
:max_nesting

入れ子になっているデータの最大の深さを指定します。偽を指定すると深さのチェックを行いません。デフォルトは 100 です。

:allow_nan

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

:symbolize_names

真を指定するとハッシュのキーを文字列ではなくシンボルにします。デフォルトは偽です。

[EXCEPTION] ArgumentError:
オプションのハッシュを位置引数で渡した場合や、未知のキーワードを指定した場合に発生します。
load_file(filespec, **options) -> objectRuby 3.0 から[permalink][rdoc][edit]

filespec で指定した JSON 形式のファイルを Ruby オブジェクトとしてロードして返します。

オプションはキーワード引数で指定します。

[PARAM] filespec:
ファイル名を指定します。
[PARAM] options:
オプションをキーワード引数で指定します。指定可能なオプションは JSON?.parse と同様です。
[EXCEPTION] ArgumentError:
オプションのハッシュを位置引数で渡した場合や、未知のキーワードを指定した場合に発生します。

[SEE_ALSO] JSON?.parse

load_file!(filespec, **options) -> objectRuby 3.0 から[permalink][rdoc][edit]

filespec で指定した JSON 形式のファイルを Ruby オブジェクトとしてロードして返します。

オプションはキーワード引数で指定します。

[PARAM] filespec:
ファイル名を指定します。
[PARAM] options:
オプションをキーワード引数で指定します。指定可能なオプションは JSON?.parse! と同様です。
[EXCEPTION] ArgumentError:
オプションのハッシュを位置引数で渡した場合や、未知のキーワードを指定した場合に発生します。

[SEE_ALSO] JSON?.parse!

parse(source, on_load: nil, object_class: nil, array_class: nil, **options) -> objectRuby 1.9.3 から[permalink][rdoc][edit]

与えられた JSON 形式の文字列を Ruby オブジェクトに変換して返します。

オプションはキーワード引数で指定します。

[PARAM] source:
JSON 形式の文字列を指定します。
[PARAM] on_load:
パースで生成した値ごとに呼び出す手続きオブジェクトを指定します。下記の :on_load を参照してください。
[PARAM] object_class:
JSON のオブジェクトを変換するクラスを指定します。下記の :object_class を参照してください。
[PARAM] array_class:
JSON の配列を変換するクラスを指定します。下記の :array_class を参照してください。
[PARAM] options:
その他のオプションをキーワード引数で指定します。指定可能なオプションは以下の通りです。
:max_nesting

入れ子になっているデータの最大の深さを指定します。偽を指定すると深さのチェックを行いません。デフォルトは 100 です。

:allow_nan

真を指定すると [RFC4627] を無視してパース時に JSON::NaN, JSON::Infinity, JSON::MinusInfinity を許可するようになります。デフォルトは偽です。

:object_class

JSON のオブジェクトを変換するクラスを指定します。デフォルトは Hash です。

:array_class

JSON の配列を変換するクラスを指定します。デフォルトは Array です。

:on_load

パースで生成したすべての値(文字列・数値・true・false・nil・配列・ハッシュ。オブジェクトのキーの文字列も含みます)ごとに呼び出す手続きオブジェクトを指定します。手続きの返り値が、その値の代わりに使われます。デフォルトは nil です。

:symbolize_names

真を指定するとハッシュのキーを文字列ではなくシンボルにします。デフォルトは偽です。

:freeze

真を指定すると、パースした結果のすべてのオブジェクト(文字列・配列・ハッシュ)を凍結して返します。同じ内容の文字列は同一のオブジェクトになります。デフォルトは偽です。

:decimal_class

JSON の小数を変換するクラスを指定します。デフォルトは nil で、Float に変換します。

:allow_trailing_comma

真を指定すると、配列やオブジェクトの末尾の余分なカンマを許可します。デフォルトは偽です。

:allow_control_characters

真を指定すると、文字列中のエスケープされていない ASCII 制御文字(改行など)を許可します。デフォルトは偽です。

:allow_duplicate_key

真を指定すると、オブジェクト内でキーが重複している場合に後の値を採用します。デフォルトは偽で、この場合はキーが重複していると JSON::ParserError が発生します。

:allow_comments

真を指定すると、JavaScript 形式のコメント(/* ... */ と // ...)を許可します。デフォルトは偽です。 4.0 までは常に許可していました。

:allow_invalid_escape

真を指定すると、文字列中の不正なエスケープ(\q など)をエラーにせず、バックスラッシュを取り除いた文字として扱います。デフォルトは偽です。

例 
require "json"

JSON.parse('[1,2,{"name":"tanaka","age":19}]')
# => [1, 2, {"name" => "tanaka", "age" => 19}]

JSON.parse('[1,2,{"name":"tanaka","age":19}]', symbolize_names: true)
# => [1, 2, {name: "tanaka", age: 19}]
例 パースのオプション 
require "json"
require "bigdecimal"

JSON.parse('[1.5]', decimal_class: BigDecimal) # => [0.15e1]

a = JSON.parse('["x","x"]', freeze: true)
a.frozen?         # => true
a[0].frozen?      # => true
a[0].equal?(a[1]) # => true

JSON.parse('[1, 2,]', allow_trailing_comma: true)   # => [1, 2]
JSON.parse('{"a": 1,}', allow_trailing_comma: true) # => {"a" => 1}

JSON.parse("\"a\nb\"", allow_control_characters: true) # => "a\nb"
JSON.parse('{"a":1,"a":2}', allow_duplicate_key: true)  # => {"a" => 2}

JSON.parse('{"a":1,"a":2}')                     # ~> duplicate key "a" at line 1 column 1 (JSON::ParserError)
JSON.parse('/* c */ [1]', allow_comments: true) # => [1]
JSON.parse('"\\q"', allow_invalid_escape: true) # => "q"
[EXCEPTION] ArgumentError:
オプションのハッシュを位置引数で渡した場合や、未知のキーワードを指定した場合に発生します。
例 on_load を指定する 
require "json"

JSON.parse('[1,2]', on_load: ->(o) { o.is_a?(Integer) ? o * 10 : o }) # => [10, 20]
例 オプションをハッシュで渡した場合と未知のキーワードを指定した場合 
require "json"

JSON.parse('{"a":1}', {symbolize_names: true}) # ~> wrong number of arguments (given 2, expected 1) (ArgumentError)
JSON.parse('{"a":1}', foo: 1)                  # ~> unknown keyword: foo (ArgumentError)

[SEE_ALSO] JSON::Parser#parse

parse!(source, **options) -> objectRuby 1.9.3 から[permalink][rdoc][edit]

与えられた JSON 形式の文字列を Ruby オブジェクトに変換して返します。

JSON?.parse よりも危険なデフォルト値が指定されているので信頼できる文字列のみを入力として使用するようにしてください。

オプションはキーワード引数で指定します。

[PARAM] source:
JSON 形式の文字列を指定します。
[PARAM] options:
オプションをキーワード引数で指定します。指定可能なオプションは以下の通りです。
:max_nesting

入れ子になっているデータの最大の深さを指定します。数値を指定すると深さのチェックを行います。偽を指定すると深さのチェックを行いません。デフォルトは偽です。

:allow_nan

真を指定すると [RFC4627] を無視してパース時に JSON::NaN, JSON::Infinity, JSON::MinusInfinity を許可するようになります。デフォルトは真です。

このほかに JSON?.parse と同じオプションを指定できます。

例 
require "json"

json_text = "[1,2,{\"name\":\"tanaka\",\"age\":19}, NaN]"
JSON.parse!(json_text)
# => [1, 2, {"name" => "tanaka", "age" => 19}, NaN]

JSON.parse!(json_text, symbolize_names: true)
# => [1, 2, {name: "tanaka", age: 19}, NaN]

JSON.parse(json_text) # => unexpected token at 'NaN]' (JSON::ParserError)
[EXCEPTION] ArgumentError:
オプションのハッシュを位置引数で渡した場合や、未知のキーワードを指定した場合に発生します。

[SEE_ALSO] JSON::Parser#parse

pretty_generate(object, options = nil) -> StringRuby 1.9.3 から[permalink][rdoc][edit]

Ruby のオブジェクトを JSON 形式の文字列に変換して返します。

このメソッドは JSON?.generate よりも人間に読みやすい文字列を返します。

[PARAM] object:
JSON 形式の文字列に変換するオブジェクトを指定します。
[PARAM] options:
JSON::State または、to_hash や to_h メソッドでハッシュに変換可能なオブジェクトを指定できます。ハッシュを使用する場合指定可能なオプションは JSON?.generate を参照してください。
[EXCEPTION] ArgumentError:
:rfc8785 オプションに真を指定した場合に発生します。
例 
require "json"

hash = { "name": "tanaka", "age": 19 }
puts JSON.generate(hash)
# => {"name":"tanaka","age":19}

puts JSON.pretty_generate(hash)
# => {
#      "name": "tanaka",
#      "age": 19
#    }

puts JSON.pretty_generate(hash, space: "\t")
# => {
#      "name":  "tanaka",
#      "age": 19
#    }

[SEE_ALSO] JSON?.generate

unsafe_load(source, proc = nil, **options) -> objectRuby 3.4 から[permalink][rdoc][edit]

与えられた JSON 形式の文字列を Ruby オブジェクトとしてロードして返します。

JSON?.load と同様のメソッドですが、こちらは信頼できる入力を読み込むためのメソッドであることを名前で明示しています。

source には JSON 形式の文字列だけでなく、to_str, to_io, read のいずれかに応答するオブジェクト (File などの IO や、パスを表すオブジェクトなど) も指定でき、その内容を読み込んだ上で内部的に JSON?.parse を呼び出します。

proc として手続きオブジェクトが与えられた場合は、読み込んだ結果を引数にその手続きを呼び出し、その返り値を最終的な結果とします。

オプションはキーワード引数で指定します。 proc の位置にハッシュを渡してもオプションとしては扱われず、Hash#to_proc で変換した手続きとして各値に適用されます。

[PARAM] source:
JSON 形式の文字列を指定します。他には、to_str, to_io, read メソッドを持つオブジェクトも指定可能です。
[PARAM] proc:
Proc オブジェクトを指定します。
[PARAM] options:
オプションをキーワード引数で指定します。指定可能なオプションは JSON?.parse と同様です。
[EXCEPTION] ArgumentError:
オプションのハッシュを位置引数で渡した場合や、未知のキーワードを指定した場合に発生します。
例 
require "json"

p JSON.unsafe_load('[1, [2, [3]]]') # => [1, [2, [3]]]

[SEE_ALSO] JSON?.load, JSON?.parse

定数

Infinity -> FloatRuby 1.9.3 から[permalink][rdoc][edit]

正の無限大を表します。

[SEE_ALSO] Float

JSON_LOADED -> boolRuby 1.9.3 から[permalink][rdoc][edit]

JSON ライブラリがロード済みである場合に真を返します。そうでない場合は偽を返します。

MinusInfinity -> FloatRuby 1.9.3 から[permalink][rdoc][edit]

負の無限大を表します。

[SEE_ALSO] Float

NaN -> FloatRuby 1.9.3 から[permalink][rdoc][edit]

NaN (Not a Number) を表します。

[SEE_ALSO] Float

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

このライブラリのバージョンを表す文字列です。