json.path.read: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
VisualWikitext
(Created page with "{{MacroFunction |name=json.path.read |version=1.5.5 |description= Returns the values in a nested JSON Array or JSON Object corresponding to the provided path. For deta...")
 
No edit summary
 
(13 intermediate revisions by 4 users not shown)
Line 3: Line 3:
|version=1.5.5
|version=1.5.5
|description=
|description=
Returns the values in a nested [[JSON Array]] or [[JSON Object]] corresponding to the provided path. For detailed information on how to specify the path, please read the [https://github.com/json-path/JsonPath following document].
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 {{code|$}} at the beginning of the requested path.  To do so, you must ''escape'' the dollar sign like this: {{code|\$.path.to.read}}. The {{code|json.path}} functions support both dot, {{code|Monsters.Orc.Attacks}}, and bracket, {{code|['Monsters']['Orc']['Attacks']}}, notation.
 
For detailed information on how to specify the path, please read the [https://github.com/json-path/JsonPath/blob/master/README.md JsonPath ReadMe].


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


'''Parameters'''
'''Parameters'''
{{param|json|The json element to get the values from.}}
{{param|json|The json data to get the values from.}}
{{param|path|The path of the values.}}
{{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
** {{code|ALWAYS_RETURN_LIST}} - Always return the results in a [[JSON Array]], even when the path is definite.
** {{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 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}} - 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. 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.
}}


|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 "Sword".
which returns {{code|Sword}} as a string.


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 [["Claw","Bite"],["Sword","Punch"]].
which would return {{code|[["Claw","Bite"],["Sword","Punch"]]}}.  Starting a path with {{code|.}} 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
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.
 
|changes=
{{change|1.5.11|Add {{code|config}} parameter.}}


which returns ["Troll"].


}}
}}


[[Category:JSON Function]]
[[Category:JSON Function]]
[[Category:JSON Path Function]]

Latest revision as of 17:37, 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://wiki.rptools.info/index.php?title=json.path.read&oldid=16299"