|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Parser-Operations > !Value Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.SetStr
Sets or updates a string value in a JSON object at a specified path.
Intention
The PSJ.SetStr command in SPR modifies a JSON document ($$DHA) by setting or updating a string value ($$VAL) at a specified path ($$PTH). It returns a status code indicating success or failure, which you can optionally store in a variable (e.g., $$RET). This is useful for adding or changing string data in JSON objects.
Imagine it as telling your robot, “Place this string at this spot in the JSON,”—and it replies with a number like 0 for success or 1 for a problem, either on the Top of Stack (TOS) or in your variable.
Illustration
Consider a JSON document:
{"person": {"name": "Alice"}}
- 🔍 PSJ.SetStr|$$DHA|person.name|Bob|$$RET updates "person.name" to "Bob", resulting in {"person": {"name": "Bob"}}, and stores "0" (success) in $$RET.
- 🔍 PSJ.SetStr|$$DHA|person.age|25 adds "person.age": "25", placing "0" on TOS.
Syntax
PSJ.SetStr|$$DHA|$$PTH|$$VAL[|$$RET]
Parameter Explanation
P1 - $$DHA - (Variable, Numeric)
The handle to the JSON document (e.g., $$DHA as "1"). Required. Obtained from PSJ.Parse.
P2 - $$PTH - (Variable, String)
The dot-separated path where the string value should be set (e.g., $$PTH as "person.name"). Required.
P3 - $$VAL - (Variable, String)
The string value to set (e.g., $$VAL as "Bob"). Required.
P4 - $$RET - (Variable, String, Optional)
The variable to store the status code (e.g., $$RET). If omitted, the result is returned on Top of Stack (TOS). See status codes below.
Examples
'***********************************
' PSJ.SetStr - Sample 1: Update Existing
'***********************************
PSJ.Parse|{"person": {"name": "Alice"}}|$$DHA
PSJ.SetStr|$$DHA|person.name|Bob|$$RET
MBX.Status: $$RET ' Displays "0" (success)
PSJ.NodeToStr|0|0|0|$$JSON ' Get full document
PRT.JSON: $$JSON ' Prints {"person":{"name":"Bob"}}
PSJ.Free|$$DHA
'
'***********************************
' PSJ.SetStr - Sample 2: Create New Path
'***********************************
PSJ.Parse|{}|$$DHA
PSJ.SetStr|$$DHA|person.city|New York|$$RET
PRT.Status: $$RET ' Prints "0" (success)
PSJ.NodeToStr|0|0|0|$$JSON
MBX.JSON: $$JSON ' Displays {"person":{"city":"New York"}}
PSJ.Free|$$DHA
'
'***********************************
' PSJ.SetStr - Sample 3: Status on TOS
'***********************************
PSJ.Parse|{"data": []}|$$DHA
PSJ.SetStr|$$DHA|data.value|test
' Places "2" (parent not an object) on TOS
PSJ.Free|$$DHA
'
Remarks
- Returns a status code as a string:
- "0" = Success
- "1" = Path not found
- "2" = Parent node is not an object
- "3" = Failed to create a new string node
- "4" = Failed to add the new string node to the parent object
- Creates the key if it doesn’t exist, or updates it if it does, within an object.
- Supports cross-type promotion (e.g., replaces a number with a string).
Limitations
- Requires the parent of the final key to be an object; fails with arrays (e.g., "arr[0]" returns "2").
- Does not create intermediate objects automatically; path must exist up to the parent.
- Invalid $$DHA may return "1" (path not found).
See also: