json.path.read

From RPTools Wiki
Revision as of 22:43, 17 January 2020 by Phergus (talk | contribs)
Jump to navigation Jump to search

json.path.read() Function

Introduced in version 1.5.5
Returns the values in a nested JSON Array or JSON Object corresponding to the provided path. It is unnecessary to include the root node operator $ at the beginning of the requested path. To do so, you must escape the dollar sign like this: \$.path.to.read. The json.path functions support both dot, Monsters.Orc.Attacks, and bracket, ['Monsters']['Orc']['Attacks'], notation. For detailed information on how to specify the path, please read the JsonPath ReadMe.

Usage

json.path.read(json, path)
json.path.read(json, path, config)

Parameters

  • json - The json data to get the values from.
  • path - The path of the value(s) to retrieve.
  • config - A String containing configuration options separated by a comma. The options can include
    • ALWAYS_RETURN_LIST - Always return the results in a JSON Array.
    • AS_PATH_LIST - Return a list of path strings representing the path of the evaluation hits.
    • DEFAULT_PATH_LEAF_TO_NULL - Return null for missing leaf.
    • REQUIRE_PROPERTIES - Require properties defined in path when an indefinite path is evaluated.
    • SUPPRESS_EXCEPTIONS - Suppress all exceptions when evaluating paths.

See the Jayway javadoc page for more info.

Examples

Suppose we have the following nested json:
[h:troll = json.set("{}", "name", "Troll", "HP", 75, "Attacks", json.append("Claw", "Bite"))]
[h:orc = json.set("{}", "name", "Orc", "HP", 13, "Attacks", json.append("Sword", "Punch"))]
[h:monsters = json.set("{}", "Troll", troll, "Orc", orc)]

To access the value of the first weapon of the Orc, we can type

[json.path.read(monsters, "Orc.Attacks.[0]")]

which returns Sword as a string.

If we instead wanted to return an array with the attacks of every monster, we could type

[r: json.path.read(monsters, ".Attacks")]

which would return [["Claw","Bite"],["Sword","Punch"]]. Starting a path with . will return an array containing the values requested.

Inline filters are also supported, so that if we want the name of the monsters with > 30 HPs, we can type

[r: json.path.read(monsters, ".[?(@.HP > 30)]['name']")]
which returns ["Troll"]. Note the use of bracket notation for the path.

Version Changes

  • 1.5.11 - Add config parameter.