WJReader API

WJReader Synopsis

The WARP JSON Reader provides the ability to parse a JSON document as a stream. All parsing is done with a portion of the document loaded into a buffer, and the buffer is reloaded as needed.

This allows the parser to be very fast, but does require that data in the document is accessed in the order of the document.

WJReader Data Types

WJReader is The WJReader document, the library's primary structure

From wjreader.h:

    typedef struct {
        uint32                  depth;
        uint32                  maxdepth;
        void                    *userdata;
    } WJReaderPublic;
    typedef WJReaderPublic *    WJReader;

WJRType specifies the type of a value being read.

From wjreader.h:

    typedef enum {
        WJR_TYPE_OBJECT         = 'O',
        WJR_TYPE_ARRAY          = 'A',

        WJR_TYPE_STRING         = 'S',
        WJR_TYPE_NUMBER         = 'N',

        WJR_TYPE_BOOL           = 'B',
        WJR_TYPE_TRUE           = 'T',
        WJR_TYPE_FALSE          = 'F',
        WJR_TYPE_NULL           = '0',

        WJR_TYPE_UNKNOWN        = '?'
    } WJRType;

WJReadCallback - Generic data reader (from file, socket, decoder, etc.)

typedef size_t (* WJReadCallback)(char *data, size_t length, size_t seen, void *userdata);

WJReader Interfaces

Document/Reader Management

WJROpenDocument - Open a JSON document and prepare to parse.

WJReader WJROpenDocument(WJReadCallback callback, void *userdata, char *buffer,
                         size_t buffersize);
WJReader _WJROpenDocument(WJReadCallback callback, void *userdata, char *buffer,
                          size_t buffersize, uint32 maxdepth);

A callback function must be provided which will be used to read data as it is needed. The callback is expected to load data into the provided buffer and return the number of bytes that where loaded. If the number of bytes loaded is less than the requested length then it is assumed that the end of the document has been reached.

If a buffer is provided to WJROpenDocument() then that buffer will be used, rather than allocating a new buffer. The size of the buffer must be provided as buffersize. If a buffer is not provided then one will be allocated of size buffersize.

If a buffersize of 0 is passed to WJROpenDocument then the default size will be used (4KB). Some data is kept in the buffer while parsing, such as element names and values. If the buffer is not large enough for these then the document will fail to be parsed and will be aborted.

WJROpenFILEDocument - helper to read from an open FILE *.

WJReader WJROpenFILEDocument(FILE *jsonfile, char *buffer, size_t buffersize);

An alternative method of opening a JSON document, which will provide a proper callback for reading the data from an open FILE *.

As with the standard WJROpenDocument() a buffersize of 0 will use the default buffer size.

WJROpenMemDocument - helper to read from memory.

WJReader WJROpenMemDocument(char *json, char *buffer, size_t buffersize);

An alternative method of opening a JSON document, which will provide a proper callback for reading from a pre-allocated buffer in memory.

As with the standard WJROpenDocument() a buffersize of 0 will use the default buffer size.

WJRCloseDocument - Close a WJReader document.

XplBool WJRCloseDocument(WJReader doc);

JSON Values

WJRNext - Get the type and name of the next element in 'doc'.

char * WJRNext(char *parent, size_t maxnamelen, WJReader doc);

Returns a string, which contains the name of the next element of the specified parent, prefixed by a single character that represents the type. The pointer returned may be used as the parent argument in future calls to WJRNext() in order to return the children of the current object.

If the object's name is larger than the maxnamelen argument then it will be truncated.

These WJReader functions Return the value of the last object returned by WJRNext(). The calling application is expected to know the type of the value, and call the appropriate function. When possible the value will be converted if it does not match the requested type.

If the buffer is not large enough to contain the entire value then the WJRString() function may return a partial value. It may be called multiple times until a NULL is returned to ensure that the entire value has been read.

char *  WJRString(XplBool *complete, WJReader doc);
char *  WJRStringEx(XplBool *complete, size_t *length, WJReader doc);
XplBool WJRBoolean(WJReader doc);

int32   WJRInt32(WJReader doc);
uint32  WJRUInt32(WJReader doc);
int64   WJRInt64(WJReader doc);
uint64  WJRUInt64(WJReader doc);
double  WJRDouble(WJReader doc);

WJRNegative - Check whether the current WJR_TYPE_NUMBER value is negative

XplBool WJRNegative(WJReader doc);

If the current element is a WJR_TYPE_NUMBER then this function can be used to determine if the value is negative or positive. If negative then TRUE will be returned.