json 2.6.2 → 2.7.2

data/lib/json/add/range.rb

@@ -5,14 +5,29 @@ end
 
 class Range
 
-  # Deserializes JSON string by constructing new Range object with arguments
-  # <tt>a</tt> serialized by <tt>to_json</tt>.
+  # See #as_json.
   def self.json_create(object)
     new(*object['a'])
   end
 
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods <tt>Range#as_json</tt> and +Range.json_create+ may be used
+  # to serialize and deserialize a \Range object;
+  # see Marshal[https://docs.ruby-lang.org/en/master/Marshal.html].
+  #
+  # \Method <tt>Range#as_json</tt> serializes +self+,
+  # returning a 2-element hash representing +self+:
+  #
+  #   require 'json/add/range'
+  #   x = (1..4).as_json     # => {"json_class"=>"Range", "a"=>[1, 4, false]}
+  #   y = (1...4).as_json    # => {"json_class"=>"Range", "a"=>[1, 4, true]}
+  #   z = ('a'..'d').as_json # => {"json_class"=>"Range", "a"=>["a", "d", false]}
+  #
+  # \Method +JSON.create+ deserializes such a hash, returning a \Range object:
+  #
+  #   Range.json_create(x) # => 1..4
+  #   Range.json_create(y) # => 1...4
+  #   Range.json_create(z) # => "a".."d"
+  #
   def as_json(*)
     {
       JSON.create_id  => self.class.name,
@@ -20,9 +35,19 @@ class Range
     }
   end
 
-  # Stores class name (Range) with JSON array of arguments <tt>a</tt> which
-  # include <tt>first</tt> (integer), <tt>last</tt> (integer), and
-  # <tt>exclude_end?</tt> (boolean) as JSON string.
+  # Returns a JSON string representing +self+:
+  #
+  #   require 'json/add/range'
+  #   puts (1..4).to_json
+  #   puts (1...4).to_json
+  #   puts ('a'..'d').to_json
+  #
+  # Output:
+  #
+  #   {"json_class":"Range","a":[1,4,false]}
+  #   {"json_class":"Range","a":[1,4,true]}
+  #   {"json_class":"Range","a":["a","d",false]}
+  #
   def to_json(*args)
     as_json.to_json(*args)
   end

data/lib/json/add/rational.rb

@@ -4,14 +4,28 @@ unless defined?(::JSON::JSON_LOADED) and ::JSON::JSON_LOADED
 end
 
 class Rational
-  # Deserializes JSON string by converting numerator value <tt>n</tt>,
-  # denominator value <tt>d</tt>, to a Rational object.
+
+  # See #as_json.
   def self.json_create(object)
     Rational(object['n'], object['d'])
   end
 
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods <tt>Rational#as_json</tt> and +Rational.json_create+ may be used
+  # to serialize and deserialize a \Rational object;
+  # see Marshal[https://docs.ruby-lang.org/en/master/Marshal.html].
+  #
+  # \Method <tt>Rational#as_json</tt> serializes +self+,
+  # returning a 2-element hash representing +self+:
+  #
+  #   require 'json/add/rational'
+  #   x = Rational(2, 3).as_json
+  #   # => {"json_class"=>"Rational", "n"=>2, "d"=>3}
+  #
+  # \Method +JSON.create+ deserializes such a hash, returning a \Rational object:
+  #
+  #   Rational.json_create(x)
+  #   # => (2/3)
+  #
   def as_json(*)
     {
       JSON.create_id => self.class.name,
@@ -20,7 +34,15 @@ class Rational
     }
   end
 
-  # Stores class name (Rational) along with numerator value <tt>n</tt> and denominator value <tt>d</tt> as JSON string
+  # Returns a JSON string representing +self+:
+  #
+  #   require 'json/add/rational'
+  #   puts Rational(2, 3).to_json
+  #
+  # Output:
+  #
+  #   {"json_class":"Rational","n":2,"d":3}
+  #
   def to_json(*args)
     as_json.to_json(*args)
   end

