json 2.7.1-java → 2.7.3.rc1-java

data/README.md

@@ -0,0 +1,264 @@
+# JSON implementation for Ruby
+
+[![CI](https://github.com/ruby/json/actions/workflows/ci.yml/badge.svg)](https://github.com/ruby/json/actions/workflows/ci.yml)
+
+## Description
+
+This is an implementation of the JSON specification according to RFC 7159
+http://www.ietf.org/rfc/rfc7159.txt . There is two variants available:
+
+* A pure ruby variant, that relies on the `strscan` extensions, which is
+  part of the ruby standard library.
+* The quite a bit faster native extension variant, which is in parts
+  implemented in C or Java and comes with a parser generated by the [Ragel]
+  state machine compiler.
+
+Both variants of the JSON generator generate UTF-8 character sequences by
+default. If an :ascii\_only option with a true value is given, they escape all
+non-ASCII and control characters with \uXXXX escape sequences, and support
+UTF-16 surrogate pairs in order to be able to generate the whole range of
+unicode code points.
+
+All strings, that are to be encoded as JSON strings, should be UTF-8 byte
+sequences on the Ruby side. To encode raw binary strings, that aren't UTF-8
+encoded, please use the to\_json\_raw\_object method of String (which produces
+an object, that contains a byte array) and decode the result on the receiving
+endpoint.
+
+## Installation
+
+It's recommended to use the extension variant of JSON, because it's faster than
+the pure ruby variant. If you cannot build it on your system, you can settle
+for the latter.
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add json
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install json
+
+
+There is also a pure ruby json only variant of the gem, that can be installed
+with:
+
+    $ gem install json_pure
+
+## Usage
+
+To use JSON you can
+
+```ruby
+require 'json'
+```
+
+to load the installed variant (either the extension `'json'` or the pure
+variant `'json_pure'`). If you have installed the extension variant, you can
+pick either the extension variant or the pure variant by typing
+
+```ruby
+require 'json/ext'
+```
+
+or
+
+```ruby
+require 'json/pure'
+```
+
+Now you can parse a JSON document into a ruby data structure by calling
+
+```ruby
+JSON.parse(document)
+```
+
+If you want to generate a JSON document from a ruby data structure call
+```ruby
+JSON.generate(data)
+```
+
+You can also use the `pretty_generate` method (which formats the output more
+verbosely and nicely) or `fast_generate` (which doesn't do any of the security
+checks generate performs, e. g. nesting deepness checks).
+
+There are also the JSON and JSON[] methods which use parse on a String or
+generate a JSON document from an array or hash:
+
+```ruby
+document = JSON 'test'  => 23 # => "{\"test\":23}"
+document = JSON['test' => 23] # => "{\"test\":23}"
+```
+
+and
+
+```ruby
+data = JSON '{"test":23}'  # => {"test"=>23}
+data = JSON['{"test":23}'] # => {"test"=>23}
+```
+
+You can choose to load a set of common additions to ruby core's objects if
+you
+
+```ruby
+require 'json/add/core'
+```
+
+After requiring this you can, e. g., serialise/deserialise Ruby ranges:
+
+```ruby
+JSON JSON(1..10) # => 1..10
+```
+
+To find out how to add JSON support to other or your own classes, read the
+section "More Examples" below.
+
+## Serializing exceptions
+
+The JSON module doesn't extend `Exception` by default. If you convert an `Exception`
+object to JSON, it will by default only include the exception message.
+
+To include the full details, you must either load the `json/add/core` mentioned
+above, or specifically load the exception addition:
+
+```ruby
+require 'json/add/exception'
+```
+
+## More Examples
+
+To create a JSON document from a ruby data structure, you can call
+`JSON.generate` like that:
+
+```ruby
+json = JSON.generate [1, 2, {"a"=>3.141}, false, true, nil, 4..10]
+# => "[1,2,{\"a\":3.141},false,true,null,\"4..10\"]"
+```
+
+To get back a ruby data structure from a JSON document, you have to call
+JSON.parse on it:
+
+```ruby
+JSON.parse json
+# => [1, 2, {"a"=>3.141}, false, true, nil, "4..10"]
+```
+
+Note, that the range from the original data structure is a simple
+string now. The reason for this is, that JSON doesn't support ranges
+or arbitrary classes. In this case the json library falls back to call
+`Object#to_json`, which is the same as `#to_s.to_json`.
+
+It's possible to add JSON support serialization to arbitrary classes by
+simply implementing a more specialized version of the `#to_json method`, that
+should return a JSON object (a hash converted to JSON with `#to_json`) like
+this (don't forget the `*a` for all the arguments):
+
+```ruby
+class Range
+  def to_json(*a)
+    {
+      'json_class'   => self.class.name, # = 'Range'
+      'data'         => [ first, last, exclude_end? ]
+    }.to_json(*a)
+  end
+end
+```
+
+The hash key `json_class` is the class, that will be asked to deserialise the
+JSON representation later. In this case it's `Range`, but any namespace of
+the form `A::B` or `::A::B` will do. All other keys are arbitrary and can be
+used to store the necessary data to configure the object to be deserialised.
+
+If the key `json_class` is found in a JSON object, the JSON parser checks
+if the given class responds to the `json_create` class method. If so, it is
+called with the JSON object converted to a Ruby hash. So a range can
+be deserialised by implementing `Range.json_create` like this:
+
+```ruby
+class Range
+  def self.json_create(o)
+    new(*o['data'])
+  end
+end
+```
+
+Now it possible to serialise/deserialise ranges as well:
+
+```ruby
+json = JSON.generate [1, 2, {"a"=>3.141}, false, true, nil, 4..10]
+# => "[1,2,{\"a\":3.141},false,true,null,{\"json_class\":\"Range\",\"data\":[4,10,false]}]"
+JSON.parse json
+# => [1, 2, {"a"=>3.141}, false, true, nil, 4..10]
+json = JSON.generate [1, 2, {"a"=>3.141}, false, true, nil, 4..10]
+# => "[1,2,{\"a\":3.141},false,true,null,{\"json_class\":\"Range\",\"data\":[4,10,false]}]"
+JSON.parse json, :create_additions => true
+# => [1, 2, {"a"=>3.141}, false, true, nil, 4..10]
+```
+
+`JSON.generate` always creates the shortest possible string representation of a
+ruby data structure in one line. This is good for data storage or network
+protocols, but not so good for humans to read. Fortunately there's also
+`JSON.pretty_generate` (or `JSON.pretty_generate`) that creates a more readable
+output:
+
+```ruby
+ puts JSON.pretty_generate([1, 2, {"a"=>3.141}, false, true, nil, 4..10])
+ [
+   1,
+   2,
+   {
+     "a": 3.141
+   },
+   false,
+   true,
+   null,
+   {
+     "json_class": "Range",
+     "data": [
+       4,
+       10,
+       false
+     ]
+   }
+ ]
+```
+
+There are also the methods `Kernel#j` for generate, and `Kernel#jj` for
+`pretty_generate` output to the console, that work analogous to Core Ruby's `p` and
+the `pp` library's `pp` methods.
+
+## Development
+
+### Release
+
+Update the `lib/json/version.rb` file.
+
+```
+rbenv shell 2.6.5
+rake build
+gem push pkg/json-2.3.0.gem
+
+rbenv shell jruby-9.2.9.0
+rake build
+gem push pkg/json-2.3.0-java.gem
+```
+
+## Author
+
+Florian Frank <mailto:flori@ping.de>
+
+## License
+
+Ruby License, see https://www.ruby-lang.org/en/about/license.txt.
+
+## Download
+
+The latest version of this library can be downloaded at
+
+* https://rubygems.org/gems/json
+
+Online Documentation should be located at
+
+* https://www.rubydoc.info/gems/json
+
+[Ragel]: http://www.colm.net/open-source/ragel/

data/json.gemspec

@@ -0,0 +1,61 @@
+version = File.foreach(File.join(__dir__, "lib/json/version.rb")) do |line|
+  /^\s*VERSION\s*=\s*'(.*)'/ =~ line and break $1
+end rescue nil
+
+spec = Gem::Specification.new do |s|
+  java_ext = Gem::Platform === s.platform && s.platform =~ 'java' || RUBY_ENGINE == 'jruby'
+
+  s.name = "json"
+  s.version = version
+
+  s.summary = "JSON Implementation for Ruby"
+  s.homepage = "https://ruby.github.io/json"
+  s.metadata = {
+    'bug_tracker_uri'   => 'https://github.com/ruby/json/issues',
+    'changelog_uri'     => 'https://github.com/ruby/json/blob/master/CHANGES.md',
+    'documentation_uri' => 'https://ruby.github.io/json/doc/index.html',
+    'homepage_uri'      => s.homepage,
+    'source_code_uri'   => 'https://github.com/ruby/json',
+    'wiki_uri'          => 'https://github.com/ruby/json/wiki'
+  }
+
+  s.required_ruby_version = Gem::Requirement.new(">= 2.3")
+
+  if java_ext
+    s.description = "A JSON implementation as a JRuby extension."
+    s.author = "Daniel Luz"
+    s.email = "dev+ruby@mernen.com"
+  else
+    s.description = "This is a JSON implementation as a Ruby extension in C."
+    s.authors = ["Florian Frank"]
+    s.email = "flori@ping.de"
+  end
+
+  s.licenses = ["Ruby"]
+
+  s.extra_rdoc_files = ["README.md"]
+  s.rdoc_options = ["--title", "JSON implementation for Ruby", "--main", "README.md"]
+
+  s.files = [
+    "CHANGES.md",
+    "COPYING",
+    "BSDL",
+    "LEGAL",
+    "README.md",
+    "json.gemspec",
+    *Dir["lib/**/*.rb"],
+  ]
+
+  if java_ext
+    s.platform = 'java'
+  else
+    s.extensions = Dir["ext/json/**/extconf.rb"]
+    s.files += Dir["ext/json/**/*.{c,h,rl}"]
+  end
+end
+
+if RUBY_ENGINE == 'jruby' && $0 == __FILE__
+  Gem::Builder.new(spec).build
+else
+  spec
+end

data/lib/json/add/bigdecimal.rb

@@ -1,4 +1,4 @@
-#frozen_string_literal: false
+# frozen_string_literal: true
 unless defined?(::JSON::JSON_LOADED) and ::JSON::JSON_LOADED
   require 'json'
 end

data/lib/json/add/complex.rb

@@ -1,4 +1,4 @@
-#frozen_string_literal: false
+# frozen_string_literal: true
 unless defined?(::JSON::JSON_LOADED) and ::JSON::JSON_LOADED
   require 'json'
 end

data/lib/json/add/core.rb

@@ -1,4 +1,4 @@
-#frozen_string_literal: false
+# frozen_string_literal: true
 # This file requires the implementations of ruby core's custom objects for
 # serialisation/deserialisation.
 

data/lib/json/add/date.rb

@@ -1,4 +1,4 @@
-#frozen_string_literal: false
+# frozen_string_literal: true
 unless defined?(::JSON::JSON_LOADED) and ::JSON::JSON_LOADED
   require 'json'
 end

data/lib/json/add/date_time.rb

@@ -1,4 +1,4 @@
-#frozen_string_literal: false
+# frozen_string_literal: true
 unless defined?(::JSON::JSON_LOADED) and ::JSON::JSON_LOADED
   require 'json'
 end

data/lib/json/add/exception.rb

@@ -1,4 +1,4 @@
-#frozen_string_literal: false
+# frozen_string_literal: true
 unless defined?(::JSON::JSON_LOADED) and ::JSON::JSON_LOADED
   require 'json'
 end

data/lib/json/add/ostruct.rb

@@ -1,8 +1,11 @@
-#frozen_string_literal: false
+# frozen_string_literal: true
 unless defined?(::JSON::JSON_LOADED) and ::JSON::JSON_LOADED
   require 'json'
 end
-require 'ostruct'
+begin
+  require 'ostruct'
+rescue LoadError
+end
 
 class OpenStruct
 
@@ -48,4 +51,4 @@ class OpenStruct
   def to_json(*args)
     as_json.to_json(*args)
   end
-end
+end if defined?(::OpenStruct)

data/lib/json/add/range.rb

@@ -1,4 +1,4 @@
-#frozen_string_literal: false
+# frozen_string_literal: true
 unless defined?(::JSON::JSON_LOADED) and ::JSON::JSON_LOADED
   require 'json'
 end

data/lib/json/add/rational.rb

@@ -1,4 +1,4 @@
-#frozen_string_literal: false
+# frozen_string_literal: true
 unless defined?(::JSON::JSON_LOADED) and ::JSON::JSON_LOADED
   require 'json'
 end

data/lib/json/add/regexp.rb

@@ -1,4 +1,4 @@
-#frozen_string_literal: false
+# frozen_string_literal: true
 unless defined?(::JSON::JSON_LOADED) and ::JSON::JSON_LOADED
   require 'json'
 end

data/lib/json/add/struct.rb

@@ -1,4 +1,4 @@
-#frozen_string_literal: false
+# frozen_string_literal: true
 unless defined?(::JSON::JSON_LOADED) and ::JSON::JSON_LOADED
   require 'json'
 end

data/lib/json/add/symbol.rb

@@ -1,5 +1,4 @@
-
-#frozen_string_literal: false
+# frozen_string_literal: true
 unless defined?(::JSON::JSON_LOADED) and ::JSON::JSON_LOADED
   require 'json'
 end

data/lib/json/add/time.rb

@@ -1,4 +1,4 @@
-#frozen_string_literal: false
+# frozen_string_literal: true
 unless defined?(::JSON::JSON_LOADED) and ::JSON::JSON_LOADED
   require 'json'
 end
@@ -10,11 +10,7 @@ class Time
     if usec = object.delete('u') # used to be tv_usec -> tv_nsec
       object['n'] = usec * 1000
     end
-    if method_defined?(:tv_nsec)
-      at(object['s'], Rational(object['n'], 1000))
-    else
-      at(object['s'], object['n'] / 1000)
-    end
+    at(object['s'], Rational(object['n'], 1000))
   end
 
   # Methods <tt>Time#as_json</tt> and +Time.json_create+ may be used
@@ -34,13 +30,10 @@ class Time
   #    # => 2023-11-25 11:00:56.472846644 -0600
   #
   def as_json(*)
-    nanoseconds = [ tv_usec * 1000 ]
-    respond_to?(:tv_nsec) and nanoseconds << tv_nsec
-    nanoseconds = nanoseconds.max
     {
       JSON.create_id => self.class.name,
       's'            => tv_sec,
-      'n'            => nanoseconds,
+      'n'            => tv_nsec,
     }
   end
 

data/lib/json/common.rb

@@ -1,8 +1,9 @@
-#frozen_string_literal: false
+#frozen_string_literal: true
 require 'json/version'
-require 'json/generic_object'
 
 module JSON
+  autoload :GenericObject, 'json/generic_object'
+
   NOT_SET = Object.new.freeze
   private_constant :NOT_SET
 
@@ -19,11 +20,16 @@ module JSON
     #   ruby = [0, 1, nil]
     #   JSON[ruby] # => '[0,1,null]'
     def [](object, opts = {})
-      if object.respond_to? :to_str
-        JSON.parse(object.to_str, opts)
-      else
-        JSON.generate(object, opts)
+      if object.is_a?(String)
+        return JSON.parse(object, opts)
+      elsif object.respond_to?(:to_str)
+        str = object.to_str
+        if str.is_a?(String)
+          return JSON.parse(object.to_str, opts)
+        end
       end
+
+      JSON.generate(object, opts)
     end
 
     # Returns the JSON parser class that is used by JSON. This is either
@@ -111,23 +117,17 @@ module JSON
     attr_accessor :state
   end
 
-  DEFAULT_CREATE_ID = 'json_class'.freeze
-  private_constant :DEFAULT_CREATE_ID
-
-  CREATE_ID_TLS_KEY = "JSON.create_id".freeze
-  private_constant :CREATE_ID_TLS_KEY
-
   # Sets 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'
   def self.create_id=(new_value)
-    Thread.current[CREATE_ID_TLS_KEY] = new_value.dup.freeze
+    Thread.current[:"JSON.create_id"] = new_value.dup.freeze
   end
 
   # Returns the current create identifier.
   # See also JSON.create_id=.
   def self.create_id
-    Thread.current[CREATE_ID_TLS_KEY] || DEFAULT_CREATE_ID
+    Thread.current[:"JSON.create_id"] || 'json_class'
   end
 
   NaN           = 0.0/0
@@ -215,8 +215,12 @@ module JSON
   #   # Raises JSON::ParserError (783: unexpected token at ''):
   #   JSON.parse('')
   #
-  def parse(source, opts = {})
-    Parser.new(source, **(opts||{})).parse
+  def parse(source, opts = nil)
+    if opts.nil?
+      Parser.new(source).parse
+    else
+      Parser.new(source, opts).parse
+    end
   end
 
   # :call-seq:
@@ -405,7 +409,7 @@ module JSON
   self.load_default_options = {
     :max_nesting      => false,
     :allow_nan        => true,
-    :allow_blank       => true,
+    :allow_blank      => true,
     :create_additions => true,
   }
 
@@ -537,15 +541,23 @@ module JSON
   #      #<Admin:0x00000000064c41f8
   #      @attributes={"type"=>"Admin", "password"=>"0wn3d"}>}
   #
-  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
+  def load(source, proc = nil, options = nil)
+    opts = if options.nil?
+      load_default_options
+    else
+      load_default_options.merge(options)
     end
+
+    unless source.is_a?(String)
+      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
+    end
+
     if opts[:allow_blank] && (source.nil? || source.empty?)
       source = 'null'
     end
@@ -575,13 +587,12 @@ 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, :script_safe=>false}
+    #   opts # => {:max_nesting=>false, :allow_nan=>true}
     attr_accessor :dump_default_options
   end
   self.dump_default_options = {
     :max_nesting => false,
     :allow_nan   => true,
-    :script_safe => false,
   }
 
   # :call-seq:
@@ -612,26 +623,42 @@ module JSON
   # Output:
   #   {"foo":[0,1],"bar":{"baz":2,"bat":3},"bam":"bad"}
   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
+    if kwargs.nil?
+      if limit.nil?
+        if anIO.is_a?(Hash)
+          kwargs = anIO
+          anIO = nil
+        end
+      elsif limit.is_a?(Hash)
+        kwargs = limit
+        limit = nil
+      end
+    end
+
+    unless anIO.nil?
+      if anIO.respond_to?(:to_io)
+        anIO = anIO.to_io
+      elsif limit.nil? && !anIO.respond_to?(:write)
+        anIO, limit = nil, anIO
+      end
     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
+
+    result = begin
+      generate(obj, opts)
+    rescue JSON::NestingError
+      raise ArgumentError, "exceed depth limit"
+    end
+
+    if anIO.nil?
+      result
+    else
       anIO.write result
       anIO
-    else
-      result
     end
-  rescue JSON::NestingError
-    raise ArgumentError, "exceed depth limit"
   end
 
   # Encodes string using String.encode.
@@ -677,11 +704,16 @@ 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.respond_to? :to_str
-      JSON.parse(object.to_str, args.first)
-    else
-      JSON.generate(object, args.first)
+    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