gason++

gason++ is a light tweak for gason parser to make its usage even simpler for end-users. There is also a simple JSon builder tool.

gason is an efficient and fantastic JSon parser in plain C++ with minimum dependency by vivkin.

please read gason documents to see the full list of features and other notes.

Table of Contents

• Notes
• Installation
• Usage
  • Parsing
  • Child elements
  • Type checking
  • Conversion
  • Iteration
  • Building
• License

Notes

TOC

gason(gason++) is efficient and fast and it does not consume any extra memory for parsed values (objects, arrays, ...)

• gason(gason++) is a destructive parser:

your source buffer will be modified! and this buffer is the only place where the values do exist.

• there is a simple and efficient JSonBuilder which is not present on original gason.

• c++11 is optional and gason++ is also compilable on older toolchains. gason requires c++11.

• JsonAllocator is reusable and auto-expandable in gason++ and the implementation does not free/alloc memory with every jsonParse() (this is not the case in gason). for more information see doxygen comments of JsonAllocator or sample:parser

Installation

TOC

Download latest version and just add gason.hpp / gason.cpp and jsonbuilder.hpp from src folder into your project tree.

Other *.pro and source files are just for testing purpose.

Usage

TOC

suppose this json:

{
  "an_array": [
    10,
    11,
    12
  ],
  "a_boolean": true,
  "a_null": null,
  "a_number": 123,
  "an_object": {
    "a": "b",
    "c": "d",
    "e": "f"
  },
  "a_message": "Hello World"
}

Parsing

TOC

to parse it simply do:

// this buffer holds the json content.
// char *jsonString;

gason::JsonAllocator    allocator;
gason::JsonValue        root;
gason::JsonParseStatus  status = gason::jsonParse(jsonString, root, allocator);

if ( status != gason::JSON_PARSE_OK ) {
    puts("parsing failed!");
    // for more info check the status.
    return false;
}

// hint: jsonString will be over-written by jsonParse()
//        and you have to keep this buffer and allocator alive
//        as long as the parsed JSon values are required.

see sample:parser for more examples.

Child elements

TOC

gason++ introduces an easy API to retrieve the child elements:

gason::JsonValue str  = root.child("a_message");        // = Hello World
gason::JsonValue arr0 = root.child("an_array").at(0);   // = 10
// short form
gason::JsonValue arr2 = root("an_array")[2];            // = 12
gason::JsonValue objc = root("an_object")("c");         // = d

All values will become invalid when allocator be destroyed.

Type checking

TOC

to check validity or the type of values:

if ( !str ) {
    puts("str is not a valid JsonValue!");
}
if ( arr2    &&    arr2.isNumber() ) {
    puts("a valid number has been found on an_array[2].");
}
if ( objc    &&    objc.isString() ) {
    puts("an string has been found in root->an_object->c.");
}

Conversion

TOC

JsonValue has some toXXX(bool *ok = nullptr) to convert a value into an int, string, ...

if conversion fails, the conversion methods:

• fire assert() if ok is not specified (default).
• return a 0,nullptr or false value and *ok will be set to false.

bool ok = false;

int  invalidValue1 = str.toInt();   // will assert() and program aborts.

const char* invalidValue2 = arr2.toString(&ok); // won't assert()
if ( !ok ) {
    puts("arr2 is an int not a string!");
}

Iteration

TOC

to iterate over children (elements) simply:

gason::JsonValue obj = root("an_object");

for ( gason::JsonIterator it =  gason::begin(obj); gason::end(obj); it++ ) {
    printf("%s = %s\n", it->key, it->value.toString());
}

// or
gason::JsonIterator it = gason::begin( obj );
while ( it.isValid() ) {
    printf("%s = %s\n", it->key, it->value.toString());

    it++;
}

// both prints:
// a = b
// c = d
// e = f

Building

TOC

to build the above json:

char buffer[257] = {0};
gason::JSonBuilder doc(buffer, 256);

doc.startObject()
        .startArray("an_array")
            .addValue(10)
            .addValue(11)
            .addValue(12)
        .endArray()

        .addValue("a_boolean", true)
        .addNull("a_null")
        .addValue("a_number", 123)

        .startObject("an_object")
            .addValue("a", "b")
            .addValue("c", "d")
            .addValue("e", "f")
        .endObject()

        .addValue("a_message", "Hello World")

        .endObject();

// now the buffer contains the proper json string.

if ( !doc.isBufferAdequate() ) {
    puts("warning: the buffer is small and the output json is not valid.");
}

JSonBuilder just makes compact form of JSon strings suitable for storage or network communications. (the output is not indented.)

see sample:builder for more examples.

License

TOC

Distributed under the MIT license. Copyright (c) 2014, Amir Zamani.