Support pair / tuple

JSON-CPP-gen

This is a program that parses C++ structures from a header file and automatically generates C++ code capable of serializing said structures into the JSON format and parsing it back.

For example, if provided with the following structure as input,

struct User {
    int id;
    std::string name;
    std::vector<int> friendIds;
};

JSON-CPP-gen can generate a UserParser class that can be used as

User user;
auto error = UserParser::parse(user, jsonString);

to automatically parse a JSON string that matches the stucture, e.g.

{
    "id": 137,
    "name": "John Smith",
    "friendIds": [ 63, 51, 206 ]
}

And analogously, it can generate a UserSerializer class for the inverse operation. Of course, the input may be more complex - see Configuration and the generated ConfigurationParser for a more complex example.

The generated parsers and serializers are highly efficient because no intermediate DOM or other auxiliary data structures are constructed - data is read directly from / to the input structures.

How to use

To build the program, simply use the provided CMake file. JSON-CPP-gen has no dependencies besides the C++ standard library.

To run the program, you must provide a JSON configuration file that corresponds to the Configuration structure as its command line argument. For example, to generate the UserParser and UserSerializer classes described above, you could use a configuration file containing:

{
    "inputs": [ "User.h" ],
    "includes": [ ],
    "settings": { },
    "parsers": [ {
        "name": "UserParser",
        "types": [ "User" ],
        "headerOutput": "UserParser.h",
        "sourceOutput": "UserParser.cpp"
    } ],
    "serializers": [ {
        "name": "UserSerializer",
        "types": [ "User" ],
        "headerOutput": "UserSerializer.h",
        "sourceOutput": "UserSerializer.cpp"
    } ],
    "stringType": "std::string"
}

All (non-absolute) file names are relative to the configuration file. includes may contain additional include files that should be present in the output files and settings may contain code generator settings. The includes, settings, and stringType fields could be omitted in this case since they are empty or equal to the default value. Even parsers or serializers could be omitted if you only needed one of the two. Additionally, custom string and container data types can be defined in the configuration file - see below. Another example is the configuration file for the ConfigurationParser class.

Features

Supported C++ types:
- All fundamental integer and floating-point types, bool, and size_t
- Structures (struct)
- Enumerations (enum and enum class) - serialized as strings
- Static arrays, including multi-dimensional
- Standard library types:
  - std::string for strings
  - std::vector, std::deque, std::list for dynamic-sized arrays
  - std::array for static-sized arrays
  - std::map for objects with arbitrary keys and homogeneous values
  - std::optional as well as std::auto_ptr, std::shared_ptr, and std::unique_ptr for optional values
- Custom string, array, object, and optional types if defined in the configuration file, see below
Namespaces
Structure inheritance (basic support)
Full UTF-8 & UTF-16 support in JSON

Currently NOT supported but planned features:

Omitting specific member variables from parsing and serialization - planned via annotations
Structure members under different name in JSON - planned via annotations
Classes - currently ignored due to their data being typically private but explicit enablement via annotations is planned - access to private members must be ensured by the user
#define, typedef, using aliases - basic support planned

What will (probably) never be supported:

Heterogeneous JSON objects - not really representable by static stuctures
Unions - impossible to serialize without more advanced logic
Raw pointers - no point in serializing memory addresses and unclear memory management otherwise
Template structures
More complex expression / macro evaluation (e.g. array of length 20*sizeof(User))

Custom types

Even though the standard library string and container types are supported by default, you are not locked into using these exclusively in order for the automatic parser and serializer generation to work. In fact, you may configure JSON-CPP-gen even to produce code where none of the C++ standard library is used.

However, in order to do that, you must provide a set of replacement classes, and for each an API that dictates how it should be used. The API consists of code snippets for specific operations with placeholders. See comments in Configuration.h for a full list of the placeholders. The following are examples for each category of definable custom types and how they should be written in the configuration file. You can specify multiple types for each category.

These are mostly demonstrated on types from the standard library, which however should not be put into the configuration file as they are present by default.

String (dynamic)

"stringTypes": [ {
    "name": "std::string",
    "api": {
        "clear": "$S.clear()",
        "getLength": "$S.size()",
        "getCharAt": "$S[$I]",
        "appendChar": "$S.push_back($X)",
        "appendCStr": "$S += $X",
        "appendStringLiteral": "$S += $X",
        "equalsStringLiteral": "$S == $X",
        "iterateChars": "for (char $E : $S) { $F }"
    }
} ]

Constant string

Represents a string type that cannot be constructed incrementally. Does not have an analogue in the standard library. An intermediate (dynamic) string type must be specified for the parser (can be std::string).

