|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Parser-Operations > !Value Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.GetBool
Retrieves a boolean value (true or false) from a JSON document at a specified path.
Intention
The PSJ.GetBool command in SPR is your tool for extracting a boolean value—either true or false—from a JSON document. You specify the document using its handle ($$DH) and the exact location within the JSON structure using a path ($$PATH). Optionally, you can store the result in a variable (e.g., $$RET). This command is perfect when you need to check a yes/no or on/off condition stored in your JSON data.
Think of it as asking your robot, “Hey, is this switch turned on in the JSON?”—and it answers with a simple 1 for true or 0 for false, placing the answer on the Top of Stack (TOS).
Illustration
Imagine a JSON document like this:
{"settings": {"isActive": true, "debugMode": false}}
- 🔍 PSJ.GetBool|123|settings.isActive|$$RET stores 1 (true) in $$RET.
- 🔍 PSJ.GetBool|123|settings.debugMode places 0 (false) on TOS.
Syntax
PSJ.GetBool|$$DH|$$PATH[|$$RET]
Parameter Explanation
P1 - $$DH - (Variable, Numeric)
The document handle identifying the JSON data to search (e.g., $$DH as "123"). Required. You get this handle from commands like PSJ.Parse or PSJ.LoadFile.
P2 - $$PATH - (Variable, String)
The path to the boolean value in the JSON (e.g., $$PATH as "settings.isActive"). Required. Use dot notation (e.g., "user.active") or array indices (e.g., "items.0.enabled").
P3 - $$RET - (Variable, String, Optional)
The variable to store the result (e.g., $$RET). If omitted, the result (1 or 0) is returned on Top of Stack (TOS).
Examples
'***********************************
' PSJ.GetBool - Sample 1: Check if a Feature is Active
'***********************************
PSJ.Parse|{"feature": {"enabled": true}}|$$DH
PSJ.GetBool|$$DH|feature.enabled|$$RET
MBX.Result: $$RET ' Displays 1 (true)
PSJ.Free|$$DH
MBX.Ready
'
'***********************************
' PSJ.GetBool - Sample 2: Check Array Element
'***********************************
PSJ.Parse|{"users": [{"active": false}]}|$$DH
PSJ.GetBool|$$DH|users.0.active|$$RET
PRT.Result: $$RET ' Prints 0 (false)
PSJ.Free|$$DH
MBX.Ready
'
'***********************************
' PSJ.GetBool - Sample 3: Result on TOS
'***********************************
PSJ.Parse|{"system": {"online": true}}|$$DH
PSJ.GetBool|$$DH|system.online
' Places 1 (true) on Top of Stack (TOS)
PSJ.Free|$$DH
MBX.Ready
'
Remarks
- Returns 1 for true and 0 for false or if an error occurs (e.g., path not found or wrong type).
- Only works on JSON nodes that are explicitly boolean; other types return 0.
- Use PSJ.GetType to verify the node type if unsure.
Limitations
- Requires a valid document handle; invalid handles return 0.
- If the path doesn’t exist or the node isn’t a boolean, you get 0, which might be ambiguous (false vs. error).
See also: