Overview

A JPRepresentationGenerator class is a semantic actions class which can be associated to a JSON parser. It implements a set of semantic actions in order to generate a JSON representation of Foundation objects from a JSON document. A JPRepresentationGenerator instance is the default semantic actions class for a JPJsonParser, unless another one is specified explicitly.

Class JPRepresentationGenerator is “self-contained” which means that it consumes and handles ALL “parse events” itself and thus, will not have a delegate nor is it meant to be subclassed.

JPRepresentationGenerator manages an internal cache for key strings and manages internal buffers that are required for parsing and for the highly efficient memory allocator which is used to create foundation objects. That cache, the buffers and the allocator can be reused when multiple JSON documents shall be parsed.

Note: Reusing a sematic actions object can reduce memory foot-print and speeds up parsing of multiple JSON documents.

Using a JPRepresentationGenerator

An instance of JPRepresentationGenerator can be setup individually and its behavior can be tailored by setting properties. An instance of a semantic actions object can be specified as a parameter when creating a parser.

For example a JPRepresentationGenerator object can be set as parameter semanticActions in method +parseData:semanticActions: of class JPJsonParser.

As a result, the parser will create a representation as a hierarchy of Foundation objects from the JSON text. When the parser is finished, this JSON structure can be retrieved with property result of the semantic actions object.

Note: The convenience methods of class JPJsonParser +parseString:options:error: and +parseData:options:error: just use a JPRepresentationGenerator object internally and configure it using the options provided in parameter options.

Depending on the configuration of the JPRepresentationGenerator instance, the parser may parse one or more JSON documents within one input. If more than one JSON documents shall be parsed, the client is required to setup handler blocks and possibly a dispatch queue for the semantic actions instance.

The handler blocks will be called by the JPRepresentationGenerator instance on the occurrence of the following events:

• The start of a JSON document was detected.
• A JSON document could be parsed completely and a Foundation object has been created, which will be passed as parameter to the client.
• The parser finished parsing the text.
• An error occurred.

The semantic actions object also contains additional information, for example an error object, which can be retrieved in case an error occurred.

Setting Up Handler Blocks

This is described in JPSemanticActionsBase Setting Up Handler Blocks.

Mapping JSON Elements to Foundation Classes

The conversion and mapping of JSON values will be done as follows:

• JSON Object maps to a NSDictionary/NSMutableDictionary.
• JSON Array maps to a NSArray/NSMutableArray.
• JSON String maps to a NSString.
• JSON Number maps to a NSDecimalNumber/NSNumber
• JSON Boolean maps to a NSNumber initialized with a BOOL.
• JSON Null maps to a NSNull.

I Detailed Mapping of an Integral JSON Number

1. If the number of digits of a JSON integer number is equal or smaller than the maximal number of digits (in decimal base) that can be represented by a signed int without overflow, then a NSNumber with underlaying type signed int will be generated.

2. Otherwise, if the number of digits of a JSON integer number is equal or smaller than the maximal number of digits (in decimal base) that can be represented by a signed long without overflow, then a NSNumber with an underlaying type signed long will be generated.

3. Otherwise, if the number of digits of the JSON integer number is equal or smaller than the maximal number of digits (in decimal base) that can be represented by a signed long long without overflow, then a NSNumber with an underlaying type signed long long will be generated.

4. Otherwise, if the number of digits of the JSON integer number is equal or smaller than the maximal number of digits (in decimal base) that can be represented by a NSDecimalNumber without loosing precision, then a NSDecimalNumber will be generated.

5. Otherwise, a NSDecimalNumber will be generated, and if this is successful, a warning will be logged to the error console to indicate the possibly loss of precision while converting a JSON Number to a NSDecimalNumber.

6. Otherwise, the conversion fails, and the parser stops parsing with a corresponding runtime error.

II Detailed Mapping of a Decimal JSON Number

A decimal number is a number with a decimal point but no exponent.

1. If the number of digits of the decimal number is equal or smaller than the maximal number of digits (in decimal base) that can be represented by a double, then a NSNumber with underlaying type double will be generated.

2. Otherwise, NSDecimalNumber will be generated. If the NSDecimalNumber cannot represent the decimal value with the same precision as in the JSON number, an additional warning will be logged. If the decimal value cannot represent the JSON number because it is out of range, a range error will be signaled.

II Detailed Mapping of a Scientific JSON Number

A number in scientific form has an optional decimal point and an exponent.

1. A JSON number in scientific format will always be converted to a NSNumber with an underlaying double type. If the resulting value is out of range, a range error will be signaled.