|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Text-Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.ExtractBool
Extracts a boolean value from JSON by path.
Intention
The PSJ.ExtractBool command in SPR reads a JSON string ($$JSON) and pulls out a true/false value (boolean) from a specific location ($$PATH), storing it in an optional variable ($$RET) as 1 for true or 0 for false. It’s like asking your robot to check a JSON checklist, find a yes/no box, and tell you if it’s checked or not.
For example, from {"settings":{"active":true}}, it can extract "true" (returned as 1) from the "active" field under "settings".
Illustration
📝 Extract: PSJ.ExtractBool|{"flag":true}|flag|$$VAL sets $$VAL to 1 (true).
📝 Nested: PSJ.ExtractBool|{"data":{"on":false}}|data.on|$$RES sets $$RES to 0 (false).
Syntax
PSJ.ExtractBool|$$JSON|$$PATH[|$$RET]
Parameter Explanation
P1 - $$JSON - (Variable, String)
The JSON string to parse (e.g., $$JSON as "{\"data\":{\"active\":true}}"). Required.
P2 - $$PATH - (Variable, String)
The dot-separated path to the boolean value (e.g., $$PATH as "data.active"). Required.
P3 - $$RET - (Variable, Numeric, Optional)
The variable to store the result (1 for true, 0 for false, -1 for error) (e.g., $$RET as "$$VAL"). If omitted, the value is returned but not stored.
Technical Background
This command calls W_JSON_ExtractBoolean, which parses a JSON string (jsonText) and extracts a boolean at path. It returns 1 for true, 0 for false, or -1 if an error occurs (e.g., invalid JSON or path). Internally, it uses W_JSON_ParseString to create a handle, W_JSON_GetBooleanByPath to get the value, and W_JSON_FreeHandle to clean up. Errors set gLastJSONError and gLastJSONErrorMsg. No handle is returned to the caller, so no freeing is needed.
Examples
'***********************************
' Sample 1: Extract True Value
PSJ.ExtractBool|{"flag":true}|flag|$$VAL
' Print the extracted boolean
PRT.Boolean: $$VAL
MBX.Ready
'***********************************
' Sample 2: Extract False from Nested
PSJ.ExtractBool|{"data":{"on":false}}|data.on|$$RES
' Print the extracted boolean
PRT.Boolean: $$RES
MBX.Ready
'***********************************
' Sample 3: No Return Variable
PSJ.ExtractBool|{"active":true}|active
' Value returned but not stored
MBX.Ready
Remarks
- Returns 1 (true), 0 (false), or -1 (error); no handle is created.
- Use PSJ.ErrCode to check errors if -1 is returned.
Limitations
- $$JSON must be valid JSON.
- $$PATH must point to a boolean value, or -1 is returned.
See also: