|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Parser-Operations > !Object Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.MergeObjs
Merges two JSON object nodes, overwriting or adding keys from source to destination.
Intention
The PSJ.MergeObjs command in SPR combines two JSON objects by taking all key-value pairs from a source object node ($$SRC) and merging them into a destination object node ($$DST). If a key exists in both, the source value overwrites the destination’s; otherwise, it’s added. It returns a status (1 for success, 0 for failure), which you can optionally store in a variable (e.g., $$RET). This is useful for updating or combining object data.
Imagine it as telling your robot, “Update this object box with everything from that object box,”—and it replies 1 if it worked, placing the status on the Top of Stack (TOS) or in your variable.
Illustration
Consider these JSON objects:
Dest: {"a": 1, "b": 2} Src: {"b": 3, "c": 4}
- 🔍 PSJ.MergeObjs|$$DST|$$SRC|$$RET merges {"b": 3, "c": 4} into {"a": 1, "b": 2}, resulting in {"a": 1, "b": 3, "c": 4}, and stores "1" (success) in $$RET.
- 🔍 PSJ.MergeObjs|$$DST|$$SRC places "1" on TOS.
Syntax
PSJ.MergeObjs|$$DST|$$SRC[|$$RET]
Parameter Explanation
P1 - $$DST - (Variable, Numeric)
The node ID of the destination JSON object (e.g., $$DST as "5"). Required. Must be an object node.
P2 - $$SRC - (Variable, Numeric)
The node ID of the source JSON object (e.g., $$SRC as "6"). Required. Must be an object node.
P3 - $$RET - (Variable, String, Optional)
The variable to store the status as a string (e.g., $$RET). If omitted, the result is returned on Top of Stack (TOS).
Examples
'***********************************
' PSJ.MergeObjs - Sample 1: Merge with Overwrite
'***********************************
PSJ.Parse|{"id": 1, "name": "Alice"}|$$DHA
PSJ.GetByPath|$$DHA||0|$$DST
PSJ.Parse|{"name": "Bob", "age": 30}|$$DHB
PSJ.GetByPath|$$DHB||0|$$SRC
PSJ.MergeObjs|$$DST|$$SRC|$$RET
MBX.Status: $$RET ' Displays "1", object now {"id": 1, "name": "Bob", "age": 30}
PSJ.Free|$$DHA
PSJ.Free|$$DHB
MBX.Ready
'
'***********************************
' PSJ.MergeObjs - Sample 2: Merge with Addition
'***********************************
PSJ.Parse|{"type": "user"}|$$DHA
PSJ.GetByPath|$$DHA||0|$$DST
PSJ.Parse|{"active": true}|$$DHB
PSJ.GetByPath|$$DHB||0|$$SRC
PSJ.MergeObjs|$$DST|$$SRC|$$RET
PRT.Status: $$RET ' Prints "1", object now {"type": "user", "active": true}
PSJ.Free|$$DHA
PSJ.Free|$$DHB
MBX.Ready
'
'***********************************
' PSJ.MergeObjs - Sample 3: Result on TOS
'***********************************
PSJ.Parse|{"x": 10}|$$DHA
PSJ.GetByPath|$$DHA||0|$$DST
PSJ.Parse|{"y": 20}|$$DHB
PSJ.GetByPath|$$DHB||0|$$SRC
PSJ.MergeObjs|$$DST|$$SRC
' Places "1" on TOS, object now {"x": 10, "y": 20}
PSJ.Free|$$DHA
PSJ.Free|$$DHB
MBX.Ready
'
Remarks
- Returns "1" for success or "0" for failure (e.g., non-object nodes).
- Overwrites existing keys in $$DST with values from $$SRC; adds new keys as needed.
- Both $$DST and $$SRC must be object nodes; use PSJ.GetType to verify (type "6").
- Modifies the destination object in place.
Limitations
- Both nodes must be objects; non-object nodes result in "0".
- Requires valid node IDs from a parsed JSON document.
See also: