reflective-rapidjson/README.md

# Reflective RapidJSON

The main goal of this project is to provide a code generator for serializing/deserializing C++ objects to/from JSON
using Clang and RapidJSON.

However, extending the generator to generate code for other applications of reflection or to provide generic
reflection functionallity would be possible as well.

This repository also contains a small, additional header to use RapidJSON with Boost.Hana. This allows to serialize
or dezerialize simple data structures using the `BOOST_HANA_DEFINE_STRUCT` macro rather than requiring the code
generator.

## Supported datatypes
The following table shows the mapping of supported C++ types to supported JSON types:

| C++ type                                 | JSON type |
| ---------------------------------------- |:---------:|
| custom structures/classes                | object    |
| bool                                     | true/false|
| signed and unsigned integral types       | number    |
| float and double                         | number    |
| enum and enum class                      | number    |
| std::string                              | string    |
| const char *                             | string    |
| iteratables (std::vector, std::list, ...)| array     |
| std::tuple                               | array     |

### Remarks
* `const char *` is only supported for serialization.
* Enums are only supported for serialization.
* For deserialization, iteratables must provide an `emplace_back` method. So deserialization of eg. `std::forward_list`
  is currently not supported.
* Using pointers is not supported yet.
* The JSON type `null` is not supported yet.

## Usage
This example shows how the library can be used to make a `struct` serializable:
```
#include <reflective-rapidjson/json/serializable.h>

// define structures, eg.
struct TestObject : public JsonSerializable<TestObject> {
    int number;
    double number2;
    vector<int> numbers;
    string text;
    bool boolean;
};
struct NestingObject : public JsonSerializable<NestingObject> {
    string name;
    TestObject testObj;
};
struct NestingArray : public JsonSerializable<NestingArray> {
    string name;
    vector<TestObject> testObjects;
};

// serialize to JSON
NestingArray obj{ ... };
cout << "JSON: " << obj.toJson().GetString();

// deserialize from JSON
const auto obj = NestingArray::fromJson(...);

// in exactly one of the project's translation units
#include "reflection/code-defining-structs.h"
```

Note that the header included at the bottom must be generated by invoking the code generator appropriately, eg.:
```
reflective_rapidjson_generator -i "$srcdir/code-defining-structs.cpp" -o "$builddir/reflection/code-defining-structs.h"
```

It is possible to use the provided CMake macro to automate this task:
```
find_package(reflective-rapidjson REQUIRED)
list(APPEND CMAKE_MODULE_PATH ${REFLECTIVE_RAPIDJSON_MODULE_DIRS})
include(ReflectionGenerator)

add_reflection_generator_invocation(
    INPUT_FILES code-defining-structs.cpp
    GENERATORS json
    OUTPUT_LISTS LIST_OF_GENERATED_HEADERS
)
```

This will produce the file `code-defining-structs.h` in the directory `reflection` in the current build directory. So
make sure the current build directory is added to the include directories of your target. The default output directory can
also be overridden by passing `OUTPUT_DIRECTORY custom/directory` to the arguments.

It is possible to specify multiple input files at once. A separate output file is generated for each input. The output files
will always have the extension "`.h`", independently of the extension of the input file.

The full paths of the generated files are also appended to the variable `LIST_OF_GENERATED_HEADERS` which then can be added
to the sources of your target. Of course this can be skipped if not required/wanted.

### Using Boost.Hana instead of the code generator
The same example as above. However, this time Boost.Hana is used - so it doesn't require invoking the generator.

```
#include "<reflective-rapidjson/json/serializable-boosthana.h>

// define structures using BOOST_HANA_DEFINE_STRUCT, eg.
struct TestObject : public JsonSerializable<TestObject> {
    BOOST_HANA_DEFINE_STRUCT(TestObject,
        (int, number),
        (double, number2),
        (vector<int>, numbers),
        (string, text),
        (bool, boolean)
    );
};
struct NestingObject : public JsonSerializable<NestingObject> {
    BOOST_HANA_DEFINE_STRUCT(NestingObject,
        (string, name),
        (TestObject, testObj)
    );
};
struct NestingArray : public JsonSerializable<NestingArray> {
    BOOST_HANA_DEFINE_STRUCT(NestingArray,
        (string, name),
        (vector<TestObject>, testObjects)
    );
};

// serialize to JSON
NestingArray obj{ ... };
cout << "JSON: " << obj.toJson().GetString();

// deserialize from JSON
const auto obj = NestingArray::fromJson(...);
```

So beside the `BOOST_HANA_DEFINE_STRUCT` macro, the usage remains the same.

## Install instructions

### Dependencies
* C++ compiler and standard library supporting at least C++14
* the CMake build system
* LibTooling from Clang for the code generator
* RapidJSON for JSON (de)serialization
* Boost.Hana for using `BOOST_HANA_DEFINE_STRUCT` instead of code generator
* `c++utilities` for various helper functions

Optional:

* CppUnit for building and running the tests
* Doxygen for generating API documentation
* Graphviz for diagrams in the API documentation

Note that Reflective RapidJSON itself and none of these dependencies are required at runtime by an application
which makes use of Reflective RapidJSON.

### How to build
Install all required dependencies and ensure the CMake script finds them. It is possible to build `c++utilities`
together with `reflective-rapidjson` to simplify the build process. The following build script makes use of this.
To use system `c++utilities`, just skip any lines with "`c++utilities`" in the following examples.

Get sources, eg. using Git:
```
cd $SOURCES
git clone https://github.com/Martchus/cpp-utilities.git c++utilities
git clone https://github.com/Martchus/reflective-rapidjson.git
```

If you don't want to build the development version, just checkout the desired version tag.

Here is an example for building with CMake and GNU Make:
```
cd $BUILD_DIR
# generate Makefile
cmake \
 -DCMAKE_BUILD_TYPE:STRING=Release \
 -DCMAKE_INSTALL_PREFIX:PATH="/final/install/prefix" \
 -DBUNDLED_CPP_UTILITIES_PATH:PATH="$SOURCES/c++utilities" \
 "$SOURCES/reflective-rapidjson"
# build library and generators
make
# build and run tests (optional, requires CppUnit)
make check
# build tests but do not run them (optional, requires CppUnit)
make tests
# generate API documentation (optional, reqquires Doxygen)
make apidoc
# install header files, libraries and generator
make install DESTDIR="/temporary/install/location"
```
Add eg. `-j$(nproc)` to `make` arguments for using all cores.