# Building a document tree directly

You can also create and populate a JSON document tree directly without needing to parse a JSON string. This approach is ideal if you want to create a JSON tree from scratch and export it as a string. The following series of code snippets demonstrate how to exactly build JSON document trees directly and export their contents as JSON strings.

The first example shows how to initialize the tree with a simple array:

    orcus::json::document_tree doc = {
        1.0, 2.0, "string value", false, nullptr
    };

    std::cout << doc.dump(4) << std::endl;

You can simply specify the content of the array via initialization list and assign it to the document. The `dump()` method then turns the content into a single string instance, which looks like the following:

    [
        1,
        2,
        "string value",
        false,
        null
    ]

If you need to build a array of arrays, do like the following:

    orcus::json::document_tree doc = {
        { true, false, nullptr },
        { 1.1, 2.2, "text" }
    };

    std::cout << doc.dump(4) << std::endl;

This will create an array of two nested child arrays with three values each. Dumping the content of the tree as a JSON string will produce something like the following:

    [
        [
            true,
            false,
            null
        ],
        [
            1.1,
            2.2,
            "text"
        ]
    ]

Creating an object can be done by nesting one of more key-value pairs, each of which is surrounded by a pair of curly braces, inside another pair of curly braces. For example, the following code:

    orcus::json::document_tree doc = {
        { "key1", 1.2 },
        { "key2", "some text" },
    };

    std::cout << doc.dump(4) << std::endl;

produces the following output:

    {
        "key1": 1.2,
        "key2": "some text"
    }

indicating that the tree consists of a single object having two key-value pairs.

You may notice that this syntax is identical to the syntax for creating an array of arrays as shown above. In fact, in order for this to be an object, each of the inner sequences must have exactly two values, and its first value must be a string value. Failing that, it will be interpreted as an array of arrays.

As with arrays, nesting of objects is also supported. The following code:

    orcus::json::document_tree doc = {
        { "parent1", {
                { "child1", true  },
                { "child2", false },
                { "child3", 123.4 },
            }
        },
        { "parent2", "not-nested" },
    };

    std::cout << doc.dump(4) << std::endl;

creates a root object having two key-value pairs one of which contains another object having three key-value pairs, as evident in the following output generated by this code:

    {
        "parent1": {
            "child1": true,
            "child2": false,
            "child3": 123.4
        },
        "parent2": "not-nested"
    }

There is one caveat that you need to be aware of because of this special object creation syntax. When you have a nested array that exactly contains two values and the first value is a string value, you must explicitly declare that as an array by using an `array` class instance. For instance, this code:

    orcus::json::document_tree doc = {
        { "array", { "one", 987.0 } }
    };

is intended to be an object containing an array. However, because the supposed inner array contains exactly two values and the first value is a string value, which could be interpreted as a key-value pair for the outer object, it ends up being too ambiguous and a `key_value_error` exception gets thrown as a result.

To work around this ambiguity, you need to declare the inner array to be explicit by using an `array` instance:

    using namespace orcus;

    json::document_tree doc = {
        { "array", json::array({ "one", 987.0 }) }
    };

    std::cout << doc.dump(4) << std::endl;

This code now correctly generates a root object containing one key-value pair whose value is an array:

    {
        "array": [
            "one",
            987
        ]
    }

Similar ambiguity issue arises when you want to construct a tree consisting only of an empty root object. You may be tempted to write something like this:

    using namespace orcus;

    json::document_tree doc = {};

However, this will result in leaving the tree entirely unpopulated i.e. the tree will not even have a root node! If you continue on and try to get a root node from this tree, you’ll get a `document_error` thrown as a result. If you inspect the error message stored in the exception:

    try
    {
        auto root = doc.get_document_root();
    }
    catch (const json::document_error& e)
    {
        std::cout << e.what() << std::endl;
    }

you will get

    json::document_error: document tree is empty

giving you further proof that the tree is indeed empty! The solution here is to directly assign an instance of `object` to the document tree, which will initialize the tree with an empty root object. The following code:

    using namespace orcus;

    json::document_tree doc = json::object();

    std::cout << doc.dump(4) << std::endl;

will therefore generate

    {
    }

You can also use the `object` class instances to indicate empty objects anythere in the tree. For instance, this code:

    using namespace orcus;

    json::document_tree doc = {
        json::object(),
        json::object(),
        json::object()
    };

    std::cout << doc.dump(4) << std::endl;

is intended to create an array containing three empty objects as its elements, and that’s exactly what it does:

    [
        {
        },
        {
        },
        {
        }
    ]

So far all the examples have shown how to initialize the document tree as the tree itself is being constructed. But our next example shows how to create new key-value pairs to existing objects after the document tree instance has been initialized.

    using namespace orcus;

    // Initialize the tree with an empty object.
    json::document_tree doc = json::object();

    // Get the root object, and assign three key-value pairs.
    json::node root = doc.get_document_root();
    root["child1"] = 1.0;
    root["child2"] = "string";
    root["child3"] = { true, false }; // implicit array

    // You can also create a key-value pair whose value is another object.
    root["child object"] = {
        { "key1", 100.0 },
        { "key2", 200.0 }
    };

    root["child array"] = json::array({ 1.1, 1.2, true }); // explicit array

    std::cout << doc.dump(4) << std::endl;

This code first initializes the tree with an empty object, then retrieves the root empty object and assigns several key-value pairs to it. When converting the tree content to a string and inspecting it you’ll see something like the following:

    {
        "child array": [
            1.1,
            1.2,
            true
        ],
        "child1": 1,
        "child3": [
            true,
            false
        ],
        "child2": "string",
        "child object": {
            "key1": 100,
            "key2": 200
        }
    }

The next example shows how to append values to an existing array after the tree has been constructed. Let’s take a look at the code:

    using namespace orcus;

    // Initialize the tree with an empty array root.
    json::document_tree doc = json::array();

    // Get the root array.
    json::node root = doc.get_document_root();

    // Append values to the array.
    root.push_back(-1.2);
    root.push_back("string");
    root.push_back(true);
    root.push_back(nullptr);

    // You can append an object to the array via push_back() as well.
    root.push_back({{"key1", 1.1}, {"key2", 1.2}});

    std::cout << doc.dump(4) << std::endl;

Like the previous example, this code first initializes the tree but this time with an empty array as its root, retrieves the root array, then appends several values to it via its `push_back()` method.

When you dump the content of this tree as a JSON string you’ll get something like this:

    [
        -1.2,
        "string",
        true,
        null,
        {
            "key1": 1.1,
            "key2": 1.2
        }
    ]