Selection paths - tooltwist/xdata GitHub Wiki

XData's selection paths allow a program to access specific elements within a block of data.

Two different forms can be interchangeably used to specify paths:

• Using '/' as a separator, similar to XML XPaths.
• Using '.' as a separator, similar to accessing Javascript objects.

These are exactly the same, except they have exact opposite meanings when the separator occurs at the start of the path. A path starting with '/' indicates an absolute path, starting from the top of the data hierarchy. On the other hand, a path starting with '.' indicates a sub-select.

See the examples to understand the difference.

In our examples, we'll assume that a variable named data contains the following information.

<data>
    <version>1.2.3</version>
    <country>
        <name>Fiji</name>
        <city>Nandi</city>
        <city>Suva</city>
    </country>
    <country>
        <name>Zimbabwe</name>
        <city>Harare</city>
    </country>
<data>

For each example, we'll show the '/' and the '.' equivalents.
(Note the output is shown in not in any particular convention or syntax).

Individual values can be accessed by specifying the hierarchy down to the required data element.

data.getString("/data/version")
data.getString("data.version")

-> "1.2.3"

data.select("/data/country/countryName")

-> [ countryName="Fiji", countryName="Zimbabwe" ]

Lists within lists can also be selected:

data.select("/data/country/city")
data.select("data.country.city")

-> [ city="Nandi", city="Suva", city="Harare" ]

The '*' wildcard can be used to replace a segment of the path, and is commonly used to replace the first element:

data.select("/*/country/city")
data.select("*.country.city")

-> [ city="Nandi", city="Suva", city="Harare" ]

A wildcard can return elements of multiple types:

data.select("/*/country/*")
data.select("*.country.*")

-> [ countryName="Fiji", city="Nandi", city="Suva", countryName="Zimbabwe", city="Harare" ]

Note that each item in the list has an name and a value. The name and the value of the item can be accessed like this:

for (XSelector item : data.select("*.country.*")) {
    String name = item.currentName();
    String value = item.getString(".");
}

An array index can be used to select single elements rather than lists.

Note that XData indexes start at zero, unlike XML XPaths where the first element has an index of one.

data.select("/data/country[0]/countryName")
data.select("data.country[0].countryName")

-> [ name="Fiji" ]

Lists can still be accessed beneath an indexed element:

data.select("/data/country[0]/city")
data.select("data.country[0].city")

-> [ city="Nandi", city="Suva" ]

Note that the index applies only within each parent element (in this case, within each country):

data.select("/*/country/city[0]")
data.select("*.country.city[0]")

-> { city="Nandi", city="Harare" }

Note that the zero'th city was returned from each country.

A path starting with '//' (two slashes) will match elements no matter where they are in the data hierarchy.

data.select("//city")

-> [ city="Nandi", city="Suva", city="Harare" ]

Elements may occur at different levels of indent, and under different types of parent element.

--