|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Parser-Operations > !Object Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.GetKeys
Retrieves all keys from a JSON object at a specified path as a comma-separated string.
Intention
The PSJ.GetKeys command in SPR lets you peek inside a JSON object and grab all its keys as a single string, separated by commas. You provide the document handle ($$DH) and the path to the object ($$PATH), and optionally store the result in a variable (e.g., $$RET). This is handy for understanding the structure of your JSON data or when you need to iterate over an object’s properties.
Imagine it like asking your robot, “What’s in this JSON box?”—and it hands you a list like "name,age,address", placing it on the Top of Stack (TOS) or in your chosen variable.
Illustration
Consider this JSON document:
{"person": {"name": "Alice", "age": 30, "city": "New York"}}
- 🔍 PSJ.GetKeys|123|person|$$RET stores "name,age,city" in $$RET.
- 🔍 PSJ.GetKeys|123|person places "name,age,city" on TOS.
Syntax
PSJ.GetKeys|$$DOC|$$PATH[|$$RET]
Parameter Explanation
P1 - $$DOC - (Variable, Numeric)
The document handle identifying the JSON data to search (e.g., $$DH as "123"). Required. Obtained from commands like PSJ.Parse or PSJ.LoadFile.
P2 - $$PATH - (Variable, String)
The path to the JSON object whose keys you want (e.g., $$PATH as "person"). Required. Use dot notation (e.g., "root.person") or leave blank for the root object.
P3 - $$RET - (Variable, String, Optional)
The variable to store the comma-separated keys (e.g., $$RET). If omitted, the result is returned on Top of Stack (TOS).
Examples
'***********************************
' PSJ.GetKeys - Sample 1: Get Keys from Root Object
'***********************************
PSJ.Parse|{"name": "Bob", "age": 25}|$$DH
PSJ.GetKeys|$$DH||$$RET
MBX.Keys: $$RET ' Displays "name,age"
PSJ.Free|$$DH
MBX.Ready
'
'***********************************
' PSJ.GetKeys - Sample 2: Get Keys from Nested Object
'***********************************
PSJ.Parse|{"user": {"id": 1, "active": true}}|$$DH
PSJ.GetKeys|$$DH|user|$$RET
PRT.Keys: $$RET ' Prints "id,active"
PSJ.Free|$$DH
MBX.Ready
'
'***********************************
' PSJ.GetKeys - Sample 3: Result on TOS
'***********************************
PSJ.Parse|{"settings": {"mode": "dark", "sound": "on"}}|$$DH
PSJ.GetKeys|$$DH|settings
' Places "mode,sound" on Top of Stack (TOS)
PSJ.Free|$$DH
MBX.Ready
'
Remarks
- Returns a comma-separated string of keys (e.g., "key1,key2,key3") or an empty string if the path doesn’t exist or isn’t an object.
- Only works on object nodes; other types (e.g., arrays, strings) return "".
- Use PSJ.GetType to verify the node is an object if unsure.
Limitations
- Requires a valid document handle; invalid handles return an empty string.
- If the path points to a non-object node, you get "", which might be ambiguous (no keys vs. error).
See also: