Module: JSON

Defined in:
lib/json.rb,
lib/json/ext.rb,
lib/json/pure.rb,
lib/json/common.rb,
lib/json/version.rb,
lib/json/pure/parser.rb,
lib/json/generic_object.rb,
lib/json/pure/generator.rb,
ext/json/ext/parser/parser.c,
ext/json/ext/generator/generator.c

Overview

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

Custom JSON Additions

In addition to the JSON additions provided, you can craft JSON additions of your own, either for Ruby built-in classes or for user-defined classes.

Here’s a user-defined class Foo:

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

Here’s the JSON addition for it:

# 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

Demonstration:

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

Output:

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)

Defined Under Namespace

Modules: Ext, Pure Classes: CircularDatastructure, GeneratorError, GenericObject, JSONError, MissingUnicodeSupport, NestingError, ParserError

Constant Summary collapse

JSON_LOADED = 
true
NaN = 
0.0/0
Infinity = 
1.0/0
MinusInfinity = 
-Infinity
UnparserError =

For backwards compatibility

GeneratorError
VERSION =

JSON version

'2.3.1'
VERSION_ARRAY =

:nodoc:

VERSION.split(/\./).map { |x| x.to_i }
VERSION_MAJOR =

:nodoc:

VERSION_ARRAY[0]
VERSION_MINOR =

:nodoc:

VERSION_ARRAY[1]
VERSION_BUILD =

:nodoc:

VERSION_ARRAY[2]
MAP = 
{
  "\x0" => '\u0000',
  "\x1" => '\u0001',
  "\x2" => '\u0002',
  "\x3" => '\u0003',
  "\x4" => '\u0004',
  "\x5" => '\u0005',
  "\x6" => '\u0006',
  "\x7" => '\u0007',
  "\b"  =>  '\b',
  "\t"  =>  '\t',
  "\n"  =>  '\n',
  "\xb" => '\u000b',
  "\f"  =>  '\f',
  "\r"  =>  '\r',
  "\xe" => '\u000e',
  "\xf" => '\u000f',
  "\x10" => '\u0010',
  "\x11" => '\u0011',
  "\x12" => '\u0012',
  "\x13" => '\u0013',
  "\x14" => '\u0014',
  "\x15" => '\u0015',
  "\x16" => '\u0016',
  "\x17" => '\u0017',
  "\x18" => '\u0018',
  "\x19" => '\u0019',
  "\x1a" => '\u001a',
  "\x1b" => '\u001b',
  "\x1c" => '\u001c',
  "\x1d" => '\u001d',
  "\x1e" => '\u001e',
  "\x1f" => '\u001f',
  '"'   =>  '\"',
  '\\'  =>  '\\\\',
}

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.create_id ⇒ Object

Sets or returns create identifier, which is used to decide if the json_create hook of a class should be called; initial value is json_class:

JSON.create_id # => 'json_class'



103
104
105
 
# File 'lib/json/common.rb', line 103

def create_id
  @create_id
end

.dump_default_options ⇒ Object

Sets or returns the default options for the JSON.dump method. Initially:

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



597
598
599
 
# File 'lib/json/common.rb', line 597

def dump_default_options
  @dump_default_options
end

.generator ⇒ Object

Returns the JSON generator module that is used by JSON. This is either JSON::Ext::Generator or JSON::Pure::Generator:

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



93
94
95
 
# File 'lib/json/common.rb', line 93

def generator
  @generator
end

.load_default_options ⇒ Object

Sets or returns default options for the JSON.load method. Initially:

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



535
536
537
 
# File 'lib/json/common.rb', line 535

def load_default_options
  @load_default_options
end

.parser ⇒ Object

Returns the JSON parser class that is used by JSON. This is either JSON::Ext::Parser or JSON::Pure::Parser:

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



27
28
29
 
# File 'lib/json/common.rb', line 27

def parser
  @parser
end

.state ⇒ Object

Sets or Returns the JSON generator state class that is used by JSON. This is either JSON::Ext::Generator::State or JSON::Pure::Generator::State:

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



98
99
100
 
# File 'lib/json/common.rb', line 98

def state
  @state
end

Class Method Details

.[](object, opts = {}) ⇒ Object

If object is a String-convertible object (implementing to_str), calls JSON.parse with object and opts:

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

Otherwise, calls JSON.generate with object and opts:

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



16
17
18
19
20
21
22
 
# File 'lib/json/common.rb', line 16

def [](object, opts = {})
  if object.respond_to? :to_str
    JSON.parse(object.to_str, opts)
  else
    JSON.generate(object, opts)
  end
end

.deep_const_get(path) ⇒ Object

Return the constant located at path. The format of path has to be either ::A::B::C or A::B::C. In any case, A has to be located at the top level (absolute namespace path?). If there doesn’t exist a constant at the given path, an ArgumentError is raised.



40
41
42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/json/common.rb', line 40

def deep_const_get(path) # :nodoc:
  path.to_s.split(/::/).inject(Object) do |p, c|
    case
    when c.empty?                  then p
    when p.const_defined?(c, true) then p.const_get(c)
    else
      begin
        p.const_missing(c)
      rescue NameError => e
        raise ArgumentError, "can't get const #{path}: #{e}"
      end
    end
  end
end

.dump(obj, anIO = nil, limit = nil) ⇒ Object

Dumps obj as a JSON string, i.e. calls generate on the object and returns the result.

If anIO (an IO-like object or an object that responds to the write method) was given, the resulting JSON is written to it.

If the number of nested arrays or objects exceeds limit, an ArgumentError exception is raised. This argument is similar (but not exactly the same!) to the limit argument in Marshal.dump.

The default options for the generator can be changed via the dump_default_options method.

This method is part of the implementation of the load/dump interface of Marshal and YAML.



619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
 
# File 'lib/json/common.rb', line 619

def dump(obj, anIO = nil, limit = nil)
  if anIO and limit.nil?
    anIO = anIO.to_io if anIO.respond_to?(:to_io)
    unless anIO.respond_to?(:write)
      limit = anIO
      anIO = nil
    end
  end
  opts = JSON.dump_default_options
  opts = opts.merge(:max_nesting => limit) if limit
  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 = nil) ⇒ Object Also known as: fast_unparse

Arguments obj and opts here are the same as arguments obj and opts in JSON.generate.

By default, generates JSON data without checking for circular references in obj (option max_nesting set to false, disabled).

Raises an exception if obj contains circular references:

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



450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
 
# File 'lib/json/common.rb', line 450

def fast_generate(obj, opts = nil)
  if State === opts
    state, opts = opts, nil
  else
    state = FAST_STATE_PROTOTYPE.dup
  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

.generate(obj, opts = nil) ⇒ Object Also known as: unparse

:call-seq:

JSON.generate(obj, opts = nil) -> new_string

Argument obj is the Ruby object to be converted to JSON.

Argument opts, if given, contains options for the generation, and must be a Hash-convertible object (implementing to_hash).

Returns a String containing the generated JSON data.

See also JSON.fast_generate, JSON.pretty_generate.

When obj is an Array-convertible object (implementing to_ary), returns a String containing a JSON array:

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

When obj is a Hash-convertible object, return a String containing a JSON object:

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

For examples of generating from other Ruby objects, see Generating JSON from Other Objects.

Input Options

Option allow_nan (boolean) specifies whether NaN, Infinity, and -Infinity may be generated; defaults to false.

With the default, 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)

Allow:

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

Option max_nesting (Integer) specifies the maximum nesting depth in obj; defaults to 100.

With the default, 100:

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

Too deep:

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

The default formatting options generate the most compact JSON data, all on one line and with no whitespace.

You can use these formatting options to generate JSON data in a more open format, using whitespace. See also JSON.pretty_generate.

  • Option array_nl (String) specifies a string (usually a newline) to be inserted after each JSON array; defaults to the empty String, ''.

  • Option object_nl (String) specifies a string (usually a newline) to be inserted after each JSON object; defaults to the empty String, ''.

  • Option indent (String) specifies the string (usually spaces) to be used for indentation; defaults to the empty String, ''; defaults to the empty String, ''; has no effect unless options array_nl or object_nl specify newlines.

  • Option space (String) specifies a string (usually a space) to be inserted after the colon in each JSON object’s pair; defaults to the empty String, ''.

  • Option space_before (String) specifies a string (usually a space) to be inserted before the colon in each JSON object’s pair; defaults to the empty String, ''.

In this example, obj is used first to generate the shortest JSON data (no whitespace), then again with all formatting options specified:

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)

Output:

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

Raises an exception if any formatting option is not a String.

Exceptions

Raises an exception if obj contains circular references:

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



414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
 
# File 'lib/json/common.rb', line 414

def generate(obj, opts = nil)
  if State === opts
    state, opts = opts, nil
  else
    state = SAFE_STATE_PROTOTYPE.dup
  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 = state.configure(opts)
  end
  state.generate(obj)
end

.iconv(to, from, string) ⇒ Object

Encodes string using String.encode.



641
642
643
 
# File 'lib/json/common.rb', line 641

def self.iconv(to, from, string)
  string.encode(to, from)
end

.load(source, proc = nil, options = {}) ⇒ Object Also known as: restore

Load a ruby data structure from a JSON source and return it. A source can either be a string-like object, an IO-like object, or an object responding to the read method. If proc was given, it will be called with any nested Ruby object as an argument recursively in depth first order. To modify the default options pass in the optional options argument as well.

BEWARE: This method is meant to serialise data from trusted user input, like from your own database server or clients under your control, it could be dangerous to allow untrusted users to pass JSON sources into it. The default options for the parser can be changed via the load_default_options method.

This method is part of the implementation of the load/dump interface of Marshal and YAML.



558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
 
# File 'lib/json/common.rb', line 558

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

.parse(source, opts = {}) ⇒ Object

:call-seq:

JSON.parse(source, opts) -> object

Argument source contains the String to be parsed. It must be a String-convertible object (implementing to_str), and must contain valid JSON data.

Argument opts, if given, contains options for the parsing, and must be a Hash-convertible object (implementing to_hash).

Returns the Ruby objects created by parsing the given source.

When source is a JSON array, returns a Ruby Array:

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

When source is a JSON object, returns a Ruby Hash:

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

For examples of parsing for all JSON data types, see Parsing JSON.

Input Options

Option max_nesting (Integer) specifies the maximum nesting depth allowed; defaults to 100; specify false to disable depth checking.

With the default, false:

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

Too deep:

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

Bad value:

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

Option allow_nan (boolean) specifies whether to allow NaN, Infinity, and MinusInfinity in source; defaults to false.

With the default, 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]')

Allow:

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

Option symbolize_names (boolean) specifies whether returned Hash keys should be Symbols; defaults to false (use Strings).

With the default, 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}

Use Symbols:

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

Option object_class (Class) specifies the Ruby class to be used for each JSON object; defaults to Hash.

With the default, Hash:

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

Use class OpenStruct:

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

Option array_class (Class) specifies the Ruby class to be used for each JSON array; defaults to Array.

With the default, Array:

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

Use class Set:

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

Option create_additions (boolean) specifies whether to use JSON additions in parsing. See JSON Additions.

Exceptions

Raises an exception if source is not valid JSON:

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



262
263
264
 
# File 'lib/json/common.rb', line 262

def parse(source, opts = {})
  Parser.new(source, **(opts||{})).parse
end

.parse!(source, opts = {}) ⇒ Object

:call-seq:

JSON.parse!(source, opts) -> object

Calls

parse(source, opts)

with source and possibly modified opts.

Differences from JSON.parse:

  • Option max_nesting, if not provided, defaults to false, which disables checking for nesting depth.

  • Option allow_nan, if not provided, defaults to true.



277
278
279
280
281
282
283
 
# File 'lib/json/common.rb', line 277

def parse!(source, opts = {})
  opts = {
    :max_nesting  => false,
    :allow_nan    => true
  }.merge(opts)
  Parser.new(source, **(opts||{})).parse
end

.pretty_generate(obj, opts = nil) ⇒ Object Also known as: pretty_unparse

:call-seq:

JSON.pretty_generate(obj, opts = nil) -> new_string

Arguments obj and opts here are the same as arguments obj and opts in JSON.generate.

Default options are:

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

Example:

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

Output:

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



505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
 
# File 'lib/json/common.rb', line 505

def pretty_generate(obj, opts = nil)
  if State === opts
    state, opts = opts, nil
  else
    state = PRETTY_STATE_PROTOTYPE.dup
  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

.recurse_proc(result, &proc) ⇒ Object

Recursively calls passed Proc if the parsed data structure is an Array or Hash



576
577
578
579
580
581
582
583
584
585
586
587
 
# File 'lib/json/common.rb', line 576

def recurse_proc(result, &proc)
  case result
  when Array
    result.each { |x| recurse_proc x, &proc }
    proc.call result
  when Hash
    result.each { |x, y| recurse_proc x, &proc; recurse_proc y, &proc }
    proc.call result
  else
    proc.call result
  end
end

.utf8_to_json(string) ⇒ Object

Convert a UTF8 encoded Ruby string string to a JSON string, encoded with UTF16 big endian characters as u????, and return it.



42
43
44
45
46
47
48
 
# File 'lib/json/pure/generator.rb', line 42

def utf8_to_json(string) # :nodoc:
  string = string.dup
  string.force_encoding(::Encoding::ASCII_8BIT)
  string.gsub!(/["\\\x0-\x1f]/) { MAP[$&] }
  string.force_encoding(::Encoding::UTF_8)
  string
end

.utf8_to_json_ascii(string) ⇒ Object

:nodoc:



50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/json/pure/generator.rb', line 50

def utf8_to_json_ascii(string) # :nodoc:
  string = string.dup
  string.force_encoding(::Encoding::ASCII_8BIT)
  string.gsub!(/["\\\x0-\x1f]/n) { MAP[$&] }
  string.gsub!(/(
    (?:
     [\xc2-\xdf][\x80-\xbf]    |
     [\xe0-\xef][\x80-\xbf]{2} |
     [\xf0-\xf4][\x80-\xbf]{3}
    )+ |
    [\x80-\xc1\xf5-\xff]       # invalid
  )/nx) { |c|
    c.size == 1 and raise GeneratorError, "invalid utf8 byte: '#{c}'"
    s = JSON.iconv('utf-16be', 'utf-8', c).unpack('H*')[0]
    s.force_encoding(::Encoding::ASCII_8BIT)
    s.gsub!(/.{4}/n, '\\\\u\&')
    s.force_encoding(::Encoding::UTF_8)
  }
  string.force_encoding(::Encoding::UTF_8)
  string
rescue => e
  raise GeneratorError.wrap(e)
end

.valid_utf8?(string) ⇒ Boolean

Returns:

  • (Boolean) 


74
75
76
77
78
 
# File 'lib/json/pure/generator.rb', line 74

def valid_utf8?(string)
  encoding = string.encoding
  (encoding == Encoding::UTF_8 || encoding == Encoding::ASCII) &&
    string.valid_encoding?
end