"constStringTypes": [ {
    "name": "ConstString",
    "stringType": "std::string",
    "api": {
        "copyFromString": "$S = $X",
        "moveFromString": "$S = std::move($X)",
        "iterateChars": "for (char $E : $S) { $F }"
    }
} ]

Array (dynamic)

"arrayContainerTypes": [ {
    "name": "std::vector<$T>",
    "api": {
        "clear": "$S.clear()",
        "refAppended": "($S.emplace_back(), $S.back())",
        "iterateElements": "for ($T const &$E : $S) { $F }"
    }
} ]

Note: The refAppended operation must add an empty element at the end of the array and return a modifiable reference to the new element.

Fixed-length array

Represents a non-statically fixed-length array that cannot be constructed incrementally. Does not have an analogue in the standard library. An intermediate (dynamic) array type must be specified for the parser (can be std::vector or another implicit array type).

"fixedArrayContainerTypes": [ {
    "name": "FixedArray<$T>",
    "arrayContainerType": "std::vector",
    "api": {
        "copyFromArrayContainer": "$S = $X",
        "moveFromArrayContainer": "$S = std::move($X)",
        "iterateElements": "for ($T const &$E : $S) { $F }"
    }
} ]

Static length array

"staticArrayContainerTypes": [ {
    "name": "std::array<$T, $N>",
    "api": {
        "refByIndex": "$S[$I]"
    }
} ]

Note: $N is array length.

Object (with implicit key type)

"objectContainerTypes": [ {
    "name": "std::map<std::string, $T>",
    "keyType": "std::string",
    "api": {
        "clear": "$S.clear()",
        "refByKey": "$S[$K]",
        "iterateElements": "for (const std::pair<$U, $T> &$I : $S) { $U const &$K = $I.first; $T const &$V = $I.second; $F }"
    }
} ]

Notes: A key type must be specified as keyType (can be std::string). The refByKey operation must create the element if it doesn't already exist and return a modifiable reference to its value. The iterateElements operation must provide keys and values separately as $K and $V.

Object map (with explicit key type)

"objectMapContainerTypes": [ {
    "name": "std::map<$K, $T>",
    "api": {
        "clear": "$S.clear()",
        "refByKey": "$S[$K]",
        "iterateElements": "for (const std::pair<$U, $T> &$I : $S) { $U const &$K = $I.first; $T const &$V = $I.second; $F }"
    }
} ]

Optional value

"optionalContainerTypes": [ {
    "name": "std::optional<$T>",
    "api": {
        "clear": "$S.reset()",
        "refInitialized": "($S = $T()).value()",
        "hasValue": "$S.has_value()",
        "getValue": "$S.value()"
    }
} ]

Note: The refInitialized operation must initialize the container with a default-constructed value and return a modifiable reference to the value.

	code += std::string(INDENT INDENT)+Error::JSON_SYNTAX_ERROR+",\n";
	code += std::string(INDENT INDENT)+Error::UNEXPECTED_END_OF_FILE+",\n";
	code += std::string(INDENT INDENT)+Error::TYPE_MISMATCH+",\n";
	code += std::string(INDENT INDENT)+Error::ARRAY_SIZE_MISMATCH+",\n";
	code += std::string(INDENT INDENT)+Error::UNKNOWN_KEY+",\n";
	code += std::string(INDENT INDENT)+Error::UNKNOWN_ENUM_VALUE+",\n";
	code += std::string(INDENT INDENT)+Error::VALUE_OUT_OF_RANGE+",\n";
	code += std::string(INDENT INDENT)+Error::STRING_EXPECTED+",\n";
	code += std::string(INDENT INDENT)+Error::UTF16_ENCODING_ERROR+",\n";

	// TODO make key a class member to reduce the number of allocations
	body += indent+generator->stringType()->name().variableDeclaration("key")+";\n";

	// TODO make str a class member to reduce the number of allocations
	body += indent+generator->stringType()->name().variableDeclaration("str")+";\n";

chlumsky / json-cpp-gen Goto Github PK

json-cpp-gen's Introduction

JSON-CPP-gen

How to use

Features

Custom types

String (dynamic)

Constant string

Array (dynamic)

Fixed-length array

Static length array

Object (with implicit key type)

Object map (with explicit key type)

Optional value

json-cpp-gen's People

Contributors

Stargazers

Watchers

Forkers

json-cpp-gen's Issues

Converted type

Custom parse / serialize implementation

String conversion

Recommend Projects

Recommend Topics

Recommend Org