README.md

SimpleJSON

1. Preface
2. Introduction
3. Example 1
4. Example 2
5. Useful Utility
6. Details

• How does stringify work?
• stringify behaviour (and STL stringification)

6. Reference

Preface

Please submit pull requests if you don't agree with some behavior or found a bug, I would appreciate it. The library is further matured now and changes less.

This library can parse and stringify and is designed for ease of use. Nobody wants to write parsing and stringification methods for every class they write. We rather want it to work "just like that" without thinking about it. This is where this library fits in. This idea of producing and consuming JSON has become the "Hello World of Introspection".

Since release 0.3, the library also features basic JSON beautification using boost iostreams.

Introduction

A JSON stringifier / parser that uses boost fusion introspection methods for automagic struct <-> JSON conversion

It supports almost all STL contstructs in stringify and the most important for parse. With the STL as a basis it is an easy to extend mechanism using classes. Use boost fusion and the provided utility (see example below) or provide your own parse/stringify methods.

NOTE: The performance of this library is mostly influenced by boost property tree which is used for parsing JSON. The main focus of this library is not speed, but ease of use and convenience. If you want to be fast, try RapidJson (not saying it is particularly slow, but probably not suitable for high data frequency or big bulk data application)

Dependencies:

boost/property_tree
boost/fusion
boost/mpl

Example 0

#ifndef Q_MOC_RUN // A Qt workaround, for those of you who use Qt
# include<SimpleJSON/parse/jsd.hpp>
# include<SimpleJSON/stringify/jss.hpp>
# include<SimpleJSON/stringify/jss_fusion_adapted_struct.hpp>
#endifstructObject : publicJSON::Stringifiable <Object>
, public JSON::Parsable <Object>
{
int A;
std::string B;
float C;
}; BOOST_FUSION_ADAPT_STRUCT(Object, A, B, C)
intmain()
{
auto o = JSON::make_from_json <Object> (R"( { "A": 0, "B": "Hello", "C": 2.4 })");
}

Example 1

#include<string>
#include<vector>
#include<sstream>structConfigContent
{
int id;
std::string libPath;
std::vector <std::string> someContainer;
};
BOOST_FUSION_ADAPT_STRUCT
(
ConfigContent,
(int, id)
(std::string, libPath)
(std::vector <std::string>, someContainer)
)
SJSON_INJECT_STRINGIFY(ConfigContent)
SJSON_INJECT_PARSE(ConfigContent)
intmain()
{
ConfigContent cc;
cc.id = 2;
cc.libPath = "./somewhere";
cc.someContainer = {"Hello", "World"};
std::stringstream sstr;
JSON::stringify(sstr, "", cc);
ConfigContent unnecessarilyComplexCopy;
JSON::parse(unnecessarilyComplexCopy, "", JSON::parse_json(sstr));
/////////////////////////////////////////////////////////////////////////// Lets check if we got what we set/////////////////////////////////////////////////////////////////////////
std::cout << sstr.str() << "\n\n";
std::cout << unnecessarilyComplexCopy.id << "\n";
std::cout << unnecessarilyComplexCopy.libPath << "\n";
for (autoconst& i : unnecessarilyComplexCopy.someContainer)
std::cout << i << "\n";
}

Example 1B

An alternatvie to deriving. Does not handle polymorphic structs. Especially useful for structs, you did not create.

structConfigContent
{
int id;
std::string libPath;
std::vector <std::string> someContainer;
};
BOOST_FUSION_ADAPT_STRUCT
(
ConfigContent,
(int, id)
(std::string, libPath)
(std::vector <std::string>, someContainer)
)
SJSON_INJECT_STRINGIFY(ConfigContent)
SJSON_INJECT_PARSE(ConfigContent)

Example 2

(Showing polymorphic serlialization / deserialization)

#ifndef Q_MOC_RUN // A Qt workaround, for those of you who use Qt
# include<SimpleJSON/parse/jsd.hpp>
# include<SimpleJSON/parse/jsd_convenience.hpp>
# include<SimpleJSON/stringify/jss.hpp>
# include<SimpleJSON/stringify/jss_fusion_adapted_struct.hpp>
#endif
#include"SimpleJSON/utility/polymorphy.hpp"
#include<string>
#include<vector>
#include<sstream>
#include<fstream>structBase
{
virtual~Base() = default;
};
structLine : Base
, public JSON::Stringifiable <Line>
, public JSON::Parsable <Line>
{
std::string text;
};
structPrimalList : Base
, public JSON::Stringifiable <PrimalList>
, public JSON::Parsable <PrimalList>
{
std::vector <std::shared_ptr <Base>> elements;
};
JSON_DECLARE_POLYMORPHIC
(
Base, (Line)(PrimalList)
)
BOOST_FUSION_ADAPT_STRUCT
(
Base
)
BOOST_FUSION_ADAPT_STRUCT
(
Line,
text
)
BOOST_FUSION_ADAPT_STRUCT
(
PrimalList,
elements
)
template <typename T>
voidparse(T& cc, std::istream& json)
{
auto tree = JSON::parse_json(json);
JSON::parse(cc, "json_pno", tree);
}
template <typename T>
std::ostream& stringify(std::ostream& stream, T const& cc)
{
stream << "{";
JSON::stringify(stream, "json_pno", cc, JSON::ProduceNamedOutput);
stream << "}";
return stream;
}
template <typename T>
//using smart_ptr_t = std::shared_ptr <T>;usingsmart_ptr_t = std::unique_ptr<T>;
intmain()
{
smart_ptr_t <Base> a {new Line};
static_cast <Line*> (a.get())->text = "test";
std::stringstream sstr;
stringify(sstr, a);
smart_ptr_t <Base> b;
parse(b, sstr);
if (b)
std::cout << "b!\n";
//std::cout << JSON::polydecls <Base>::identify_type(b.get()) << "\n";/////////////////////////////////////////////////////////////////////////// Lets check if we got what we set/////////////////////////////////////////////////////////////////////////
std::cout << static_cast <Line*> (b.get())->text << "\n";
}

