JsonWax for Qt

GETTING STARTED

Download the newest version from the GitHub repository.

You'll need 4 files:
JsonWax.h, JsonWaxEditor.h, JsonWaxParser.h & JsonWaxSerializer.h
Put all 4 files in your Qt-project folder. You'll only need to:

#include "JsonWax.h"

in your project to use JsonWax.

If you haven't enabled C++11 support in your project, you'll need to include this text in your .pro file:

CONFIG += c++11

HOW TO READ VALUES

Let's start out by creating a new JsonWax object, and save it to a file, which we shall call "test.json":

JsonWax json;
json.saveAs("test.json");

The file "test.json" now contains:

{

}

because the JsonWax-object was empty.

What if you have a JSON-document (called "input.json"), and would like to load it? Your JSON-document looks like this:

{
  "component1": "value1",
  "component2": {
    "detail1": "value2"
  }
}

You write:

JsonWax json;
if (json.loadFile("input.json"))
{
qDebug() << json.value({"component1"}).toString();
} else {
qDebug() << "The document wasn't found.";
}

This prints out:

"value1"

since you asked for the value of "component1", and converted it to a string.

But what if you wanted the value of "detail1" inside of "component2"? You write:

JsonWax json;
if (json.loadFile("input.json"))
{
qDebug() << json.value({"component2","detail1"}).toString();
} else {
qDebug() << "The document wasn't found.";
}

Which prints out:

"value2"

If you check what arguments .value(...) requires, it says:

value(const QVariantList& keys, const QVariant& defaultValue = QVariant())

The arguments you gave in the two previous examples were: {"component1"} and {"component2","detail1"}. These were accepted as QVariantLists. So, whenever you see a function with the argument QVariantList keys, it expects a list like this.

But, as you might have noticed, you can have a second argument when using that function. That's a default value for, if the location didn't exist, as a value, in the document. For example, if you wrote:

JsonWax json;
if (json.loadFile("input.json"))
{
qDebug() << json.value({"component3"}, "not there").toString();
} else {
qDebug() << "The document wasn't found.";
}

it would print out:

"not there"

because there is no such value as component3. The same thing goes for:

json.value({"component2"}, "not there").toString();

because the location didn't contain a value - it contained another object.

But you can also have arrays in JSON-documents (square bracket notation).
How would you retrieve an array element with a list of keys like this?

This is your document:

[
  "value1",
  "value2",
  [
    "value3"
  ]
]

We want to retrieve the first value. It's done like this:

JsonWax json;
if (json.loadFile("input.json"))
{
qDebug() << json.value({0}).toString();
} else {
qDebug() << "The document wasn't found.";
}

This prints out:

"value1"

because you asked for the first element in the array (0 is first, 1 is second, etc.).

You may have guessed the next step... retrieving "value3" from the document.

JsonWax json;
if (json.loadFile("input.json"))
{
qDebug() << json.value({2, 0}).toString();
} else {
qDebug() << "The document wasn't found.";
}

It outputs:

"value3"

because you asked for the 3rd element in the root array (number 2), and then asked for the 1st element in that array (number 0).
But, what if you had both? Objects inside an array? And the values weren't strings, but integers?

[
  {
    "component": 15648
  },
  {
    "component": 77
  }
]

You mix the numbers and strings. First, a number specifying the position in the array, then the name of the object, as a string.

JsonWax json;
if (json.loadFile("input.json"))
{
qDebug() << json.value({0, "component"}).toInt();
} else {
qDebug() << "The document wasn't found.";
}

And you get this:

15648

Those were the basics of reading values from JSON-data.

As a final note, I need to tell you the meaning of an empty keys-list: {}.
It refers to the root array or object, which is the top-level element, that exists in every valid JSON-document. Since the JSON document format doesn't allow that to be a value, writing .value({}) will always return the defaultValue.
However, you can use this whenever a function works on arrays or objects, fx. when using the .move or .keys functions.

HOW TO SET VALUES

You've learned how to read values, but what if you wanted to create your own documents, or edit existing ones?
The function you need is setValue(). Our goal is to create this:

{
  "mask1": "value1",
  "mask2": 15000,
  "mask3": {
    "part1": "value2",
    "part2": [
      "value3",
      "value4"
    ]
  }
}

This can be created with just a few lines of code. Let's start with mask1 and mask2.

JsonWax json;
json.setValue({"mask1"}, "value1");
json.setValue({"mask2"}, 15000);

See, if it were a string, we used quotes, and if it were a number, we didn't.
Now, "value2" is the value of an object within an object. We refer to this element the same way as when reading a value, with a list of keys:

json.setValue({"mask3","part1"}, "value2");

And the last part are two values within an array. So, we end the list with a number:

json.setValue({"mask3","part2", 0}, "value3");
json.setValue({"mask3","part2", 1}, "value4");

Finally, we want to save this to a file. We write:

json.saveAs("result.json");

And that's it! We've successfully created a JSON-document, and saved it to a file.
You should notice that setValue always, automatically, overwrites any existing values, or changes the document, so that your setValue-request may be fulfilled.

Okay, but what would happen if the array element number were a negative one, or not just increasing the array size by one?
If we added one more line to the previous code:

json.setValue({"mask3","part2", 5}, "value5");

We would get this document:

{
  "mask1": "value1",
  "mask2": 15000,
  "mask3": {
    "part1": "value2",
    "part2": [
      "value3",
      "value4",
      null,
      null,
      null,
      "value5"
    ]
  }
}

So, it just inserts null values in place of the non-existing array elements.

And using a negative array element value, like this:

json.setValue({"mask3","part2", -1}, "value5");

attempts to fulfill your request as far as possible: it creates "mask3", "part2", and it turns the location into an array. But it can't save the value.
So you'll receive the error message:

JsonWax-insert error: invalid key.

See all available functions here.

JsonWax for Qt

NOW WITH SERIALIZATION

GETTING STARTED

HOW TO READ VALUES

HOW TO SET VALUES