documentation/wjelement.html

<html>
<head>
<title>WJElement Documentation: wjelement</title>
</head>
<body>

<a href="index.html">Index</a>

<h1>WJElement Synopsis</h1>
<p>
  The WJElement interfaces allow you to load an entire JSON document into
  memory and to then access elements within it more easily.
</p>
<p>
  WJElement uses UTF-8 encoding internally, as do the underlying
  <a href="wjreader.html">WJReader</a>
  and
  <a href="wjwriter.html">WJWriter</a>.
  libraries.
  Adding other unicode support to WJR/WJW would not take too much work.
</p>
<p>
  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.
</p>

<h1>WJElement Data Types</h1>
<p>
<strong>WJElement</strong>
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.
</p>
<p>
From wjelement.h:
<blockquote><pre>
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;
</pre></blockquote>
</p>
<p>
<strong>WJEAction</strong>
specifies which operation to carry out when calling the JSON manipulation
functions.
</p>
<p>
From wjelement.h:
<blockquote><pre>
typedef enum {
    WJE_GET = 0,
    WJE_SET,
    WJE_NEW,
    WJE_MOD
} WJEAction;
</pre></blockquote>
</p>
<p>
<ul>
<li>
<strong>WJE_GET</strong>
 <ul>
 <li>
   Return the value of an element.  If the element does not exist then the
   provided default value will be returned.
 </li>
 </ul>
</li>
<li>
<strong>WJE_SET</strong>
 <ul>
 <li>
   Assign the specified value to an element.  If the element does not exist
   then it will be created.
 </li>
 <li>
   If the element can not be created then an appropriate value will be
   returned to indicate the error.
 </li>
 <li>
   When applicable a NULL will be returned.  Otherwise a value that does
   not match the requested value will be returned.
 </li>
 </ul>
</li>
<li>
<strong>WJE_NEW</strong>
 <ul>
 <li>
   Create a new element and assign it the specified value.
 </li>
 <li>
   If an element already exists then it will not be modified, and the value
   of that existing element will be returned.
 </li>
 </ul>
</li>
<li>
<strong>WJE_MOD</strong>
 <ul>
 <li>
   Assign the specified value to an existing element, and return the value
   if successful.
 </li>
 <li>
   If the element does not exist then no elements are created or modified.
 </li>
 <li>
   When applicable a NULL will be returned.  Otherwise a value that does
   not match the requested value will be returned.
 </li>
 </ul>
</li>
</ul>
</p>

<h1>WJElement Interfaces</h1>
<h2>Document/Element Management</h2>
<p>
<strong>WJEParse</strong>
 - Parse the provided JSON document and return the new WJElement
</p>
<p>
<blockquote><pre>
WJElement WJEParse(const char *json);
WJElement _WJEParse(const char *json, char quote);
</pre></blockquote>
</p>
<p>
	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:
    <blockquote><pre>
doc = _WJEParse("{ 'foo': true, 'bar': 'yup' }", '\'');
    </pre></blockquote>
</p>
<p>
<strong>WJEOpenDocument</strong>
 - Load a WJElement object from the provided
<a href="wjreader.html">WJReader</a>
</p>
<p>
<blockquote><pre>
WJElement WJEOpenDocument(WJReader reader, char *where, WJELoadCB loadcb, void *data);
</pre></blockquote>
</p>
<p>
  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.
</p>
<p>
<strong>WJEWriteDocument</strong>
 - Write a WJElement object to the provided
<a href="wjwriter.html">WJWriter</a>
<blockquote><pre>
XplBool WJEWriteDocument(WJElement document, WJWriter writer, char *name);
</pre></blockquote>
</p>
<p>
<strong>WJEWriteFILE</strong>
 - Write a WJElement object to the provided FILE*
<blockquote><pre>
void WJEWriteFILE(WJElement document, FILE* fd);
</pre></blockquote>
</p>
<p>
  WJEWriteFILE() requires an already opened FILE* to write to.
  It is also used internally by <a href="#WJEDump">WJEDump()</a>
</p>

<p>
<strong>WJEWriteMEM</strong>
 - Allocate and write to a string
<blockquote><pre>
char * WJEWriteMEM(WJElement document, XplBool pretty, size_t maxlength);
</pre></blockquote>
</p>
<p>
  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.
</p>

<p>
<strong>WJECloseDocument</strong>
 - Destroy a WJElement object
</p>
<p>
<blockquote><pre>
XplBool WJECloseDocument(WJElement document);
</pre></blockquote>
</p>
<p>
  WJECloseDocument is also used to delete/remove an item from a parent document:
  WJECloseDocument(WJEGet(...));
