模块 JSON

JavaScript 对象表示法 (JSON)¶ ↑

JSON 是一种轻量级的数据交换格式。

JSON 值可以是以下之一

双引号文本："foo"。
数字：1、1.0、2.0e2。
布尔值：true、false。
空值：null。
数组：由方括号括起来的值的有序列表
```
["foo", 1, 1.0, 2.0e2, true, false, null]
```
对象：由花括号括起来的名称/值对的集合；每个名称都是双引号文本；值可以是任何 JSON 值
```
{"a": "foo", "b": 1, "c": 1.0, "d": 2.0e2, "e": true, "f": false, "g": null}
```

JSON 数组或对象可以包含嵌套的数组、对象和标量，深度不受限制

{"foo": {"bar": 1, "baz": 2}, "bat": [0, 1, 2]}
[{"foo": 0, "bar": 1}, ["baz", 2]]

使用模块 JSON¶ ↑

要在代码中使用模块 JSON，请从以下开始

require 'json'

此处的所有示例都假设已完成此操作。

解析 JSON¶ ↑

可以使用两种方法解析包含 JSON 数据的字符串

JSON.parse(source, opts)
JSON.parse!(source, opts)

其中

source 是一个 Ruby 对象。
opts 是一个 Hash 对象，包含控制允许输入和输出格式的选项。

两种方法的区别在于 JSON.parse! 省略了一些检查，对于某些 source 数据可能不安全；仅对来自受信任来源的数据使用它。对于不太受信任的来源，请使用更安全的方法 JSON.parse。

解析 JSON 数组¶ ↑

当 source 是 JSON 数组时，JSON.parse 默认情况下返回一个 Ruby 数组

json = '["foo", 1, 1.0, 2.0e2, true, false, null]'
ruby = JSON.parse(json)
ruby # => ["foo", 1, 1.0, 200.0, true, false, nil]
ruby.class # => Array

JSON 数组可以包含嵌套数组、对象和标量，深度不受限制。

json = '[{"foo": 0, "bar": 1}, ["baz", 2]]'
JSON.parse(json) # => [{"foo"=>0, "bar"=>1}, ["baz", 2]]

解析 JSON 对象¶ ↑

当源是 JSON 对象时，JSON.parse 默认返回一个 Ruby 哈希。

json = '{"a": "foo", "b": 1, "c": 1.0, "d": 2.0e2, "e": true, "f": false, "g": null}'
ruby = JSON.parse(json)
ruby # => {"a"=>"foo", "b"=>1, "c"=>1.0, "d"=>200.0, "e"=>true, "f"=>false, "g"=>nil}
ruby.class # => Hash

JSON 对象可以包含嵌套数组、对象和标量，深度不受限制。

json = '{"foo": {"bar": 1, "baz": 2}, "bat": [0, 1, 2]}'
JSON.parse(json) # => {"foo"=>{"bar"=>1, "baz"=>2}, "bat"=>[0, 1, 2]}

解析 JSON 标量¶ ↑

当源是 JSON 标量（不是数组或对象）时，JSON.parse 返回一个 Ruby 标量。

字符串

ruby = JSON.parse('"foo"')
ruby # => 'foo'
ruby.class # => String

整数

ruby = JSON.parse('1')
ruby # => 1
ruby.class # => Integer

浮点数

ruby = JSON.parse('1.0')
ruby # => 1.0
ruby.class # => Float
ruby = JSON.parse('2.0e2')
ruby # => 200
ruby.class # => Float

布尔值

ruby = JSON.parse('true')
ruby # => true
ruby.class # => TrueClass
ruby = JSON.parse('false')
ruby # => false
ruby.class # => FalseClass

空值

ruby = JSON.parse('null')
ruby # => nil
ruby.class # => NilClass

解析选项¶ ↑

输入选项¶ ↑

选项 max_nesting（整数）指定允许的最大嵌套深度；默认值为 100；指定 false 禁用深度检查。

默认情况下，false

source = '[0, [1, [2, [3]]]]'
ruby = JSON.parse(source)
ruby # => [0, [1, [2, [3]]]]

深度过深

# Raises JSON::NestingError (nesting of 2 is too deep):
JSON.parse(source, {max_nesting: 1})

无效值

# Raises TypeError (wrong argument type Symbol (expected Fixnum)):
JSON.parse(source, {max_nesting: :foo})

选项 allow_nan（布尔值）指定是否允许在 source 中使用 NaN、Infinity 和 MinusInfinity；默认值为 false。

默认情况下，false

# Raises JSON::ParserError (225: unexpected token at '[NaN]'):
JSON.parse('[NaN]')
# Raises JSON::ParserError (232: unexpected token at '[Infinity]'):
JSON.parse('[Infinity]')
# Raises JSON::ParserError (248: unexpected token at '[-Infinity]'):
JSON.parse('[-Infinity]')

允许

source = '[NaN, Infinity, -Infinity]'
ruby = JSON.parse(source, {allow_nan: true})
ruby # => [NaN, Infinity, -Infinity]

输出选项¶ ↑

选项 symbolize_names（布尔值）指定返回的哈希键是否应该为符号；默认值为 false（使用字符串）。

默认情况下，false

source = '{"a": "foo", "b": 1.0, "c": true, "d": false, "e": null}'
ruby = JSON.parse(source)
ruby # => {"a"=>"foo", "b"=>1.0, "c"=>true, "d"=>false, "e"=>nil}

使用符号

ruby = JSON.parse(source, {symbolize_names: true})
ruby # => {:a=>"foo", :b=>1.0, :c=>true, :d=>false, :e=>nil}

选项 object_class（类）指定用于每个 JSON 对象的 Ruby 类；默认值为 Hash。

默认情况下，Hash

source = '{"a": "foo", "b": 1.0, "c": true, "d": false, "e": null}'
ruby = JSON.parse(source)
ruby.class # => Hash

使用类 OpenStruct

ruby = JSON.parse(source, {object_class: OpenStruct})
ruby # => #<OpenStruct a="foo", b=1.0, c=true, d=false, e=nil>

选项 array_class（类）指定用于每个 JSON 数组的 Ruby 类；默认值为 Array。

默认情况下，Array

source = '["foo", 1.0, true, false, null]'
ruby = JSON.parse(source)
ruby.class # => Array

使用类 Set

ruby = JSON.parse(source, {array_class: Set})
ruby # => #<Set: {"foo", 1.0, true, false, nil}>

选项 create_additions（布尔值）指定是否在解析时使用 JSON 扩展。请参阅 JSON 扩展。

生成 JSON¶ ↑

要生成包含 JSON 数据的 Ruby 字符串，请使用方法 JSON.generate(source, opts)，其中

source 是一个 Ruby 对象。
opts 是一个 Hash 对象，包含控制允许输入和输出格式的选项。

从数组生成 JSON¶ ↑

当源是 Ruby 数组时，JSON.generate 返回一个包含 JSON 数组的字符串。

ruby = [0, 's', :foo]
json = JSON.generate(ruby)
json # => '[0,"s","foo"]'

Ruby 数组可以包含嵌套数组、哈希和标量，深度不受限制。

ruby = [0, [1, 2], {foo: 3, bar: 4}]
json = JSON.generate(ruby)
json # => '[0,[1,2],{"foo":3,"bar":4}]'

从哈希生成 JSON¶ ↑

当源是 Ruby 哈希时，JSON.generate 返回一个包含 JSON 对象的字符串。

ruby = {foo: 0, bar: 's', baz: :bat}
json = JSON.generate(ruby)
json # => '{"foo":0,"bar":"s","baz":"bat"}'

Ruby 的 Hash 数组可以包含嵌套数组、哈希和标量，深度不受限制。

ruby = {foo: [0, 1], bar: {baz: 2, bat: 3}, bam: :bad}
json = JSON.generate(ruby)
json # => '{"foo":[0,1],"bar":{"baz":2,"bat":3},"bam":"bad"}'

从其他对象生成 JSON¶ ↑

当源数据既不是数组也不是哈希时，生成的 JSON 数据取决于源数据的类。

当源数据是 Ruby 整数或浮点数时，JSON.generate 返回一个包含 JSON 数字的字符串。

JSON.generate(42) # => '42'
JSON.generate(0.42) # => '0.42'

当源数据是 Ruby 字符串时，JSON.generate 返回一个包含 JSON 字符串（带双引号）的字符串。

JSON.generate('A string') # => '"A string"'

当源数据是 true、false 或 nil 时，JSON.generate 返回一个包含相应 JSON 标记的字符串。

JSON.generate(true) # => 'true'
JSON.generate(false) # => 'false'
JSON.generate(nil) # => 'null'

当源数据不是以上任何一种时，JSON.generate 返回一个包含源数据 JSON 字符串表示的字符串。

JSON.generate(:foo) # => '"foo"'
JSON.generate(Complex(0, 0)) # => '"0+0i"'
JSON.generate(Dir.new('.')) # => '"#<Dir>"'

生成选项¶ ↑

输入选项¶ ↑

选项 allow_nan（布尔值）指定是否允许生成 NaN、Infinity 和 -Infinity；默认值为 false。

默认情况下，false

