README.md in json-2.7.6-java vs README.md in json-2.8.0.alpha1
- old
+ new
@@ -3,20 +3,14 @@
[](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:
+http://www.ietf.org/rfc/rfc7159.txt .
-* 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
+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
@@ -25,50 +19,26 @@
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)
```
@@ -80,55 +50,16 @@
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:
+## Handling arbitrary types
-```ruby
-document = JSON 'test' => 23 # => "{\"test\":23}"
-document = JSON['test' => 23] # => "{\"test\":23}"
-```
+> [!CAUTION]
+> You should never use `JSON.unsafe_load` nor `JSON.parse(str, create_additions: true)` to parse untrusted user input,
+> as it can lead to remote code execution vulnerabilities.
-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]
@@ -189,10 +120,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
+JSON.unsafe_load json
# => [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