</p>
<p>
<strong>WJECopyDocument</strong>
 - Duplicate an existing WJElement
</p>
<p>
<blockquote><pre>
WJElement WJECopyDocument(WJElement to, WJElement from, WJECopyCB loadcb, void *data);
</pre></blockquote>
</p>
<p>
  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.
</p>
<p>
<strong>WJEDetach</strong>
 - Remove a WJElement from it's parent (and siblings)
</p>
<p>
<blockquote><pre>
XplBool WJEDetach(WJElement document);
</pre></blockquote>
</p>
<p>
<strong>WJEAttach</strong>
 - Add a document to another document as a child
</p>
<p>
<blockquote><pre>
XplBool WJEAttach(WJElement container, WJElement document);
</pre></blockquote>
</p>
<p>
<strong>WJERename</strong>
 - Rename an element
</p>
<p>
<blockquote><pre>
XplBool WJERename(WJElement document, const char *name);
</pre></blockquote>
</p>
<p>
<strong>WJEMergeObjects</strong>
 - Merge all fields from one object to another
</p>
<p>
<blockquote><pre>
XplBool WJEMergeObjects(WJElement to, WJElement from, XplBool overwrite);
</pre></blockquote>
</p>
<h2>JSON Manipulation</h2>
<p>
  All JSON manipulation functions take a 'path' argument.  This is a string as
  explained below, see <a href="#selectors">WJElement Selectors</a>
</p>
<p>
  Functions which take a 'last' parameter allow enumeration of multiple
  matching elements, if non-NULL is passed.  Handy for looping through objects
  and arrays.
</p>
<p>
<strong>WJEGet</strong>
 - Find the first element within the hierarchy of a WJElement that matches the
specified path.
</p>
<p>
<blockquote><pre>
WJElement WJEGet(WJElement container, char *path, WJElement last);
</pre></blockquote>
</p>
<p>
  In cases where a direct child of the WJElement is needed,
  <strong>WJEChild</strong> may be more suitable, especially if the child's
  name begins with a non-alphanumeric character.
</p>
<p>
<strong>WJEBool</strong>
 - Access a boolean element
</p>
<p>
<blockquote><pre>
XplBool WJEBool(WJElement container, char *path, WJEAction action, XplBool value);
XplBool _WJEBool(WJElement container, char *path, WJEAction action, WJElement *last, XplBool value);
</pre></blockquote>
</p>
<p>
<strong>WJEString, WJEStringN</strong>
 - Access a string element
</p>
<p>
<blockquote><pre>
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);
</pre></blockquote>
</p>
<p>
<strong>WJEObject</strong>
 - Access an object element
</p>
<p>
<blockquote><pre>
WJElement WJEObject(WJElement container, char *path, WJEAction action);
WJElement _WJEObject(WJElement container, char *path, WJEAction action, WJElement *last);
</pre></blockquote>
</p>
<p>
<strong>WJEArray</strong>
 - Access an array element
</p>
<p>
<blockquote><pre>
WJElement WJEArray(WJElement container, char *path, WJEAction action);
WJElement _WJEArray(WJElement container, char *path, WJEAction action, WJElement *last);
</pre></blockquote>
</p>
<p>
<strong>WJENull</strong>
 - Access a null element
</p>
<p>
<blockquote><pre>
WJElement WJENull(WJElement container, char *path, WJEAction action);
WJElement _WJENull(WJElement container, char *path, WJEAction action, WJElement *last);
</pre></blockquote>
</p>
<p>
<strong>WJEInt32</strong>
 - Access a number element, as a 32-bit integer
</p>
<p>
<blockquote><pre>
int32 WJEInt32(WJElement container, char *path, WJEAction action, int32 value);
int32 _WJEInt32(WJElement container, char *path, WJEAction action, WJElement *last, int32 value);
</pre></blockquote>
</p>
<p>
<strong>WJEUInt32</strong>
 - Access a number element, as a 32-bit unsigned integer
</p>
<p>
<blockquote><pre>
uint32 WJEUInt32(WJElement container, char *path, WJEAction action, uint32 value);
uint32 _WJEUInt32(WJElement container, char *path, WJEAction action, WJElement *last, uint32 value);
</pre></blockquote>
</p>
<p>
<strong>WJEInt64</strong>
 - Access a number element, as a 64-bit integer
