-
Notifications
You must be signed in to change notification settings - Fork 56
WJElement API
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 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.
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 ignore 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);
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);
All JSON manipulation functions take a 'path' argument. This is a string as explained below, see 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);
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);
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().
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);
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);
WJEDump - write a document to stdout
void WJEDump(WJElement document);
============================================ Elements within the hierarchy of a JSON document can be referenced using a path. Multiple levels of hierarchy can be referenced to find any element below the provided container. The following rules apply to any WJE functions that take a path argument.
A child may be referenced with a alpha-numeric name, or a subscript within square brackets:
["foo"]
Additional levels of heirarchy can be referenced by appending an additional subscript, or appending a dot and an additional alpha-numeric name:
one.two.three.four
one["two"]["three"].four
Subscripts may contain double quoted names. Any special characters, (including .[]*?"') can be included by prefixing with a .
foo["bar.smeg"]
foo["something with a \"quote\""]
Subscripts may contain single quoted names, which behave as double quoted names but also allow for * and ? wild card substitution:
foo['bar.*']
Subscripts may reference an item by it's offset in an array (or object):
foo[0]
foo[3]
Negative offsets are wrapped to the end of the array (or object) meaning that [-1] references the last item.
Subscripts may reference a range of offsets by providing 2 offsets seperated by a colon:
foo[2:5]
Subscripts may reference a set of items by seperating offsets, offset, ranges, double quoted and single quoted values:
foo[2,4:6,'bar.*', "smeg"]
An empty subscript may be specified to reference all children.
[]
A subscript of $ may be specified in actions perform creations to reference the item after the end of an array. This allows appending to an array.
[$]
A NULL path refers to the container itself.
A path may end in a condition. The condition consists of an operator and a value. The value may be a number, a double quoted string, or a single quoted string. If a single quoted string is used it may contain * and ? wild cards.
The following operators are supported for any value:
==, !=
A number value may also use the following operators:
<, >, <=, >=
Example:
foo.bar <= 3
foo.bar != 'foo*'
foo.bar != "one"