json.path.read: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
VisualWikitext
No edit summary
No edit summary
 
(4 intermediate revisions by 3 users not shown)
Line 8: Line 8:


|usage=
|usage=
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
json.path.read(json, path)
json.path.read(json, path)
json.path.read(json, path, config)
json.path.read(json, path, config)
</source>
</syntaxhighlight>


'''Parameters'''
'''Parameters'''
Line 17: Line 17:
{{param|path|The path of the value(s) to retrieve.}}
{{param|path|The path of the value(s) to retrieve.}}
{{param|config|A String containing configuration options separated by a comma. The options can include
{{param|config|A String containing configuration options separated by a comma. The options can include
** {{code|ALWAYS_RETURN_LIST}} - Always return the results in a [[JSON Array]].
** {{code|ALWAYS_RETURN_LIST}} - Always return the results in a [[JSON Array]], even when the path is definite.
** {{code|AS_PATH_LIST}} - Return a list of path strings representing the path of the evaluation hits.
** {{code|AS_PATH_LIST}} - Return a JSON Array of path strings representing the path of the evaluation hits.
** {{code|DEFAULT_PATH_LEAF_TO_NULL}} - Return null for missing leaf.
** {{code|DEFAULT_PATH_LEAF_TO_NULL}} - Return null when the given path almost exists but ends with a JSON Object key that is missing. Without this configuration, a definite path will return an error. With this configuration, an indefinite path will include null in the JSON Array if the key is missing. Without this configuration or if any other kind of nonexistent path structure is provided, an indefinite path will simply not match and return an empty JSON Array or less results in the JSON Array.
** {{code|REQUIRE_PROPERTIES}} - Require properties defined in path when an indefinite path is evaluated.
** {{code|REQUIRE_PROPERTIES}} - When an indefinite path is evaluated and ends in a key, all matching JSON Objects must have that key, otherwise an error is returned. This are the cases where DEFAULT_PATH_LEAF_TO_NULL will return null instead.
** {{code|SUPPRESS_EXCEPTIONS}} - Suppress all exceptions when evaluating paths.
** {{code|SUPPRESS_EXCEPTIONS}} - Suppress all exceptions when evaluating paths. If ALWAYS_RETURN_LIST is also used return an empty list. Otherwise return null.
See the [https://www.javadoc.io/doc/com.jayway.jsonpath/json-path/2.0.0/com/jayway/jsonpath/Option.html Jayway javadoc page] for more info.
See the [https://www.javadoc.io/doc/com.jayway.jsonpath/json-path/2.0.0/com/jayway/jsonpath/Option.html Jayway javadoc page] for more info.
}}
}}
Line 27: Line 27:
|examples=
|examples=
Suppose we have the following nested json:
Suppose we have the following nested json:
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h:troll = json.set("{}", "name", "Troll", "HP", 75, "Attacks", json.append("Claw", "Bite"))]
[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:orc = json.set("{}", "name", "Orc", "HP", 13, "Attacks", json.append("Sword", "Punch"))]
[h:monsters = json.set("{}", "Troll", troll, "Orc", orc)]
[h:monsters = json.set("{}", "Troll", troll, "Orc", orc)]
</source>
</syntaxhighlight>


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


<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[json.path.read(monsters, "Orc.Attacks.[0]")]
[json.path.read(monsters, "Orc.Attacks.[0]")]
</source>
</syntaxhighlight>


which returns {{code|Sword}} as a string.
which returns {{code|Sword}} as a string.
Line 43: Line 43:
If we instead wanted to return an array with the attacks of every monster, we could type
If we instead wanted to return an array with the attacks of every monster, we could type


<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[r: json.path.read(monsters, ".Attacks")]
[r: json.path.read(monsters, ".Attacks")]
</source>
</syntaxhighlight>


which would return {{code|[["Claw","Bite"],["Sword","Punch"]]}}.  Starting a path with {{code|.}} will return an array containing the values requested.
which would return {{code|[["Claw","Bite"],["Sword","Punch"]]}}.  Starting a path with {{code|.}} will return an array containing the values requested.
Line 51: Line 51:
Inline filters are also supported, so that if we want the name of the monsters with > 30 HPs, we can type
Inline filters are also supported, so that if we want the name of the monsters with > 30 HPs, we can type


<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[r: json.path.read(monsters, ".[?(@.HP > 30)]['name']")]
[r: json.path.read(monsters, ".[?(@.HP > 30)]['name']")]
</source>
</syntaxhighlight>


which returns {{code|["Troll"]}}.  Note the use of bracket notation for the path.
which returns {{code|["Troll"]}}.  Note the use of bracket notation for the path.

Latest revision as of 23:59, 15 March 2023

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, even when the path is definite.
    • AS_PATH_LIST - Return a JSON Array of path strings representing the path of the evaluation hits.
    • DEFAULT_PATH_LEAF_TO_NULL - Return null when the given path almost exists but ends with a JSON Object key that is missing. Without this configuration, a definite path will return an error. With this configuration, an indefinite path will include null in the JSON Array if the key is missing. Without this configuration or if any other kind of nonexistent path structure is provided, an indefinite path will simply not match and return an empty JSON Array or less results in the JSON Array.
    • REQUIRE_PROPERTIES - When an indefinite path is evaluated and ends in a key, all matching JSON Objects must have that key, otherwise an error is returned. This are the cases where DEFAULT_PATH_LEAF_TO_NULL will return null instead.
    • SUPPRESS_EXCEPTIONS - Suppress all exceptions when evaluating paths. If ALWAYS_RETURN_LIST is also used return an empty list. Otherwise return null.

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.
Retrieved from "https://rptools.hyperbooks.com/index.php?title=json.path.read&oldid=35224"