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 is built atop WJReader and WJWriter.

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

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);

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, WJELoadCB loadcb, void *data);

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);

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 - 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);

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);

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.

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);

Schema

Callbacks:

typedef WJElement (* WJESchemaLoadCB)(const char *name, void *client, const char *file, const int line);
typedef void (* WJESchemaFreeCB)(WJElement schema, void *client);
typedef void (* WJESchemaMatchCB)(WJElement schema, const char *selector, void *client);
typedef void (* WJEErrCB)(void *client, const char *format, ...);

WJESchemaLoadCB callbacks are used to fetch schema as needed. WJESchemaFreeCB are called when schema is no longer needed.

WJESchemaValidate - Validate a document against a given schema.

XplBool WJESchemaValidate(WJElement schema, WJElement document,
                          WJEErrCB err, WJESchemaLoadCB load,
                          WJESchemaFreeCB freecb, void *client);

Additional schema will be loaded via the load callback if needed. Any validation errors will be reported, printf-style, to errcb.

WJESchemaIsType - Determine if a document implements a specific schema.

XplBool WJESchemaIsType(WJElement document, const char *type,
                        WJESchemaLoadCB loadcb, WJESchemaFreeCB freecb,
                        void *client);

Additional schema will be loaded via the load callback if needed.

If a load callback is not provided then the object type will still be checked but it will not be considered a match if it is a type that extends the specifed type.

WJESchemaNameIsType - variation of WJESchemaIsType which acts on schema name instead of a document

XplBool WJESchemaNameIsType(const char *describedby, const char *type,
                            WJESchemaLoadCB loadcb,
                            WJESchemaFreeCB freecb, void *client);

WJESchemaGetSelectors - find type/format-matching properties

void WJESchemaGetSelectors(WJElement document,
                           char *type, char *format,
                           WJESchemaLoadCB load,
                           WJESchemaFreeCB freecb,
                           WJESchemaMatchCB matchcb, void *client);

WJESchemaGetSelectors calls back matchcb for each WJElement selector which will fetch a property of a given type and format, from a given document. The load callback will be used to load all necessary schema, starting with the document's "describedby". stripat-type wildcards may be used; "Date*" will find "date" and "date-time".

WJESchemaGetAllSelectors - variation of WJESchemaGetSelectors which provides selectors that could exist in objects of the given "describedby" schema name

void WJESchemaGetAllSelectors(char *describedby,
                              char *type, char *format,
                              WJESchemaLoadCB load,
                              WJESchemaFreeCB freecb,
                              WJESchemaMatchCB matchcb, void *client);

WJESchemaFindBacklink - find "backlink" property by schema

char * WJESchemaFindBacklink(WJElement document, const char *format,
                             WJESchemaLoadCB loadcb, WJESchemaFreeCB freecb,
                             void *client);

WJESchemaNameFindBacklink - find "backlink" property by name

char * WJESchemaNameFindBacklink(char *describedby, const char *format,
                                 WJESchemaLoadCB loadcb, WJESchemaFreeCB freecb,
                                 void *client);

WJESchemaFreeBacklink - clean up a previously-found backlink

void WJESchemaFreeBacklink(char *backlink);

Debug

WJEDump - write a document to stdout

void WJEDump(WJElement document);