</p>
<p>
<blockquote><pre>
int64 WJEInt64(WJElement container, char *path, WJEAction action, int64 value);
int64 _WJEInt64(WJElement container, char *path, WJEAction action, WJElement *last, int64 value);
</pre></blockquote>
</p>
<p>
<strong>WJEUInt64</strong>
 - Access a number element, as a 64-bit unsigned integer
</p>
<p>
<blockquote><pre>
uint64 WJEUInt64(WJElement container, char *path, WJEAction action, uint64 value);
uint64 _WJEUInt64(WJElement container, char *path, WJEAction action, WJElement *last, uint64 value);
</pre></blockquote>
</p>
<p>
<strong>WJEDouble</strong>
 - Access a number element, as a double (as in double-precision floating point)
</p>
<p>
<blockquote><pre>
double WJEDouble(WJElement container, char *path, WJEAction action, double value);
double _WJEDouble(WJElement container, char *path, WJEAction action, WJElement *last, double value);
</pre></blockquote>
</p>
<p>
<strong>WJE...F variants</strong>
 - Format-capable versions of element functions
</p>
<p>
The following functions...
<ul>
<li><strong>WJEGetF</strong></li>
<li><strong>WJEBoolF</strong></li>
<li><strong>WJEStringF</strong></li>
<li><strong>WJEStringNF</strong></li>
<li><strong>WJEObjectF</strong></li>
<li><strong>WJEArrayF</strong></li>
<li><strong>WJENullF</strong></li>
<li><strong>WJEInt32F</strong></li>
<li><strong>WJEUInt32F</strong></li>
<li><strong>WJEInt64F</strong></li>
<li><strong>WJEUInt64F</strong></li>
<li><strong>WJEDoubleF</strong></li>
</ul>
...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:
<blockquote><pre>
val = WJENumberF(doc, WJE_GET, NULL, 0, "foo[%d]", x);
</pre></blockquote>
</p>
<p>
<strong>WJEChild</strong>
 - 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.
</p>
<p>
<blockquote><pre>
WJElement WJEChild(WJElement container, char *name, WJEAction action);
</pre></blockquote>
</p>
<p>
  Type specific actions may be done by passing the resulting WJElement and a
  NULL path to WJEBool(), WJENumber(), WJEString(), WJEObject(), WJEArray() or
  WJENull().
</p>
<h2>Data Processing</h2>
<p>
<strong>WJEHash</strong>
 - Calculate a hash for a document
</p>
<p>
<blockquote><pre>
typedef int (* WJEHashCB)(void *context, void *data, size_t size);
EXPORT void WJEHash(WJElement document, WJEHashCB update, void *context);
</pre></blockquote>
</p>
<h2>Schema</h2>
<p>
Callbacks:
</p>
<p>
<blockquote><pre>
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, ...);
</pre></blockquote>
</p>
<p>
  WJESchemaLoadCB callbacks are used to fetch schema as needed.
  WJESchemaFreeCB are called when schema is no longer needed.
</p>
<p>
<strong>WJESchemaValidate</strong>
 - Validate a document against a given schema.
</p>
<p>
<blockquote><pre>
XplBool WJESchemaValidate(WJElement schema, WJElement document,
                          WJEErrCB err, WJESchemaLoadCB load,
                          WJESchemaFreeCB freecb, void *client);
</pre></blockquote>
</p>
<p>
Additional schema will be loaded
via the load callback if needed.  Any validation errors will be reported,
printf-style, to errcb.</p>
<p>
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.
</p>
<p>
<strong>WJESchemaIsType</strong>
 - Determine if a document implements a specific schema.
</p>
<p>
<blockquote><pre>
XplBool WJESchemaIsType(WJElement document, const char *type,
                        WJESchemaLoadCB loadcb, WJESchemaFreeCB freecb,
                        void *client);
</pre></blockquote>
</p>
<p>
  Additional schema will be loaded via the load callback if needed.
</p>
<p>
  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.
</p>
<p>
<strong>WJESchemaNameIsType</strong>
 - variation of WJESchemaIsType which acts on schema name instead of a document
</p>
<p>
<blockquote><pre>
XplBool WJESchemaNameIsType(const char *describedby, const char *type,
                            WJESchemaLoadCB loadcb,
                            WJESchemaFreeCB freecb, void *client);
</pre></blockquote>
</p>
<p>
<strong>WJESchemaGetSelectors</strong>
 - find type/format-matching properties
</p>
<p>
<blockquote><pre>
void WJESchemaGetSelectors(WJElement document,
                           char *type, char *format,
                           WJESchemaLoadCB load,
                           WJESchemaFreeCB freecb,
                           WJESchemaMatchCB matchcb, void *client);
</pre></blockquote>
</p>
<p>
  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".
</p>
<p>
<strong>WJESchemaGetAllSelectors</strong>
 - variation of WJESchemaGetSelectors which provides selectors that
<em>could</em> exist in objects of the given "describedby" schema name
</p>
<p>
<blockquote><pre>
void WJESchemaGetAllSelectors(char *describedby,
                              char *type, char *format,
                              WJESchemaLoadCB load,
                              WJESchemaFreeCB freecb,
                              WJESchemaMatchCB matchcb, void *client);
</pre></blockquote>
</p>
<p>
<strong>WJESchemaFindBacklink</strong>
 - find "backlink" property by schema
</p>
<p>
<blockquote><pre>
char * WJESchemaFindBacklink(WJElement document, const char *format,
                             WJESchemaLoadCB loadcb, WJESchemaFreeCB freecb,
                             void *client);
</pre></blockquote>
</p>
<p>
<strong>WJESchemaNameFindBacklink</strong>
 - find "backlink" property by name
</p>
<p>
<blockquote><pre>
char * WJESchemaNameFindBacklink(char *describedby, const char *format,
                                 WJESchemaLoadCB loadcb, WJESchemaFreeCB freecb,
                                 void *client);
</pre></blockquote>
</p>
<p>
<strong>WJESchemaFreeBacklink</strong>
 - clean up a previously-found backlink
</p>
<p>
<blockquote><pre>
void WJESchemaFreeBacklink(char *backlink);
</pre></blockquote>
</p>
<h2>Debug</h2>
<p><a name="WJEDump" />
<strong>WJEDump</strong>
 - write a document to stdout
</p>
<p>
<blockquote><pre>
void WJEDump(WJElement document);
</pre></blockquote>
</p>

<a name="selectors"><h1>WJElement Selectors</h1></a>
<p>
  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.
</p>
<p>
  A child may be referenced with an alpha-numeric name, or a subscript within
  square brackets:
<blockquote><pre>
foo
["foo"]
["$foo"]
</pre></blockquote>
</p>
<p>
  Additional levels of heirarchy can be referenced by appending an additional
  subscript, or appending a dot and an additional alpha-numeric name:
<blockquote><pre>
one.two.three.four
one["two"]["three"].four
</pre></blockquote>
</p>
<p>
  Subscripts may contain double quoted names.  Any special characters,
  (including .[]*?&quot;'\) can be included by prefixing with a \.
<blockquote><pre>
foo["bar.smeg"]
foo["something with a \&quot;quote\&quot;"]
</pre></blockquote>
</p>
<p>
  Subscripts may contain single quoted names, which behave as double quoted
  names but also allow for * and ? wild card substitution:
<blockquote><pre>
foo['bar.*']
</pre></blockquote>
</p>
<p>
  Subscripts may reference an item by it's offset in an array (or object):
<blockquote><pre>
foo[0]
foo[3]
</pre></blockquote>
</p>
<p>
  Negative offsets are wrapped to the end of the array (or object) meaning
  that [-1] references the last item.
</p>
<p>
  Subscripts may reference a range of offsets by providing 2 offsets seperated
  by a colon:
<blockquote><pre>
foo[2:5]
</pre></blockquote>
</p>
<p>
  Subscripts may reference a set of items by seperating offsets, offset,
  ranges, double quoted and single quoted values:
<blockquote><pre>
foo[2,4:6,'bar.*', "smeg"]
</pre></blockquote>
</p>
<p>
  An empty subscript may be specified to reference all children.
<blockquote><pre>
[]
</pre></blockquote>
</p>
<p>
  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.
<blockquote><pre>
[$]
</pre></blockquote>
</p>
<p>
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.
</p>
<p>
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:
<blockquote><pre>
foo|[]
</pre></blockquote>
</p>
<p>
  A NULL path refers to the container itself.
</p>
<p>
  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.
</p>
<p>
  The following operators are supported for any value:
<blockquote><pre>
==, !=
</pre></blockquote>
</p>
<p>
  A number value may also use the following operators:
<blockquote><pre>
<, >, <=, >=
</pre></blockquote>
</p>
<p>
  Example:
<blockquote><pre>
foo.bar <= 3
foo.bar != 'foo*'
foo.bar != "one"
</pre></blockquote>
<p>
  A condition may be separated from a path with a ; character.
</p>
<p>
  In the following examples the object named "foo" will be returned if it has
  a child named "bar" that matches the condition.
<blockquote><pre>
foo; bar <= 3
foo; bar != 'foo*'
foo; bar != "one"
</pre></blockquote>
</p>

</body>
</html>