JSONPP: JSON Pull Parser (Work in Progress)

try {
    var parser = factory.createParser(reader);
    while (parser.hasNext()) {
        parser.next();
        switch (parser.getEvent()) {
            case START_ARRAY:
                // and so on ...
        }
    }
} finally {
    reader.close();
}

_producer.setEvent(JsonEvent.START_ARRAY);
_producer.push();
_producer.setEvent(JsonEvent.END_ARRAY);
_producer.push();

package com.frank_mitchell.jsonpp;

/**
 * Enumeration of all possible JsonPullParser events.
 */
public enum JsonEvent {
    /**
     * Invalid JSON syntax.
     */
    SYNTAX_ERROR,

    /**
     * Before first JSON element
     */
    START_STREAM,

    /**
     * Start of JSON array ('[')
     */
    START_ARRAY,

    /**
     * End of JSON array (']')
     */
    END_ARRAY,

    /**
     * Start of JSON object ('{')
     */
    START_OBJECT,

    /**
     * End of JSON object ('}')
     */
    END_OBJECT,

    /**
     * Key of JSON object member ('"'...'"' ':')
     */
    KEY_NAME,

    /**
     * JSON null ("null")
     */
    VALUE_NULL,

    /**
     * JSON boolean true ("true")
     */
    VALUE_TRUE,

    /**
     * JSON boolean false ("false")
     */
    VALUE_FALSE,

    /**
     * JSON number
     */
    VALUE_NUMBER,

    /**
     * JSON string ("...")
     */
    VALUE_STRING,

    /**
     * After last JSON element
     */
    END_STREAM
};

package com.frank_mitchell.jsonpp;

import java.io.Closeable;
import java.io.IOException;

/**
 * This interface traverses a JSON Value as a stream of events.
 *
 * Each call to {@link #next()} moves to the next event in the stream, and the
 * various "get" methods identify the type of event, the value of a String or
 * Number, and/or the name of a key String.
 *
 * Implementations of this interface aren't guaranteed to be thread safe. In
 * most cases one thread will parse an input stream and then discard this
 * parser. In some cases one thread <strong>might</strong> hand a parser off to
 * another thread, then continue parsing once that thread has finished. (In the
 * latter case a co-routine or cooperative single-threaded framework might be
 * more efficient.)
 *
 * @author Frank Mitchell
 *
 */
public interface JsonPullParser extends Closeable {

    /**
     * Get the event parsed by the most recent call to {@link #next()}.
     *
     * @return most recently parsed event.
     */
    public JsonEvent getEvent();

    /**
     * Indicates if the enclosing value is a JSON Array.
     *
     * If this object is currently processing the contents of a JSON Array, this
     * method will return {@code true}.
     *
     * @return {@code true} if the enclosing value is a JSON Array.
     *
     * @see #isInObject()
     */
    public boolean isInArray();

    /**
     * Indicates if the enclosing value is a JSON Object.
     *
     * If this parser is currently processing the contents of a JSON Object,
     * this method will return {@code true}. If neither this method nor
     * {@link #isInArray()} are true, this parser is either at the start or end
     * of the document, the document contains only an atomic value, or the
     * parser encountered an error.
     *
     * @return {@code true} if the enclosing value is a JSON Object.
     */
    public boolean isInObject();

    /**
     * Whether this implementation supports {@link #getCurrentKey}.
     * While most should, some implementers may choose memory footprint
     * and speed over convenience.
     * Override this method for implementations that don't.
     *
     * @return whether {@link #getCurrentKey
     */
    default public boolean isCurrentKeySupported() {
        return true;
    }

    /**
     * Gets the key associated with the current value.
     *
     * On {@link JsonEvent#KEY_NAME}, the result is the JSON Object key
     * with outer quotes removed and backslash escapes resoved.
     *
     * On {@link JsonEvent#END_OBJECT},
     * {@link JsonEvent#END_ARRAY},
     * {@link JsonEvent#VALUE_STRING},
     * {@link JsonEvent#VALUE_NUMBER},
     * {@link JsonEvent#VALUE_TRUE},
     * {@link JsonEvent#VALUE_FALSE}, or {@link JsonEvent#VALUE_NULL}, the
     * result is the JSON Object key this value should be assigned to, if the
     * enclosing construct is a JSON Object.
     *
     * On {@link JsonEvent#START_STREAM},
     * {@link JsonEvent#START_ARRAY},
     * {@link JsonEvent#START_OBJECT},
     * {@link JsonEvent#END_STREAM}, or {@link JsonEvent#SYNTAX_ERROR} or if
     * there is no immediately enclosing JSON object, this method returns
     * {@code null};
     *
     * @return the value of a String or Number or {@code null}
     * @throws UnsupportedOperationException if method not supported.
     */
    public String getCurrentKey();

    /**
     * Gets the string value associated with the current event.
     *
     * On {@link JsonEvent#KEY_NAME}, the result is the JSON Object key with all
     * escape sequences converted to their character values.
     *
     * On {@link JsonEvent#VALUE_STRING}, the result is the JSON String with all
     * escape sequences converted to their character values.
     *
     * On a {@link JsonEvent#VALUE_NUMBER}, the result is the number as
     * originally read.
     *
     * Otherwise the method throws an exception
     *
     * @return the value of a String or Number or {@code null}
     *
     * @throws IllegalStateException if the current event has no string value.
     */
    public String getString();

    /**
     * Gets the {@link Number} value associated with the current event.
     *
     * If {@link #getEvent()} is {@link JsonEvent#VALUE_NUMBER}, this method
     * returns an unspecified subclass of Number. Otherwise this method throws
     * an exception.
     *
     * @return the value of the current JSON Number
     *
     * @throws IllegalStateException if the current event is not a number.
     */
    public Number getNumber() throws IllegalStateException;

    /**
     * Gets the {@code double} value associated with the current event.
     *
     * If {@link #getEvent()} is {@link JsonEvent#VALUE_NUMBER}, this method
     * returns an unspecified subclass of Number. Otherwise this method throws
     * an exception.
     *
     * @return the value of the current JSON Number
     *
     * @throws IllegalStateException if the current event is not a number.
     */
    default double getDouble() throws IllegalStateException {
        Number n = getNumber();
        if (n == null) {
            return Double.NaN;
        } else {
            return n.doubleValue();
        }
    }

    /**
     * Gets the {@code int} value associated with the current event.
     *
     * If {@link #getEvent()} is {@link JsonEvent#VALUE_NUMBER}, this method
     * returns an unspecified subclass of Number. Otherwise this method throws
     * an exception.
     *
     * @return the value of the current JSON Number
     *
     * @throws IllegalStateException if the current event is not a number.
     */
    default int getInt() throws IllegalStateException {
        Number n = getNumber();
        if (n == null) {
            throw new IllegalStateException("!" + JsonEvent.VALUE_NUMBER);
        }
        return n.intValue();
    }

    /**
     * Gets the {@code long} value associated with the current event.
     *
     * If {@link #getEvent()} is {@link JsonEvent#VALUE_NUMBER}, this method
     * returns an unspecified subclass of Number. Otherwise this method throws
     * an exception.
     *
     * @return the value of the current JSON Number
     *
     * @throws IllegalStateException
     */
    default public long getLong() throws IllegalStateException {
        Number n = getNumber();
        if (n == null) {
            throw new IllegalStateException("!" + JsonEvent.VALUE_NUMBER);
        }
        return n.longValue();
    }

    /**
     * Advances to the next significant JSON element in the underlying stream.
     *
     * @throws IOException if the character source could not be read.
     */
    public void next() throws IOException;

    /**
     * Equivalent to calling {@link #next()} followed by {@link #getEvent()}.
     *
     * @return most recently parsed event.
     *
     * @throws IOException if the character source could not be read
     */
    default public JsonEvent nextEvent() throws IOException {
        next();
        return getEvent();
    }

    /**
     * Close the underlying IO or NIO object.
     *
     * @throws IOException from the underlying object.
     */
    @Override
    void close() throws IOException;
}

package com.frank_mitchell.jsonpp;

import com.frank_mitchell.codepoint.CodePointSource;
import java.io.IOException;
import java.io.InputStream;
import java.io.Reader;
import java.nio.charset.Charset;
import java.util.Map;

/**
 * Creates JsonPullParser instances without clients knowing the specific
 * class(es) used.
 *
 * {@link #setConfiguration(Map)} provides a hook to configure a factory without
 * knowing or caring what specific instance performs the work.
 */
public interface JsonPullParserFactory {

    /**
     * Create a parser to read {@code char}s.
     *
     * @param reader a stream of UTF-16 characters to parse
     * @return new parser
     * @throws IOException if source throws an IOException
     */
    JsonPullParser createParser(Reader reader) throws IOException;

    /**
     * Create a parser to process an ASCII or UTF-8 stream.
     *
     * @param input a stream of ASCII or UTF-8 bytes
     * @return new parser
     * @throws IOException if source throws an IOException
     */
    JsonPullParser createUtf8Parser(InputStream input) throws IOException;

    /**
     * Create a parser to process an encoded byte stream.
     *
     * @param input a stream of encoded bytes to parse
     * @param enc   the standard name for the stream's encoding
     * @return new parser
     * @throws IOException if source throws an IOException
     */
    JsonPullParser createParser(InputStream input, Charset enc) throws IOException;

    /**
     * Create a parser to process a stream of Unicode code points.
     *
     * @param source provider of code points
     * @return new parser
     * @throws IOException if source throws an IOException
     */
    JsonPullParser createParser(CodePointSource source) throws IOException;
}

package com.frank_mitchell.codepoint;

import java.io.Closeable;
import java.io.IOException;
import java.util.Iterator;

/**
 * An iterator over an external sequence of Unicode code points.
 * Using {@code int} instead of {@code char} is a bit of 
 * future-proofing for when streams commonly contain characters
 * outside of the Basic Multilingual Plane (0x0000 - 0xFFFF).
 * Implementers can transparently decode UTF-8 or UTF-16 multi-byte
 * characters into a single code point.  (At least until Unicode expands
 * past 32 bits.)
 * 
 * Unlike standard Java {@link Iterator}s, advancing the iterator and
 * reading the next item in the sequence can be two separate actions.
 * That way one can pass the source to other methods and they can read
 * the last code point read without altering state.
 * 
 * @author Frank Mitchell
 */
public interface CodePointSource extends Closeable {

    /**
     * Read the current code point after the last call to {@link #next()}.
     * 
     * @return current code point.
     */
    int getCodePoint();

    /**
     * Whether this source still has code points remaining.
     * This method may read ahead to the next character, which may
     * cause an exception.
     * 
     * @return whether this object has a next code point.
     * 
     * @throws java.io.IOException if read-ahead throws an exception
     */
    boolean hasNext() throws IOException;

    /**
     * Get the next code point.
     * 
     * @throws IOException 
     */
    void next() throws IOException;
   
    /**
     * Close the underlying IO or NIO object.
     * 
     * @throws IOException from the underlying object.
     */
    @Override
    void close() throws IOException;
 }