# Raises JSON::GeneratorError (920: NaN not allowed in JSON):
JSON.generate(JSON::NaN)
# Raises JSON::GeneratorError (917: Infinity not allowed in JSON):
JSON.generate(JSON::Infinity)
# Raises JSON::GeneratorError (917: -Infinity not allowed in JSON):
JSON.generate(JSON::MinusInfinity)

允许

ruby = [Float::NaN, Float::Infinity, Float::MinusInfinity]
JSON.generate(ruby, allow_nan: true) # => '[NaN,Infinity,-Infinity]'

选项 max_nesting（整数）指定 obj 中的最大嵌套深度；默认值为 100。

默认情况下，100。

obj = [[[[[[0]]]]]]
JSON.generate(obj) # => '[[[[[[0]]]]]]'

深度过深

# Raises JSON::NestingError (nesting of 2 is too deep):
JSON.generate(obj, max_nesting: 2)

转义选项¶ ↑

选项 script_safe（布尔值）指定是否应该将 '\u2028'、'\u2029' 和 '/' 转义，以使 JSON 对象在脚本标签中安全地进行插值。

选项 ascii_only（布尔值）指定是否应该转义所有超出 ASCII 范围的字符。

输出选项¶ ↑

默认格式化选项生成最紧凑的 JSON 数据，所有数据都在一行上，没有空格。

您可以使用这些格式化选项以更开放的格式生成 JSON 数据，使用空格。另请参见 JSON.pretty_generate。

选项 array_nl（字符串）指定在每个 JSON 数组后插入的字符串（通常是换行符）；默认值为空字符串 ''。
选项 object_nl（字符串）指定在每个 JSON 对象后插入的字符串（通常是换行符）；默认值为空字符串 ''。
选项 indent（字符串）指定用于缩进的字符串（通常是空格）；默认值为空字符串 ''；默认值为空字符串 ''；除非选项 array_nl 或 object_nl 指定换行符，否则无效。
选项 space（字符串）指定在每个 JSON 对象的键值对中的冒号后插入的字符串（通常是空格）；默认值为空字符串 ''。
选项 space_before（字符串）指定在每个 JSON 对象的键值对中的冒号前插入的字符串（通常是空格）；默认值为空字符串 ''。

在本例中，obj 首先用于生成最短的 JSON 数据（无空格），然后再次使用所有指定的格式选项

obj = {foo: [:bar, :baz], bat: {bam: 0, bad: 1}}
json = JSON.generate(obj)
puts 'Compact:', json
opts = {
  array_nl: "\n",
  object_nl: "\n",
  indent: '  ',
  space_before: ' ',
  space: ' '
}
puts 'Open:', JSON.generate(obj, opts)

输出

Compact:
{"foo":["bar","baz"],"bat":{"bam":0,"bad":1}}
Open:
{
  "foo" : [
    "bar",
    "baz"
],
  "bat" : {
    "bam" : 0,
    "bad" : 1
  }
}

JSON 添加¶ ↑

当您将非字符串对象从 Ruby 到 JSON 再返回时，您将获得一个新的字符串，而不是您开始时的对象

ruby0 = Range.new(0, 2)
json = JSON.generate(ruby0)
json # => '0..2"'
ruby1 = JSON.parse(json)
ruby1 # => '0..2'
ruby1.class # => String

您可以使用 JSON 添加来保留原始对象。添加是对 ruby 类的一个扩展，因此

JSON.generate 在 JSON 字符串中存储更多信息。
JSON.parse，在使用选项 create_additions 调用时，使用该信息来创建一个合适的 Ruby 对象。

此示例显示了将范围生成到 JSON 中并将其解析回 Ruby，既没有添加范围，也有添加范围

ruby = Range.new(0, 2)
# This passage does not use the addition for Range.
json0 = JSON.generate(ruby)
ruby0 = JSON.parse(json0)
# This passage uses the addition for Range.
require 'json/add/range'
json1 = JSON.generate(ruby)
ruby1 = JSON.parse(json1, create_additions: true)
# Make a nice display.
display = <<EOT
Generated JSON:
  Without addition:  #{json0} (#{json0.class})
  With addition:     #{json1} (#{json1.class})
Parsed JSON:
  Without addition:  #{ruby0.inspect} (#{ruby0.class})
  With addition:     #{ruby1.inspect} (#{ruby1.class})
EOT
puts display

此输出显示了不同的结果

Generated JSON:
  Without addition:  "0..2" (String)
  With addition:     {"json_class":"Range","a":[0,2,false]} (String)
Parsed JSON:
  Without addition:  "0..2" (String)
  With addition:     0..2 (Range)

JSON 模块包含某些类的添加。您也可以制作自定义添加。请参阅自定义 JSON 添加。

内置添加¶ ↑

JSON 模块包含某些类的添加。要使用添加，请 require 其源代码

BigDecimal: require 'json/add/bigdecimal'
Complex: require 'json/add/complex'
Date: require 'json/add/date'
DateTime: require 'json/add/date_time'
Exception: require 'json/add/exception'
OpenStruct: require 'json/add/ostruct'
Range: require 'json/add/range'
Rational: require 'json/add/rational'
Regexp: require 'json/add/regexp'
Set: require 'json/add/set'
Struct: require 'json/add/struct'
Symbol: require 'json/add/symbol'
Time: require 'json/add/time'

为了减少标点符号的混乱，以下示例通过 puts 显示生成的 JSON，而不是通常的 inspect，

BigDecimal

require 'json/add/bigdecimal'
ruby0 = BigDecimal(0) # 0.0
json = JSON.generate(ruby0) # {"json_class":"BigDecimal","b":"27:0.0"}
ruby1 = JSON.parse(json, create_additions: true) # 0.0
ruby1.class # => BigDecimal

Complex

require 'json/add/complex'
ruby0 = Complex(1+0i) # 1+0i
json = JSON.generate(ruby0) # {"json_class":"Complex","r":1,"i":0}
ruby1 = JSON.parse(json, create_additions: true) # 1+0i
ruby1.class # Complex

Date

require 'json/add/date'
ruby0 = Date.today # 2020-05-02
json = JSON.generate(ruby0) # {"json_class":"Date","y":2020,"m":5,"d":2,"sg":2299161.0}
ruby1 = JSON.parse(json, create_additions: true) # 2020-05-02
ruby1.class # Date

DateTime

require 'json/add/date_time'
ruby0 = DateTime.now # 2020-05-02T10:38:13-05:00
json = JSON.generate(ruby0) # {"json_class":"DateTime","y":2020,"m":5,"d":2,"H":10,"M":38,"S":13,"of":"-5/24","sg":2299161.0}
ruby1 = JSON.parse(json, create_additions: true) # 2020-05-02T10:38:13-05:00
ruby1.class # DateTime

Exception（及其子类，包括 RuntimeError）

require 'json/add/exception'
ruby0 = Exception.new('A message') # A message
json = JSON.generate(ruby0) # {"json_class":"Exception","m":"A message","b":null}
ruby1 = JSON.parse(json, create_additions: true) # A message
ruby1.class # Exception
ruby0 = RuntimeError.new('Another message') # Another message
json = JSON.generate(ruby0) # {"json_class":"RuntimeError","m":"Another message","b":null}
ruby1 = JSON.parse(json, create_additions: true) # Another message
ruby1.class # RuntimeError

OpenStruct

require 'json/add/ostruct'
ruby0 = OpenStruct.new(name: 'Matz', language: 'Ruby') # #<OpenStruct name="Matz", language="Ruby">
json = JSON.generate(ruby0) # {"json_class":"OpenStruct","t":{"name":"Matz","language":"Ruby"}}
ruby1 = JSON.parse(json, create_additions: true) # #<OpenStruct name="Matz", language="Ruby">
ruby1.class # OpenStruct

Range

require 'json/add/range'
ruby0 = Range.new(0, 2) # 0..2
json = JSON.generate(ruby0) # {"json_class":"Range","a":[0,2,false]}
ruby1 = JSON.parse(json, create_additions: true) # 0..2
ruby1.class # Range

Rational

require 'json/add/rational'
ruby0 = Rational(1, 3) # 1/3
json = JSON.generate(ruby0) # {"json_class":"Rational","n":1,"d":3}
ruby1 = JSON.parse(json, create_additions: true) # 1/3
ruby1.class # Rational

Regexp

require 'json/add/regexp'
ruby0 = Regexp.new('foo') # (?-mix:foo)
json = JSON.generate(ruby0) # {"json_class":"Regexp","o":0,"s":"foo"}
ruby1 = JSON.parse(json, create_additions: true) # (?-mix:foo)
ruby1.class # Regexp

Set

require 'json/add/set'
ruby0 = Set.new([0, 1, 2]) # #<Set: {0, 1, 2}>
json = JSON.generate(ruby0) # {"json_class":"Set","a":[0,1,2]}
ruby1 = JSON.parse(json, create_additions: true) # #<Set: {0, 1, 2}>
ruby1.class # Set

Struct

require 'json/add/struct'
Customer = Struct.new(:name, :address) # Customer
ruby0 = Customer.new("Dave", "123 Main") # #<struct Customer name="Dave", address="123 Main">
json = JSON.generate(ruby0) # {"json_class":"Customer","v":["Dave","123 Main"]}
ruby1 = JSON.parse(json, create_additions: true) # #<struct Customer name="Dave", address="123 Main">
ruby1.class # Customer