data/lib/json/add/regexp.rb

@@ -5,15 +5,26 @@ end
 
 class Regexp
 
-  # Deserializes JSON string by constructing new Regexp object with source
-  # <tt>s</tt> (Regexp or String) and options <tt>o</tt> serialized by
-  # <tt>to_json</tt>
+  # See #as_json.
   def self.json_create(object)
     new(object['s'], object['o'])
   end
 
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods <tt>Regexp#as_json</tt> and +Regexp.json_create+ may be used
+  # to serialize and deserialize a \Regexp object;
+  # see Marshal[https://docs.ruby-lang.org/en/master/Marshal.html].
+  #
+  # \Method <tt>Regexp#as_json</tt> serializes +self+,
+  # returning a 2-element hash representing +self+:
+  #
+  #   require 'json/add/regexp'
+  #   x = /foo/.as_json
+  #   # => {"json_class"=>"Regexp", "o"=>0, "s"=>"foo"}
+  #
+  # \Method +JSON.create+ deserializes such a hash, returning a \Regexp object:
+  #
+  #   Regexp.json_create(x) # => /foo/
+  #
   def as_json(*)
     {
       JSON.create_id => self.class.name,
@@ -22,8 +33,15 @@ class Regexp
     }
   end
 
-  # Stores class name (Regexp) with options <tt>o</tt> and source <tt>s</tt>
-  # (Regexp or String) as JSON string
+  # Returns a JSON string representing +self+:
+  #
+  #   require 'json/add/regexp'
+  #   puts /foo/.to_json
+  #
+  # Output:
+  #
+  #    {"json_class":"Regexp","o":0,"s":"foo"}
+  #
   def to_json(*args)
     as_json.to_json(*args)
   end

data/lib/json/add/set.rb

@@ -4,16 +4,27 @@ end
 defined?(::Set) or require 'set'
 
 class Set
-  # Import a JSON Marshalled object.
-  #
-  # method used for JSON marshalling support.
+
+  # See #as_json.
   def self.json_create(object)
     new object['a']
   end
 
-  # Marshal the object to JSON.
+  # Methods <tt>Set#as_json</tt> and +Set.json_create+ may be used
+  # to serialize and deserialize a \Set object;
+  # see Marshal[https://docs.ruby-lang.org/en/master/Marshal.html].
+  #
+  # \Method <tt>Set#as_json</tt> serializes +self+,
+  # returning a 2-element hash representing +self+:
+  #
+  #   require 'json/add/set'
+  #   x = Set.new(%w/foo bar baz/).as_json
+  #   # => {"json_class"=>"Set", "a"=>["foo", "bar", "baz"]}
+  #
+  # \Method +JSON.create+ deserializes such a hash, returning a \Set object:
+  #
+  #   Set.json_create(x) # => #<Set: {"foo", "bar", "baz"}>
   #
-  # method used for JSON marshalling support.
   def as_json(*)
     {
       JSON.create_id => self.class.name,
@@ -21,7 +32,15 @@ class Set
     }
   end
 
-  # return the JSON value
+  # Returns a JSON string representing +self+:
+  #
+  #   require 'json/add/set'
+  #   puts Set.new(%w/foo bar baz/).to_json
+  #
+  # Output:
+  #
+  #   {"json_class":"Set","a":["foo","bar","baz"]}
+  #
   def to_json(*args)
     as_json.to_json(*args)
   end

data/lib/json/add/struct.rb

@@ -5,14 +5,28 @@ end
 
 class Struct
 
-  # Deserializes JSON string by constructing new Struct object with values
-  # <tt>v</tt> serialized by <tt>to_json</tt>.
+  # See #as_json.
   def self.json_create(object)
     new(*object['v'])
   end
 
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods <tt>Struct#as_json</tt> and +Struct.json_create+ may be used
+  # to serialize and deserialize a \Struct object;
+  # see Marshal[https://docs.ruby-lang.org/en/master/Marshal.html].
+  #
+  # \Method <tt>Struct#as_json</tt> serializes +self+,
+  # returning a 2-element hash representing +self+:
+  #
+  #   require 'json/add/struct'
+  #   Customer = Struct.new('Customer', :name, :address, :zip)
+  #   x = Struct::Customer.new.as_json
+  #   # => {"json_class"=>"Struct::Customer", "v"=>[nil, nil, nil]}
+  #
+  # \Method +JSON.create+ deserializes such a hash, returning a \Struct object:
+  #
+  #   Struct::Customer.json_create(x)
+  #   # => #<struct Struct::Customer name=nil, address=nil, zip=nil>
+  #
   def as_json(*)
     klass = self.class.name
     klass.to_s.empty? and raise JSON::JSONError, "Only named structs are supported!"
@@ -22,8 +36,16 @@ class Struct
     }
   end
 
-  # Stores class name (Struct) with Struct values <tt>v</tt> as a JSON string.
-  # Only named structs are supported.
+  # Returns a JSON string representing +self+:
+  #
+  #   require 'json/add/struct'
+  #   Customer = Struct.new('Customer', :name, :address, :zip)
+  #   puts Struct::Customer.new.to_json
+  #
+  # Output:
+  #
+  #   {"json_class":"Struct","t":{'name':'Rowdy',"age":null}}
+  #
   def to_json(*args)
     as_json.to_json(*args)
   end

data/lib/json/add/symbol.rb

@@ -1,11 +1,26 @@
+
 #frozen_string_literal: false
 unless defined?(::JSON::JSON_LOADED) and ::JSON::JSON_LOADED
   require 'json'
 end
 
 class Symbol
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+
+  # Methods <tt>Symbol#as_json</tt> and +Symbol.json_create+ may be used
+  # to serialize and deserialize a \Symbol object;
+  # see Marshal[https://docs.ruby-lang.org/en/master/Marshal.html].
+  #
+  # \Method <tt>Symbol#as_json</tt> serializes +self+,
+  # returning a 2-element hash representing +self+:
+  #
+  #   require 'json/add/symbol'
+  #   x = :foo.as_json
+  #   # => {"json_class"=>"Symbol", "s"=>"foo"}
+  #
+  # \Method +JSON.create+ deserializes such a hash, returning a \Symbol object:
+  #
+  #   Symbol.json_create(x) # => :foo
+  #
   def as_json(*)
     {
       JSON.create_id => self.class.name,
@@ -13,12 +28,20 @@ class Symbol
     }
   end
 
-  # Stores class name (Symbol) with String representation of Symbol as a JSON string.
+  # Returns a JSON string representing +self+:
+  #
+  #   require 'json/add/symbol'
+  #   puts :foo.to_json
+  #
+  # Output:
+  #
+  #   # {"json_class":"Symbol","s":"foo"}
+  #
   def to_json(*a)
     as_json.to_json(*a)
   end
 
-  # Deserializes JSON string by converting the <tt>string</tt> value stored in the object to a Symbol
+  # See #as_json.
   def self.json_create(o)
     o['s'].to_sym
   end

data/lib/json/add/time.rb

@@ -5,7 +5,7 @@ end
 
 class Time
 
-  # Deserializes JSON string by converting time since epoch to Time
+  # See #as_json.
   def self.json_create(object)
     if usec = object.delete('u') # used to be tv_usec -> tv_nsec
       object['n'] = usec * 1000
@@ -17,8 +17,22 @@ class Time
     end
   end
 
