json 2.9.0 → 2.11.3

data/lib/json/common.rb

@@ -5,8 +5,111 @@ require 'json/version'
 module JSON
   autoload :GenericObject, 'json/generic_object'
 
-  NOT_SET = Object.new.freeze
-  private_constant :NOT_SET
+  module ParserOptions # :nodoc:
+    class << self
+      def prepare(opts)
+        if opts[:object_class] || opts[:array_class]
+          opts = opts.dup
+          on_load = opts[:on_load]
+
+          on_load = object_class_proc(opts[:object_class], on_load) if opts[:object_class]
+          on_load = array_class_proc(opts[:array_class], on_load) if opts[:array_class]
+          opts[:on_load] = on_load
+        end
+
+        if opts.fetch(:create_additions, false) != false
+          opts = create_additions_proc(opts)
+        end
+
+        opts
+      end
+
+      private
+
+      def object_class_proc(object_class, on_load)
+        ->(obj) do
+          if Hash === obj
+            object = object_class.new
+            obj.each { |k, v| object[k] = v }
+            obj = object
+          end
+          on_load.nil? ? obj : on_load.call(obj)
+        end
+      end
+
+      def array_class_proc(array_class, on_load)
+        ->(obj) do
+          if Array === obj
+            array = array_class.new
+            obj.each { |v| array << v }
+            obj = array
+          end
+          on_load.nil? ? obj : on_load.call(obj)
+        end
+      end
+
+      # TODO: exctract :create_additions support to another gem for version 3.0
+      def create_additions_proc(opts)
+        if opts[:symbolize_names]
+          raise ArgumentError, "options :symbolize_names and :create_additions cannot be  used in conjunction"
+        end
+
+        opts = opts.dup
+        create_additions = opts.fetch(:create_additions, false)
+        on_load = opts[:on_load]
+        object_class = opts[:object_class] || Hash
+
+        opts[:on_load] = ->(object) do
+          case object
+          when String
+            opts[:match_string]&.each do |pattern, klass|
+              if match = pattern.match(object)
+                create_additions_warning if create_additions.nil?
+                object = klass.json_create(object)
+                break
+              end
+            end
+          when object_class
+            if opts[:create_additions] != false
+              if class_name = object[JSON.create_id]
+                klass = JSON.deep_const_get(class_name)
+                if (klass.respond_to?(:json_creatable?) && klass.json_creatable?) || klass.respond_to?(:json_create)
+                  create_additions_warning if create_additions.nil?
+                  object = klass.json_create(object)
+                end
+              end
+            end
+          end
+
+          on_load.nil? ? object : on_load.call(object)
+        end
+
+        opts
+      end
+
+      GEM_ROOT = File.expand_path("../../../", __FILE__) + "/"
+      def create_additions_warning
+        message = "JSON.load implicit support for `create_additions: true` is deprecated " \
+          "and will be removed in 3.0, use JSON.unsafe_load or explicitly " \
+          "pass `create_additions: true`"
+
+        uplevel = 4
+        caller_locations(uplevel, 10).each do |frame|
+          if frame.path.nil? || frame.path.start_with?(GEM_ROOT) || frame.path.end_with?("/truffle/cext_ruby.rb", ".c")
+            uplevel += 1
+          else
+            break
+          end
+        end
+
+        if RUBY_VERSION >= "3.0"
+          warn(message, uplevel: uplevel - 1, category: :deprecated)
+        else
+          warn(message, uplevel: uplevel - 1)
+        end
+      end
+    end
+  end
 
   class << self
     # :call-seq:
@@ -20,7 +123,7 @@ module JSON
     # Otherwise, calls JSON.generate with +object+ and +opts+ (see method #generate):
     #   ruby = [0, 1, nil]
     #   JSON[ruby] # => '[0,1,null]'
-    def [](object, opts = {})
+    def [](object, opts = nil)
       if object.is_a?(String)
         return JSON.parse(object, opts)
       elsif object.respond_to?(:to_str)
@@ -70,37 +173,38 @@ module JSON
       end
       self.state = generator::State
       const_set :State, self.state
-      const_set :SAFE_STATE_PROTOTYPE, State.new # for JRuby
-      const_set :FAST_STATE_PROTOTYPE, create_fast_state
-      const_set :PRETTY_STATE_PROTOTYPE, create_pretty_state
     ensure
       $VERBOSE = old
     end
 
-    def create_fast_state
-      State.new(
-        :indent         => '',
-        :space          => '',
-        :object_nl      => "",
-        :array_nl       => "",
-        :max_nesting    => false
-      )
-    end
-
-    def create_pretty_state
-      State.new(
-        :indent         => '  ',
-        :space          => ' ',
-        :object_nl      => "\n",
-        :array_nl       => "\n"
-      )
-    end
-
     # Returns the JSON generator module that is used by JSON.
     attr_reader :generator
 
     # Sets or Returns the JSON generator state class that is used by JSON.
     attr_accessor :state
+
+    private
+
+    def deprecated_singleton_attr_accessor(*attrs)
+      args = RUBY_VERSION >= "3.0" ? ", category: :deprecated" : ""
+      attrs.each do |attr|
+        singleton_class.class_eval <<~RUBY
+          def #{attr}
+            warn "JSON.#{attr} is deprecated and will be removed in json 3.0.0", uplevel: 1 #{args}
+            @#{attr}
+          end
+
+          def #{attr}=(val)
+            warn "JSON.#{attr}= is deprecated and will be removed in json 3.0.0", uplevel: 1 #{args}
+            @#{attr} = val
+          end
+
+          def _#{attr}
+            @#{attr}
+          end
+        RUBY
+      end
+    end
   end
 
   # Sets create identifier, which is used to decide if the _json_create_
@@ -116,20 +220,14 @@ module JSON
     Thread.current[:"JSON.create_id"] || 'json_class'
   end
 
-  NaN           = 0.0/0
+  NaN           = Float::NAN
 
-  Infinity      = 1.0/0
+  Infinity      = Float::INFINITY
 
   MinusInfinity = -Infinity
 
   # The base exception for JSON errors.
-  class JSONError < StandardError
-    def self.wrap(exception)
-      obj = new("Wrapped(#{exception.class}): #{exception.message.inspect}")
-      obj.set_backtrace exception.backtrace
-      obj
-    end
-  end
+  class JSONError < StandardError; end
 
   # This exception is raised if a parser error occurs.
   class ParserError < JSONError; end
@@ -138,10 +236,6 @@ module JSON
   # deep.
   class NestingError < ParserError; end
 
-  # :stopdoc:
-  class CircularDatastructure < NestingError; end
-  # :startdoc:
-
   # This exception is raised if a generator or unparser error occurs.
   class GeneratorError < JSONError
     attr_reader :invalid_object
@@ -152,20 +246,40 @@ module JSON
     end
 
     def detailed_message(...)
+      # Exception#detailed_message doesn't exist until Ruby 3.2
+      super_message = defined?(super) ? super : message
+
       if @invalid_object.nil?
-        super
+        super_message
       else
-        "#{super}\nInvalid object: #{@invalid_object.inspect}"
+        "#{super_message}\nInvalid object: #{@invalid_object.inspect}"
       end
     end
   end
 
-  # For backwards compatibility
-  UnparserError = GeneratorError # :nodoc:
+  # Fragment of JSON document that is to be included as is:
+  #   fragment = JSON::Fragment.new("[1, 2, 3]")
+  #   JSON.generate({ count: 3, items: fragments })
+  #
+  # This allows to easily assemble multiple JSON fragments that have
+  # been persisted somewhere without having to parse them nor resorting
+  # to string interpolation.
+  #
+  # Note: no validation is performed on the provided string. It is the
+  # responsability of the caller to ensure the string contains valid JSON.
+  Fragment = Struct.new(:json) do
+    def initialize(json)
+      unless string = String.try_convert(json)
+        raise TypeError, " no implicit conversion of #{json.class} into String"
+      end
+
+      super(string)
+    end
 
