summaryrefslogtreecommitdiff
path: root/ext/json/lib
diff options
context:
space:
mode:
authorBurdetteLamar <burdettelamar@yahoo.com>2020-07-04 09:21:12 -0500
committerHiroshi SHIBATA <hsbt@ruby-lang.org>2020-09-25 17:28:42 +0900
commit8c057bb845d57d20e285030bfd73bcb5ca1143f9 (patch)
tree7fdb309a81a2512c3b7d48308b39f2c2c9f34349 /ext/json/lib
parent36b2177ea80663437daac92c50db378cf1bff799 (diff)
[flori/json] RDoc example for JSON.load
https://github.com/flori/json/commit/e4eead665c
Notes
Notes: Merged: https://github.com/ruby/ruby/pull/3581
Diffstat (limited to 'ext/json/lib')
-rw-r--r--ext/json/lib/json.rb2
-rw-r--r--ext/json/lib/json/common.rb100
2 files changed, 88 insertions, 14 deletions
diff --git a/ext/json/lib/json.rb b/ext/json/lib/json.rb
index 6bb82245b84..aeb9774ee94 100644
--- a/ext/json/lib/json.rb
+++ b/ext/json/lib/json.rb
@@ -319,7 +319,7 @@ require 'json/common'
# opts = {
# array_nl: "\n",
# object_nl: "\n",
-# indent+: ' ',
+# indent: ' ',
# space_before: ' ',
# space: ' '
# }
diff --git a/ext/json/lib/json/common.rb b/ext/json/lib/json/common.rb
index 3ff6df10cef..0e43fa2291d 100644
--- a/ext/json/lib/json/common.rb
+++ b/ext/json/lib/json/common.rb
@@ -414,21 +414,95 @@ module JSON
:create_additions => true,
}
- # Load a ruby data structure from a JSON _source_ and return it. A source can
- # either be a string-like object, an IO-like object, or an object responding
- # to the read method. If _proc_ was given, it will be called with any nested
- # Ruby object as an argument recursively in depth first order. To modify the
- # default options pass in the optional _options_ argument as well.
- #
- # BEWARE: This method is meant to serialise data from trusted user input,
- # like from your own database server or clients under your control, it could
- # be dangerous to allow untrusted users to pass JSON sources into it. The
- # default options for the parser can be changed via the load_default_options
- # method.
+ # :call-seq:
+ # JSON.load(source, proc = nil, options = {}) -> object
#
- # This method is part of the implementation of the load/dump interface of
- # Marshal and YAML.
+ # Returns the Ruby objects created by parsing the given +source+.
#
+ # - Argument +source+ must be, or be convertible to, a \String:
+ # - If +source+ responds to instance method +to_str+,
+ # <tt>source.to_str</tt> becomes the source.
+ # - If +source+ responds to instance method +to_io+,
+ # <tt>source.to_io.read</tt> becomes the source.
+ # - If +source+ responds to instance method +read+,
+ # <tt>source.read</tt> becomes the source.
+ # - If both of the following are true, source becomes the \String <tt>'null'</tt>:
+ # - Option +allow_blank+ specifies a truthy value.
+ # - The source, as defined above, is +nil+ or the empty \String <tt>''</tt>.
+ # - Otherwise, +source+ remains the source.
+ # - Argument +proc+, if given, must be a \Proc that accepts one argument.
+ # It will be called recursively with each result (depth-first order).
+ # See details below.
+ # BEWARE: This method is meant to serialise data from trusted user input,
+ # like from your own database server or clients under your control, it could
+ # be dangerous to allow untrusted users to pass JSON sources into it.
+ # - Argument +opts+, if given, contains options for the parsing, and must be a
+ # {Hash-convertible object}[doc/implicit_conversion_rdoc.html#label-Hash+Convertible+Objects].
+ # See {Parsing Options}[#module-JSON-label-Parsing+Options].
+ # The default options can be changed via method JSON.load_default_options=.
+ #
+ # Examples in this section assume prior execution of:
+ # source = <<-EOT
+ # {
+ # "name": "Dave",
+ # "age" :40,
+ # "hats": [
+ # "Cattleman's",
+ # "Panama",
+ # "Tophat"
+ # ]
+ # }
+ # EOT
+ #
+ # ---
+ #
+ # When +proc+ is not given, modifies +source+ as above and returns the result of
+ # <tt>parse(source, opts)</tt>; see #parse.
+ #
+ # Load a \String:
+ # ruby = JSON.load(source)
+ # ruby # => {"name"=>"Dave", "age"=>40, "hats"=>["Cattleman's", "Panama", "Tophat"]}
+ #
+ # Load an \IO object:
+ # require 'stringio'
+ # object = JSON.load(StringIO.new(source))
+ # object # => {"name"=>"Dave", "age"=>40, "hats"=>["Cattleman's", "Panama", "Tophat"]}
+ #
+ # Load a \File object:
+ # path = 't.json'
+ # File.write(path, source)
+ # File.open(path) do |file|
+ # JSON.load(file)
+ # end # => {"name"=>"Dave", "age"=>40, "hats"=>["Cattleman's", "Panama", "Tophat"]}
+ #
+ # ---
+ #
+ # When +proc+ is given:
+ # - Modifies +source+ as above.
+ # - Gets the +result+ from calling <tt>parse(source, opts)</tt>.
+ # - Recursively calls <tt>proc(result)</tt>.
+ # - Returns the final result.
+ #
+ # Example:
+ # def mung(obj)
+ # case obj
+ # when String
+ # obj.upcase
+ # when Integer
+ # obj * 100
+ # else
+ # obj
+ # end
+ # end
+ # new_obj = JSON.load(source, proc {|obj|
+ # case obj
+ # when Hash
+ # obj.each {|k, v| obj[k] = mung(v) }
+ # when Array
+ # obj.map! {|v| mung(v) }
+ # end
+ # })
+ # new_obj # => {"name"=>"DAVE", "age"=>4000, "hats"=>["CATTLEMAN'S", "PANAMA", "TOPHAT"]}
def load(source, proc = nil, options = {})
opts = load_default_options.merge options
if source.respond_to? :to_str