[Ruby] Extended JSON (#168)

* DOCSP-51932: v2.21.2 patch release (#163)

* shared content

* write

* link formatting

* link formatting

* NR feedback

* NR feedback

* JB feedback

* rephrase

* remove extra change

---------

Co-authored-by: Nora Reidy <[email protected]>

Author: rachel-mack

source/data-formats.txt

@@ -24,6 +24,7 @@ Data Formats
 
    Time Series Data </data-formats/time-series>
    BSON </data-formats/bson>
+   Extended JSON </data-formats/extended-json>
 
 Overview
 --------

source/data-formats/extended-json.txt

@@ -0,0 +1,103 @@
+.. _ruby-extended-json:
+
+=============
+Extended JSON
+=============
+
+.. facet::
+   :name: genre
+   :values: reference
+ 
+.. meta::
+   :keywords: code example, json, standard formatting
+   :description: Learn how to use extended JSON in the MongoDB Ruby Driver.
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: twocols
+
+.. sharedinclude:: dbx/extended-json.rst
+
+Read Extended JSON
+------------------
+
+You can read an Extended JSON string into an Ruby array by calling
+the ``BSON::ExtJSON.parse`` method. This method parses an Extended
+JSON string and returns an array containing the data.
+
+The following example shows how you can read an Extended JSON string into a
+array of hashes by using the ``parse`` method:
+
+.. io-code-block::
+    :copyable:
+
+    .. input:: /includes/data-formats/extended-json.rb
+       :start-after: start-ex-json-read
+       :end-before: end-ex-json-read
+       :language: ruby
+       :dedent:
+
+   .. output::
+      :language: none
+      :visible: false
+
+      {"foo" => [1, 2]}
+      {"bar" => {"hello" => "world"}}
+      {"code" => #<BSON::CodeWithScope:0x0000000123f398e0 @javascript="function x() { return 1; }", @scope={}>}
+      {"bin" => <BSON::Binary:0x7144 type=user data=0x01020304...>}
+
+Write Extended JSON
+-------------------
+
+You can write an Extended JSON string by using the ``as_extended_json``
+method. By default, this method returns the Extended JSON string in canonical
+format, but you can specify relaxed or legacy formats by passing a ``mode`` argument. 
+
+.. note:: Legacy Version
+
+   The legacy format option tells the {+driver-short+} to serialize BSON types
+   with the MongoDB Extended JSON v1 format, which predates the current
+   relaxed and canonical formats. 
+
+   For more information see, the :manual:`MongoDB Extended JSON v1
+   </reference/mongodb-extended-json-v1/>` page in the Server manual. 
+
+The ``as_extended_json`` method is available for several core and standard
+library types, including ``Array`` and ``Hash``. The following example creates
+Extended JSON strings in the canonical, relaxed, and legacy formats, from an
+array of hashes:
+
+.. io-code-block::
+    :copyable:
+
+    .. input:: /includes/data-formats/extended-json.rb
+       :start-after: start-ex-json-write
+       :end-before: end-ex-json-write
+       :language: ruby
+       :dedent:
+
+   .. output::
+      :language: none
+      :visible: false
+
+      canonical: [{"foo":[{"$numberInt":"1"},{"$numberInt":"2"}]},{"bin":{"$binary":{"base64":"AQIDBA==","subType":"80"}}},{"number":{"$numberLong":"42"}}]
+      relaxed:   [{"foo":[1,2]},{"bin":{"$binary":{"base64":"AQIDBA==","subType":"80"}}},{"number":42}]
+      legacy:    [{"foo":[1,2]},{"bin":{"$binary":"AQIDBA==","$type":"80"}},{"number":42}]
+      
+Additional Information
+----------------------
+
+For more information, see the following resources:
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+- `BSON::ExtJSON.parse <https://www.rubydoc.info/gems/bson/{+bson-version+}/BSON/ExtJSON#parse-class_method>`__
+- `#as_extended_json <https://www.rubydoc.info/gems/bson/{+bson-version+}/BSON/Array#as_extended_json-instance_method>`__
+
+Server Manual Pages
+~~~~~~~~~~~~~~~~~~~
+
+- :manual:`MongoDB Extended JSON (v2)</reference/mongodb-extended-json/>`

source/includes/data-formats/extended-json.rb

@@ -0,0 +1,39 @@
+# start-ex-json-read
+require 'bson'
+
+ex_json = '''[
+    {"foo": [1, 2]},
+    {"bar": {"hello": "world"}},
+    {"code": {
+    "$scope": {},
+    "$code": "function x() { return 1; }"
+    }},
+    {"bin": {
+    "$type": "80",
+    "$binary": "AQIDBA=="
+    }}
+    ]'''
+
+doc = BSON::ExtJSON.parse(ex_json)
+
+puts doc.class
+puts doc
+# end-ex-json-read
+
+# start-ex-json-write
+require 'bson'
+
+hash_array = [
+    { "foo" => [1, 2] },
+    { "bin" => BSON::Binary.new("\x01\x02\x03\x04", :user) },
+    { "number" => BSON::Int64.new(42) }
+]
+
+json_string_canonical = hash_array.as_extended_json
+json_string_relaxed = hash_array.as_extended_json(mode: :relaxed)
+json_string_legacy = hash_array.as_extended_json(mode: :legacy)
+
+puts "canonical:\t #{json_string_canonical}"
+puts "relaxed:\t #{json_string_relaxed}"
+puts "legacy:\t\t #{json_string_legacy}"
+# end-ex-json-write