The qx-json header file provides various utilities for JSON data manipulation. More...

#include "qx/core/qx_core_export.h"
#include <QString>
#include <QJsonValueRef>
#include <QJsonObject>
#include <QJsonArray>
#include <QJsonDocument>
#include <QFile>
#include <QFileInfo>
#include "qx/core/qx-abstracterror.h"
#include "qx/core/qx-error.h"
#include "qx/utility/qx-macros.h"
#include "qx/utility/qx-concepts.h"

Include dependency graph for qx-json.h:

Classes
class	QxJson::Array
	The array class represents a JSON array node for use in error contexts. More...

class	QxJson::ArrayElement
	The array element key class represents a JSON Array element node for use in error contexts. More...

class	QxJson::Document
	The document class represents a JSON document node for use in error contexts. More...

class	QxJson::File
	The file class represents a JSON file node for use in error contexts. More...

class	Qx::JsonError
	The JsonError class is used to report errors related to JSON manipulation. More...

class	QxJson::Object
	The object class represents a JSON object node for use in error contexts. More...

class	QxJson::ObjectKey
	The object key class represents a JSON Object key node for use in error contexts. More...

class	Qx::QJsonParseErrorAdapter
	Allows QJsonParseError to be used via the Qx::Error interface. More...

Namespaces
namespace	Qx
	The `Qx` namespace is the main namespace through which all non-global functionality of the Qx library is accessed.

namespace	QxJson
	The `QxJson` namespace encapsulates the user-extensible implementation of Qx's JSON parsing facilities.

Concepts
concept	QxJson::qjson_type
	Specifies that a type is one of the fundamental JSON types within Qt's JSON system.

concept	QxJson::json_struct_inside
	Specifies that a type is a JSON-tied struct registered with QX_JSON_STRUCT().

concept	QxJson::json_struct_outside
	Specifies that a type is a JSON-tied struct registered with QX_JSON_STRUCT_OUTSIDE().

concept	QxJson::json_struct
	Specifies that a type is a JSON-tied struct.

concept	QxJson::json_convertible
	Specifies that a type is generally convertible to/from JSON.

concept	QxJson::json_override_convertible

concept	QxJson::json_keyable
	Specifies that a type has a known method for creating a corresponding key.

concept	QxJson::json_collective
	Specifies that a type is a non-associative container, the value type of which is convertible to/from JSON.

concept	QxJson::json_associative
	Specifies that a type is an associative container, the value type of which is convertible, to/from JSON, and for which a key/value type specializaton of keygen() exists.

concept	QxJson::json_containing
	Specifies that a type is a container, and abides by the other corresponding restrictions for that kind of a container.

concept	QxJson::json_optional
	Specifies that a type is a specialization of std::optional that manages values of a JSON convertible type.

concept	Qx::json_root
	Specifies that a type is a valid analogue for a JSON document root element.

Macros
#define	QX_JSON_MEMBER(member) QxJsonPrivate::makeMemberMetadata<#member>(&StructT::member)

#define	QX_JSON_MEMBER_ALIASED(member, key) QxJsonPrivate::makeMemberMetadata<key>(&StructT::member)

#define	QX_JSON_MEMBER_OVERRIDE(Struct, member, ...)

#define	QX_JSON_STRUCT(...) __QX_JSON_META_STRUCT_INSIDE(std::make_tuple(QX_FOR_EACH_DELIM(QX_JSON_MEMBER, __VA_ARGS__)))

#define	QX_JSON_STRUCT_OUTSIDE(Struct, ...) __QX_JSON_META_STRUCT_OUTSIDE(Struct, std::make_tuple(QX_FOR_EACH_DELIM(QX_JSON_MEMBER, __VA_ARGS__)))

#define	QX_JSON_STRUCT_OUTSIDE_X(Struct, ...) __QX_JSON_META_STRUCT_OUTSIDE(Struct, std::make_tuple(__VA_ARGS__))

#define	QX_JSON_STRUCT_X(...) __QX_JSON_META_STRUCT_INSIDE(std::make_tuple(__VA_ARGS__))

Typedefs
using	QxJson::ContextNode = std::variant<File, Document, Object, ObjectKey, Array, ArrayElement>

Functions
QString	Qx::asString (const QJsonValue &value)

QList< QJsonValue >	Qx::findAllValues (const QJsonValue &rootValue, QStringView key)

template<typename Key , class Value >
Key	QxJson::keygen (const Value &value)=delete
	The keygen template function acts as an interface through which the derivation of a key for a given type, when used in associative containers, is defined.

template<typename T > requires QxJson::json_containing<T>
JsonError	Qx::parseJson (T &parsed, const QJsonArray &array)

template<typename T > requires json_root<T>
JsonError	Qx::parseJson (T &parsed, const QJsonDocument &doc)

template<typename T > requires QxJson::json_struct<T>
JsonError	Qx::parseJson (T &parsed, const QJsonObject &obj)

template<typename T > requires json_root<T>
JsonError	Qx::parseJson (T &parsed, const QString &filePath)

template<typename T > requires json_root<T>
JsonError	Qx::parseJson (T &parsed, QFile &file)

template<typename T > requires json_root<T>
JsonError	Qx::serializeJson (const QString &serializedPath, const T &root)

template<typename T > requires json_root<T>
JsonError	Qx::serializeJson (QFile &serialized, const T &root)

template<typename T > requires QxJson::json_containing<T>
void	Qx::serializeJson (QJsonArray &serialized, const T &container)

template<typename T > requires json_root<T>
void	Qx::serializeJson (QJsonDocument &serialized, const T &root)

