moshi/com.squareup.moshi/JsonValueReader

JsonValueReader

This class reads a JSON document by traversing a Java object comprising maps, lists, and JSON primitives. It does depth-first traversal keeping a stack starting with the root object. During traversal a stack tracks the current position in the document:

The next element to act upon is on the top of the stack.
When the top of the stack is a List , calling beginArray replaces the list with a JsonIterator . The first element of the iterator is pushed on top of the iterator.
Similarly, when the top of the stack is a Map , calling beginObject replaces the map with an JsonIterator of its entries. The first element of the iterator is pushed on top of the iterator.
When the top of the stack is a Map.Entry , calling nextName returns the entry's key and replaces the entry with its value on the stack.
When an element is consumed it is popped. If the new top of the stack has a non-exhausted iterator, the next element of that iterator is pushed.
If the top of the stack is an exhausted iterator, calling endArray or will pop it.

class JsonValueReader : JsonReader

Constructors

JsonValueReader

open fun JsonValueReader(root: Any)

JsonValueReader

Copy-constructor makes a deep copy for peeking.

open fun JsonValueReader(copyFrom: JsonValueReader)

Types

JsonIterator

class JsonIterator : Iterator<Any> , Cloneable

Functions

beginArray

Consumes the next token from the JSON stream and asserts that it is the beginning of a new array.

open fun beginArray()

beginObject

Consumes the next token from the JSON stream and asserts that it is the beginning of a new object.

open fun beginObject()

open fun close()

abstract fun close()

endArray

Consumes the next token from the JSON stream and asserts that it is the end of the current array.

open fun endArray()

endObject

Consumes the next token from the JSON stream and asserts that it is the end of the current object.

open fun endObject()

failOnUnknown

Returns true if this parser forbids skipping names and values.

@CheckReturnValue()

fun failOnUnknown(): Boolean

getPath

Returns a JsonPath to the current location in the JSON value.

@CheckReturnValue()

fun getPath(): String

hasNext

Returns true if the current array or object has another element.

open fun hasNext(): Boolean

isLenient

Returns true if this parser is liberal in what it accepts.

@CheckReturnValue()

fun isLenient(): Boolean

nextBoolean

Returns the boolean value of the next token, consuming it.

open fun nextBoolean(): Boolean

nextDouble

Returns the double value of the next token, consuming it. If the next token is a string, this method will attempt to parse it as a double using .

open fun nextDouble(): Double

nextInt

Returns the int value of the next token, consuming it. If the next token is a string, this method will attempt to parse it as an int. If the next token's numeric value cannot be exactly represented by a Java {@code int} , this method throws.

open fun nextInt(): Int

nextLong

Returns the long value of the next token, consuming it. If the next token is a string, this method will attempt to parse it as a long. If the next token's numeric value cannot be exactly represented by a Java {@code long} , this method throws.

open fun nextLong(): Long

nextName

Returns the next token, a property name , and consumes it.

open fun nextName(): String

nextNull

Consumes the next token from the JSON stream and asserts that it is a literal null. Returns null.

@Nullable()

open fun <T> nextNull(): T

nextSource

Returns the next value as a stream of UTF-8 bytes and consumes it.

The following program demonstrates how JSON bytes are returned from an enclosing stream as their original bytes, including their original whitespace:

{@code * String json = "{\"a\": [4, 5 ,6.0, {\"x\":7}, 8], \"b\": 9}"; * JsonReader reader = JsonReader.of(new Buffer().writeUtf8(json)); * reader.beginObject(); * assertThat(reader.nextName()).isEqualTo("a"); * try (BufferedSource bufferedSource = reader.valueSource()) { * assertThat(bufferedSource.readUtf8()).isEqualTo("[4, 5 ,6.0, {\"x\":7}, 8]"); * } * assertThat(reader.nextName()).isEqualTo("b"); * assertThat(reader.nextInt()).isEqualTo(9); * reader.endObject(); * }