-  # Returns a hash, that will be turned into a JSON object and represent this
-  # object.
+  # Methods <tt>Time#as_json</tt> and +Time.json_create+ may be used
+  # to serialize and deserialize a \Time object;
+  # see Marshal[https://docs.ruby-lang.org/en/master/Marshal.html].
+  #
+  # \Method <tt>Time#as_json</tt> serializes +self+,
+  # returning a 2-element hash representing +self+:
+  #
+  #   require 'json/add/time'
+  #   x = Time.now.as_json
+  #   # => {"json_class"=>"Time", "s"=>1700931656, "n"=>472846644}
+  #
+  # \Method +JSON.create+ deserializes such a hash, returning a \Time object:
+  #
+  #    Time.json_create(x)
+  #    # => 2023-11-25 11:00:56.472846644 -0600
+  #
   def as_json(*)
     nanoseconds = [ tv_usec * 1000 ]
     respond_to?(:tv_nsec) and nanoseconds << tv_nsec
@@ -30,8 +44,15 @@ class Time
     }
   end
 
-  # Stores class name (Time) with number of seconds since epoch and number of
-  # microseconds for Time as JSON string
+  # Returns a JSON string representing +self+:
+  #
+  #   require 'json/add/time'
+  #   puts Time.now.to_json
+  #
+  # Output:
+  #
+  #   {"json_class":"Time","s":1700931678,"n":980650786}
+  #
   def to_json(*args)
     as_json.to_json(*args)
   end

data/lib/json/common.rb

@@ -1,8 +1,12 @@
 #frozen_string_literal: false
 require 'json/version'
-require 'json/generic_object'
 
 module JSON
+  autoload :GenericObject, 'json/generic_object'
+
+  NOT_SET = Object.new.freeze
+  private_constant :NOT_SET
+
   class << self
     # :call-seq:
     #   JSON[object] -> new_array or new_string
@@ -295,19 +299,9 @@ module JSON
   #
   def generate(obj, opts = nil)
     if State === opts
-      state, opts = opts, nil
+      state = opts
     else
-      state = State.new
-    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)
+      state = State.new(opts)
     end
     state.generate(obj)
   end
@@ -334,19 +328,9 @@ module JSON
   #   JSON.fast_generate(a)
   def fast_generate(obj, opts = nil)
     if State === opts
-      state, opts = opts, nil
+      state = opts
     else
-      state = JSON.create_fast_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)
+      state = JSON.create_fast_state.configure(opts)
     end
     state.generate(obj)
   end
@@ -592,13 +576,13 @@ module JSON
     # Sets or returns the default options for the JSON.dump method.
     # Initially:
     #   opts = JSON.dump_default_options
-    #   opts # => {:max_nesting=>false, :allow_nan=>true, :escape_slash=>false}
+    #   opts # => {:max_nesting=>false, :allow_nan=>true, :script_safe=>false}
     attr_accessor :dump_default_options
   end
   self.dump_default_options = {
     :max_nesting => false,
     :allow_nan   => true,
-    :escape_slash => false,
+    :script_safe => false,
   }
 
   # :call-seq:
@@ -628,16 +612,18 @@ module JSON
   #   puts File.read(path)
   # Output:
   #   {"foo":[0,1],"bar":{"baz":2,"bat":3},"bam":"bad"}
-  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
+  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
@@ -653,6 +639,15 @@ module JSON
   def self.iconv(to, from, string)
     string.encode(to, from)
   end
+
+  def merge_dump_options(opts, strict: NOT_SET)
+    opts = opts.merge(strict: strict) if NOT_SET != strict
+    opts
+  end
+
+  class << self
+    private :merge_dump_options
+  end
 end
 
 module ::Kernel

data/lib/json/generic_object.rb

@@ -1,5 +1,9 @@
 #frozen_string_literal: false
-require 'ostruct'
+begin
+  require 'ostruct'
+rescue LoadError
+  warn "JSON::GenericObject requires 'ostruct'. Please install it with `gem install ostruct`."
+end
 
 module JSON
   class GenericObject < OpenStruct
@@ -67,5 +71,5 @@ module JSON
     def to_json(*a)
       as_json.to_json(*a)
     end
-  end
+  end if defined?(::OpenStruct)
 end