Example 3

Shows formatted output to a file

#ifndef Q_MOC_RUN // A Qt workaround, for those of you who use Qt
# include<SimpleJSON/parse/jsd.hpp>
# include<SimpleJSON/stringify/jss.hpp>
# include<SimpleJSON/stringify/jss_fusion_adapted_struct.hpp>
#endifstructObject : publicJSON::Stringifiable <Object>
, public JSON::Parsable <Object>
{
int A;
std::string B;
float C;
}; BOOST_FUSION_ADAPT_STRUCT(Object, A, B, C)
intmain()
{
Object o;
try_stringifiy_beautiful("myfile.json", "root", o);
// alternative:
{
boost::iostreams::filtering_ostream filter;
// or however else, refer to boost::iostreams doc
filter.push(JSON::BeautifiedStreamWrapper{});
filter.push(boost::iostreams::file_sink(file));
// will not compile with a readable message, // if Object is not a JSON::StringifiableJSON::try_stringify_start(filter, o);
}
}

Useful Utility

JSON::Base64 < T> mem;

mem will be handled as a base64 string. useful if mem can contain any character or binary sequence, including quotes.

JSON::fill_missing

auto tree = JSON::parse_json(str); // str contains some JSON.JSON::fill_missing <MyJsonType> ("", tree); // missing members in the tree of MyJsonType get default constructed.

JSON::rename <T, Name>

Renames a member. This is necessary if something is not a valid C++ identifier, such as "." or "6".

structMyJsonType : /* ... */
{
/** *	SJSON_SHORT_STRING -> handles up to 16 characters. (prefer whenever possible) *	SJSON_STRING -> handles up to 64 characters. *	SJSON_LONG_STRING -> 256 chars. (dont use if possible, heavy compiler performance hit) *	SJSON_LONG_LONG_STRING -> 1024 chars. (dont use if possible, heavy compiler performance hit)*/JSON::rename <std::string, SJSON_SHORT_STRING("__.bla")> blaProperty;
};

Details

How does stringify work?

There is just one function for stringification. This stringify function is heavily overloaded and makes use of SFINAE in almost every overload. The compiler then finds the correct overload to stringify the parameter.

• The library supports almost all STL containers (stringify supports even more) as well as fundamental types.
  
• Containers will decay into json arrays, if their value_type is a stringifiable (this is recursive).
• Classes will turn into objects, if it is adapted, derives from Stringifiable<> and each member is stringifiable.
• For other classes, the "stringify" method is called, if provided, but then you will have to make sure on your own to produce a valid output. (The base64 wrapper uses this).

stringify behaviour (and STL stuff stringification)

It is quite import to know how certain STL constructs translate into JSON and here is a brief summary:

What it is	What it becomes	Remarks
std::vector	[...]
std::deque	[...]
std::list	[...]
std::forward_list	[...]	Who uses forward_list anyway?
std::array	[...]
std::pair	{"first": ..., "second": ...}
std::atomic <T>	What T would produce.	Caution! Obviously calls load().
std::bitset	[1, 0, ...]
std::string	"..."
fundamental types	themselves
JSON::IteratorRange <STL_IteratorT>	[...]
std::map <std::string, T>	{"key": "value", "key2": "value2", ...}	A map basically represents a JSON object
std::mutex	nothing	??? why would you???
std::set	[...]
std::stack	[...]	Don't use if possible, better use deque.
std::queue	[...]	Don't use if possible, better use deque.
std::shared_ptr <T>	What T would produce.	Throws if invalid.
std::unique_ptr <T>	What T would produce.	Throws if invalid.
std::weak_ptr <T>	What T would produce	Throws if invalid.
std::tuple	{"_1": ..., "_2": ..., ...}
std::valarray <T>	[...]
boost::optional	T or nothing	Very useful for making things optional... ofc

Reference

Please visit the wiki: Wiki