bdljsn.h

Go to the documentation of this file.

/// @file bdljsn.h
///
///
/// @defgroup bdljsn Package bdljsn
/// @brief  Basic Development Library JSoN (bdljsn)
/// @addtogroup bdl
/// @{
/// @addtogroup bdljsn
/// [bdljsn]: group__bdljsn.html
/// @{
///
/// # Purpose {#bdljsn-purpose}
/// Provide a value-semantic JSON type and supporting utilities
///
/// # Mnemonic {#bdljsn-mnemonic}
/// Basic Development Library JSoN (bdljsn)
///
/// # Description {#bdljsn-description}
/// The 'bdljsn' package provides the 'bdljsn::Json' type, found in
/// the @ref bdljsn_json  component, which is a value-semantic representation of JSON
/// data.  This package also provides facilities for reading and writing
/// 'bdljsn::Json' objects to JSON documents.  'bdljsn::Json' has close structural
/// similarities to the JSON grammar itself, which looks like the following, at a
/// high level:
/// @code
///  JSON ::= Object
///         | Array
///         | String
///         | Number
///         | Boolean
///         | null
/// @endcode
/// Noting that the 'Object' and 'Array' alternatives can recursively contain
/// 'JSON'.  Just like this grammar, the value of a 'bdljsn::Json' object can be
/// an object, array, string, number, boolean, or the null value.  Objects and
/// Arrays are represented by the 'bdljsn::JsonObject' and 'bdljsn::JsonArray'
/// types, respectively, and are also provided by the @ref bdljsn_json  component.
/// 'bdljsn::JsonObject' is an associative container from strings to
/// 'bdljsn::Json' objects, and 'bdljsn::JsonArray' is a sequence container with
/// 'bdljsn::Json' elements.  Strings and booleans are represented with the
/// standard 'bsl::string' and 'bool' types.  The singular "null" value is
/// represented by the 'bdljsn::JsonNull' type, which has a single value like
/// 'std::monostate'.  Numbers are represented by the 'bdljsn::JsonNumber' type,
/// which has facilities for storing any number that satisfies the JSON number
/// grammar with arbitrary precision.  It also provides operations for converting
/// these arbitrary-precision numbers to common finite-precision number vocabulary
/// types like 'int', 'double', and 'bdldfp::Decimal64', and detecting where
/// overflow, underflow, and/or truncation would occur during conversion.
///
/// Though this package provides several types representing different kinds of
/// JSON values, in general the 'bdljsn::Json' interface is rich enough to be the
/// primary vocabulary type for working with JSON.  For example, if the value
/// stored in a 'bdljsn::Json' holds a JSON object, then you can use much of the
/// associative container interface on the 'bdljsn::Json' object directly, e.g.,
/// @code
///  void getName(bsl::string *name, const bdljsn::Json& json)
///      // Load to the specified 'name' the "name" member of the specified
///      // 'json'.  The behavior is undefined unless 'json' is a JSON object and
///      // has a "name" member that is a string.
///  {
///      // First, verify that the 'json' is a JSON object, and not another
///      // kind of value.
///      assert(json.isObject());
///
///      // Then, we can use the subscript operator with string keys, just like a
///      // map.
///      *name = json["name"].theString();
///  }
/// @endcode
/// Alternatively, if a 'bdljsn::Json' holds a JSON array, then we can use it like
/// a sequence container,
/// @code
///  bool findWaldo(const bdljsn::Json& json)
///      // Return 'true' if 'json' is an array that contains the string "waldo",
///      // and return 'false' otherwise.
///  {
///      if (!json.isArray()) {
///          return false;                                               // RETURN
///      }
///
///      for (bsl::size_t i = 0; i != json.size(); ++i) {
///          const bdljsn::Json& element = json[i];
///
///          if (!element.isString()) {
///              continue;                                             // CONTINUE
///          }
///
///          if (element.theString() == "waldo") {
///              return true;                                            // RETURN
///          }
///      }
///
///      return false;
///  }
/// @endcode
/// For an example of constructing 'bdljsn::Json' objects, consider the use case
/// where we have a simple representation of an organization chart, which we would
/// like to convert to JSON for printing to standard output:
/// @code
///  struct Employee {
///      // PUBLIC DATA
///      int         d_id;
///      bsl::string d_firstName;
///      bsl::string d_lastName;
///  };
///
///  struct Team {
///      // PUBLIC DATA
///      Employee              d_manager;
///      bsl::vector<Employee> d_members;
///  };
/// @endcode
/// We can define utility functions for converting these types to JSON:
/// @code
///  struct Utility {
///      // CLASS METHODS
///      static void toJson(bdljsn::Json *json, const Employee& employee)
///          // Load to the specified 'json' the value of the specified 'employee'
///          // converted to a JSON value.
///      {
///          bdljsn::Json& result = *json;
///
///          result.makeObject();
///
///          result["id"]        = employee.d_id;
///          result["firstName"] = employee.d_firstName;
///          result["lastName"]  = employee.d_lastName;
///      }
///
///      static void toJson(bdljsn::Json *json, const Team& team)
///          // Load to the specified 'json' the value of the specified 'team'
///          // converted to a JSON value.
///      {
///          bdljsn::Json& result = *json;
///          result.makeObject();
///
///          bdljsn::Json manager;
///          toJson(&manager, team.d_manager);
///          result["manager"] = bsl::move(manager);
///
///          bdljsn::Json members;
///          members.makeArray();
///          for (bsl::size_t i = 0; i != team.d_members.size(); ++i) {
///              bdljsn::Json member;
///              toJson(&member, team.d_members[i]);
///              members[i] = bsl::move(member);
///          }
///          result["members"] = bsl::move(members);
///      }
///  };
/// @endcode
/// And then we can create a sample 'Team' and print it to standard output using
/// our 'toJson' functions,
/// @code
///  void example()
///  {
///      Employee manager = { 1, "Michael", "Bloomberg" };
///      Employee employee0 = { 2, "Peter", "Grauer" };
///      Employee employee1 = { 3, "Tom", "Secunda" };
///
///      Team team;
///      team.d_manager = manager;
///      team.d_members.push_back(employee0);
///      team.d_members.push_back(employee1);
///
///      bdljsn::Json teamAsJson;
///      Utility::toJson(&teamAsJson, team);
///
///      // The following set of options to 'write' specify that we would prefer
///      // the output to be pretty-printed.
///      bdljsn::WriteOptions options;
///      options.setStyle(bdljsn::WriteStyle::e_PRETTY);
///
///      int rc = bdljsn::JsonUtil::write(bsl::cout, teamAsJson, options);
///      assert(0 == rc);
///  }
/// @endcode
/// Then, we can observe the following printed to standard output:
/// @code
///  {
///      "manager": {
///          "id": 1,
///          "firstName": "Michael",
///          "lastName": "Bloomberg"
///      },
///      "members": [
///          {
///              "id": 2,
///              "firstName": "Peter",
///              "lastName": "Grauer"
///          },
///          {
///              "id": 3,
///              "firstName": "Tom",
///              "lastName": "Secunda"
///          }
///      ]
///  }
/// @endcode
///
/// ## Hierarchical Synopsis
///
/// The 'bdljsn' package currently has 15 components having 5 levels of physical
/// dependency.  The list below shows the hierarchical ordering of the components.
/// The order of components within each level is not architecturally significant,
/// just alphabetical.
/// @code
///  5. bdljsn_jsonliterals
///
///  4. bdljsn_jsonutil
///
///  3. bdljsn_json
///
///  2. bdljsn_error
///     bdljsn_jsonnumber
///     bdljsn_tokenizer
///     bdljsn_writeoptions
///
///  1. bdljsn_jsonnull
///     bdljsn_jsontestsuiteutil
///     bdljsn_jsontype
///     bdljsn_location
///     bdljsn_numberutil
///     bdljsn_readoptions
///     bdljsn_stringutil
///     bdljsn_writestyle
/// @endcode
///
/// ## Component Synopsis
///
///  @ref bdljsn_error :
///       Provide a description of an error processing a document.
/// 
///  @ref bdljsn_json :
///       Provide an in-memory representation of a JSON document.
/// 
///  @ref bdljsn_jsonliterals :
///       Provide user-defined literals for `bdljsn::Json` objects.
/// 
///  @ref bdljsn_jsonnull :
///       Provide a type that represents the JSON `null` value.
/// 
///  @ref bdljsn_jsonnumber :
///       Provide a value-semantic type representing a JSON number.
/// 
///  @ref bdljsn_jsontestsuiteutil :
///       Provide JSON Test Suite for BDE table-driven testing.
/// 
///  @ref bdljsn_jsontype :
///       Enumerate the set of JSON value types.
/// 
///  @ref bdljsn_jsonutil :
///       Provide common non-primitive operations on `Json` objects.
/// 
///  @ref bdljsn_location :
///       Provide a value-semantic type for location in a JSON document.
/// 
///  @ref bdljsn_numberutil :
///       Provide utilities converting between JSON text and numeric types.
/// 
///  @ref bdljsn_readoptions :
///       Provide options for reading a JSON document.
/// 
///  @ref bdljsn_stringutil :
///       Provide a utility functions for JSON strings.
/// 
///  @ref bdljsn_tokenizer :
///       Provide a tokenizer for extracting JSON data from a `streambuf`.
/// 
///  @ref bdljsn_writeoptions :
///       Provide options for writing a JSON document.
/// 
///  @ref bdljsn_writestyle :
///       Enumerate the formatting styles for a writing a JSON document.
///
/// @}
/** @} */