Tag constants

Each constant is a static Int32 tag used by JSON.

JSON

JSON stores one tag and one payload. Its payload is an Int64, Real64, Cond, String, JSON Array, or String JSON HashTable.

Fields

• SCHEMA_NAME: static Text schema-name field with value "Json".
• mem0: reserved Nat64 implementation storage.
• mem1: reserved Nat64 implementation storage.
• mem2: reserved Natx implementation storage.
• mem3: reserved Natx implementation storage.
• impl: public internal implementation field; use tag and payload methods for ordinary access.

Initialization sets the active payload to JSONNull. Assignment copies the active payload, and destruction destroys it. Parsed strings, arrays, and objects therefore belong to the containing JSON value.

Methods

For every payload getter, a runtime tag mismatch reports Wrong tag in Tagged Union! and exits with status 2 when DEBUG is enabled. With DEBUG disabled, the runtime check is omitted; do not use a wrong-payload reference.

Payload getters return borrowed views, mutable through a mutable JSON and immutable through an immutable JSON. Reacquire them after relevant tag changes or storage-moving mutations of the containing arrays or objects; do not outlive the owner.

Value conversions

Each conversion requires the payload schema itself: Int64, Real64, Cond, String, JSON Array, or String JSON HashTable, respectively. No implicit conversion is performed. Convert inputs first; for example, use "abc" toString stringAsJSON. Each result is a new owning JSON object. Immutable managed inputs are copied and mutable managed inputs may be moved from. intAsJSON accepts every Int64 value.

Payload and ownership rules

• A parsed JSON array is a JSON Array of JSON values; a parsed object is a String JSON HashTable whose keys are strings and whose values are JSON values.
• The parse result owns its JSON tree and diagnostic message, but errorInfo.position.currentSymbol borrows the original source bytes. Keep those bytes alive and unmoved while using that view. A copied position still refers to the same source bytes.
• Check success before using a parsed value, and also require finished for a complete-input parse. On failure, json may contain a partial value; on clean completion, errorInfo.position remains the default position.
• Copying a JSON copies its active payload. A copied parsed tree can be changed without changing the original tree.
• Changing the active tag or destroying a JSON invalidates references into its previous payload.

JSONParserResult

Fields

• success: TRUE when lexical processing and node parsing succeed; FALSE on a JSON failure or when splitting reports an encoding failure.
• finished: starts TRUE. parseStringToJSON sets it to FALSE when trailing source characters remain; parseJSONNode does not derive it from remaining input.
• errorInfo: JSONParserErrorInfo containing the diagnostic and position.
• json: the first parsed JSON node when parsing reaches a node. With trailing input, it still contains that node.

Remarks

• finished is not a success flag: a failure at end of input can leave it TRUE. A clean, fully consumed parse leaves errorInfo.position at its default position.

JSONParserPosition

Fields

• column: Int32 one-based column in the split character views.
• line: Int32 one-based line in the split character views.
• offset: Int32 zero-based index into the split character views.
• currentSymbol: the current source-byte view from the split source, or an empty view at end of input.
• currentCode: the first byte of currentSymbol converted to Nat32, not a decoded Unicode code point; it is zero at end of input.

Remarks

• Line and column are one-based; LF advances line and resets column to 1. A multibyte UTF-8 character advances one offset and one column.
• If splitting reports an encoding failure, success is FALSE, the message is Wrong encoding, can not recognize line and column, offset in bytes, offset and column contain the byte offset, and line is zero.

JSONParserErrorInfo

Fields

• message: parser diagnostic as a String.
• position: JSONParserPosition at the failure or first unparsed position.

Parser model and low-level helpers

Parsing runs at run time, including when source is known Text; inspect success, finished, payload, and position at run time.

• One source value is parsed as one JSON node. Leading and trailing whitespace is ignored; non-space trailing input makes finished FALSE.
• Arrays preserve source order. Object keys must be unique; duplicate keys fail with duplicate key.
• Numbers without a fractional or exponent part produce JSONInt; numbers with either produce JSONReal.
• Leading zeros after the first digit fail with not allowed digits after leading zero. Integer overflow normally fails with integer constant overflow.
• The accepted JSONInt range is -9223372036854775807 through 9223372036854775807. 9223372036854775808, -9223372036854775808, and -9223372036854775809 fail with integer constant overflow, found in errorInfo.message at end of input.
• Fractional or exponent notation produces JSONReal, including 9223372036854775808.0 and 9223372036854775808e0; an oversized integer without either notation fails rather than becoming JSONReal.
• String escapes include \", \\, \/, \b, \f, \t, \n, \r, and \uXXXX.
• A high and low UTF-16 surrogate escape pair is combined into one code point. A high surrogate without \u followed by a low surrogate, or a lone low surrogate, fails. Saving writes supplementary code points as paired \uXXXX escapes.

Current parser limitations

• Supply valid UTF-8; the parser is not a UTF-8 validator: malformed bytes inside a quoted string can be accepted and retained in the payload. Saving such a payload can replace malformed sequences with \ufffd rather than report an error.
• If splitting reports an encoding failure, success is FALSE and message is Wrong encoding, can not recognize line and column, offset in bytes. In that case offset and column contain the byte offset, and line is zero.
• Large whole-number parts have a further limitation: after the integer accumulator wraps to zero, a following digit can cause not allowed digits after leading zero. For example, 184467440737095516160.0 and 184467440737095516160e0 both fail at offset 20 with not allowed digits after leading zero, 0 found. Fractional or exponent notation does not avoid this case.
• The parser is not a strict JSON validator. It accepts trailing commas in arrays and objects, skips non-NUL control bytes up to 0x20 outside strings, and accepts malformed number spellings such as a single minus sign, --1, 1., 1e, and 1e++2.
• For an accepted number, digits in the fractional or exponent part select JSONReal; otherwise the result is JSONInt. Thus the accepted spellings 1. and 1e yield JSONInt, while 1.0e yields JSONReal. Validate syntax separately when strict JSON input is required.

Failure messages

• Node diagnostics are MESSAGE + ', ' + currentSymbol + ' found', with empty currentSymbol at end.
• Malformed strings use unterminated string, wrong code after \, or error in unicode before the current symbol is appended.
• An unquoted object key reports quote expected. Malformed number syntax can report wrong number constant. Surrogate failures use \u expected after high surrogate in \u escape, low surrogate expected after high surrogate in \u escape, or unexpected low surrogate in \u escape.
• Malformed literals use failed to read "true", failed to read "false", failed to read "null", or unexpected symbol.
• Malformed containers use : expected here, , or } expected here, or , or ] expected here.

Remarks

• Detected string-encoding failures use Wrong encoding in JSON string! and Wrong encoding in splitted array! when DEBUG is enabled. They do not make the current implementation a UTF-8 validator.

Low-level helpers

parseStringToJSON

saveJSONToString

Examples

Runtime parser results

"Json"    use
"String"  use
"control" use

{} () {} [
  result: "{\"x\":1}" parseStringToJSON;
  ("success=" result.success
    ",finished=" result.finished
    ",tag=" result.json.getTag
    ",size=" result.json.getObject.size LF) printList
  trailing: "{} x" parseStringToJSON;
  duplicate: "{\"x\":1,\"x\":2}" parseStringToJSON;
  ("trailing-success=" trailing.success
    ",finished=" trailing.finished
    ",offset=" trailing.errorInfo.position.offset LF
    "duplicate-success=" duplicate.success LF) printList
] "main" exportFunction

Expected Output

success=TRUE,finished=TRUE,tag=6,size=1
trailing-success=TRUE,finished=FALSE,offset=3
duplicate-success=FALSE

Parse and serialize array

"Json"    use
"String"  use
"control" use

{} Int32 {} [
  result: "[1,true]" parseStringToJSON;
  result.success ~ [
    1
  ] [
    result.json saveJSONToString print
    0
  ] if
] "main" exportFunction

Expected Output

[
  1,
  true
]

See also

• HashTable: Hash-based map and set module.
• String: UTF-8 string views, owned strings, formatting helpers, and text conversion utilities.
• Xml: XML document, parser, and serialization helpers.