WJElement Selectors

penduin edited this page Feb 28, 2014 · 10 revisions

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
["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 which 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"