Symbol

require 'json/add/symbol'
ruby0 = :foo # foo
json = JSON.generate(ruby0) # {"json_class":"Symbol","s":"foo"}
ruby1 = JSON.parse(json, create_additions: true) # foo
ruby1.class # Symbol

Time

require 'json/add/time'
ruby0 = Time.now # 2020-05-02 11:28:26 -0500
json = JSON.generate(ruby0) # {"json_class":"Time","s":1588436906,"n":840560000}
ruby1 = JSON.parse(json, create_additions: true) # 2020-05-02 11:28:26 -0500
ruby1.class # Time

自定义 JSON 添加¶ ↑

除了提供的 JSON 添加之外，您还可以创建自己的 JSON 添加，无论是针对 Ruby 内置类还是针对用户定义的类。

这是一个用户定义的类 Foo

class Foo
  attr_accessor :bar, :baz
  def initialize(bar, baz)
    self.bar = bar
    self.baz = baz
  end
end

这是它的 JSON 添加

# Extend class Foo with JSON addition.
class Foo
  # Serialize Foo object with its class name and arguments
  def to_json(*args)
    {
      JSON.create_id  => self.class.name,
      'a'             => [ bar, baz ]
    }.to_json(*args)
  end
  # Deserialize JSON string by constructing new Foo object with arguments.
  def self.json_create(object)
    new(*object['a'])
  end
end

演示

require 'json'
# This Foo object has no custom addition.
foo0 = Foo.new(0, 1)
json0 = JSON.generate(foo0)
obj0 = JSON.parse(json0)
# Lood the custom addition.
require_relative 'foo_addition'
# This foo has the custom addition.
foo1 = Foo.new(0, 1)
json1 = JSON.generate(foo1)
obj1 = JSON.parse(json1, create_additions: true)
#   Make a nice display.
display = <<EOT
Generated JSON:
  Without custom addition:  #{json0} (#{json0.class})
  With custom addition:     #{json1} (#{json1.class})
Parsed JSON:
  Without custom addition:  #{obj0.inspect} (#{obj0.class})
  With custom addition:     #{obj1.inspect} (#{obj1.class})
EOT
puts display

输出

Generated JSON:
  Without custom addition:  "#<Foo:0x0000000006534e80>" (String)
  With custom addition:     {"json_class":"Foo","a":[0,1]} (String)
Parsed JSON:
  Without custom addition:  "#<Foo:0x0000000006534e80>" (String)
  With custom addition:     #<Foo:0x0000000006473bb8 @bar=0, @baz=1> (Foo)

常量

CREATE_ID_TLS_KEY
DEFAULT_CREATE_ID
Infinity
JSON_LOADED
MinusInfinity
NOT_SET
NaN
VERSION: JSON 版本

属性

dump_default_options[RW]

设置或返回 JSON.dump 方法的默认选项。最初

opts = JSON.dump_default_options
opts # => {:max_nesting=>false, :allow_nan=>true, :script_safe=>false}

generator[R]

返回 JSON 生成器模块，该模块由 JSON 使用。这要么是 JSON::Ext::Generator 要么是 JSON::Pure::Generator

JSON.generator # => JSON::Ext::Generator

load_default_options[RW]

设置或返回 JSON.load 方法的默认选项。最初

opts = JSON.load_default_options
opts # => {:max_nesting=>false, :allow_nan=>true, :allow_blank=>true, :create_additions=>true}

parser[R]

返回 JSON 解析器类，该类由 JSON 使用。这要么是 JSON::Ext::Parser 要么是 JSON::Pure::Parser

JSON.parser # => JSON::Ext::Parser

state[RW]

设置或返回 JSON 生成器状态类，该类由 JSON 使用。这要么是 JSON::Ext::Generator::State 要么是 JSON::Pure::Generator::State

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

公共类方法

JSON[object] → new_array or new_string 点击以切换源代码

如果 object 是一个字符串，则调用 JSON.parse，使用 object 和 opts（参见方法 parse）

json = '[0, 1, null]'
JSON[json]# => [0, 1, nil]

否则，调用 JSON.generate，使用 object 和 opts（参见方法 generate）

ruby = [0, 1, nil]
JSON[ruby] # => '[0,1,null]'

# File json/lib/json/common.rb, line 21
def [](object, opts = {})
  if object.respond_to? :to_str
    JSON.parse(object.to_str, opts)
  else
    JSON.generate(object, opts)
  end
end

create_fast_state() 点击以切换源代码

