baljsn_jsonformatter

Detailed Description

Provide a formatter for converting bdlat object to Json analog.

Outline

• Purpose
• Classes
• Description
  • Assembling an Array
  • Assembling an Object
  • Usage
    • Basic Syntax

Purpose

Provide a formatter for converting bdlat object to Json analog.

Classes

• baljsn::JsonFormatter: mechanism for setting the value of a bdljsn::Json

See also

baljsn_encoder, baljsn_formatter, bdljsn_json

Description

This component provides a stateful mechanism, baljsn::JsonFormatter, that sets the value of a bdljsn::Json object according to the invocations of the formatter`s various manipulator methods.

The target bdljsn::Json object can be set to either a JSON scalar (i.e., isNull(), isBoolean(), isNumber(), isString()), or an a JSON array (isArray()), or a JSON object (isObject()). Recall that JSON arrays consist of a list of elements that can each be either a scalar or an object or an array. Also recall that each object is a name/value pair where the value portion can be either a scalar or an object or an array.

The bdljsn::Json object must be built up in top-down order. The proper order of manipulator calls must, in effect, follow a pre-order tranversal of the object being created. For details of adding arrays and adding objects see Assembling an Array and [](Assembling an Object) . Calling these mainipulators in other orders can cause undefined behavior.

The provided manipulators do not allow for any editing once a value has been set. Once a bdljsn::Json target object has been given a scalar value or started as an array or as an object, any attempt to undo that action results in undefined behavior.

Note that two of the manipulators, addArrayElementSeparators and nestingDepth, are not relevant to assembling bdljsn::Json objects and are defined as "no-ops". These manipulators are provided so baljsn::JsonFormatter can be used in the same context as baljsn::Formatter.

Assembling an Array

A bdljsn::Json object of array type is assembled using the following series of manipulator calls.

• openArray starts an array (the "current" array).
• putValue/putNullValue calls each adds to the current array an element having the appropriate scalar type.
• openObject adds an array element that is a name/value pair (an Json object).
• openArray starts a new array within the current array. Subsequent operations assemble this new array until closeArray is called.
• Repeat the addition of new elements to the current array by calls to putValue/putNullValue/openObject/openArray as appropriate.
• closeArray indicates that there are no more elements to be added to the current array.

Assembling an Object

A bdljsn::Json object of object type (i.e., a name/value) is assembled using the following series of manipulator calls in the order shown below.

• openObject starts a new object (the "current" object).
• openMember starts a new member of the object and provides the name portion of the name/value pair.
• putValue/putNullValue sets the provided value as the "value" portion of the name/value pair.
• openArray starts an array as the value portion of the name/value pair.
• openObject starts a new object as the value portion of the name/value pair. Subsequent calls define this object until closeMember is called.
• closeMember indicates that the member has been completed.
• Repeat the addition of new members as appropriate.
• closeObject indicates that there are no more members to be added to the current object.

Usage

This section illustrates intended use of this component.

Basic Syntax

Let us say that we have a JSON document describing some (hypothetical) employee data that we wish to convert to a bdljsn::Json object so we can examine and manipulate that data programmatically.

 { "name"        : "Bob",
   "homeAddress" :
      { "street" : "Lexington Ave",
        "city"   : "New York City",
        "state"  : "New York"
      },
   "age"        :  21
 }

First, we create a bdljsn::Json object and directly use the manipulators provided by that class.

 bdljsn::Json json1;
 json1.makeObject();
 json1["name"];
 json1["homeAddress"];
 json1["age"];
 
 bdljsn::Json address;
 address.makeObject();
 address["street"] = "Lexington Ave";
 address["city"]   = "New York City";
 address["state"]  = "New York";
 
 json1["name"]        = "Bob";
 json1["homeAddress"] = address;
 json1["age"]         = 21;

Notice that, since we have the freedom to do so, we choose to assemble json1 in a breadth-first order:

1. First we enter the top-level members by name, "name", "homeAddress", and "age".
2. Then we assign values to each of those members. In the case of "homeAddress", we use a separately assembled object.

Now, we confirm that we can also assemble an equivalent object using the baljsn::JsonFormatter mechanism.

 bdljsn::Json          json2;
 baljsn::JsonFormatter formatter(&json2);
 
 formatter.openObject();
 
     formatter.openMember("name");
     formatter.putValue("Bob");
     formatter.closeMember();
 
     formatter.openMember("homeAddress");
     formatter.openObject();  // The "value" of the "homeAddress" member.
 
         formatter.openMember("street");
         formatter.putValue("Lexington Ave");
         formatter.closeMember();
 
         formatter.openMember("city");
         formatter.putValue("New York City");
         formatter.closeMember();
 
         formatter.openMember("state");
         formatter.putValue("New York");
         formatter.closeMember();
 
     formatter.closeObject();
     formatter.closeMember(); // "homeAddress"
 
     formatter.openMember("age");
     formatter.putValue(21);
     formatter.closeMember();
 
    formatter.closeObject();

Finally, we confirm that the two assembled objects are equal.

 assert(json1 == json2);