|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Parser-Operations > !Node Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.SetArrByPath
Ensures the node at the specified path exists and is of type Array.
Intention
Use the PSJ.SetArrByPath command to guarantee that the node located at $$PATH within document $$DOC is an Array ([]). If the node doesn't exist, this command will create all necessary parent Objects/Arrays along the path and create an empty Array at the final location. If a node already exists at the path but is not an Array (e.g., it's a String or an Object), its current value and any children will be cleared, and its type will be converted to Array. This is useful for preparing a path before appending array elements.
Illustration
📝 Create new array:
PSJ.Parse|'{}'|$$DOC
PSJ.SetArrByPath|$$DOC|data.results|$$RES_A // Creates data object and results array
Result: $$DOC contains {"data":{"results":[]}}. $$RES_A=0.
📝 Convert existing value to array:
PSJ.Parse|'{"config":"old_value"}'|$$DOC2
PSJ.SetArrByPath|$$DOC2|config|$$RES_B // Converts string "old_value" to []
Result: $$DOC2 contains {"config":[]}. $$RES_B=0.
Syntax
PSJ.SetArrByPath|$$DOC|$$PTH[|$$RES]
Parameter Explanation
P1 - $$DOC - (Variable, Numeric)
The identifier of the JSON document handle. Required.
P2 - $$PTH - (Variable, String)
The Universal Path (Dot-Notation or JSON Pointer) to the node that should be an Array. Assumed UTF-8, converted internally. Required.
P3 - $$RES - (Variable, Numeric, Optional)
The variable where the result code (%JSON_ERR_*) will be stored. 0 indicates success. If omitted, the result code is returned but not stored.
Technical Background
This command calls the W_JSON_SetArrayByPath(docHandle, pathW) function in the JSW library. The JSW function first uses W_JSON_EnsureNodeByPath to locate or create the node at the specified path. If the node is successfully found or created, it then calls the internal W_JSON_ConvertNodeToType helper function, passing the target node ID and %JSON_TYPE_ARRAY. The helper ensures the node is of type Array, clearing previous data (including any associated WsLnTre handle if it was an Object) and initializing array-specific structures if a conversion was necessary.
Examples
'***********************************
' Sample 1: Ensure an array exists before appending
PSJ.Parse|'{}'|$$DOC
PSJ.SetArrByPath|$$DOC|users|$$RES1
IFE $$RES1=0 THEN
PSJ.AppendStr|$$DOC|users|"Alice"|$$RES2
PSJ.ToString|$$DOC|$$JSON_OUT
PRT.Result: $$JSON_OUT ' Output: {"users":["Alice"]}
ELSE
PRT.Failed to set array path!
END
PSJ.Free|$$DOC
MBX.Ready
'***********************************
Remarks
- If the node at the path already exists and is an Array, this command simply succeeds without modifying it.
- If the node exists but is a different type (Object, String, etc.), its contents are discarded during the conversion to an empty Array.
- This command is idempotent: running it multiple times on the same path will have no further effect after the first successful execution ensures an array exists there.
Limitations
- Path traversal errors or memory allocation failures during node creation/conversion will result in an error code.
See also:
• PSJ.AppendStr (and other Append* commands)