# File json/lib/json/common.rb, line 84
def create_fast_state
  State.new(
    :indent         => '',
    :space          => '',
    :object_nl      => "",
    :array_nl       => "",
    :max_nesting    => false
  )
end

create_id() 点击以切换源代码

返回当前创建标识符。另请参见 JSON.create_id=.

# File json/lib/json/common.rb, line 129
def self.create_id
  Thread.current[CREATE_ID_TLS_KEY] || DEFAULT_CREATE_ID
end

create_id=(new_value) 点击以切换源代码

设置创建标识符，用于决定是否应该调用类的 json_create 钩子；初始值为 json_class

JSON.create_id # => 'json_class'

# File json/lib/json/common.rb, line 123
def self.create_id=(new_value)
  Thread.current[CREATE_ID_TLS_KEY] = new_value.dup.freeze
end

create_pretty_state() 点击以切换源代码

# File json/lib/json/common.rb, line 94
def create_pretty_state
  State.new(
    :indent         => '  ',
    :space          => ' ',
    :object_nl      => "\n",
    :array_nl       => "\n"
  )
end

iconv(to, from, string) 点击以切换源代码

使用 String.encode 编码字符串。

# File json/lib/json/common.rb, line 638
def self.iconv(to, from, string)
  string.encode(to, from)
end

restore(source, proc = nil, options = {})

别名：load

公共实例方法

dump(obj, io = nil, limit = nil) 点击切换源代码

将 obj 作为 JSON 字符串转储，即调用对象的 generate 方法并返回结果。

默认选项可以通过方法 JSON.dump_default_options 修改。

如果给出参数 io，则它应该响应方法 write；JSON 字符串将写入 io，并返回 io。如果未给出 io，则返回 JSON 字符串。
如果给出参数 limit，则将其作为选项 max_nesting 传递给 JSON.generate。

当参数 io 未给出时，返回从 obj 生成的 JSON 字符串

obj = {foo: [0, 1], bar: {baz: 2, bat: 3}, bam: :bad}
json = JSON.dump(obj)
json # => "{\"foo\":[0,1],\"bar\":{\"baz\":2,\"bat\":3},\"bam\":\"bad\"}"

当参数 io 给出时，将 JSON 字符串写入 io 并返回 io

path = 't.json'
File.open(path, 'w') do |file|
  JSON.dump(obj, file)
end # => #<File:t.json (closed)>
puts File.read(path)

输出

{"foo":[0,1],"bar":{"baz":2,"bat":3},"bam":"bad"}

# File json/lib/json/common.rb, line 614
def dump(obj, anIO = nil, limit = nil, kwargs = nil)
  io_limit_opt = [anIO, limit, kwargs].compact
  kwargs = io_limit_opt.pop if io_limit_opt.last.is_a?(Hash)
  anIO, limit = io_limit_opt
  if anIO.respond_to?(:to_io)
    anIO = anIO.to_io
  elsif limit.nil? && !anIO.respond_to?(:write)
    anIO, limit = nil, anIO
  end
  opts = JSON.dump_default_options
  opts = opts.merge(:max_nesting => limit) if limit
  opts = merge_dump_options(opts, **kwargs) if kwargs
  result = generate(obj, opts)
  if anIO
    anIO.write result
    anIO
  else
    result
  end
rescue JSON::NestingError
  raise ArgumentError, "exceed depth limit"
end

fast_generate(obj, opts) → new_string 点击切换源代码

这里的参数 obj 和 opts 与 JSON.generate 中的参数 obj 和 opts 相同。

默认情况下，生成 JSON 数据时不会检查 obj 中的循环引用（选项 max_nesting 设置为 false，禁用）。

如果 obj 包含循环引用，则会引发异常

a = []; b = []; a.push(b); b.push(a)
# Raises SystemStackError (stack level too deep):
JSON.fast_generate(a)

# File json/lib/json/common.rb, line 328
def fast_generate(obj, opts = nil)
  if State === opts
    state = opts
  else
    state = JSON.create_fast_state.configure(opts)
  end
  state.generate(obj)
end

generate(obj, opts = nil) → new_string 点击切换源代码

返回包含生成的 JSON 数据的字符串。

另请参阅 JSON.fast_generate，JSON.pretty_generate。

参数 obj 是要转换为 JSON 的 Ruby 对象。

如果给出参数 opts，则它包含用于生成的选项的哈希。请参阅生成选项。

当 obj 是数组时，返回包含 JSON 数组的字符串

obj = ["foo", 1.0, true, false, nil]
json = JSON.generate(obj)
json # => '["foo",1.0,true,false,null]'

当 obj 是哈希时，返回包含 JSON 对象的字符串

obj = {foo: 0, bar: 's', baz: :bat}
json = JSON.generate(obj)
json # => '{"foo":0,"bar":"s","baz":"bat"}'

