Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Enhance generic JSON and #generate docs #347

Merged
merged 2 commits into from
Jan 6, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 45 additions & 5 deletions lib/json.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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
#
Expand All @@ -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 <tt>''</tt> around the hash notation. Ruby expects
# the argument to be a string and can't convert objects like a hash or array.
Expand All @@ -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\"}"
#
# <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'

Expand Down
29 changes: 16 additions & 13 deletions lib/json/common.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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 <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
Expand Down