Misc #14581 ยป json-docs.patch
| ext/json/lib/json.rb | ||
|---|---|---|
|
# 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
|
||
|
#
|
||
| ... | ... | |
|
# 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.
|
||
| ... | ... | |
|
# 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
|
||
| ... | ... | |
|
#
|
||
|
# 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'
|
||
| ext/json/lib/json/common.rb | ||
|---|---|---|
|
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
|
||