|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Text-Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.ExtractArrAllStr
Extracts all strings from a JSON array at a specified subpath.
Intention
The PSJ.ExtractArrAllStr command in SPR takes a JSON string ($$JSON), a path to an array ($$PATH), and a subpath within each array element ($$SUBPATH), extracts all string values at that subpath, and stores them in a numbered array ($$VALARR). Optionally, it returns the count of extracted strings in $$RET. It’s like telling your robot to dive into a JSON structure, find an array, and grab all the strings at a specific spot within each item.
For example, from {"data":[{"id":"Hi"},{"id":"Hello"}]} with path "data" and subpath "id", it stores "Hi" and "Hello" in the array.
Illustration
📝 Extract: PSJ.ExtractArrAllStr|{"data":[{"id":"Hi"},{"id":"Hello"}]}|data|id|1 stores "Hi" at ARR(1,0) and "Hello" at ARR(1,1).
📝 With Count: PSJ.ExtractArrAllStr|{"items":[{"name":"Yes"}]}|items|name|2|$$CNT stores "Yes" at ARR(2,0) and sets $$CNT to 1.
Syntax
PSJ.ExtractArrAllStr|$$JSON|$$PATH|$$SUBPATH|$$VALARR[|$$RET]
Parameter Explanation
P1 - $$JSON - (Variable, String)
The JSON string to parse (e.g., $$JSON as "{\"data\":[{\"id\":\"Hi\"}]}"). Required.
P2 - $$PATH - (Variable, String)
The path to the array in the JSON (e.g., $$PATH as "data"). Required.
P3 - $$SUBPATH - (Variable, String)
The subpath within each array element to extract strings from (e.g., $$SUBPATH as "id"). Required.
P4 - $$VALARR - (Variable, Numeric)
The array number (e.g., $$VALARR as "1") where extracted strings are stored using ARR command syntax (e.g., ARR(1,0)). Required.
P5 - $$RET - (Variable, Numeric, Optional)
The variable to store the count of extracted strings (e.g., $$RET as "$$CNT"). Returns -1 on error. If omitted, the count is returned but not stored.
Technical Background
This command parses jsonText, locates the array at path, and extracts all string values at subpath within each array element into the ARR.-Array.
It returns the count of extracted strings or -1 if an error occurs (e.g., invalid JSON, non-array at path, or missing subpath). No document handle is retained, so no cleanup is needed.
Examples
'***********************************
' Sample 1: Extract Multiple Strings
PSJ.ExtractArrAllStr|{"data":[{"id":"Hi"},{"id":"Hello"}]}|data|id|1
' Print the extracted values
PRT.Value 0: ARR(1,0) ' Outputs: Hi
PRT.Value 1: ARR(1,1) ' Outputs: Hello
MBX.Ready
'***********************************
' Sample 2: Extract with Count
PSJ.ExtractArrAllStr|{"items":[{"name":"Yes"}]}|items|name|2|$$CNT
' Print the results
PRT.Value 0: ARR(2,0) ' Outputs: Yes
PRT.Count: $$CNT ' Outputs: 1
MBX.Ready
Remarks
- Stores strings in ARR($$VALARR, index) starting at index 0 up to count-1.
- $$RET is the count of extracted strings or -1 on error.
- Use PSJ.ErrCode to diagnose errors if $$RET is -1.
Limitations
- $$JSON must be valid JSON with an array at $$PATH.
- $$SUBPATH must point to string values within each array element.
See also: