|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Parser-Operations > !Node Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.GetByPath
Retrieves or creates a node by path in a JSON document and returns its node ID.
Intention
The PSJ.GetByPath command in SPR either retrieves an existing node or creates a new one at a specified path ($$PATH) within a JSON document identified by its handle ($$DHA). You control whether to create the node if it’s missing with $$CREATE (0 for no, 1 for yes), and optionally store the resulting node ID in a variable (e.g., $$RET). This is useful for navigating or building JSON structures dynamically.
Imagine it as telling your robot, “Find or make this spot in the JSON map,”—and it hands you a number like 7 to mark that spot, either placing it on the Top of Stack (TOS) or storing it for later use.
Illustration
Consider this JSON document:
{"user": {"name": "Alice"}}
- 🔍 PSJ.GetByPath|$$DHA|user|0|$$RET retrieves the node ID (e.g., "3") of the existing "user" object, storing it in $$RET.
- 🔍 PSJ.GetByPath|$$DHA|user.address|1 creates a new "address" object under "user" and places its node ID (e.g., "4") on TOS.
Syntax
PSJ.GetByPath|$$DHA|$$PATH|$$CREATE[|$$RET]
Parameter Explanation
P1 - $$DHA - (Variable, Numeric)
The document handle identifying the JSON data (e.g., $$DHA as "123"). Required. Obtained from PSJ.Parse or PSJ.LoadFile.
P2 - $$PATH - (Variable, String)
The path to the node to retrieve or create (e.g., $$PATH as "user.address"). Required. Use dot notation (e.g., "data.info").
P3 - $$CREATE - (Variable, Numeric)
Flag to create the node if missing (e.g., $$CREATE as "1"). Required. Set to 0 to only retrieve, or 1 to create an object if the path doesn’t exist.
P4 - $$RET - (Variable, String, Optional)
The variable to store the node ID as a string (e.g., $$RET). If omitted, the result is returned on Top of Stack (TOS).
Examples
'***********************************
' PSJ.GetByPath - Sample 1: Retrieve Existing Node
'***********************************
PSJ.Parse|{"data": {"id": 1}}|$$DHA
PSJ.GetByPath|$$DHA|data|0|$$RET
MBX.Node ID: $$RET ' Displays the "data" node ID (e.g., "2")
PSJ.Free|$$DHA
MBX.Ready
'
'***********************************
' PSJ.GetByPath - Sample 2: Create New Node
'***********************************
PSJ.Parse|{"user": {}}|$$DHA
PSJ.GetByPath|$$DHA|user.info|1|$$RET
PRT.Node ID: $$RET ' Prints the new "info" node ID (e.g., "3")
PSJ.Free|$$DHA
MBX.Ready
'
'***********************************
' PSJ.GetByPath - Sample 3: Retrieve or Create to TOS
'***********************************
PSJ.Parse|{"settings": {}}|$$DHA
PSJ.GetByPath|$$DHA|settings.theme|1
' Places the "theme" node ID (e.g., "3") on Top of Stack (TOS)
PSJ.Free|$$DHA
MBX.Ready
'
Remarks
- Returns a numeric node ID as a string (e.g., "3"). If $$CREATE is 0 and the path doesn’t exist, returns "0".
- When $$CREATE is 1, creates an empty object at the specified path if it doesn’t exist.
- Use PSJ.GetType to check the node’s type after creation or retrieval.
Limitations
- Requires a valid document handle; invalid handles return "0".
- If $$CREATE is 0 and the path is missing, returns "0", which may be ambiguous.
See also: