WJElement Documentation: wjelement

Index

# 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.

# 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 wjelement.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 wjelement.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);

WJEWriteFILE - Write a WJElement object to the provided FILE*

>     void WJEWriteFILE(WJElement document, FILE* fd);

WJEWriteFILE() requires an already opened FILE* to write to. It is also used internally by WJEDump()

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.

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

>     XplBool WJEDetach(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);

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

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

## 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.

If a the load callback is used to acquire schema but a NULL free callback is provided, WJECloseDocument will be used internally to release it.

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

# WJElement Selectors

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 an alpha-numeric name, or a subscript within square brackets:

>     foo
>     ["foo"]
>     ["$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 subscript may be prefixed by an | character to indicate that the subscript is optional. The portion of the selector from the | on will be ignored if there is a match and that match has no children.

For example, if an element named foo may either be a string or an array of strings you can enumerate all values using a selector of:

>     foo|[]

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"

A condition may be separated from a path with a ; character.

In the following examples the object named "foo" will be returned if it has a child named "bar" that matches the condition.

>     foo; bar <= 3
>     foo; bar != 'foo*'
>     foo; bar != "one"