Overview

JPJsonParser provides two class methods for conveniently parse JSON documents which return a JSON representation of Foundation objects:

• +parseString:options:error:
• +parseData:options:error:

The JSON document can be provided either with a NSString or with a NSData object. The JSON text contained in a NSData object shall be encoded in one of the Unicode encoding schemes: UTF-8, UTF-16, UTF-16LE, UTF-16BE, UTF-32, UTF-32LE or UTF-32BE. A BOM may optionally precede the start of the byte stream.

A number of options can be set in parameter options which are ored flags from constants defined in enum “JPJsonParserOptions”.

A more powerful class method can be used in conjunction with a Semantic Actions Object:

• +parseData:semanticActions:

A Semantic Actions Object acts as a delegate for the internal JSON parser. It conforms to the protocol JPSemanticActionsProtocol and implements a set of semantic actions to corresponding parse events. The parse events will be sent from the internal JSON parser to the semantic actions delegate when it encounters JSON elements in the JSON document.

JPJsonParserOptions

Unicode Handling

• JPJsonParserSignalErrorOnNoncharacter

If this option is set, the parser will signal an error if it encounters an Unicode noncharacter within the JSON document. This is the default setting.

• JPJsonParserSubstituteUnicodeNoncharacter

If this option is set, the parser will substitute Unicode noncharacters encountered within JSON Strings in the input text with the Unicode replacement character U+FFFD when creating the strings for a JSON container.

It is not recommended to enable this option. Substituting an Unicode noncharacter may modify the meaning of the input source and should be used with care. Usually, Unicode noncharacters are not allowed in valid Unicode sequences which is used to transmit data. Occurrences of Unicode noncharacters outside of JSON Strings will be always syntax errors and treated as such.

• JPJsonParserSkipUnicodeNoncharacter

If this option is set, the parser will ignore the Unicode noncharacter and remove it from the decoded JSON string when generating a representation. Note: this feature is not yet implemented

Parser Options

• JPJsonParserIgnoreSpuriousTrailingBytes

If this options is set, the parser will ignore any additional characters that occur after the last significant character of a valid JSON document (namely, either a “}” or a “]”). Otherwise, if the parser encounters code units which can not be interpreted as white-space Unicode characters it will issue an error, and if it encounters an Unicode NULL (U+0000) or EOF it will issue a warning to the console.

• JPJsonParserParseMultipleDocuments

If this option is set, the parser parses one or more documents from the input until it receives EOF. Otherwise, the parser treats any non white spaces after the first JSON document as an error.

Note: This option is ignored when invoking the JSON parser through one of the two convenience methods +parseString:options:error: and +parseData:options:error: since parsing multiple documents require to use a Semantic Actions object, and possibly a asynchronous parser.

• JPJsonParserParseMultipleDocumentsAsynchronously

If this option is set, the parser invokes the jsonObjectHandlerBlock asynchronously and immediately processes the next JSON document within the input data. The JSON container is then retained in the dispatch queue till it is processed by the client. This may tie up a lot of system resources if the client processes frees the JSON containers slowly. If the flag is NO, the parser’s thread is blocked until the handler routine returns.

Note: This option has no effect when invoking the JSON parser through one of the convenience methods +parseString:options:error: and +parseData:options:error:.

It is recommended to leave this flag disabled in systems where system resources are scarce or if the data input possibly contains many and large JSON documents. When downloading large data, this helps throttling the consumption of system resources by the underlaying network layer.

• JPJsonParserEncodedStrings

If this option is set, the parser sends properly encoded JSON Strings to the semantic actions object in method -parserFoundKeyValuePairBeginWithKey:length:encoding:index: and method -parserFoundString:length:hasMore:encoding:. That is, the string is encoded as required by RFC 4627.

Otherwise (the default), the parser sends properly decoded strings to the semantic actions object which match the original source string.

JSON Representation Generation

• JPJsonParserCheckForDuplicateKey

Checks whether a key for a JSON object already exists. If it exists, an “duplicate key error” will be logged to error console and error will be set.

• JPJsonParserCreateMutableContainers

If this option is set, the semantic actions object creates a JSON representation with mutable containers. That is, a JSON Array will be represented by a NSMutableArray and a JSON Object will be represented by a NSMutableDictionary.

Number Generation Options

Note: The options for number generation can be used only mutual exclusive.

• JPJsonParserNumberGeneratorGenerateAuto

The parser’s number generator creates a suitable NSNumber or a NSDecimalNumber object when it encounters a number in the input text. JPJsonParserNumberGeneratorGenerateAuto equals zero and is the default option.

• JPJsonParserNumberGeneratorGenerateStrings

If this option is set, the parser number generator creates a NSString when it encounters numbers in the input text and initializes it accordingly. Usually, you wouldn’t select this option if you want to output a JSON container into a string or stream as a proper JSON text. In this case it would treat the numbers as JSON Strings enclosed in quotes. However, when using a string it preserves the format of the number.

• JPJsonParserNumberGeneratorGenerateDecimals

If this option is set the parser’s number generator will always create a NSDecimalNumber object when encountering a number in the input.

Note: Detailed information about mapping of JSON number to a corresponding Foundation class can be found in class JPRepresentationGenerator.

Other options

• JPJsonParserKeepStringCacheOnClear

Clears the string cache if the semantic actions is receives the message clear.

• JPJsonParserCacheDataStrings

Caches data strings in addition to key strings.

Using a Semantic Actions object

Each parser, that is an instance of JPJsonParser or and instance of JPAsyncJsonParser, needs to be associated to a Semantic Actions object. If none is specified when a parser is created, the parser itself creates a default one, which is a JPRepresentationGenerator.

Info: A parser sends parse events to the semantic actions object as they appear in the JSON text. The task of a semantic actions object is to handle these events appropriately.

There are two “built-in” semantic actions classes:

• JPRepresentationGenerator and
• JPStreamSemanticActions