-  # This exception is raised if the required unicode support is missing on the
-  # system. Usually this means that the iconv library is not installed.
-  class MissingUnicodeSupport < JSONError; end
+    def to_json(state = nil, *)
+      json
+    end
+  end
 
   module_function
 
@@ -218,9 +332,16 @@ module JSON
   #   JSON.parse('')
   #
   def parse(source, opts = nil)
+    opts = ParserOptions.prepare(opts) unless opts.nil?
     Parser.parse(source, opts)
   end
 
+  PARSE_L_OPTIONS = {
+    max_nesting: false,
+    allow_nan: true,
+  }.freeze
+  private_constant :PARSE_L_OPTIONS
+
   # :call-seq:
   #   JSON.parse!(source, opts) -> object
   #
@@ -232,12 +353,12 @@ module JSON
   # - Option +max_nesting+, if not provided, defaults to +false+,
   #   which disables checking for nesting depth.
   # - Option +allow_nan+, if not provided, defaults to +true+.
-  def parse!(source, opts = {})
-    opts = {
-      :max_nesting  => false,
-      :allow_nan    => true
-    }.merge(opts)
-    Parser.new(source, **(opts||{})).parse
+  def parse!(source, opts = nil)
+    if opts.nil?
+      parse(source, PARSE_L_OPTIONS)
+    else
+      parse(source, PARSE_L_OPTIONS.merge(opts))
+    end
   end
 
   # :call-seq:
@@ -258,7 +379,7 @@ module JSON
   #   JSON.parse!(File.read(path, opts))
   #
   # See method #parse!
-  def load_file!(filespec, opts = {})
+  def load_file!(filespec, opts = nil)
     parse!(File.read(filespec, encoding: Encoding::UTF_8), opts)
   end
 
@@ -306,13 +427,6 @@ module JSON
     end
   end
 
-  # :stopdoc:
-  # I want to deprecate these later, so I'll first be silent about them, and
-  # later delete them.
-  alias unparse generate
-  module_function :unparse
-  # :startdoc:
-
   # :call-seq:
   #   JSON.fast_generate(obj, opts) -> new_string
   #
@@ -327,19 +441,21 @@ module JSON
   #   # Raises SystemStackError (stack level too deep):
   #   JSON.fast_generate(a)
   def fast_generate(obj, opts = nil)
-    if State === opts
-      state = opts
+    if RUBY_VERSION >= "3.0"
+      warn "JSON.fast_generate is deprecated and will be removed in json 3.0.0, just use JSON.generate", uplevel: 1, category: :deprecated
     else
-      state = JSON.create_fast_state.configure(opts)
+      warn "JSON.fast_generate is deprecated and will be removed in json 3.0.0, just use JSON.generate", uplevel: 1
     end
-    state.generate(obj)
+    generate(obj, opts)
   end
 
-  # :stopdoc:
-  # I want to deprecate these later, so I'll first be silent about them, and later delete them.
-  alias fast_unparse fast_generate
-  module_function :fast_unparse
-  # :startdoc:
+  PRETTY_GENERATE_OPTIONS = {
+    indent: '  ',
+    space: ' ',
+    object_nl: "\n",
+    array_nl: "\n",
+  }.freeze
+  private_constant :PRETTY_GENERATE_OPTIONS
 
   # :call-seq:
   #   JSON.pretty_generate(obj, opts = nil) -> new_string
@@ -372,52 +488,46 @@ module JSON
   #   }
   #
   def pretty_generate(obj, opts = nil)
-    if State === opts
-      state, opts = opts, nil
-    else
-      state = JSON.create_pretty_state
-    end
+    return state.generate(obj) if State === opts
+
+    options = PRETTY_GENERATE_OPTIONS
+
     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"
