Enchance generic JSON and #generate docs

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 <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'
 #
 #   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'
 

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 <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

tmp/rdoc/BigDecimal.html

@@ -0,0 +1,239 @@
+<!DOCTYPE html>
+
+<html>
+<head>
+<meta charset="UTF-8">
+
+<title>class BigDecimal - RDoc Documentation</title>
+
+<script type="text/javascript">
+  var rdoc_rel_prefix = "./";
+  var index_rel_prefix = "./";
+</script>
+
+<script src="./js/jquery.js"></script>
+<script src="./js/darkfish.js"></script>
+
+<link href="./css/fonts.css" rel="stylesheet">
+<link href="./css/rdoc.css" rel="stylesheet">
+
+
+
+<body id="top" role="document" class="class">
+<nav role="navigation">
+  <div id="project-navigation">
+    <div id="home-section" role="region" title="Quick navigation" class="nav-section">
+  <h2>
+    <a href="./index.html" rel="home">Home</a>
+  </h2>
+
+  <div id="table-of-contents-navigation">
+    <a href="./table_of_contents.html#pages">Pages</a>
+    <a href="./table_of_contents.html#classes">Classes</a>
+    <a href="./table_of_contents.html#methods">Methods</a>
+  </div>
+</div>
+
+    <div id="search-section" role="search" class="project-section initially-hidden">
+  <form action="#" method="get" accept-charset="utf-8">
+    <div id="search-field-wrapper">
+      <input id="search-field" role="combobox" aria-label="Search"
+             aria-autocomplete="list" aria-controls="search-results"
+             type="text" name="search" placeholder="Search" spellcheck="false"
+             title="Type to search, Up and Down to navigate, Enter to load">
+    </div>
+
+    <ul id="search-results" aria-label="Search Results"
+        aria-busy="false" aria-expanded="false"
+        aria-atomic="false" class="initially-hidden"></ul>
+  </form>
+</div>
+
+  </div>
+
+
+
+  <div id="class-metadata">
+
+    <div id="parent-class-section" class="nav-section">
+  <h3>Parent</h3>
+
+
+  <p class="link">Object
+
+</div>
+
+
+
+    <!-- Method Quickref -->
+<div id="method-list-section" class="nav-section">
+  <h3>Methods</h3>
+
+  <ul class="link-list" role="directory">
+
+    <li ><a href="#method-c-json_create">::json_create</a>
+
+    <li ><a href="#method-i-as_json">#as_json</a>
+
+    <li ><a href="#method-i-to_json">#to_json</a>
+
+  </ul>
+</div>
+
+  </div>
+</nav>
+
+<main role="main" aria-labelledby="class-BigDecimal">
+  <h1 id="class-BigDecimal" class="class">
+    class BigDecimal
+  </h1>
+
+  <section class="description">
+
+  </section>
+
+
+
+
+  <section id="5Buntitled-5D" class="documentation-section">
+
+
+
+
+
+
+
+
+
+     <section id="public-class-5Buntitled-5D-method-details" class="method-section">
+       <header>
+         <h3>Public Class Methods</h3>
+       </header>
+
+
+      <div id="method-c-json_create" class="method-detail ">
+
+        <div class="method-heading">
+          <span class="method-name">json_create</span><span
+            class="method-args">(object)</span>
+
+          <span class="method-click-advice">click to toggle source</span>
+
+        </div>
+
+
+        <div class="method-description">
+
+          <p>Import a <a href="JSON.html">JSON</a> Marshalled object.</p>
+
+<p>method used for <a href="JSON.html">JSON</a> marshalling support.</p>
+
+
+
+
+          <div class="method-source-code" id="json_create-source">
+            <pre><span class="ruby-comment"># File lib/json/add/bigdecimal.rb, line 11</span>
+<span class="ruby-keyword">def</span> <span class="ruby-keyword">self</span>.<span class="ruby-identifier">json_create</span>(<span class="ruby-identifier">object</span>)
+  <span class="ruby-constant">BigDecimal</span>.<span class="ruby-identifier">_load</span> <span class="ruby-identifier">object</span>[<span class="ruby-string">&#39;b&#39;</span>]
+<span class="ruby-keyword">end</span></pre>
+          </div>
+
+        </div>
+
+
+
+
+      </div>
+
+
+    </section>
+
+     <section id="public-instance-5Buntitled-5D-method-details" class="method-section">
+       <header>
+         <h3>Public Instance Methods</h3>
+       </header>
+
+
+      <div id="method-i-as_json" class="method-detail ">
+
+        <div class="method-heading">
+          <span class="method-name">as_json</span><span
+            class="method-args">(*)</span>
+
+          <span class="method-click-advice">click to toggle source</span>
+
+        </div>
+
+
+        <div class="method-description">
+
+          <p>Marshal the object to <a href="JSON.html">JSON</a>.</p>
+
+<p>method used for <a href="JSON.html">JSON</a> marshalling support.</p>
+
+
+
+
+          <div class="method-source-code" id="as_json-source">
+            <pre><span class="ruby-comment"># File lib/json/add/bigdecimal.rb, line 18</span>
+<span class="ruby-keyword">def</span> <span class="ruby-identifier">as_json</span>(<span class="ruby-operator">*</span>)
+  {
+    <span class="ruby-constant">JSON</span>.<span class="ruby-identifier">create_id</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-keyword">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">name</span>,
+    <span class="ruby-string">&#39;b&#39;</span>            =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">_dump</span>,
+  }
+<span class="ruby-keyword">end</span></pre>
+          </div>
+
+        </div>
+
+
+
+
+      </div>
+
+
+      <div id="method-i-to_json" class="method-detail ">
+
+        <div class="method-heading">
+          <span class="method-name">to_json</span><span
+            class="method-args">(*)</span>
+
+          <span class="method-click-advice">click to toggle source</span>
+
+        </div>
+
+
+        <div class="method-description">
+
+          <p>return the <a href="JSON.html">JSON</a> value</p>
+
+
+
+
+          <div class="method-source-code" id="to_json-source">
+            <pre><span class="ruby-comment"># File lib/json/add/bigdecimal.rb, line 26</span>
+<span class="ruby-keyword">def</span> <span class="ruby-identifier">to_json</span>(<span class="ruby-operator">*</span>)
+  <span class="ruby-identifier">as_json</span>.<span class="ruby-identifier">to_json</span>
+<span class="ruby-keyword">end</span></pre>
+          </div>
+
+        </div>
+
+
+
+
+      </div>
+
+
+    </section>
+
+  </section>
+</main>
+
+
+<footer id="validator-badges" role="contentinfo">
+  <p><a href="http://validator.w3.org/check/referer">Validate</a>
+  <p>Generated by <a href="https://rdoc.github.io/rdoc">RDoc</a> 5.0.0.
+  <p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
+</footer>
+