WJElement API

WJElement Synopsis

The WJElement interfaces allow you to load an entire JSON document into memory and to then access elements within it more easily.

WJElement uses UTF-8 encoding internally, as do the underlying WJReader and WJWriter libraries. Adding other unicode support to WJR/WJW would not take too much work.

WJElement is thread-safe, though an individual WJElement document and its children should not be used across threads without locking. WJElement does not provide locking, but its structure provides a handy client pointer which you may use for this or any other purpose.

Many WJE* functions use selector strings; see WJElement Selectors.

Schema selection and validation is supported by WJESchema* functions; see WJElement Schema.

WJElement Data Types

WJElement is the main structure used for JSON documents. In most circumstances it will not be necessary to access anything within such a structure directly, but there are times when peeking at a JSON object's name or type (and other properties) comes in handy.

From wjelemeht.h:

    typedef struct WJElementPublic {
        char                            *name;
        WJRType                         type;

        struct WJElementPublic          *next;
        struct WJElementPublic          *prev;

        struct WJElementPublic          *child;
        struct WJElementPublic          *parent;

        /* The number of children */
        int                             count;

        /*
            A count of changes that have been performed on this element, which can
            be reset by the consumer.
        */
        int                             changes;

        void                            *client;

        /*
            If set then this freecb will be called before actually free'ing a
            WJElement.  If it returns FALSE then the WJElement will NOT be free'd.

            This can be used to allow caching of objects.  If used in this way then
            the consumer that set the callback is responsible for ensuring that it
            does get free'd correctly at the correct time.
        */
        XplBool                         (* freecb)(struct WJElementPublic *);
    } WJElementPublic;
    typedef WJElementPublic *            WJElement;

WJEAction specifies which operation to carry out when calling the JSON manipulation functions.

From wjelemeht.h:

    typedef enum {
        WJE_GET = 0,
        WJE_SET,
        WJE_NEW,
        WJE_MOD
    } WJEAction;

• WJE_GET
  • Return the value of an element. If the element does not exist then the provided default value will be returned.
• WJE_SET
  • Assign the specified value to an element. If the element does not exist then it will be created.
  • If the element can not be created then an appropriate value will be returned to indicate the error.
  • When applicable a NULL will be returned. Otherwise a value that does not match the requested value will be returned.
• WJE_NEW
  • Create a new element and assign it the specified value.
  • If an element already exists then it will not be modified, and the value of that existing element will be returned.
• WJE_MOD
  • Assign the specified value to an existing element, and return the value if successful.
  • If the element does not exist then no elements are created or modified.
  • When applicable a NULL will be returned. Otherwise a value that does not match the requested value will be returned.

WJElement Interfaces

Document/Element Management

WJEParse - Parse the provided JSON document and return the new WJElement

WJElement WJEParse(const char *json);
WJElement _WJEParse(const char *json, char quote);

The _WJEParse version can be used to parse a document with a non-standard quote character. This allows easy parsing of simple documents directly in a C source file without having to escape double quote characters. Example:

doc = _WJEParse("{ 'foo': true, 'bar': 'yup' }", '\'');

WJEOpenDocument - Load a WJElement object from the provided WJReader

WJElement WJEOpenDocument(WJReader reader, char *where, WJELoadCB loadcb, void *data);

If a load callback is provided then it will be called before adding any new children, allowing the consumer to leave specific elements of the hierarchy.

WJEWriteDocument - Write a WJElement object to the provided WJWriter

XplBool WJEWriteDocument(WJElement document, WJWriter writer, char *name);

WJEWriteFILE - Write a WJElement object to the provided FILE*

void WJEWriteFILE(WJElement document, FILE* fd);

WJEWriteMEM - Allocate and write to a string

char * WJEWriteMEM(WJElement document, XplBool pretty, size_t maxlength);

WJEWriteMEM() allocates and returns a string containing the document. A maxlength of 0 means the string may be of unlimited length. The returned string must be freed with MemFree by the consumer.

WJECloseDocument - Destroy a WJElement object

XplBool WJECloseDocument(WJElement document);

WJECloseDocument is also used to delete/remove an item from a parent document: WJECloseDocument(WJEGet(...));

WJECopyDocument - Duplicate an existing WJElement

WJElement WJECopyDocument(WJElement to, WJElement from, WJECopyCB loadcb, void *data);

If a copy callback is provided, then it will be called with each element in order to allow filtered copying on an element-by-element basis, using any criteria.

WJECopyDocument is normally used to create a new copy or to populate a new, empty document, but that is not required or enforced. If "to" is already populated, WJEMergeObjects is probably the desired function for copying in other contents.

WJEDettach - Remove a WJElement from it's parent (and siblings)

