|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Parser-Operations > !Value Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.SetRaw
Parses a raw JSON string and replaces the node at a specified path with the result.
Intention
The PSJ.SetRaw command takes a complete JSON string ($$JSON), parses it into a temporary internal JSON structure, and then uses the root of that new structure to replace whatever node currently exists at $$PATH within the target document ($$DOC). If nodes along $$PATH do not exist, they are created. The existing node at the final path (and its entire subtree) is freed before the new structure is linked in. This command is useful for inserting pre-formed JSON objects or arrays into an existing document.
Illustration
📝 Initial JSON in $$DOC=1:
{ "data": { "old": 123 } }
📝 Command:
PSJ.SetRaw|1|data|'{ "new": [true, false] }'|$$RES
Result: The content of $$DOC=1 becomes { "data": { "new": [true, false] } }. The original { "old": 123 } object is replaced. $$RES will be 0 if successful.
Syntax
PSJ.SetRaw|$$DOC|$$PTH|$$JSN[|$$RES]
Parameter Explanation
P1 - $$DOC - (Variable, Numeric)
The identifier of the target JSON document handle. Required.
P2 - $$PTH - (Variable, String)
The Universal Path (Dot-Notation or JSON Pointer) within the target document where the replacement should occur. Assumed UTF-8, converted internally. Required. Cannot be root ("/").
P3 - $$JSN - (Variable, String)
A string containing the raw, valid JSON text to be parsed and inserted. Assumed UTF-8, converted internally. Required.
P4 - $$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 W_JSON_SetRawJsonByPath(docHandle, pathW, rawJsonW) after converting path and rawJson strings to WSTRINGs. The JSW function performs the following steps:
1. Validates the target document handle.
2. Uses W_JSON_EnsureNodeByPath to make sure a node exists at the target path (creating parents if needed).
3. Calls W_JSON_ParseString on the provided `rawJsonW` to create a temporary document structure.
4. Gets the root node ID of the newly parsed structure using W_JSON_Node_GetRootNode.
5. Detaches the new root node from the temporary document handle (marks handle unused).
6. Calls W_JSON_ReplaceNode, which finds the node at the target path, frees its subtree, and links the newly parsed root node into the parent structure at that path.
7. If replacement fails, it frees the orphaned new node structure.
Examples
'***********************************
' Sample: Replace an object value with a raw JSON array string
PSJ.Parse|'{"id":1, "values":{"a":1}}'|$$DOC
VAR $$JSON_ARRAY_STR = '[ 10, 20, "thirty" ]'
PSJ.SetRaw|$$DOC|values|$$JSON_ARRAY_STR|$$RES
IFE $$RES=0 THEN
PSJ.ToString|$$DOC|1|$$FINAL_JSON ' Pretty print the result
PRT.Result: $$CRLF$$FINAL_JSON
ELSE
PSJ.ErrMsg|$$ERR
PRT.Error setting raw JSON: $$ERR
END
PSJ.Free|$$DOC
MBX.Ready
' Expected Output:
' Result:
' {
' "id": 1,
' "values": [
' 10,
' 20,
' "thirty"
' ]
' }
'***********************************
Remarks
- The $$JSN parameter must contain a complete, valid JSON value (e.g., a full object {}, array [], string "", number, boolean, or null).
- This command effectively replaces the node found at $$PATH. If the node didn't exist, it will be created.
- The root node ("/") cannot be replaced using this command.
Limitations
- Requires the input $$JSN string to be well-formed JSON.
- Path cannot be the root path.
See also:
• PSJ.GetByPath (Used internally via EnsureNodeByPath)