template<typename T > requires QxJson::json_struct<T>
void	Qx::serializeJson (QJsonObject &serialized, const T &struc)

Detailed Description

The mechanisms of this file introduce a highly flexible, simple to use, declarative mechanism for parsing/serializing JSON data into user structs and other types.

For example, the following JSON data:

{
    "title": "Sample JSON Data",
    "info": {
        "rating": 10,
        "cool": true
    },
    "reviews": [
        "Wicked!",
        "Awesome!",
        "Fantastic!"
    ]
}

can easily be parsed into a corresponding set of C++ data structures like so:

#include <qx/core/qx-json.h>
 
struct Info
{
    int rating;
    bool cool;
    
    QX_JSON_STRUCT(rating, cool);
};
 
struct MyJson
{
    QString title;
    Info info;
    QList<QString> reviews;
    
    QX_JSON_STRUCT(title, info, reviews);
};
 
int main()
{
    QFile jsonFile("data.json");
    MyJson myJsonDoc;
 
    // Parse into custom structures
    Qx::JsonError je = Qx::parseJson(myJsonDoc, jsonFile);
    Q_ASSERT(!je.isValid());
    
    ...
}

Likewise, the structure can be serialized back out into textual JSON data with:

int main()
{
    ...
    
    // Serialize to JSON
    je = Qx::serializeJson(jsonFile, myJsonDoc);
    Q_ASSERT(!je.isValid());
}

See also: QX_JSON_STRUCT(), and QxJson.

Macro Definition Documentation

◆ QX_JSON_MEMBER

#define QX_JSON_MEMBER ( member ) QxJsonPrivate::makeMemberMetadata<#member>(&StructT::member)

Used to denote a JSON struct member whose name matches its key when using QX_JSON_STRUCT_X().

See also: QX_JSON_STRUCT_X()

◆ QX_JSON_MEMBER_ALIASED

#define QX_JSON_MEMBER_ALIASED	(		member,
			key ) QxJsonPrivate::makeMemberMetadata<key>(&StructT::member)

Used to denote a JSON struct member with a key that is different from its name when using QX_JSON_STRUCT_X().

key is to be a string literal.

See also: QX_JSON_STRUCT_X()

◆ QX_JSON_MEMBER_OVERRIDE

#define QX_JSON_MEMBER_OVERRIDE	(	Struct,
		member,
		... )

Value:

namespace QxJson \
{ \
        template<> \
        struct MemberOverrideCoverter<Struct, #member> \
    { \
            __VA_ARGS__\
    }; \
}

Used to define a member/key specific value parsing/serialzing override for a JSON-tried struct. The specified member will be proccessed using the provided functions instead of potentially available generic ones for that type.

Must be used in namespace scope, outside of the struct definition.

struct MySpecialStruct
{
    int number;
    QString name;
    
    QX_JSON_STRUCT(number, name);     
}
 
QX_JSON_MEMBER_OVERRIDE(MySpecialStruct, name,
    static Qx::JsonError fromJson(QString& member, const QJsonValue& jv)
    {
        // Add prefix when parsing
        member = "Prefix" + jv.toString();
        return Qx::JsonError();
    }
    
    static QString toJson(const QString& member)
    {
        // Remove prefix when serializing
        return QString(member).remove("Prefix");
    }
)

◆ QX_JSON_STRUCT

#define QX_JSON_STRUCT ( ... ) __QX_JSON_META_STRUCT_INSIDE(std::make_tuple(QX_FOR_EACH_DELIM(QX_JSON_MEMBER, __VA_ARGS__)))

Specifies that a struct is a JSON-tied struct, which enables support for automatic parsing/serializing of a corresponding JSON object.

The name of each included member must match the name their corresponding JSON key.

struct MyStruct
{
    int number;
    QString name;
    
    QX_JSON_STRUCT(number, name);
}

See also: QX_JSON_STRUCT_OUTSIDE() and QX_JSON_STRUCT_X()

◆ QX_JSON_STRUCT_OUTSIDE

#define QX_JSON_STRUCT_OUTSIDE	(		Struct,
			... ) __QX_JSON_META_STRUCT_OUTSIDE(Struct, std::make_tuple(QX_FOR_EACH_DELIM(QX_JSON_MEMBER, __VA_ARGS__)))

Same as QX_JSON_STRUCT(), but is used outside of a struct instead of inside.

struct MyStruct
{
    int number;
    QString name;
}
 
// At global scope
QX_JSON_STRUCT_OUTSIDE(number, name);

This is useful for hiding the JSON parsing implementation details of a public struct within a different source file.

See also: QX_JSON_STRUCT()

◆ QX_JSON_STRUCT_OUTSIDE_X

#define QX_JSON_STRUCT_OUTSIDE_X	(		Struct,
			... ) __QX_JSON_META_STRUCT_OUTSIDE(Struct, std::make_tuple(__VA_ARGS__))

Same as QX_JSON_STRUCT_X(), but is used outside of a struct instead of inside.

See also: QX_JSON_STRUCT_OUTSIDE()

◆ QX_JSON_STRUCT_X

#define QX_JSON_STRUCT_X ( ... ) __QX_JSON_META_STRUCT_INSIDE(std::make_tuple(__VA_ARGS__))

Same as QX_JSON_STRUCT(), but allows for customization of member keys.

Each member must be wrapped in QX_JSON_MEMBER() or QX_JSON_MEMBER_ALIASED().

struct MyStruct
{
    int number;
    QString name;
    
    QX_JSON_STRUCT_X(
        QX_JSON_MEMBER(number),
        QX_JSON_MEMBER_ALIASED(name, "aliasName")
    );
}

Classes

Namespaces

Concepts

Macros

Typedefs

Functions