CDRIVER-4659 add extended json output capability for bson_array_as_json (#1305)

Author: joshbsiegel

src/libbson/doc/bson_array_as_canonical_extended_json.rst

@@ -0,0 +1,70 @@
+:man_page: bson_array_as_canonical_extended_json
+
+bson_array_as_canonical_extended_json()
+=======================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  char *
+  bson_array_as_canonical_extended_json (const bson_t *bson, size_t *length);
+
+Parameters
+----------
+
+* ``bson``: A :symbol:`bson_t`.
+* ``length``: An optional location for the length of the resulting string.
+
+Description
+-----------
+
+The :symbol:`bson_array_as_canonical_extended_json()` encodes ``bson`` as a UTF-8 string in the canonical `MongoDB Extended JSON format`_, except the outermost element is encoded as a JSON array, rather than a JSON document.
+
+The caller is responsible for freeing the resulting UTF-8 encoded string by calling :symbol:`bson_free()` with the result.
+
+If non-NULL, ``length`` will be set to the length of the result in bytes.
+
+Returns
+-------
+
+If successful, a newly allocated UTF-8 encoded string and ``length`` is set.
+
+Upon failure, NULL is returned.
+
+Example
+-------
+
+.. code-block:: c
+
+  #include <bson/bson.h>
+
+  int main ()
+  {
+     bson_t bson;
+     char *str;
+
+     bson_init (&bson);
+     /* BSON array is a normal BSON document with integer values for the keys,
+      * starting with 0 and continuing sequentially
+      */
+     BSON_APPEND_INT32 (&bson, "0", 1);
+     BSON_APPEND_UTF8 (&bson, "1", "bar");
+
+     str = bson_array_as_canonical_extended_json (&bson, NULL);
+     /* Prints
+      * [ { "$numberInt" : 1 }, "bar" ]
+      */
+     printf ("%s\n", str);
+     bson_free (str);
+
+     bson_destroy (&bson);
+  }
+
+
+.. only:: html
+
+  .. include:: includes/seealso/bson-as-json.txt
+
+.. _MongoDB Extended JSON format: https://github.com/mongodb/specifications/blob/master/source/extended-json.rst

src/libbson/doc/bson_array_as_json.rst

@@ -22,7 +22,10 @@ Description
 
 The :symbol:`bson_array_as_json()` function shall encode ``bson`` as a UTF-8
 string using libbson's legacy JSON format, except the outermost element is
-encoded as a JSON array, rather than a JSON document.
+encoded as a JSON array, rather than a JSON document. This function is
+superseded by :symbol:`bson_array_as_canonical_extended_json()` and
+:symbol:`bson_array_as_relaxed_extended_json()`, which use the same 
+`MongoDB Extended JSON format`_ as all other MongoDB drivers.
 The caller is responsible for freeing the resulting UTF-8 encoded string by
 calling :symbol:`bson_free()` with the result.
 
@@ -68,3 +71,5 @@ Example
 .. only:: html
 
   .. include:: includes/seealso/bson-as-json.txt
+
+.. _MongoDB Extended JSON format: https://github.com/mongodb/specifications/blob/master/source/extended-json.rst

src/libbson/doc/bson_array_as_relaxed_extended_json.rst

@@ -0,0 +1,70 @@
+:man_page: bson_array_as_relaxed_extended_json
+
+bson_array_as_relaxed_extended_json()
+=====================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  char *
+  bson_array_as_relaxed_extended_json (const bson_t *bson, size_t *length);
+
+Parameters
+----------
+
+* ``bson``: A :symbol:`bson_t`.
+* ``length``: An optional location for the length of the resulting string.
+
+Description
+-----------
+
+The :symbol:`bson_as_relaxed_extended_json()` encodes ``bson`` as a UTF-8 string in the relaxed `MongoDB Extended JSON format`_, except the outermost element is encoded as a JSON array, rather than a JSON document.
+
+The caller is responsible for freeing the resulting UTF-8 encoded string by calling :symbol:`bson_free()` with the result.
+
+If non-NULL, ``length`` will be set to the length of the result in bytes.
+
+Returns
+-------
+
+If successful, a newly allocated UTF-8 encoded string and ``length`` is set.
+
+Upon failure, NULL is returned.
+
+Example
+-------
+
+.. code-block:: c
+
+  #include <bson/bson.h>
+
+  int main ()
+  {
+     bson_t bson;
+     char *str;
+
+     bson_init (&bson);
+     /* BSON array is a normal BSON document with integer values for the keys,
+      * starting with 0 and continuing sequentially
+      */
+     BSON_APPEND_DOUBLE (&bson, "0", 3.14);
+     BSON_APPEND_UTF8 (&bson, "1", "bar");
+
+     str = bson_array_as_relaxed_extended_json (&bson, NULL);
+     /* Prints
+      * [ 3.14, "bar" ]
+      */
+     printf ("%s\n", str);
+     bson_free (str);
+
+     bson_destroy (&bson);
+  }
+
+
+.. only:: html
+
+  .. include:: includes/seealso/bson-as-json.txt
+
+.. _MongoDB Extended JSON format: https://github.com/mongodb/specifications/blob/master/source/extended-json.rst

src/libbson/doc/bson_json_opts_set_outermost_array.rst

@@ -0,0 +1,23 @@
+:man_page: bson_json_opts_set_outermost_array
+
+bson_json_opts_set_outermost_array()
+====================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  void 
+  bson_json_opts_set_outermost_array (bson_json_opts_t *opts, bool is_outermost_array);
+
+Parameters
+----------
+
+* ``opts``: A :symbol:`bson_json_opts_t`.
+* ``is_outermost_array``: A value determining what we want to set the is_outermost_array variable to.
+
+Description
+-----------
+
+The :symbol:`bson_json_opts_set_outermost_array()` function shall set the ``is_outermost_array`` variable on the :symbol:`bson_json_opts_t` parameter using the boolean provided.

src/libbson/doc/bson_json_opts_t.rst

@@ -48,3 +48,4 @@ The ``max_len`` member holds a maximum length for the resulting JSON string. Enc
 
 	     bson_json_opts_new
 	     bson_json_opts_destroy
+	     bson_json_opts_set_outermost_array

src/libbson/doc/bson_t.rst

@@ -190,7 +190,9 @@ BSON document contains duplicate keys.
     bson_append_undefined
     bson_append_utf8
     bson_append_value
+    bson_array_as_canonical_extended_json
     bson_array_as_json
+    bson_array_as_relaxed_extended_json
     bson_as_canonical_extended_json
     bson_as_json
     bson_as_json_with_opts

src/libbson/doc/includes/seealso/bson-as-json.txt

@@ -1,7 +1,10 @@
 .. seealso::
+  | :symbol: `bson_array_as_canonical_extended_json()`
 
   | :symbol:`bson_array_as_json()`
 
+  | :symbol: `bson_array_as_relaxed_extended_json()`
+
   | :symbol:`bson_as_canonical_extended_json()`
 
   | :symbol:`bson_as_json()`

src/libbson/src/bson/bson-json-private.h

@@ -23,6 +23,7 @@
 struct _bson_json_opts_t {
    bson_json_mode_t mode;
    int32_t max_len;
+   bool is_outermost_array;
 };
 
 

src/libbson/src/bson/bson-json.c

@@ -394,8 +394,11 @@ bson_json_opts_new (bson_json_mode_t mode, int32_t max_len)
    bson_json_opts_t *opts;
 
    opts = (bson_json_opts_t *) bson_malloc (sizeof *opts);
-   opts->mode = mode;
-   opts->max_len = max_len;
+   *opts = (bson_json_opts_t){
+      .mode = mode,
+      .max_len = max_len,
+      .is_outermost_array = false,
+   };
 
    return opts;
 }
@@ -2335,6 +2338,14 @@ bson_json_reader_destroy (bson_json_reader_t *reader) /* IN */
 }
 
 
+void
+bson_json_opts_set_outermost_array (bson_json_opts_t *opts,
+                                    bool is_outermost_array)
+{
+   opts->is_outermost_array = is_outermost_array;
+}
+
+
 typedef struct {
    const uint8_t *data;
    size_t len;

src/libbson/src/bson/bson-json.h

@@ -61,7 +61,9 @@ BSON_EXPORT (bson_json_opts_t *)
 bson_json_opts_new (bson_json_mode_t mode, int32_t max_len);
 BSON_EXPORT (void)
 bson_json_opts_destroy (bson_json_opts_t *opts);
-
+BSON_EXPORT (void)
+bson_json_opts_set_outermost_array (bson_json_opts_t *opts,
+                                    bool is_outermost_array);
 
 typedef ssize_t (*bson_json_reader_cb) (void *handle,
                                         uint8_t *buf,