NBT Path

NBT Path is derived from JSON Path, and offers a way to select data from an NBT tag via a string expression. NBT Path uses the same syntax as JSON Path, which is possible due to NBT's JSON-like nature.

For example, in order the value inside a nested NBT tag such as { root: { child1: { child2: "some value" } }}, you could use the NBT Path expression "$.root.child1.child2". When applying this expression to our NBT tag, you will get "some value" as a result.

The org.cyclops.cyclopscore.nbt.path package contains helpers for creating and using NBT Path expressions, with NbtPath being the main entry class.

Next to selecting nested fields, other expressions are supported as well:

Expression	Description
$	Root tag
@	Current tag
.fieldName	Field by name.
["fieldName"]	Field by name. (accepts special characters)
[1]	List element by index.
..	Parent tag
*	All children. Works on NBT lists or NBT tags.
[fieldA,fieldB,fieldC] or [0,3,5]	A selection of NBT tag fields by names, or NBT list elements by indexes. The combination of fields and indexes is not allowed.
[0:10:2]	List slice operator, corresponding to [start:end:step]. Only start is required, the other elements may be omitted.
?()	Filter expressions over NBT tags or lists. (e.g. [?(@.childName < 10)])

Examples

A nested child

NBT:

{
 a: {
  b: {
   c: "V"
  }
 }
}

NBT Path: $.a.b

Output:

{
 c: "V"
}

A nested child with special characters in its name

NBT:

{
 a*: {
  b: {
   c: "V"
  }
 }
}

NBT Path: $["a*"].b

Output:

{
 c: "V"
}

All children of a tag

NBT:

{
 a: {
  b: "B",
  c: "C"
 }
}

NBT Path: $.a*

Output:

[
 "B",
 "C"
]

All children of a list

NBT:

{
 a: [
  "B",
  "C"
 ]
}

NBT Path: $.a*

Output:

[
 "B",
 "C"
]

A specific list element

NBT:

{
 a: [
  "B",
  "C"
 ]
}

NBT Path: $.a[1]

Output:

"C"

Specific list elements

NBT:

{
 a: [
  "B",
  "C",
  "D"
 ]
}

NBT Path: $.a[0,2]

Output:

[
 "B",
 "D"
]

Specific tag elements

NBT:

{
 a: {
  b: "B",
  c: "C",
  d: "D"
 }
}

NBT Path: $.a[b,d]

Output:

[
 "B",
 "D"
]

Slicing list elements

NBT:

{
 a: [
  "0",
  "1",
  "2",
  "3",
  "4"
  "5"
 ]
}

NBT Path: $.a[1:4:2]

Output:

[
 "1",
 "3"
]

Get list length

NBT:

{
 a: [
  "0",
  "1",
  "2",
  "3",
  "4"
  "5"
 ]
}

NBT Path: $.a.length

Output:

6

Filter list elements

NBT:

{
 a: [
  "0",
  "1",
  "2",
  "3",
  "4"
  "5"
 ]
}

NBT Path: $.a[?(@ == "3")]

Output:

[
 "3"
]