有关从其他 Ruby 对象生成示例，请参阅从其他对象生成 JSON。

如果任何格式选项不是字符串，则会引发异常。

如果 obj 包含循环引用，则会引发异常

a = []; b = []; a.push(b); b.push(a)
# Raises JSON::NestingError (nesting of 100 is too deep):
JSON.generate(a)

# File json/lib/json/common.rb, line 299
def generate(obj, opts = nil)
  if State === opts
    state = opts
  else
    state = State.new(opts)
  end
  state.generate(obj)
end

load(source, proc = nil, options = {}) → object 点击切换源代码

返回通过解析给定的 source 创建的 Ruby 对象。

参数 source 必须是字符串，或者可以转换为字符串。
- 如果 source 响应实例方法 to_str，source.to_str 将成为源代码。
- 如果 source 响应实例方法 to_io，source.to_io.read 将成为源代码。
- 如果 source 响应实例方法 read，source.read 将成为源代码。
- 如果以下两个条件都满足，源代码将变为字符串 'null'
  - 选项 allow_blank 指定一个真值。
  - 如上所述，源代码为 nil 或空字符串 ''。
- 否则，source 保持不变。
参数 proc（如果给出）必须是一个接受一个参数的 Proc。它将以递归方式调用每个结果（深度优先顺序）。请参阅下面的详细信息。注意：此方法旨在将数据从受信任的用户输入（例如来自您自己的数据库服务器或您控制的客户端）序列化，允许不受信任的用户将 JSON 源代码传递到其中可能很危险。
参数 opts（如果给出）包含一个用于解析的选项哈希。请参阅解析选项。默认选项可以通过方法 JSON.load_default_options= 更改。

当没有给出 proc 时，将如上所述修改 source 并返回 parse(source, opts) 的结果；请参阅 parse。

以下示例的源代码

source = <<-EOT
{
"name": "Dave",
  "age" :40,
  "hats": [
    "Cattleman's",
    "Panama",
    "Tophat"
  ]
}
EOT

加载字符串

ruby = JSON.load(source)
ruby # => {"name"=>"Dave", "age"=>40, "hats"=>["Cattleman's", "Panama", "Tophat"]}

加载 IO 对象

require 'stringio'
object = JSON.load(StringIO.new(source))
object # => {"name"=>"Dave", "age"=>40, "hats"=>["Cattleman's", "Panama", "Tophat"]}

加载文件对象

path = 't.json'
File.write(path, source)
File.open(path) do |file|
  JSON.load(file)
end # => {"name"=>"Dave", "age"=>40, "hats"=>["Cattleman's", "Panama", "Tophat"]}

当给出 proc 时

如上所述修改 source。
从调用 parse(source, opts) 获取 result。
递归调用 proc(result)。
返回最终结果。

示例

require 'json'

# Some classes for the example.
class Base
  def initialize(attributes)
    @attributes = attributes
  end
end
class User    < Base; end
class Account < Base; end
class Admin   < Base; end
# The JSON source.
json = <<-EOF
{
  "users": [
      {"type": "User", "username": "jane", "email": "[email protected]"},
      {"type": "User", "username": "john", "email": "[email protected]"}
  ],
  "accounts": [
      {"account": {"type": "Account", "paid": true, "account_id": "1234"}},
      {"account": {"type": "Account", "paid": false, "account_id": "1235"}}
  ],
  "admins": {"type": "Admin", "password": "0wn3d"}
}
EOF
# Deserializer method.
def deserialize_obj(obj, safe_types = %w(User Account Admin))
  type = obj.is_a?(Hash) && obj["type"]
  safe_types.include?(type) ? Object.const_get(type).new(obj) : obj
end
# Call to JSON.load
ruby = JSON.load(json, proc {|obj|
  case obj
  when Hash
    obj.each {|k, v| obj[k] = deserialize_obj v }
  when Array
    obj.map! {|v| deserialize_obj v }
  end
})
pp ruby

输出

{"users"=>
   [#<User:0x00000000064c4c98
     @attributes=
       {"type"=>"User", "username"=>"jane", "email"=>"[email protected]"}>,
     #<User:0x00000000064c4bd0
     @attributes=
       {"type"=>"User", "username"=>"john", "email"=>"[email protected]"}>],
 "accounts"=>
   [{"account"=>
       #<Account:0x00000000064c4928
       @attributes={"type"=>"Account", "paid"=>true, "account_id"=>"1234"}>},
    {"account"=>
       #<Account:0x00000000064c4680
       @attributes={"type"=>"Account", "paid"=>false, "account_id"=>"1235"}>}],
 "admins"=>
   #<Admin:0x00000000064c41f8
   @attributes={"type"=>"Admin", "password"=>"0wn3d"}>}

