|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Parser-Operations > !Array Operations > PSJ. - JSON Operations |
PSJ.AppendBool |
Previous ChapterTopNext |
SPR Script Language
PSJ.AppendBool
Appends a boolean value (true or false) to the end of a JSON array.
Intention
Use the PSJ.AppendBool command when you need to add a new boolean (`true` or `false`) element to an existing JSON array within a document structure you have previously parsed or created (represented by $$DOC). You specify the array using a path ($$PATH) and provide the boolean value ($$VALUE) as a number (0 for false, any non-zero number for true). The new boolean element will be added to the very end of the specified array.
This is commonly used when dynamically building lists of flags, settings, or results where values are inherently true or false.
Illustration
Imagine a JSON like { "flags": [ true ] }, loaded into handle $$DOC.
📝 Append False: PSJ.AppendBool|$$DOC|flags|0 changes the JSON to { "flags": [ true, false ] }.
📝 Append True: PSJ.AppendBool|$$DOC|flags|1 changes it further to { "flags": [ true, false, true ] }.
Syntax
PSJ.AppendBool|$$DOC|$$PATH|$$VALUE[|$$RET]
Parameter Explanation
P1 - $$DOC - (Variable, Numeric)
The document handle (a number greater than 0) representing the loaded/parsed JSON structure you want to modify. Obtained from PSJ.Parse, PSJ.LoadFile, or creation commands. Required.
P2 - $$PATH - (Variable, String)
The path string identifying the target JSON array within the document specified by $$DOC. See Understanding JSON Paths in PSJ. for syntax details (e.g., `config.enabledFeatures`, `results[0].flags`). The node found at this path must be an array. Required.
P3 - $$VALUE - (Variable, Numeric)
The boolean value to append. Provide **0** to append `false`, or any **non-zero** number (typically **1**) to append `true`. Required.
P4 - $$RET - (Variable, Numeric, Optional)
An optional variable name (e.g., `$$StatusCode`) to store the command's execution status. Returns **0** (%JSON_ERR_NONE) on success, or a non-zero JSW error code on failure.
Examples
VAR $$MyJson = '{ "settings": { "active": true, "flags": [ true ] } }'
VAR $$RetVal : PSJ.Parse|$$MyJson|$$Doc
IF $$Doc > 0 THEN
// Append false to the "flags" array
PSJ.AppendBool|$$Doc|settings.flags|0|$$RET
IF $$RET <> 0 THEN PRT.Error: PSJ.AppendBool (false) failed, code=$$RET
// Append true to the "flags" array
PSJ.AppendBool|$$Doc|settings.flags|1|$$RET
IF $$RET <> 0 THEN PRT.Error: PSJ.AppendBool (true) failed, code=$$RET
// Display the modified JSON (pretty printed)
PSJ.ToString|$$Doc|1|2|$$ResultJSON
PRT.Modified JSON:
PRT.$$ResultJSON
PSJ.Free|$$Doc
ELSE
PRT.Error: Failed to parse initial JSON.
END IF
MBX.Ready
Remarks
- The target node specified by $$PATH must exist and must be a JSON array. Use PSJ.SetArrByPath to ensure the path exists as an array if necessary.
- The `$$VALUE` parameter is interpreted numerically: 0 means `false`, any other value (including negative numbers) means `true`.
- If the operation fails (e.g., path not found, target not an array), the optional `$$RET` variable will contain a non-zero error code. Use PSJ.ErrCode and PSJ.ErrMsg to get more details.
Limitations
- Cannot append to non-array nodes (objects, strings, numbers, etc.).
- The path must correctly identify an existing array within the document.
See also: