|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Text-Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.ExtractArrStr
Extracts a string from an array element.
Intention
The PSJ.ExtractArrStr command in SPR dives into a JSON string ($$JSON), finds an array at a specific location ($$PATH), picks an element by its position ($$IDX), and extracts a string from a specific spot within that element ($$SUB), storing it in an optional variable ($$RET). It’s like asking your robot to open a JSON mailbox, find a tray of letters (the array), pick one letter by number, and read a specific line from it—like the subject or sender.
For example, from {"messages":[{"text":"Hello"}]}, it can pull out "Hello" from the "text" field of the first message in the "messages" array.
Illustration
📝 Extract: PSJ.ExtractArrStr|{"items":[{"v":"x"}]}|items|0|v|$$VAL sets $$VAL to "x".
📝 Nested: PSJ.ExtractArrStr|{"data":{"list":[{"t":"Hi"}]}}|data.list|0|t|$$TXT sets $$TXT to "Hi".
Syntax
PSJ.ExtractArrStr|$$JSON|$$PATH|$$IDX|$$SUB[|$$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 - $$SUB - (Variable, String)
The subpath within the element (e.g., $$SUB as "content"). Required.
P5 - $$RET - (Variable, String, Optional)
The variable to store the extracted string (e.g., $$RET as "$$VAL"). If omitted, the string is returned but not stored.
Technical Background
This command calls W_JSON_ExtractArrayStringAt, which parses a JSON string (jsonText), locates an array at path, selects the element at index, and extracts a string at subpath. It returns the string (e.g., "Hi" from {"choices":[{"content":"Hi"}]} with path "choices", index 0, subpath "content") or an empty string if an error occurs (e.g., invalid path, index, or subpath). No handle is created, so no freeing is needed.
Examples
'***********************************
' Sample 1: Extract String from Object
PSJ.ExtractArrStr|{"msgs":[{"t":"Hi"}]}|msgs|0|t|$$VAL
' Print the extracted string
PRT.String: $$VAL
MBX.Ready
'***********************************
' Sample 2: Nested Array String
PSJ.ExtractArrStr|{"data":{"list":[{"v":"x"}]}}|data.list|0|v|$$TXT
' Print the extracted string
PRT.String: $$TXT
MBX.Ready
'***********************************
' Sample 3: No Return Variable
PSJ.ExtractArrStr|{"list":[{"k":"v"}]}|list|0|k
' String returned but not stored
MBX.Ready
Remarks
- Returns the string directly; no handle is created.
- Returns an empty string if the path, index, or subpath is invalid.
- Use PSJ.ErrCode to check for errors if the result is empty.
Limitations
- $$JSON must be valid JSON.
- $$PATH must point to an array, $$IDX must be in bounds, and $$SUB must exist.
- Only extracts strings; other types return empty.
See also: