|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Parser-Operations > !Document Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.ToString
Converts an entire JSON document, referenced by its handle, into a JSON formatted string representation.
Intention
The PSJ.ToString command takes a document handle ($$DOC), which represents a JSON structure previously parsed or created using commands like PSJ.Parse or PSJ.LoadFile, and serializes it back into a standard JSON text string. This string can then be stored in a variable ($$VAR), saved to a file, or sent via an API. You can optionally specify if the output string should be "pretty-printed" with indentation and line breaks for better human readability.
This is essentially the reverse operation of PSJ.Parse.
Illustration
📝 Compact Output: PSJ.ToString|$$DOC|$$JSC serializes compactly (e.g., `{"name":"value","arr":[1,2]}`).
📝 Pretty Output: PSJ.ToString|$$DOC|1|$$JSP serializes with default indentation.
📝 Custom Indent: PSJ.ToString|$$DOC|1|4|$$JSO serializes with 4 spaces per indent level.
Syntax
PSJ.ToString|$$DOC[|$$PRT[|$$IND[|$$VAR]]]
Parameter Explanation
P1 - $$DOC (Variable, Numeric)
The document handle (integer > 0) representing the loaded JSON document to serialize. Required.
P2 - $$PRT (Variable, Numeric, Optional)
Flag indicating whether to format the output for readability. Specify 1 (or non-zero) for pretty-printing (adds indentation and line breaks). Specify 0 or omit for compact output (no extra whitespace). Default is 0 (compact).
P3 - $$IND (Variable, Numeric, Optional)
The number of space characters to use for each indentation level when pretty-printing is enabled ($$PRT = 1). Must be 1 or greater if specified. If omitted or 0, defaults to 2 spaces. Ignored if $$PRT is 0.
P4 - $$VAR (Variable, String, Optional)
An optional variable name (e.g., $$VAR, $$RES) to store the resulting JSON string (UTF-8 encoded). If omitted, the result is still available via PSJ.GetLastResultS or PSJ.GetLastResultW (and potentially copied to clipboard if PSJ.SetClipOutput is enabled).
Examples
// Assume $$DOC contains handle for: { "a": 1, "b": [ "x", "y" ] }
// Example 1: Compact Serialization
PSJ.ToString|$$DOC|$$JSC
// $$JSC = {"a":1,"b":["x","y"]}
// Example 2: Pretty Serialization (Default Indent=2)
PSJ.ToString|$$DOC|1|$$JSP
// $$JSP =
// {
// "a": 1,
// "b": [
// "x",
// "y"
// ]
// }
// Example 3: Pretty Serialization (Indent=4)
PSJ.ToString|$$DOC|1|4|$$JSW
// $$JSW =
// {
// "a": 1,
// "b": [
// "x",
// "y"
// ]
// }
MBX.OK|Results|$$JSC$CRLF$$JSP$CRLF$$JSW
Remarks
§ This command serializes the entire JSON document structure associated with the provided $$DOC handle.
§ The output string is always UTF-8 encoded when returned to SPR variables.
§ Due to the WsLnTre implementation for objects, the order of keys in the output string may differ from the original insertion order (typically alphabetical).
§ If serialization fails (e.g., invalid handle, invalid node structure encountered internally), an empty string ("") will be returned, and an error code/message will be set. Use PSJ.ErrCode.
§ To serialize only a part of the document, use PSJ.GetByPath to get the Node ID of the desired subtree root, then call PSJ.NodeToStr.
See also: