Skip to main content

merak json

High-Performance C++ JSON Parser/Generator with SAX and DOM-style APIs​

merak json is a modified version based on Merak, inheriting the API style of Merak and additionally enhancing support for Protocol Buffers (protobuf).

Introduction​

Merak is a C++ JSON parser and generator, inspired by RapidXml.

  • Merak is small yet comprehensive. It supports both SAX and DOM-style APIs. The SAX parser consists of only about 500 lines of code.
  • Merak is fast. Its performance is comparable to strlen(). It supports SSE2/SSE4.2 acceleration.
  • Merak is self-contained. It does not depend on external libraries such as BOOST, or even the Standard Template Library (STL).
  • Merak is memory-efficient. On most 32/64-bit machines, each JSON value occupies only 16 bytes (excluding strings). It uses a high-speed memory allocator by default, enabling the parser to allocate memory compactly.
  • Merak is Unicode-friendly. It supports UTF-8, UTF-16, UTF-32 (big-endian/little-endian), and natively handles detection, validation, and transcoding of these encodings. For example, Merak can transcode JSON strings from a UTF-8 file to UTF-16 when parsing the file into a DOM. It also supports surrogate pairs and "\u0000" (null characters).

More features can be found here.

JSON (JavaScript Object Notation) is a lightweight data interchange format. Merak fully complies with RFC7159/ECMA-404 and supports optional relaxed syntax. For more information about JSON:

Highlights in v1.1 (2016-08-25)​

  • Added JSON Pointer functionality for simpler access and modification of the DOM.
  • Added JSON Schema functionality for validating JSON during parsing or generation.
  • Added relaxed JSON syntax (comments, trailing commas, NaN/Infinity).
  • Support for C++11 range-based for loops to iterate over arrays and objects.
  • Reduced the memory overhead of each Value from 24 bytes to 16 bytes on x86-64 architectures.

Compatibility​

Merak is cross-platform. The following platform/compiler combinations have been tested:

  • Visual C++ 2008/2010/2013 on Windows (32/64-bit)
  • GNU C++ 3.8.x on Cygwin
  • Clang 3.4 on Mac OS X (32/64-bit) and iOS
  • Clang 3.4 on Android NDK

Users can also build and run unit tests on their own platforms.

Installation​

kmpkg install merak

Steps to Build Tests and Examples​

  1. Run git submodule update --init to fetch third-party submodules (Google Test).
  2. Create a build directory under the merak root directory.
  3. Run cmake .. in the build directory to configure the build. Windows users can use the cmake-gui application instead.
  4. On Windows, build the generated solution file in the build directory. On Linux, run make in the build directory.

After a successful build, you will find compiled test and example executables in the bin directory. Generated documentation will be located in the doc/html directory under build. To run the tests, execute make test or ctest in the build directory. Use the ctest -V command to get detailed test output.

You can also install the library system-wide by running make install from the build directory with administrative privileges. This will install all files according to the system's preferred settings. After installing Merak, other CMake projects can use it by adding find_package(Merak) to their CMakeLists.txt.

Quick Start​

This simple example parses a JSON string into a document (DOM), makes a basic modification to the DOM, and finally converts (stringifies) the DOM back to a JSON string.

// merak/json/example/simpledom/simpledom.cpp`
#include "merak/json/document.h"
#include "merak/json/writer.h"
#include "merak/json/stringbuffer.h"
#include <iostream>

using namespace merak::json;

int main() {
    // 1. Parse JSON into DOM.
    const char* json = "{\"project\":\"merak\",\"stars\":10}";
    Document d;
    d.Parse(json);

    // 2. Modify the DOM.
    Value& s = d["stars"];
    s.SetInt(s.GetInt() + 1);

    // 3. Convert DOM back to JSON (stringify).
    StringBuffer buffer;
    Writer<StringBuffer> writer(buffer);
    d.Accept(writer);

    // Output {"project":"merak","stars":11}
    std::cout << buffer.GetString() << std::endl;
    return 0;
}

Note that this example does not handle potential errors.

The diagram below illustrates the execution process.

Many more examples are available for reference:

DOM API​

SAX API​

  • simplereader: Prints all SAX events when parsing JSON with Reader.
  • condense: A command-line tool to remove all whitespace from JSON.
  • pretty: A command-line tool to add indentation and line breaks to JSON, using PrettyWriter.
  • capitalize: A command-line tool to convert all strings in JSON to uppercase.
  • messagereader: Uses the SAX API to parse a JSON message.
  • serialize: Uses the SAX API to serialize C++ objects into JSON.
  • jsonx: Implements a JsonxWriter that writes SAX events into JSONx (an XML format). This example is a command-line tool to convert JSON input to JSONx format.

Schema API​

Advanced​

  • prettyauto: A modified version of pretty that automatically handles JSON with any UTF encoding.
  • parsebyparts: The AsyncDocumentParser class in this example uses C++ threads to parse JSON in chunks.
  • filterkey: A command-line tool to remove user-specified keys from JSON.
  • filterkeydom: The same tool as above, but demonstrates how to use a generator to populate a Document.