|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Parser-Operations > !Utility and Conversion > PSJ. - JSON Operations |
SPR Script Language
PSJ.Search
Searches for nodes with a matching key-value pair, returning their paths.
Intention
The PSJ.Search command in SPR searches a JSON document ($$DHA) for nodes that have a specific key ($$KEY) and value ($$VAL), returning a comma-separated list of paths where matches are found. You can optionally store the result in a variable (e.g., $$RET). This is useful for locating specific data within a JSON structure.
Imagine it as telling your robot, “Find all places in this JSON where this key equals this value, and give me their addresses,”—and it hands you a list like "root.people[0],root.people[2]", either on the Top of Stack (TOS) or in your variable.
Illustration
Consider this JSON document:
{"people": [{"name": "Alice"}, {"name": "Bob"}, {"name": "Alice"}]}
- 🔍 PSJ.Search|$$DHA|name|Alice|$$RET searches for "name": "Alice", storing "people[0],people[2]" in $$RET.
- 🔍 PSJ.Search|$$DHA|name|Alice places "people[0],people[2]" on TOS.
Syntax
PSJ.Search|$$DHA|$$KEY|$$VAL[|$$RET]
Parameter Explanation
P1 - $$DHA - (Variable, Numeric)
The handle to the JSON document (e.g., $$DHA as "1"). Required. Obtained from PSJ.Parse.
P2 - $$KEY - (Variable, String)
The key to search for (e.g., $$KEY as "name"). Required.
P3 - $$VAL - (Variable, String)
The value to match (e.g., $$VAL as "Alice"). Required.
P4 - $$RET - (Variable, String, Optional)
The variable to store the comma-separated paths (e.g., $$RET). If omitted, the result is returned on Top of Stack (TOS).
Examples
'***********************************
' PSJ.Search - Sample 1: Search in Array
'***********************************
PSJ.Parse|{"people": [{"name": "Alice"}, {"name": "Bob"}, {"name": "Alice"}]}|$$DHA
PSJ.Search|$$DHA|name|Alice|$$RET
MBX.Paths: $$RET ' Displays "people[0],people[2]"
PSJ.Free|$$DHA
'
'***********************************
' PSJ.Search - Sample 2: Search in Object
'***********************************
PSJ.Parse|{"a": {"id": "x"}, "b": {"id": "x"}}|$$DHA
PSJ.Search|$$DHA|id|x|$$RET
PRT.Paths: $$RET ' Prints "a,b"
PSJ.Free|$$DHA
'
'***********************************
' PSJ.Search - Sample 3: No Matches on TOS
'***********************************
PSJ.Parse|{"people": [{"name": "Bob"}]}|$$DHA
PSJ.Search|$$DHA|name|Alice
' Places "" (empty string) on TOS
PSJ.Free|$$DHA
'
Remarks
- Returns a comma-separated string of paths (e.g., "people[0],people[2]") or an empty string ("") if no matches are found or an error occurs.
- Paths use dot notation for objects (e.g., "a.b") and brackets for arrays (e.g., "people[0]").
- Searches the entire document starting from the root node.
Limitations
- Requires a valid $$DHA; invalid handles return "".
- Only matches exact key-value pairs; no partial or type-converted matches (e.g., "1" won’t match 1).
- Returns paths as strings, not node IDs; use PSJ.GetByPath to resolve them if needed.
See also: