|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > PSJ. - Parser Operations |
PSJ. - Parser Operations |
Top |
SPR Script Language
PSJ. - Parser Operations
Commands for converting JSON text into usable structures or extracting data directly.
Intention
This chapter covers commands related to getting JSON data into the SPR system. This includes parsing JSON text from strings or files into internal representations (identified by a Document Handle) that can then be manipulated by other PSJ. commands. It also includes commands for creating simple JSON document handles directly from delimited strings and a suite of "one-shot" commands for extracting specific pieces of data from JSON text without needing to manage a document handle explicitly.
Key Concepts
• Document Handles: Commands like PSJ.Parse and PSJ.LoadFile return a numeric Document Handle (e.g., 1, 2, etc.). This handle represents the parsed JSON structure in memory and is required as input for most subsequent querying and modification commands (e.g., PSJ.GetStr, PSJ.SetStr). Remember to free these handles using PSJ.Free or PSJ.FreeAll when done.
• One-Shot Extraction: Commands prefixed with `Extract` (e.g., PSJ.ExtractStr, PSJ.ExtractNum) perform parsing, data retrieval via a path, and cleanup in a single step. They are convenient for quickly getting specific data points from JSON text (like an API response) without the need to manage a document handle. They generally return the extracted value directly or a status code.
• Encoding: SPR typically uses UTF-8 encoded strings. The PSJ. commands handle the necessary conversion to/from the internal WSTRING (UTF-16LE) format used by the JSW library. PSJ.Parse expects its input string parameter to be UTF-8. PSJ.LoadFile attempts to detect the encoding (UTF-8 BOM, UTF-16LE BOM, UTF-16BE BOM) and defaults to UTF-8 if no BOM is found.
Command Groups
Parsing & Loading (Creating Document Handles)
These commands read JSON text and create a persistent document handle for further manipulation.
•PSJ.Parse - Parses a JSON string (assumed UTF-8) into a new document handle.
•PSJ.LoadFile - Loads JSON from a file (detects encoding) into a new document handle.
Direct Document Creation (from Strings)
These commands create simple documents directly without parsing full JSON text.
•PSJ.CreateArrFromStr - Creates an array document from a string of delimited values.
•PSJ.CreateObjPairs - Creates an object document from a string of key=value; pairs.
One-Shot Extraction Commands
These parse JSON text and extract specific values directly, discarding the internal structure afterwards. Useful for API responses.
•PSJ.ExtractStr - Extract a string value.
•PSJ.ExtractNum - Extract a number value (as a string).
•PSJ.ExtractBool - Extract a boolean value (1/0/-1).
•PSJ.ExtractArrLen - Extract the length of an array.
•PSJ.ExtractArrStr - Extract a string from within an array element using an index and optional sub-path.
•PSJ.ExtractArrAllStr - Extract all matching strings from an array into an SSPR array.
•PSJ.ExtractArrObj - Extract an object or array element itself as a JSON string.
•PSJ.ExtractChoicesContent - OpenAI Specific: Extracts content from the first choice.
•PSJ.ExtractChoicesAllContent - OpenAI Specific: Extracts content from all choices into an SSPR array.
•PSJ.ExtractFinishReason - OpenAI Specific: Extracts the finish reason.
•PSJ.ExtractUsageTokens - OpenAI Specific: Extracts token usage counts.
Illustration
📝 Example 1: Parse a JSON String
VAR $$MyJson = '{ "city": "New York", "temp": 15 }'
PSJ.Parse|$$MyJson|$$DocHandle // Parses the string, returns handle in $$DocHandle
// Now use $$DocHandle with PSJ.GetStr, PSJ.SetStr, etc.
PSJ.Free|$$DocHandle
📝 Example 2: Extract a Value Directly
PSJ.ExtractStr|{"id":123,"name":"Widget"}|name|$$ProdName
// $$ProdName now contains "Widget". No handle created or freed.
Remarks
- Use the Parsing & Loading commands when you need to perform multiple operations on the same JSON structure.
- Use the One-Shot Extraction Commands for quick retrieval of specific data without persistent handles.
- Use the Direct Document Creation commands to quickly build simple JSON structures from basic string formats.
- Always check return codes or use PSJ.ErrCode / PSJ.ErrMsg to handle potential errors during parsing or extraction.
See also:
• PSJ. - JSON Operations Overview (WsLnTre)
• Understanding JSON Paths in PSJ.