PSJ. - JSON Operations Overview |
SPR Script Language
PSJ. - JSON Operations Overview (WsLnTre)
Comprehensive guide to the PSJ. commands for JSON manipulation, leveraging the JSW (JSON Wide) library with WsLnTre integration.
Intention
This overview serves as the central entry point for the PSJ. command set, which interfaces with the underlying JSW (JSON Wide) library. This library handles JSON parsing, manipulation, querying, and serialization using an internal WSTRING (UTF-16LE) representation and utilizes the advanced WsLnTre (WString Key -> LONG Value Tree) library for efficient storage and retrieval of JSON object members. This overview categorizes the commands, making it easier to find the right tool for your JSON tasks.
Key Concepts (JSW & WsLnTre)
• WSTRING Internal Representation: The JSW library stores all string values and key names internally as WSTRINGs (UTF-16LE). The PSJ. command dispatcher automatically handles conversion between SPR's standard STRING (assumed UTF-8) and the library's internal WSTRING format where necessary.
• WsLnTre for Objects: JSON object members (key-value pairs) are stored using the WsLnTre library. This provides significant performance benefits for object key lookups (e.g., PSJ.FindFromNode, path navigation within objects) compared to linear searches.
• Object Key Order: A consequence of using WsLnTre is that the order of keys within an object during serialization (PSJ.ToString) or querying (PSJ.GetKeys) will depend on the Tree's internal sort order (typically alphabetical), not the original insertion order.
• Array vs. Object Functions: Because Objects use the Tree structure, some functions that rely on ordered indices or sibling relationships (e.g., PSJ.ChildAt, PSJ.NextSib, PSJ.ChildIDs) are now only applicable and reliable for ARRAY nodes.
Overview of PSJ. Commands
The PSJ. library organizes commands into chapters based on their functionality:
• Initialization, State & Error Handling - Resetting the library, getting errors/results.
• Parsing, Loading & File I/O - Creating JSON documents from strings or files.
• Document & Node Lifecycle - Managing handles, freeing memory, duplicating, replacing nodes.
• Path Navigation & Querying - Finding nodes, getting types, counts using path strings.
• Value Get/Set Operations - Retrieving and modifying primitive values (string, number, boolean, null).
• Array Operations - Appending, removing, and querying JSON arrays specifically.
• Object Operations - Retrieving keys and removing key/value pairs from JSON objects.
• Merge Operations - Combining arrays, objects, or entire documents.
• Serialization - Converting JSON document structures back into JSON strings.
• Utility & One-Shot Commands - Searching, validation, repair, and direct parsing/extraction commands.
This page links to detailed chapters that group related commands, making it easier for users to find the tools they need for specific JSON tasks.
In this Sample we access the Local LLM via "LM Studio" and Parse the Output and paste it from the Clipboard. This way Unicode Emojis can get preserved.
Illustration
📝 Example 1: Parse and Modify a JSON Document
JSON Input:
{ "person": { "name": "Alice", "age": 25 } }
SPR Code:
PSJ.Parse|'{ "person": { "name": "Alice", "age": 25 } }'|$$DOC
PSJ.SetStr|$$DOC|person.name|Bob // Use Dot-Notation path
PSJ.ToString|$$DOC|$$RESULT
Result (stored in $$RESULT):
{"person":{"name":"Bob","age":25}} // Default is compact
📝 Example 2: Append to an Array and Save to File
JSON Input:
{ "items": [1, 2] }
SPR Code:
PSJ.Parse|'{ "items": [1, 2] }'|$$DOC
PSJ.AppendNum|$$DOC|items|3 // Appends 3 to the 'items' array
PSJ.SaveFile|$$DOC|output.json|1|2 // Save pretty-printed with 2 spaces
Result (saved to output.json):
{
"items": [
1,
2,
3
]
}
📝 Navigate to Specific Chapters: Use the links below to explore related commands in detail.
Chapters
• Initialization, State & Error Handling - Starting/stopping, getting status.
• Parsing, Loading & File I/O - Creating documents from strings/files.
• Document & Node Lifecycle - Freeing, duplicating, replacing nodes.
• Path Navigation & Querying - Finding nodes and information via paths.
• Value Get/Set Operations - Reading/writing primitive JSON values.
• Array Operations - Modifying and querying Array nodes.
• Object Operations - Getting keys and removing members from Object nodes.
• Merge Operations - Combining JSON structures.
• Serialization - Converting documents/nodes back to JSON strings.
• Utility & One-Shot Commands - Searching, validation, repair, and direct parsing/extraction utilities.
Remarks
- The PSJ library uses document handles (integers > 0) to manage parsed JSON structures in memory. Ensure these handles are freed using PSJ.Free or PSJ.FreeAll when no longer needed to avoid memory leaks.
- Input strings for commands like PSJ.Parse, PSJ.SetStr, paths, etc., are treated as UTF-8 and converted internally to WSTRING as needed.
- Output strings returned (e.g., via PSJ.GetStr, PSJ.ToString) are converted from the internal WSTRING format back to UTF-8 STRINGs.
- The WsLnTre integration improves performance for object operations but means key order is generally not preserved.
- Always check the return code or use PSJ.ErrCode / PSJ.ErrMsg after operations that return a status code to verify success.