Introduction
"JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format." [1] The motivation for including a JSON parser in this application suite is the need for a convenient and general means of transmitting input arrays of character codes to APG parsers. APG parsers may require simple 7-bit ASCII characters, a 32-bit array of Unicode code points or in general, an arbitrary array of 32-bit or even 64-bit integers. JSON is a suitable format that encompasses all of these data types, while providing for transmission as a simple byte stream in all cases.
Why not XML? XML is a well-developed system for the mark up of text data. However, it is not designed for and is severely limited as mark up for an arbitrary array of ABNF alphabet character codes. For one, it delivers only Unicode. And, for some reason, it doesn't deliver complete Unicode. It specifically forbids the ASCII control characters other than 0x09, 0x0A, 0x0D and 0x7F, even as escaped characters. On the other hand, several, probably many, important Internet standards are defined in ABNF that specifies a character set of “octets”. That is, all bytes from 0-255. This data would require overlaying a secondary data conversion, base64 for example, for transmission via XML
JSON, fills the needs of transmitting any and all types of data that an APG parser might require. JSON strings carry all allowed Unicode code points, including all ASCII control characters. If non-Unicode characters are required, JSON provides arrays of numbers. Therefore, even an array of 64-bit integer character codes can be represented in JSON format and, because the standard requires that JSON files be UTF-8 encoded, they can be transmitted as a simple byte stream with no byte-order ambiguities.
With these points in mind, a general, RFC8259-compliant JSON parser has been developed and included in this application suite. The full documentation can be found in json/json.h, json/json.c and json/builder.c
Implementation
This JSON parser follows the object model of other APG component objects. That is, a constructor generates a context – an opaque state structure – and fatal errors are reported with a simple exception handling technique. See vpJsonCtor() and vJsonDtor().
In addition, value iterators and JSON text builders are sub-objects. That is, their constructors require a valid JSON object as parent. While they do have their own separate destructors they share a memory object with their parent. Therefore, the destruction of the parent object, vJsonDtor(), will clean up all memory from all child iterators and builders as well.
Design
From the ABNF grammar for a JSON text it is apparent that the grammar defines a tree of values.
In this APG implementation, all nodes of this tree, except for the alternation and concatenations, which do not appear in the concrete syntax tree, are "values". Values are defined sufficiently generally that one structure, json_value_tag, describes fully any node of the tree.
The parser will return an iterator which will walk the tree from value to value in a depth-first fashion. Additionally, iterators can be generated which will walk any value node as the root of a sub-tree, or walk horizontally across all siblings of an object or array parent value node.
