jWrite v2

C JSON Writer

Credit to Tony Wilk

Orginal publish jWrite-a-really-simple-JSON-writer-in-C

Introduction

Version 2. This has a new API and differ from orginal implementation. The goal is to be easier to use and maintain.

jWrite is a simple way of writing JSON to a char buffer in C, directly from native variables. It manages the output buffer so you don't overrun, it handles all the fiddly quotes, brackets and commas and reports where you have tried to create invalid JSON.

There is now a C++ version with demo sketch for Arduino. jWriteCpp

You can, of course, write json to a string with sprintf()... but this is miles better.

Background

This is a companione set of functions to "jRead an in-place JSON element reader" jRead.

The same basic design principles apply: it should be in straight C, have little or no memory overhead, execute fast and be simple to use. It is intended for use in embedded projects where using some nice and big C++ structured solution is just not appropriate.

Several approaches were considered; the 'most automatic' was to define a structure which described the JSON and contained pointers to external variables to get the data - this seemed a good idea since it would then be a single call to 'stringify' everything... the downside was the complexity of API required to define such a structure and keep it all in memory.

For the programmer, it is pointless to make configuration of a JSON writer more complicated than writing the stuff out by hand!

jWrite attempts a happy medium in that it is simple and doesn't seem to do much - you just tell it what to write and it does it.

Using the Code

Jumping straight in:

Basic object

int main() {
  char json[1024];
  jwOpen(json, 1024, JW_OBJECT, JW_PRETTY);  // open root node as object
    jw_key( "key" );                         // writes "key":
    jw_string( "value" );                    // writes "value"
    jw_key( "int" );                         // writes "int":
    jw_int( 1 );                             // writes 1
    jw_key( "anArray" );                     // writes "anArray":
    jw_array();                              // start "anArray": [...] 
      jw_int( 0 );                           // add a few integers to the array
      jw_int( 1 );
      jw_int( 2 );
    jwEnd();                                 // end the array
  jwClose();                                 // close root object - done
}

The json is build up from multiple write calls:

There are longer examples in the examples directory.

Error handling

Although this looks very straightforward, not a lot different than a load of sprintf()s you may say, but jWrite does a few really useful things: it helps you make the output valid JSON.

You can easily call a sequence of jWrite functions which are invalid, like:

jwOpen( buffer, buflen, JW_OBJECT, JW_PRETTY );  // open root node as object
jw_key( "key" );                         // writes "key":
jw_string( "value" );                    // writes "value"
jw_key( "int" );                         // writes "int":
jw_int( 1 );                             // writes 1
  jw_int( 0 );                              // invalid, no key
...

Since the JSON root is an object, we must insert "key":"value" pairs, so the call to jw_int( 0 ) is not valid at this point... this sets an internal error flag to "tried to write value without key"" and ignores subsequent function calls until the ending jwClose() when it reports the error.

When writing a large JSON file, it may be difficult to figure out where you went wrong... in this case, jWrite helps out by giving you the number of the function which caused the error and leaving the partially-constructed JSON in your buffer (with '\0' termianator). In the above case, jwErrorPos() would return 6 because the 6th function in this sequence caused the error (the jwOpen() call is number 1)

"Advanced" usage

Since jWrite handles the JSON formatting, it's easy to create the output programatically (rather than in-line as above) like:

jwOpen( buffer, buflen, JWOBJECT, JW_COMPACT );    // outer JSON is an object, compact format

jw_key( "myArray" );
jw_array();                          // contains an array: "myArray":[...]
for( i=0; i<myArrayLen; i++ )
    jw_int( myArray[i] );                       // write zero or more array entries
jwEnd();

err= jwClose();

In this example, myArrayLen could be anything (0,1,2...) and jWrite handles the output and puts the array value separator commas in the right places.

Any valid JSON sequence can be created with value types of Object, Array, int, double, bool, null and string. You can also add your own stringified values by inserting them raw, e.g., jw_raw( rawtext ).

Points of Interest

The Internal Control Structure Internally, the jWrite functions keep a stack of the Object/Array depth and at every call check if that would result in an error or not. An almost minor point is that it manages your output buffer - once you pass a buffer and length to jwOpen(), it will not overrun it (it will return you an "output buffer full" error) and it will keep it '\0' terminated.

You may have realised that these functions must store some state information (and the node stack) somewhere...

...yes, there is a struct jWriteControl which keeps track of the internals and is used by all of the functions.

Some of you may say "Oh, ok, fine" and others may say "Wait a minute... that's not GLOBAL is it ?"

Well, yes and no...

To Be, or Not To Be, GLOBAL

For many applications it is a lot simpler to have one global (static) instance of a structure which can be used for jWrite, it makes the API calls easy to type in - you don't have to supply a reference every time.

However, that is not very flexible and does not allow for multiple uses of jWrite functions at the same time, so jWrite allows you to turn off the global by undefining JW_GLOBAL_CONTROL_STRUCT. This causes all the API functions to require a pointer to an application-supplied instance of struct jWriteControl.

The above example with #define JW_GLOBAL_CONTROL_STRUCT commented out looks like:

struct jWriteControl jwc;
jwOpen( &jwc, buffer, buflen, JW_OBJECT, JW_PRETTY );  // open root node as object
  jw_key( &jwc, "key" );                         // writes "key":
  jw_string( &jwc, "value" );                    // writes "value"
  jw_key( &jwc, "int" );                         // writes "int":
  jw_int( &jwc, 1 );                             // writes 1
  jw_key( &jwc, "anArray" );                     // writes "anArray":
  jw_array( &jwc );                              // start "anArray": [...] 
    jw_int( &jwc, 0 );                           // add a few integers to the array
    jw_int( &jwc, 1 );
    jw_int( &jwc, 2 );
  jwEnd( &jwc );                                 // end the array
wClose( &jwc );                                 // close root object - done

Which is a lot more to type in and begs to be a C++ class really... which has now been written with an example sketch for Arduino, although the class itself is applicable to any platform.

Conclusion

The jWrite and jRead are simple to use and make handling JSON in C manageable without overhead nor a complicated API to learn, especially in embedded projects where you still need to be careful of memory and processor usage.

jWrite C version is written in C89 and has no dependencies.

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)