From 4ede0a7d1957bab4df69c81ef0808c83f0930931 Mon Sep 17 00:00:00 2001 From: zverok Date: Thu, 8 Mar 2018 17:32:36 +0200 Subject: [PATCH] Enchance generic JSON and #generate docs --- lib/json.rb | 50 +++++++++++++++++++++++++++++++++++++++++----- lib/json/common.rb | 29 +++++++++++++++------------ 2 files changed, 61 insertions(+), 18 deletions(-) diff --git a/lib/json.rb b/lib/json.rb index 947ac630..ec9b571b 100644 --- a/lib/json.rb +++ b/lib/json.rb @@ -9,8 +9,11 @@ # 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' # # my_hash = JSON.parse('{"hello": "goodbye"}') -# puts my_hash["hello"] => "goodbye" +# puts my_hash["hello"] # => "goodbye" # # Notice the extra quotes '' 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' # # 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\"}" +# +# JSON.generate only allows objects or arrays to be converted +# to JSON syntax. to_json, 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/lib/json/common.rb b/lib/json/common.rb index 3be9fd8d..5ba8f1d2 100644 --- a/lib/json/common.rb +++ b/lib/json/common.rb @@ -180,27 +180,30 @@ def parse!(source, opts = {}) 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 JSON::State 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: ''), + # * *space*: a string that is put after a : pair 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: ''), # * *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 max_nesting: false, 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