# File json/lib/json/common.rb, line 540
def load(source, proc = nil, options = {})
  opts = load_default_options.merge options
  if source.respond_to? :to_str
    source = source.to_str
  elsif source.respond_to? :to_io
    source = source.to_io.read
  elsif source.respond_to?(:read)
    source = source.read
  end
  if opts[:allow_blank] && (source.nil? || source.empty?)
    source = 'null'
  end
  result = parse(source, opts)
  recurse_proc(result, &proc) if proc
  result
end

也称为：restore

load_file(path, opts={}) → object 点击切换源代码

调用

parse(File.read(path), opts)

请参阅方法 parse。

# File json/lib/json/common.rb, line 248
def load_file(filespec, opts = {})
  parse(File.read(filespec), opts)
end

load_file!(path, opts = {}) 点击切换源代码

调用

JSON.parse!(File.read(path, opts))

参见方法 parse!

# File json/lib/json/common.rb, line 259
def load_file!(filespec, opts = {})
  parse!(File.read(filespec), opts)
end

merge_dump_options(opts, strict: NOT_SET) 点击切换源代码

# File json/lib/json/common.rb, line 642
def merge_dump_options(opts, strict: NOT_SET)
  opts = opts.merge(strict: strict) if NOT_SET != strict
  opts
end

parse(source, opts) → object 点击切换源代码

返回通过解析给定的 source 创建的 Ruby 对象。

参数 source 包含要解析的字符串。

参数 opts，如果提供，包含用于解析的选项哈希。参见解析选项。

当 source 是 JSON 数组时，返回一个 Ruby 数组

source = '["foo", 1.0, true, false, null]'
ruby = JSON.parse(source)
ruby # => ["foo", 1.0, true, false, nil]
ruby.class # => Array

当 source 是 JSON 对象时，返回一个 Ruby 哈希

source = '{"a": "foo", "b": 1.0, "c": true, "d": false, "e": null}'
ruby = JSON.parse(source)
ruby # => {"a"=>"foo", "b"=>1.0, "c"=>true, "d"=>false, "e"=>nil}
ruby.class # => Hash

有关解析所有 JSON 数据类型的示例，请参见解析 JSON。

解析嵌套的 JSON 对象

source = <<-EOT
{
"name": "Dave",
  "age" :40,
  "hats": [
    "Cattleman's",
    "Panama",
    "Tophat"
  ]
}
EOT
ruby = JSON.parse(source)
ruby # => {"name"=>"Dave", "age"=>40, "hats"=>["Cattleman's", "Panama", "Tophat"]}

如果 source 不是有效的 JSON，则抛出异常

# Raises JSON::ParserError (783: unexpected token at ''):
JSON.parse('')

# File json/lib/json/common.rb, line 218
def parse(source, opts = {})
  Parser.new(source, **(opts||{})).parse
end

parse!(source, opts) → object 点击切换源代码

调用

parse(source, opts)

使用 source 和可能修改后的 opts。

与 JSON.parse 的区别

选项 max_nesting，如果未提供，默认为 false，这将禁用对嵌套深度的检查。
选项 allow_nan，如果未提供，默认为 true。

# File json/lib/json/common.rb, line 233
def parse!(source, opts = {})
  opts = {
    :max_nesting  => false,
    :allow_nan    => true
  }.merge(opts)
  Parser.new(source, **(opts||{})).parse
end

pretty_generate(obj, opts = nil) → new_string 点击切换源代码

这里的参数 obj 和 opts 与 JSON.generate 中的参数 obj 和 opts 相同。

默认选项是

{
  indent: '  ',   # Two spaces
  space: ' ',     # One space
  array_nl: "\n", # Newline
  object_nl: "\n" # Newline
}

示例

obj = {foo: [:bar, :baz], bat: {bam: 0, bad: 1}}
json = JSON.pretty_generate(obj)
puts json

输出

{
  "foo": [
    "bar",
    "baz"
  ],
  "bat": {
    "bam": 0,
    "bad": 1
  }
}

# File json/lib/json/common.rb, line 373
def pretty_generate(obj, opts = nil)
  if State === opts
    state, opts = opts, nil
  else
    state = JSON.create_pretty_state
  end
  if opts
    if opts.respond_to? :to_hash
      opts = opts.to_hash
    elsif opts.respond_to? :to_h
      opts = opts.to_h
    else
      raise TypeError, "can't convert #{opts.class} into Hash"
    end
    state.configure(opts)
  end
  state.generate(obj)
end

私有实例方法

restore(source, proc = nil, options = {})

别名：load