+      unless opts.is_a?(Hash)
+        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
       end
-      state.configure(opts)
+      options = options.merge(opts)
     end
-    state.generate(obj)
+
+    State.generate(obj, options, nil)
   end
 
-  # :stopdoc:
-  # I want to deprecate these later, so I'll first be silent about them, and later delete them.
-  alias pretty_unparse pretty_generate
-  module_function :pretty_unparse
-  # :startdoc:
+  # Sets or returns default options for the JSON.unsafe_load method.
+  # Initially:
+  #   opts = JSON.load_default_options
+  #   opts # => {:max_nesting=>false, :allow_nan=>true, :allow_blank=>true, :create_additions=>true}
+  deprecated_singleton_attr_accessor :unsafe_load_default_options
 
-  class << self
-    # Sets or returns default options for the JSON.unsafe_load method.
-    # Initially:
-    #   opts = JSON.load_default_options
-    #   opts # => {:max_nesting=>false, :allow_nan=>true, :allow_blank=>true, :create_additions=>true}
-    attr_accessor :unsafe_load_default_options
-  end
-  self.unsafe_load_default_options = {
+  @unsafe_load_default_options = {
     :max_nesting      => false,
     :allow_nan        => true,
     :allow_blank      => true,
     :create_additions => true,
   }
 
-  class << self
-    # 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}
-    attr_accessor :load_default_options
-  end
-  self.load_default_options = {
+  # 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}
+  deprecated_singleton_attr_accessor :load_default_options
+
+  @load_default_options = {
     :allow_nan        => true,
     :allow_blank      => true,
     :create_additions => nil,
@@ -553,9 +663,9 @@ module JSON
   #
   def unsafe_load(source, proc = nil, options = nil)
     opts = if options.nil?
-      unsafe_load_default_options
+      _unsafe_load_default_options
     else
-      unsafe_load_default_options.merge(options)
+      _unsafe_load_default_options.merge(options)
     end
 
     unless source.is_a?(String)
@@ -713,9 +823,9 @@ module JSON
   #
   def load(source, proc = nil, options = nil)
     opts = if options.nil?
-      load_default_options
+      _load_default_options
     else
-      load_default_options.merge(options)
+      _load_default_options.merge(options)
     end
 
     unless source.is_a?(String)
@@ -731,36 +841,21 @@ module JSON
     if opts[:allow_blank] && (source.nil? || source.empty?)
       source = 'null'
     end
-    result = parse(source, opts)
-    recurse_proc(result, &proc) if proc
-    result
-  end
 
-  # Recursively calls passed _Proc_ if the parsed data structure is an _Array_ or _Hash_
-  def recurse_proc(result, &proc) # :nodoc:
-    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
+    if proc
+      opts = opts.dup
+      opts[:on_load] = proc.to_proc
     end
-  end
-
-  alias restore load
-  module_function :restore
 
-  class << self
-    # Sets or returns the default options for the JSON.dump method.
-    # Initially:
-    #   opts = JSON.dump_default_options
-    #   opts # => {:max_nesting=>false, :allow_nan=>true}
-    attr_accessor :dump_default_options
+    parse(source, opts)
   end
-  self.dump_default_options = {
+
+  # Sets or returns the default options for the JSON.dump method.
+  # Initially:
+  #   opts = JSON.dump_default_options
+  #   opts # => {:max_nesting=>false, :allow_nan=>true}
+  deprecated_singleton_attr_accessor :dump_default_options
+  @dump_default_options = {
     :max_nesting => false,
     :allow_nan   => true,
   }
@@ -813,33 +908,152 @@ module JSON
       end
     end
 
-    opts = JSON.dump_default_options
+    opts = JSON._dump_default_options
     opts = opts.merge(:max_nesting => limit) if limit
-    opts = merge_dump_options(opts, **kwargs) if kwargs
+    opts = opts.merge(kwargs) if kwargs
 
     begin
-      if State === opts
-        opts.generate(obj, anIO)
-      else
-        State.generate(obj, opts, anIO)
-      end
+      State.generate(obj, opts, anIO)
     rescue JSON::NestingError
       raise ArgumentError, "exceed depth limit"
     end
   end
 
-  # Encodes string using String.encode.
-  def self.iconv(to, from, string)
-    string.encode(to, from)
+  # :stopdoc:
+  # All these were meant to be deprecated circa 2009, but were just set as undocumented
+  # so usage still exist in the wild.
+  def unparse(...)
+    if RUBY_VERSION >= "3.0"
+      warn "JSON.unparse is deprecated and will be removed in json 3.0.0, just use JSON.generate", uplevel: 1, category: :deprecated
+    else
+      warn "JSON.unparse is deprecated and will be removed in json 3.0.0, just use JSON.generate", uplevel: 1
+    end
+    generate(...)
   end
+  module_function :unparse
+
+  def fast_unparse(...)
+    if RUBY_VERSION >= "3.0"
+      warn "JSON.fast_unparse is deprecated and will be removed in json 3.0.0, just use JSON.generate", uplevel: 1, category: :deprecated
+    else
+      warn "JSON.fast_unparse is deprecated and will be removed in json 3.0.0, just use JSON.generate", uplevel: 1
+    end
+    generate(...)
+  end
+  module_function :fast_unparse
 
-  def merge_dump_options(opts, strict: NOT_SET)
-    opts = opts.merge(strict: strict) if NOT_SET != strict
-    opts
+  def pretty_unparse(...)
+    if RUBY_VERSION >= "3.0"
+      warn "JSON.pretty_unparse is deprecated and will be removed in json 3.0.0, just use JSON.pretty_generate", uplevel: 1, category: :deprecated
+    else
+      warn "JSON.pretty_unparse is deprecated and will be removed in json 3.0.0, just use JSON.pretty_generate", uplevel: 1
+    end
+    pretty_generate(...)
   end
+  module_function :fast_unparse
+
+  def restore(...)
+    if RUBY_VERSION >= "3.0"
+      warn "JSON.restore is deprecated and will be removed in json 3.0.0, just use JSON.load", uplevel: 1, category: :deprecated
+    else
+      warn "JSON.restore is deprecated and will be removed in json 3.0.0, just use JSON.load", uplevel: 1
+    end
+    load(...)
+  end
+  module_function :restore
 
   class << self
-    private :merge_dump_options
+    private
+
+    def const_missing(const_name)
+      case const_name
+      when :PRETTY_STATE_PROTOTYPE
+        if RUBY_VERSION >= "3.0"
+          warn "JSON::PRETTY_STATE_PROTOTYPE is deprecated and will be removed in json 3.0.0, just use JSON.pretty_generate", uplevel: 1, category: :deprecated
+        else
+          warn "JSON::PRETTY_STATE_PROTOTYPE is deprecated and will be removed in json 3.0.0, just use JSON.pretty_generate", uplevel: 1
+        end
+        state.new(PRETTY_GENERATE_OPTIONS)
+      else
+        super
+      end
+    end
+  end
+  # :startdoc:
+
+  # JSON::Coder holds a parser and generator configuration.
+  #
+  #   module MyApp
+  #     JSONC_CODER = JSON::Coder.new(
+  #       allow_trailing_comma: true
+  #     )
+  #   end
+  #
+  #   MyApp::JSONC_CODER.load(document)
+  #
+  class Coder
+    # :call-seq:
+    #   JSON.new(options = nil, &block)
+    #
+    # Argument +options+, if given, contains a \Hash of options for both parsing and generating.
+    # See {Parsing Options}[#module-JSON-label-Parsing+Options], and {Generating Options}[#module-JSON-label-Generating+Options].
+    #
+    # For generation, the <tt>strict: true</tt> option is always set. When a Ruby object with no native \JSON counterpart is
+    # encoutered, the block provided to the initialize method is invoked, and must return a Ruby object that has a native
+    # \JSON counterpart:
+    #
+    #  module MyApp
+    #    API_JSON_CODER = JSON::Coder.new do |object|
+    #      case object
+    #      when Time
+    #        object.iso8601(3)
+    #      else
+    #        object # Unknown type, will raise
+    #      end
+    #    end
+    #  end
+    #
+    #  puts MyApp::API_JSON_CODER.dump(Time.now.utc) # => "2025-01-21T08:41:44.286Z"
+    #
+    def initialize(options = nil, &as_json)
+      if options.nil?
+        options = { strict: true }
+      else
+        options = options.dup
+        options[:strict] = true
+      end
+      options[:as_json] = as_json if as_json
+
+      @state = State.new(options).freeze
+      @parser_config = Ext::Parser::Config.new(ParserOptions.prepare(options))
+    end
+
+    # call-seq:
+    #   dump(object) -> String
+    #   dump(object, io) -> io
+    #
+    # Serialize the given object into a \JSON document.
+    def dump(object, io = nil)
+      @state.generate_new(object, io)
+    end
+    alias_method :generate, :dump
+
+    # call-seq:
+    #   load(string) -> Object
+    #
+    # Parse the given \JSON document and return an equivalent Ruby object.
+    def load(source)
+      @parser_config.parse(source)
+    end
+    alias_method :parse, :load
+
+    # call-seq:
+    #   load(path) -> Object
+    #
+    # Parse the given \JSON document and return an equivalent Ruby object.
+    def load_file(path)
+      load(File.read(path, encoding: Encoding::UTF_8))
+    end
   end
 end
 
@@ -849,6 +1063,12 @@ module ::Kernel
   # Outputs _objs_ to STDOUT as JSON strings in the shortest form, that is in
   # one line.
   def j(*objs)
+    if RUBY_VERSION >= "3.0"
+      warn "Kernel#j is deprecated and will be removed in json 3.0.0", uplevel: 1, category: :deprecated
+    else
+      warn "Kernel#j is deprecated and will be removed in json 3.0.0", uplevel: 1
+    end
+
     objs.each do |obj|
       puts JSON::generate(obj, :allow_nan => true, :max_nesting => false)
     end
@@ -858,6 +1078,12 @@ module ::Kernel
   # Outputs _objs_ to STDOUT as JSON strings in a pretty format, with
   # indentation and over many lines.
   def jj(*objs)
+    if RUBY_VERSION >= "3.0"
+      warn "Kernel#jj is deprecated and will be removed in json 3.0.0", uplevel: 1, category: :deprecated
+    else
+      warn "Kernel#jj is deprecated and will be removed in json 3.0.0", uplevel: 1
+    end
+
     objs.each do |obj|
       puts JSON::pretty_generate(obj, :allow_nan => true, :max_nesting => false)
     end
@@ -870,27 +1096,7 @@ module ::Kernel
   #
   # The _opts_ argument is passed through to generate/parse respectively. See
   # generate and parse for their documentation.
-  def JSON(object, *args)
-    if object.is_a?(String)
-      return JSON.parse(object, args.first)
-    elsif object.respond_to?(:to_str)
-      str = object.to_str
-      if str.is_a?(String)
-        return JSON.parse(object.to_str, args.first)
-      end
-    end
-
-    JSON.generate(object, args.first)
-  end
-end
-
-# Extends any Class to include _json_creatable?_ method.
-class ::Class
-  # Returns true if this class can be used to create an instance
-  # from a serialised JSON string. The class has to implement a class
-  # method _json_create_ that expects a hash as first parameter. The hash
-  # should include the required data.
-  def json_creatable?
-    respond_to?(:json_create)
+  def JSON(object, opts = nil)
+    JSON[object, opts]
   end
 end