|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Text-Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.ExtractArrObj
Extracts an object from a JSON array by index.
Intention
The PSJ.ExtractArrObj command in SPR digs into a JSON string ($$JSON), finds an array at a specific location ($$PATH), and pulls out an object from that array at a given position ($$IDX), storing it as a JSON string in an optional variable ($$RET). It’s like asking your robot to open a JSON filing cabinet, find a drawer (the array), and hand you a specific folder (the object) from it as a neatly written note.
For example, from {"messages":[{"text":"Hi"},{"text":"Bye"}]}, it can extract {"text":"Hi"} from the "messages" array at index 0.
Illustration
📝 Extract: PSJ.ExtractArrObj|{"items":[{"id":1}]}|items|0|$$OBJ sets $$OBJ to {"id":1}.
📝 Nested: PSJ.ExtractArrObj|{"data":{"list":[{"v":"x"}]}}|data.list|0|$$RES sets $$RES to {"v":"x"}.
Syntax
PSJ.ExtractArrObj|$$JSON|$$PATH|$$IDX[|$$RET]
Parameter Explanation
P1 - $$JSON - (Variable, String)
The JSON string to parse (e.g., $$JSON as "{\"choices\":[{\"content\":\"Hi\"}]}"). Required.
P2 - $$PATH - (Variable, String)
The dot-separated path to the array (e.g., $$PATH as "choices"). Required.
P3 - $$IDX - (Variable, Numeric)
The zero-based index of the array element (e.g., $$IDX as "0"). Required.
P4 - $$RET - (Variable, String, Optional)
The variable to store the extracted JSON string (e.g., $$RET as "$$OBJ"). If omitted, the string is returned but not stored.
Technical Background
This command calls W_JSON_ExtractArrayObject, which parses a JSON string (jsonText), locates an array at path, and extracts the element at index as a JSON string. It returns the object as a string (e.g., {"content":"Hi"} from {"choices":[{"content":"Hi"}]} at "choices" index 0) or an empty string if an error occurs (e.g., invalid path, index, or not an object). Errors set gLastJSONError and gLastJSONErrorMsg. It relies on W_JSON_ToString for serialization and doesn’t check if the element is an object. No handle is created, so no freeing is needed.
Examples
'***********************************
' Sample 1: Extract First Object
PSJ.ExtractArrObj|{"msgs":[{"t":"Hi"}]}|msgs|0|$$OBJ
' Print the extracted object
PRT.Object: $$OBJ
MBX.Ready
'***********************************
' Sample 2: Nested Array Object
PSJ.ExtractArrObj|{"data":{"list":[{"v":"x"}]}}|data.list|0|$$RES
' Print the extracted object
PRT.Object: $$RES
MBX.Ready
'***********************************
' Sample 3: No Return Variable
PSJ.ExtractArrObj|{"list":[{"k":"v"}]}|list|0
' Object returned but not stored
MBX.Ready
Remarks
- Returns a JSON string of the object; no handle is created.
- Returns an empty string if the index is invalid or the element isn’t serializable.
- Use PSJ.ErrCode to diagnose errors.
Limitations
- $$JSON must be valid JSON.
- $$PATH must point to an array, and $$IDX must be within bounds.
- Doesn’t verify if the element is an object.
See also: