Overview

JPSemanticActionsProtocol defines the interface between the underlaying JSON parser and the semantic actions object. The protocol must be implemented by concrete subclasses of JPSemanticActionsBase.

The JSON parser will not perform semantic actions by itself, instead it will notify the semantic actions object of certain parse events and provide necessary information for the event.

Parse events are signaled by the underlaying JSON parser via messages sent to the semantic actions object whose signature is prefixed with “parserFound”. The semantic actions object is supposed to implement a corresponding “semantic action” appropriate for the event and the current context and current state.

A “begin” message, that is a parserFoundArrayBegin or a parserFoundObjectBegin message, indicates the start of a JSON container (a JSON Array, or a JSON Object). An “end” message, that is a parserFoundArrayEnd or a parserFoundObjectEnd message, indicates the end of the container which refers to the container signaled with the “begin” message immediately preceding this “end” message.

Additionally, there are two events parserFoundKeyValuePairBeginWithKey:length:encoding:index: and parserFoundKeyValuePairEnd which are sent when the parser encountered a JSON string which is a key in the key-value pair of a JSON Object, and when the parser encountered the end of the JSON Value associated to this key.

“begin” and “end” messages are strictly balanced and reflect the recursive, respectively hierarchical, structure of a JSON representation.

Finally, the underlaying parser sends messages parserFound<JSON_primitive>, that is parserFoundString, parserFoundNull, parserFoundBoolean and parserFoundNumber when it encounters a corresponding JSON primitive value.

If the semantic actions property generateEncodedStrings returns NO (the default) the parser sends decoded JSON Strings (which include keys) to the semantic actions object. Otherwise, if the property generateEncodedStrings returns YES, the parser sends encoded JSON Strings to the semantic actions object. (see also JPSemanticActionsBase) If the parser uses a representation generator as a semantic actions object, it usually requires a properly decoded string which is equal to the original source string.

Below is a typical flow of the complete messages:

parserFoundArrayBegin
    parserFoundObjectBegin
        parserFoundKeyValuePairBeginWithKey:length:encoding:index:
            parserFoundArrayBegin
                parserFoundValueBeginAtIndex:
                parserFoundString:length:hasMore:encoding:
                parserFoundString:length:hasMore:encoding:
                parserFoundValueEndAtIndex:

                parserFoundValueBeginAtIndex:
                parserFoundString:length:hasMore:encoding:
                parserFoundValueEndAtIndex:


            parserFoundArrayEnd
        parserFoundKeyValuePairEnd

        parserFoundKeyValuePairBeginWithKey:length:encoding:index:
            parserFoundArrayBegin
                parserFoundValueBeginAtIndex:
                parserFoundNumber:length:
                parserFoundValueEndAtIndex:

                parserFoundValueBeginAtIndex:
                parserFoundNumber:length:
                parserFoundValueEndAtIndex:
                ..
            parserFoundArrayEnd
        parserFoundKeyValuePairEnd

    parserFoundObjectEnd
    parserFoundObjectBegin
        ..
    parserFoundObjectEnd
 parserFoundArrayEnd

A parserFoundString message may be possibly sent repeatedly, if the string is handled in “chunks”. The method has a parameter hasMore which indicates when the string is eventually complete. A data string will be split into chunks if its size becomes large. The exact size of a chunk is dependent on the implementation. Currently, this equals about 2000 code units. Occasionally, this may become larger if the implementation can utilize an already allocated buffer whose size is larger.

Implementing actions for “begin”, “end” and “found primitive value” messages will be usually sufficient to implement a semantic actions class which creates a JSON representation., e.g. with Foundation objects as containers and primitive values.

A concrete implementation would purposefully use an internal stack in order to aid the construction of a JSON representation, e.g. with Foundation objects.

Basically, a “representation generator” could be implemented as follows:

A “begin” message will be the first message sent from the parser – besides the more informative “parserFoundJsonBegin” event. A valid JSON starts with either a JSON Array or a JSON Object.

Now, a “begin” event may not be immediately followed by the corresponding “end” event – rather, since a JSON representation is a hierarchical data structure, “begin” may be followed by one or more other “begin” events. But eventually, the “begin” and “end” become balanced. Nonetheless, the basic principle of building a representation remains simple:

So, on a “begin” message, the generator would create the corresponding container (for Foundation, a NSArray or NSDictionary object) and push it onto its internal stack.

On a “found primitive value” message, the generator would simply construct a corresponding representation (e.g. a Foundation object) for a JSON String (Key), JSON Boolean, and a JSON Null and push them onto the stack as well.

On an “end” message the generator would pop all objects from laying above the current container to the top of the stack and insert them into it. Now, this container will become the top of the stack – which in turn may be an element of another container.

Note that the corresponding action on an “end” message for JSON Array respectively JSON Object do differ slightly, since a JSON Object expects key-value pairs on the stack and a JSON Array expects values in a sequence and must retain the order of elements.

The process ends with the last message, an “end” message, whose action is exactly the same: pop the elements from the stack and insert them into the current container. The current container is, of course, the last remaining object residing in the stack, and this becomes the final result.

The four methods

• -parserFoundValueBeginAtIndex:,
• -parserFoundValueEndAtIndex:,
• -parserFoundValueBeginWithKey:length:encoding:index and
• -parserFoundValueEndWithKey:length:encoding:index

are helpful when implementing a streaming API. These additional messages give fine grained control for all relevant parser events. For more information see JPSemanticActionsProtocol and JPStreamSemanticActions.

For instance, these messages will be required, reconstructing the JSON text from the parser events (possibly converted to another Unicode encoding, with unescaped Unicode characters, removed comments, etc.)

These message are invoked as follows:

parserFoundArrayBegin
    parserFoundValueBeginAtIndex:
    parserFoundValueEndAtIndex:
parserFoundArrayEnd

parserFoundObjectBegin
    parserFoundKeyValuePairBeginWithKey:length:encoding:index:
    parserFoundKeyValuePairEnd
parserFoundObjectEnd