XplBool WJEDettach(WJElement document);

WJEAttach - Add a document to another document as a child

XplBool WJEAttach(WJElement container, WJElement document);

WJERename - Rename an element

XplBool WJERename(WJElement document, const char *name);

WJMergeObjects - Merge all fields from one object to another

XplBool WJEMergeObjects(WJElement to, WJElement from, XplBool overwrite);

JSON Manipulation

All JSON manipulation functions take a 'path' argument. This is a string as explained here: WJElement Selectors

Functions which take a 'last' parameter allow enumeration of multiple matching elements, if non-NULL is passed. Handy for looping through objects and arrays.

WJEGet - Find the first element within the hierarchy of a WJElement that matches the specified path.

WJElement WJEGet(WJElement container, char *path, WJElement last);

In cases where a direct child of the WJElement is needed, WJEChild may be more suitable, especially if the child's name begins with a non-alphanumeric character.

WJEBool - Access a boolean element

XplBool WJEBool(WJElement container, char *path, WJEAction action, XplBool value);
XplBool _WJEBool(WJElement container, char *path, WJEAction action, WJElement *last, XplBool value);

WJEString, WJEStringN - Access a string element

char * WJEString(WJElement container, char *path, WJEAction action, char *value);
char * _WJEString(WJElement container, char *path, WJEAction action, WJElement *last, char *value);

char * WJEStringN(WJElement container, char *path, WJEAction action, char *value, size_t len);
char * _WJEStringN(WJElement container, char *path, WJEAction action, WJElement *last, char *value, size_t len);

WJEObject - Access an object element

WJElement WJEObject(WJElement container, char *path, WJEAction action);
WJElement _WJEObject(WJElement container, char *path, WJEAction action, WJElement *last);

WJEArray - Access an array element

WJElement WJEArray(WJElement container, char *path, WJEAction action);
WJElement _WJEArray(WJElement container, char *path, WJEAction action, WJElement *last);

WJENull - Access a null element

WJElement WJENull(WJElement container, char *path, WJEAction action);
WJElement _WJENull(WJElement container, char *path, WJEAction action, WJElement *last);

WJEInt32 - Access a number element, as a 32-bit integer

int32 WJEInt32(WJElement container, char *path, WJEAction action, int32 value);
int32 _WJEInt32(WJElement container, char *path, WJEAction action, WJElement *last, int32 value);

WJEUInt32 - Access a number element, as a 32-bit unsigned integer

uint32 WJEUInt32(WJElement container, char *path, WJEAction action, uint32 value);
uint32 _WJEUInt32(WJElement container, char *path, WJEAction action, WJElement *last, uint32 value);

WJEInt64 - Access a number element, as a 64-bit integer

int64 WJEInt64(WJElement container, char *path, WJEAction action, int64 value);
int64 _WJEInt64(WJElement container, char *path, WJEAction action, WJElement *last, int64 value);

WJEUInt64 - Access a number element, as a 64-bit unsigned integer

uint64 WJEUInt64(WJElement container, char *path, WJEAction action, uint64 value);
uint64 _WJEUInt64(WJElement container, char *path, WJEAction action, WJElement *last, uint64 value);

WJEDouble - Access a number element, as a double (as in double-precision floating point)

double WJEDouble(WJElement container, char *path, WJEAction action, double value);
double _WJEDouble(WJElement container, char *path, WJEAction action, WJElement *last, double value);

WJE...F variants - Format-capable versions of element functions

The following functions...

• WJEGetF
• WJEBoolF
• WJEStringF
• WJEStringNF
• WJEObjectF
• WJEArrayF
• WJENullF
• WJEInt32F
• WJEUInt32F
• WJEInt64F
• WJEUInt64F
• WJEDoubleF

...are identical to the non F variants except that the path argument has been moved to the end and is used as a format string. For example if you need a value by index, and that index is stored in the variable x:

val = WJENumberF(doc, WJE_GET, NULL, 0, "foo[%d]", x);

WJEChild - Find, create or update an element by name instead of path. This allows access to elements that would be difficult to reference by path. No selector syntax is used, so only direct children of the element can be found.

WJElement WJEChild(WJElement container, char *name, WJEAction action);

Type specific actions may be done by passing the resulting WJElement and a NULL path to WJEBool(), WJENumber(), WJEString(), WJEObject(), WJEArray() or WJENull().

Data Processing

WJEHash - Calculate a hash for a document

typedef int (* WJEHashCB)(void *context, void *data, size_t size);
EXPORT void WJEHash(WJElement document, WJEHashCB update, void *context);

Debug

WJEDump - write a document to stdout

void WJEDump(WJElement document);