|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Text-Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.CreateObjPairs
Creates a JSON object from key-value pairs.
Intention
The PSJ.CreateObjPairs command in SPR takes a string of key-value pairs (like a list of settings separated by semicolons, with "=" between each key and value) and turns it into a JSON object—a structured format that organizes data into named slots. You provide the string of pairs ($$PAIRS) and optionally a variable to store the result ($$RET). The command creates a JSON object where each key-value pair becomes a property, ready for use in your script. You must free the resulting handle with PSJ.Free when done.
Imagine it as turning a note like "name=Alice;age=30" into a JSON file card: {"name": "Alice", "age": "30"}—easy for your robot to read and manage!
Illustration
📝 Input: PSJ.CreateObjPairs|name=cat;type=pet|$$OBJ creates {"name": "cat", "type": "pet"}.
📝 Simple: PSJ.CreateObjPairs|id=123|$$KEY makes {"id": "123"}.
Syntax
PSJ.CreateObjPairs|$$PAIRS[|$$RET]
Parameter Explanation
P1 - $$PAIRS - (Variable, String)
The string of key-value pairs separated by semicolons, with "=" between keys and values (e.g., $$PAIRS as "method=getUser;id=123"). Required.
P2 - $$RET - (Variable, Numeric, Optional)
The variable to store the JSON object handle (e.g., $$RET as "$$OBJ"). If omitted, the handle is returned but not stored.
Technical Background
This command calls W_JSON_CreateObjectFromPairs, which creates a JSON object from a semicolon-separated string of key-value pairs, using "=" to split keys and values. It returns a document handle—a number representing the object (e.g., {"method": "getUser", "id": "123"} from "method=getUser;id=123"). If an error occurs (e.g., invalid format or memory failure), it returns 0 and sets gLastJSONError and gLastJSONErrorMsg. The caller must free the handle with PSJ.Free (which calls W_JSON_FreeHandle) to avoid memory leaks.
Examples
'***********************************
' Sample 1: Basic Object Creation
PSJ.CreateObjPairs|name=Alice;age=30|$$OBJ
' Print the object handle
PRT.Object handle: $$OBJ
' Free the handle
PSJ.Free|$$OBJ
MBX.Ready
'***********************************
' Sample 2: Single Pair
PSJ.CreateObjPairs|id=123|$$KEY
' Print the object handle
PRT.Object handle: $$KEY
' Free the handle
PSJ.Free|$$KEY
MBX.Ready
'***********************************
' Sample 3: No Return Variable
PSJ.CreateObjPairs|key=value
' Handle returned but not stored
MBX.Ready
' Note: Memory leak if not freed!
Remarks
- Returns a handle to the JSON object, usable with commands like PSJ.ToString.
- Keys and values become string properties in the JSON object.
- The caller must free the handle with PSJ.Free to prevent memory leaks.
Limitations
- Pairs must use "=" to separate keys and values, and ";" between pairs.
- Empty values (e.g., "key=;next=val") result in empty strings.
- Failing to free the handle causes memory leaks.
See also:
• PSJ.Free