Path

TIBET Paths

wins

  • De-facto standard query format for JSON content access (JSON Path)
  • Industry-standard query format for XML content access (XPath 1.0)
  • Powerful/extensible query format for JavaScript objects (TIBET paths)

concepts

Access paths are essentially queries, a way of defining a traversal that should be undertaken on a piece of data to arrive at the desired result set.

In most cases the only thing you need to be aware of to leverage a path/query in TIBET is the syntax of the particular query language you want to use.

In TIBET there are three primary data formats that can be queried using the current set of TP.path.AccessPath subtypes: JSON, XML, and JavaScript objects.

TIBET automatically creates and invokes instances of TP.path.AccessPath subtype to process most queries. In particular it will create paths automatically when:

  • a URL includes an XPointer such as #xpath(...), #jpath(...), or #tibet(...).
  • a get() or set() call includes a "path character" such as /, ., [, etc.

A couple quick examples are shown below:

//  URL
target = TP.uc('~app_dat/sourcedoc.json#jpath($.foo.bar)');

//  get/set
target = myObject.get('foo.bar[1]');

In both cases above TIBET will create an access path instance from the provided path string. The specific subtype of path depends on a number of factors and TIBET will try its best to "guess" the proper type based on the target data and the syntax of the path itself.

JSON Path queries almost always begin with $., XPath queries with /, and typical "TIBET paths" with an initial JavaScript attribute name.

Once the path instance has been constructed it is passed to TIBET's get or set machinery which effectively turns around and hands the path its content data to be traversed.

You can also construct an access path yourself, ensuring that you get the path type you explicitly desire, and pass it directly although this is rarely necessary.

Paths have a couple of interesting features that go beyond simple query ability.

First, they can be "auto collapsed" meaning that when a result set includes only a single data item only that item is returned without any enclosing collection.

Second, and far more interesting, is that paths can be instructed to force creation of any intermediate steps. This latter feature allows you to bind an empty XML or JSON structure to a form or other construct and have it literally build out the entire XML or JSON tree as it is queried, simplifying authoring of forms and other features.

Query Syntax

For JSON queries see the documentation on the jsonpath-plus npm module.

TIBET path syntax is effectively just a simple dot-separated path syntax (foo.bar.baz) augmented with the ability to use Python-style slicing syntax.

For XML queries see the documentation on XPath 1.0. Google XPath 1.0 Examples for more.

cookbook

See ~lib/test/src/tibet/databinding/TP.core.DataPath_Tests.js for examples of a wide variety of paths and queries.

Create A Path

//  create a path, letting TIBET determine the specific subtype:
path = TP.apc(somepath);

Create A Specific Type Of Path

//  create a specific subtype by invoking the proper construct call:
path = TP.path.ComplexTIBETPath.construct(somepath);

Use A Constructed Path

//  pass the path and get the result of the traversal:
data = sourceObject.get(path);

Force Collapse Of Result Sets

path = TP.apc(somepath);
path.set('shouldCollapse', true);

Force Creation Along A Path

path = TP.apc(somepath);
path.set('shouldMakeStructures', true);

code

Numerous path tests (and syntax examples) can be found in TIBET's test files, in particular ~lib/test/src/tibet/databinding/TP.core.DataPath_Tests.js.

JSONPath support in TIBET is encapsulated within TP.path.JSONPath type in ~lib/src/tibet/kernel/TIBETContentTypes.js. The underlying implementation is provided by the common npm module jsonpath-plus.

TIBET's "custom path" support is implemented in the TP.path.SimpleTIBETPath and TP.path.ComplexTIBETPath types in ~lib/src/tibet/kernel/TIBETContentTypes.js

Support for XPath 1.0 is built in to all major browsers. TIBET leverages this infrastructure via the TP.path.XMLPath type in ~lib/src/tibet/kernel/TIBETContentTypes.js