summaryrefslogtreecommitdiff
path: root/ext/json/lib
diff options
context:
space:
mode:
authorzverok <zverok.offline@gmail.com>2018-03-08 17:32:36 +0200
committerHiroshi SHIBATA <hsbt@ruby-lang.org>2020-01-06 15:13:15 +0900
commit2e5ef30cb9f56e5a7a8139e0f1d75bbcf5ee8362 (patch)
treec61ed15ef8cce5142c68af27e0706e5e498fe75c /ext/json/lib
parent1658e6b5db0380c39d2423281e10acc5b6c6a8bd (diff)
[flori/json] Enchance generic JSON and #generate docs
https://github.com/flori/json/commit/4ede0a7d19
Diffstat (limited to 'ext/json/lib')
-rw-r--r--ext/json/lib/json.rb50
-rw-r--r--ext/json/lib/json/common.rb29
2 files changed, 61 insertions, 18 deletions
diff --git a/ext/json/lib/json.rb b/ext/json/lib/json.rb
index 947ac630ad9..ec9b571be2d 100644
--- a/ext/json/lib/json.rb
+++ b/ext/json/lib/json.rb
@@ -9,8 +9,11 @@ require 'json/common'
# JSON is completely language agnostic, making it the ideal interchange format.
#
# Built on two universally available structures:
-# 1. A collection of name/value pairs. Often referred to as an _object_, hash table, record, struct, keyed list, or associative array.
-# 2. An ordered list of values. More commonly called an _array_, vector, sequence or list.
+#
+# 1. A collection of name/value pairs. Often referred to as an _object_, hash table,
+# record, struct, keyed list, or associative array.
+# 2. An ordered list of values. More commonly called an _array_, vector, sequence or
+# list.
#
# To read more about JSON visit: http://json.org
#
@@ -22,7 +25,7 @@ require 'json/common'
# require 'json'
#
# my_hash = JSON.parse('{"hello": "goodbye"}')
-# puts my_hash["hello"] => "goodbye"
+# puts my_hash["hello"] # => "goodbye"
#
# Notice the extra quotes <tt>''</tt> around the hash notation. Ruby expects
# the argument to be a string and can't convert objects like a hash or array.
@@ -37,13 +40,50 @@ require 'json/common'
# require 'json'
#
# my_hash = {:hello => "goodbye"}
-# puts JSON.generate(my_hash) => "{\"hello\":\"goodbye\"}"
+# puts JSON.generate(my_hash) # => "{\"hello\":\"goodbye\"}"
#
# Or an alternative way:
#
# require 'json'
-# puts {:hello => "goodbye"}.to_json => "{\"hello\":\"goodbye\"}"
+# puts {:hello => "goodbye"}.to_json # => "{\"hello\":\"goodbye\"}"
+#
+# <tt>JSON.generate</tt> only allows objects or arrays to be converted
+# to JSON syntax. <tt>to_json</tt>, however, accepts many Ruby classes
+# even though it acts only as a method for serialization:
+#
+# require 'json'
#
+# 1.to_json => "1"
+#
+# The {#generate}[rdoc-ref:JSON#generate] method accepts a variety of options
+# to set the formatting of string output and defining what input is accepteable.
+# There are also shortcut methods pretty_generate (with a set of options to
+# generate human-readable multiline JSON) and fast_generate (with a set of
+# options to generate JSON faster at the price of disabling some checks).
+#
+# == Extended rendering and loading of Ruby objects
+#
+# JSON library provides optional _additions_ allowing to serialize and
+# deserialize Ruby classes without loosing their type.
+#
+# # without additions
+# require "json"
+# json = JSON.generate({range: 1..3, regex: /test/})
+# # => '{"range":"1..3","regex":"(?-mix:test)"}'
+# JSON.parse(json)
+# # => {"range"=>"1..3", "regex"=>"(?-mix:test)"}
+#
+# # with additions
+# require "json/add/range"
+# require "json/add/regexp"
+# json = JSON.generate({range: 1..3, regex: /test/})
+# # => '{"range":{"json_class":"Range","a":[1,3,false]},"regex":{"json_class":"Regexp","o":0,"s":"test"}}'
+# JSON.parse(json)
+# # => {"range"=>{"json_class"=>"Range", "a"=>[1, 3, false]}, "regex"=>{"json_class"=>"Regexp", "o"=>0, "s"=>"test"}}
+# JSON.load(json)
+# # => {"range"=>1..3, "regex"=>/test/}
+#
+# See JSON.load for details.
module JSON
require 'json/version'
diff --git a/ext/json/lib/json/common.rb b/ext/json/lib/json/common.rb
index 3be9fd8dc55..5ba8f1d298d 100644
--- a/ext/json/lib/json/common.rb
+++ b/ext/json/lib/json/common.rb
@@ -180,27 +180,30 @@ module JSON
end
# Generate a JSON document from the Ruby data structure _obj_ and return
- # it. _state_ is * a JSON::State object,
- # * or a Hash like object (responding to to_hash),
- # * an object convertible into a hash by a to_h method,
- # that is used as or to configure a State object.
+ # it. _opts_ is
+ # * a Hash like object (responding to +to_hash+),
+ # * or an object convertible into a hash by a +to_h+ method,
+ # * or a <tt>JSON::State</tt> object.
#
- # It defaults to a state object, that creates the shortest possible JSON text
- # in one line, checks for circular data structures and doesn't allow NaN,
+ # If hash-alike or hash-convertible object is provided, it is internally
+ # converted into a State object.
+ #
+ # The default options are set to create the shortest possible JSON text
+ # in one line, check for circular data structures and do not allow NaN,
# Infinity, and -Infinity.
#
- # A _state_ hash can have the following keys:
- # * *indent*: a string used to indent levels (default: ''),
- # * *space*: a string that is put after, a : or , delimiter (default: ''),
- # * *space_before*: a string that is put before a : pair delimiter (default: ''),
- # * *object_nl*: a string that is put at the end of a JSON object (default: ''),
- # * *array_nl*: a string that is put at the end of a JSON array (default: ''),
+ # An _opts_ hash can have the following keys:
+ # * *indent*: a string used to indent levels (default: <tt>''</tt>),
+ # * *space*: a string that is put after a <tt>:</tt> pair delimiter (default: <tt>''</tt>),
+ # * *space_before*: a string that is put before a <tt>:</tt> pair delimiter (default: <tt>''</tt>),
+ # * *object_nl*: a string that is put at the end of a JSON object (default: <tt>''</tt>),
+ # * *array_nl*: a string that is put at the end of a JSON array (default: <tt>''</tt>),
# * *allow_nan*: true if NaN, Infinity, and -Infinity should be
# generated, otherwise an exception is thrown if these values are
# encountered. This options defaults to false.
# * *max_nesting*: The maximum depth of nesting allowed in the data
# structures from which JSON is to be generated. Disable depth checking
- # with :max_nesting => false, it defaults to 100.
+ # with <tt>max_nesting: false</tt>, it defaults to 100.
#
# See also the fast_generate for the fastest creation method with the least
# amount of sanity checks, and the pretty_generate method for some