.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BSON_JSON" "3" "Feb 22, 2024" "1.26.0" "libbson"
.sp
Libbson provides routines for converting to and from the JSON format. In particular, it supports the \fI\%MongoDB extended JSON\fP format.
.SH CONVERTING BSON TO JSON
.sp
There are often times where you might want to convert a BSON document to JSON. It is convenient for debugging as well as an interchange format. To help with this, Libbson contains the functions \fI\%bson_as_canonical_extended_json()\fP and \fI\%bson_as_relaxed_extended_json()\fP\&. The canonical format preserves BSON type information for values that may have ambiguous representations in JSON (e.g. numeric types).
.INDENT 0.0
.INDENT 3.5
.sp
.EX
bson_t *b;
size_t len;
char *str;

b = BCON_NEW (\(dqa\(dq, BCON_INT32 (1));

str = bson_as_canonical_extended_json (b, &len);
printf (\(dq%s\en\(dq, str);
bson_free (str);

bson_destroy (b);
.EE
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.EX
{ \(dqa\(dq : { \(dq$numberInt\(dq: \(dq1\(dq } }
.EE
.UNINDENT
.UNINDENT
.sp
The relaxed format prefers JSON primitives for numeric values and may be used if type fidelity is not required.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
bson_t *b;
size_t len;
char *str;

b = BCON_NEW (\(dqa\(dq, BCON_INT32 (1));

str = bson_as_relaxed_extended_json (b, &len);
printf (\(dq%s\en\(dq, str);
bson_free (str);

bson_destroy (b);
.EE
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.EX
{ \(dqa\(dq : 1 }
.EE
.UNINDENT
.UNINDENT
.SH CONVERTING JSON TO BSON
.sp
Converting back from JSON is also useful and common enough that we added \fI\%bson_init_from_json()\fP and \fI\%bson_new_from_json()\fP\&.
.sp
The following example creates a new \fI\%bson_t\fP from the JSON string \fB{\(dqa\(dq:1}\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
bson_t *b;
bson_error_t error;

b = bson_new_from_json (\(dq{\e\(dqa\e\(dq:1}\(dq, \-1, &error);

if (!b) {
   printf (\(dqError: %s\en\(dq, error.message);
} else {
   bson_destroy (b);
}
.EE
.UNINDENT
.UNINDENT
.SH STREAMING JSON PARSING
.sp
Libbson provides \fI\%bson_json_reader_t\fP to allow for parsing a sequence of JSON documents into BSON. The interface is similar to \fI\%bson_reader_t\fP but expects the input to be in the \fI\%MongoDB extended JSON\fP format.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
/*
 * Copyright 2013 MongoDB, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the \(dqLicense\(dq);
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE\-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an \(dqAS IS\(dq BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */


/*
 * This program will print each JSON document contained in the provided files
 * as a BSON string to STDOUT.
 */


#include <bson/bson.h>
#include <stdlib.h>
#include <stdio.h>


int
main (int argc, char *argv[])
{
   bson_json_reader_t *reader;
   bson_error_t error;
   const char *filename;
   bson_t doc = BSON_INITIALIZER;
   int i;
   int b;

   /*
    * Print program usage if no arguments are provided.
    */
   if (argc == 1) {
      fprintf (stderr, \(dqusage: %s FILE...\en\(dq, argv[0]);
      return 1;
   }

   /*
    * Process command line arguments expecting each to be a filename.
    */
   for (i = 1; i < argc; i++) {
      filename = argv[i];

      /*
       * Open the filename provided in command line arguments.
       */
      if (0 == strcmp (filename, \(dq\-\(dq)) {
         reader = bson_json_reader_new_from_fd (STDIN_FILENO, false);
      } else {
         if (!(reader = bson_json_reader_new_from_file (filename, &error))) {
            fprintf (
               stderr, \(dqFailed to open \e\(dq%s\e\(dq: %s\en\(dq, filename, error.message);
            continue;
         }
      }

      /*
       * Convert each incoming document to BSON and print to stdout.
       */
      while ((b = bson_json_reader_read (reader, &doc, &error))) {
         if (b < 0) {
            fprintf (stderr, \(dqError in json parsing:\en%s\en\(dq, error.message);
            abort ();
         }

         if (fwrite (bson_get_data (&doc), 1, doc.len, stdout) != doc.len) {
            fprintf (stderr, \(dqFailed to write to stdout, exiting.\en\(dq);
            exit (1);
         }
         bson_reinit (&doc);
      }

      bson_json_reader_destroy (reader);
      bson_destroy (&doc);
   }

   return 0;
}
.EE
.UNINDENT
.UNINDENT
.SH EXAMPLES
.sp
The following example reads BSON documents from \fBstdin\fP and prints them to \fBstdout\fP as JSON.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
/*
 * Copyright 2013 MongoDB, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the \(dqLicense\(dq);
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE\-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an \(dqAS IS\(dq BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */


/*
 * This program will print each BSON document contained in the provided files
 * as a JSON string to STDOUT.
 */


#include <bson/bson.h>
#include <stdio.h>


int
main (int argc, char *argv[])
{
   bson_reader_t *reader;
   const bson_t *b;
   bson_error_t error;
   const char *filename;
   char *str;
   int i;

   /*
    * Print program usage if no arguments are provided.
    */
   if (argc == 1) {
      fprintf (stderr, \(dqusage: %s [FILE | \-]...\enUse \- for STDIN.\en\(dq, argv[0]);
      return 1;
   }

   /*
    * Process command line arguments expecting each to be a filename.
    */
   for (i = 1; i < argc; i++) {
      filename = argv[i];

      if (strcmp (filename, \(dq\-\(dq) == 0) {
         reader = bson_reader_new_from_fd (STDIN_FILENO, false);
      } else {
         if (!(reader = bson_reader_new_from_file (filename, &error))) {
            fprintf (
               stderr, \(dqFailed to open \e\(dq%s\e\(dq: %s\en\(dq, filename, error.message);
            continue;
         }
      }

      /*
       * Convert each incoming document to JSON and print to stdout.
       */
      while ((b = bson_reader_read (reader, NULL))) {
         str = bson_as_canonical_extended_json (b, NULL);
         fprintf (stdout, \(dq%s\en\(dq, str);
         bson_free (str);
      }

      /*
       * Cleanup after our reader, which closes the file descriptor.
       */
      bson_reader_destroy (reader);
   }

   return 0;
}
.EE
.UNINDENT
.UNINDENT
.SH AUTHOR
MongoDB, Inc
.SH COPYRIGHT
2017-present, MongoDB, Inc
.\" Generated by docutils manpage writer.
.