This reads an entire value: composite objects like arrays and objects are returned in their entirety. The stream starts with the first character of the value (typically {@code [} , { , or {@code "} ) and ends with the last character of the object (typically {@code ]} , } , or {@code "} ).

The returned source may not be used after any other method on this {@code JsonReader} is called. For example, the following code crashes with an exception:

{@code * JsonReader reader = ... * reader.beginArray(); * BufferedSource source = reader.valueSource(); * reader.endArray(); * source.readUtf8(); // Crash! * }

The returned bytes are not validated. This method assumes the stream is well-formed JSON and only attempts to find the value's boundary in the byte stream. It is the caller's responsibility to check that the returned byte stream is a valid JSON value.

Closing the returned source does not close this reader.

open fun nextSource(): BufferedSource

nextString

Returns the string value of the next token, consuming it. If the next token is a number, this method will return its string form.

open fun nextString(): String

Returns a new instance that reads UTF-8 encoded JSON from {@code source} .

@CheckReturnValue()

open fun of(source: BufferedSource): JsonReader

peek

Returns the type of the next token without consuming it.

open fun peek(): JsonReader.Token

peekJson

Returns a new {@code JsonReader} that can read data from this {@code JsonReader} without consuming it. The returned reader becomes invalid once this one is next read or closed.

For example, we can use {@code peekJson()} to lookahead and read the same data multiple times.

{@code * Buffer buffer = new Buffer(); * buffer.writeUtf8("[123, 456, 789]") * * JsonReader jsonReader = JsonReader.of(buffer); * jsonReader.beginArray(); * jsonReader.nextInt(); // Returns 123, reader contains 456, 789 and ]. * * JsonReader peek = reader.peekJson(); * peek.nextInt() // Returns 456. * peek.nextInt() // Returns 789. * peek.endArray() * * jsonReader.nextInt() // Returns 456, reader contains 789 and ]. * }

open fun peekJson(): JsonReader

promoteNameToValue

Changes the reader to treat the next name as a string value. This is useful for map adapters so that arbitrary type adapters can use nextString to read a name value.

In this example, calling this method allows two sequential calls to nextString :

{@code * JsonReader reader = JsonReader.of(new Buffer().writeUtf8("{\"a\":\"b\"}")); * reader.beginObject(); * reader.promoteNameToValue(); * assertEquals("a", reader.nextString()); * assertEquals("b", reader.nextString()); * reader.endObject(); * }

open fun promoteNameToValue()

pushScope

fun pushScope(newTop: Int)

readJsonValue

Returns the value of the next token, consuming it. The result may be a string, number, boolean, null, map, or list, according to the JSON structure.

@Nullable()

fun readJsonValue(): Any

selectName

If the next token is a property name that's in {@code options} , this consumes it and returns its index. Otherwise this returns -1 and no name is consumed.

open fun selectName(options: JsonReader.Options): Int

selectString

If the next token is a string that's in {@code options} , this consumes it and returns its index. Otherwise this returns -1 and no string is consumed.

open fun selectString(options: JsonReader.Options): Int

setFailOnUnknown

Configure whether this parser throws a JsonDataException when skipValue is called. By default this parser permits values to be skipped.

Forbid skipping to prevent unrecognized values from being silently ignored. This option is useful in development and debugging because it means a typo like "locatiom" will be detected early. It's potentially harmful in production because it complicates revising a JSON schema.

fun setFailOnUnknown(failOnUnknown: Boolean)

setLenient

Configure this parser to be liberal in what it accepts. By default this parser is strict and only accepts JSON as specified by RFC 7159. Setting the parser to lenient causes it to ignore the following syntax errors:

Streams that include multiple top-level values. With strict parsing, each stream must contain exactly one top-level value.
Numbers may be NaNs or infinities .
End of line comments starting with {@code //} or {@code #} and ending with a newline character.
C-style comments starting with {@code /*} and ending with {@code *}{@code /} . Such comments may not be nested.
Names that are unquoted or {@code 'single quoted'} .
Strings that are unquoted or {@code 'single quoted'} .
Array elements separated by {@code ;} instead of {@code ,} .
Unnecessary array separators. These are interpreted as if null was the omitted value.
Names and values separated by {@code =} or {@code =>} instead of {@code :} .
Name/value pairs separated by {@code ;} instead of {@code ,} .

fun setLenient(lenient: Boolean)

setTag

Assigns the tag value using the given class key and value.

fun <T> setTag(clazz: Class<T>, value: T)

skipName

Skips the next token, consuming it. This method is intended for use when the JSON token stream contains unrecognized or unhandled names.

This throws a JsonDataException if this parser has been configured to names.

open fun skipName()

skipValue

Skips the next value recursively. If it is an object or array, all nested elements are skipped. This method is intended for use when the JSON token stream contains unrecognized or unhandled values.

This throws a JsonDataException if this parser has been configured to values.

open fun skipValue()

syntaxError

Throws a new IO exception with the given message and a context snippet with this reader's content.

fun syntaxError(message: String): JsonEncodingException

tag

Returns the tag value for the given class key.

@CheckReturnValue()

@Nullable()

fun <T> tag(clazz: Class<T>): T

typeMismatch

fun typeMismatch(value: Any, expected: Any): JsonDataException