|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Parser-Operations > !Node Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.SetObjByPath
Ensures the node at the specified path exists and is of type Object.
Intention
Use the PSJ.SetObjByPath command to guarantee that the node located at $$PATH within document $$DOC is an Object ({}). If the node doesn't exist, this command will create all necessary parent Objects/Arrays along the path and create an empty Object at the final location (associating a new WsLnTre structure with it). If a node already exists at the path but is not an Object (e.g., it's a String or an Array), its current value and any children will be cleared, and its type will be converted to Object (including creating a new, empty WsLnTre structure). This is useful for preparing a path before setting key-value pairs within an object.
Illustration
📝 Create new object:
PSJ.Parse|'[]'|$$DOC // Start with root array
PSJ.SetObjByPath|$$DOC|[0]|$$RES_A // Creates an object at index 0
Result: $$DOC contains [{}]. $$RES_A=0.
📝 Convert existing value to object:
PSJ.Parse|'{"user":"Alice"}'|$$DOC2
PSJ.SetObjByPath|$$DOC2|user|$$RES_B // Converts string "Alice" to {}
Result: $$DOC2 contains {"user":{}}. $$RES_B=0.
Syntax
PSJ.SetObjByPath|$$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 Object. 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_SetObjectByPath(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_OBJECT. The helper ensures the node is of type Object, clearing previous data and children (if it was an Array) and ensuring a valid WsLnTre handle is associated with the node (creating a new one if a conversion occurred or the node was newly created).
Examples
'***********************************
' Sample 1: Ensure an object exists before setting a key
PSJ.Parse|'{}'|$$DOC
PSJ.SetObjByPath|$$DOC|user.profile|$$RES1
IFE $$RES1=0 THEN
PSJ.SetStr|$$DOC|user.profile.email|"test@example.com"|$$RES2
PSJ.ToString|$$DOC|1|$$JSON_OUT ' Pretty print
PRT.Result: $$CRLF$$JSON_OUT
ELSE
PRT.Failed to set object path!
END
PSJ.Free|$$DOC
MBX.Ready
' Expected Output:
' Result:
' {
' "user": {
' "profile": {
' "email": "test@example.com"
' }
' }
' }
'***********************************
Remarks
- If the node at the path already exists and is an Object, this command simply succeeds without modifying it.
- If the node exists but is a different type (Array, String, etc.), its contents are discarded during the conversion to an empty Object.
- This command is idempotent: running it multiple times on the same path will have no further effect after the first successful execution ensures an object exists there.
Limitations
- Path traversal errors or memory allocation failures during node creation/conversion will result in an error code.
See also:
• PSJ.SetStr (and other Set* commands)