JsonReader<SourceSlice> class abstract interface

A JSON reader which provides pull-based access to individual JSON tokens.

A JSON reader is a low-level API for deconstructing JSON source without creating unnecessary intermediate values. As a low-level API, it is not attempting to provide all possible conveniences, and it does not validate that it is being used correctly. It is possible to call methods in an order which does not correspond to a valid JSON structure. The user is intended to make sure this doesn't happen. (However, the validateJsonReader can be used to add extra validation/ to a reader for testing.)

The JSON reader scans JSON source code from start to end. It provides access to the next token, either an individual value or the start of a JSON object or array. Inside an object or array, it allows iterating through the entries or elements, or skipping to the end. It also allows completely skipping the next JSON value, which recursively skips objects and arrays.

expect methods predict the type of the next value, and throws if that kind of value is not the next found. This consumes the value for non-composite values and prepares for iterating elements or entries for object or arrays. Examples: expectString, expectObject.
try methods checks whether the next value is of the expected kind, and if so, it works like the correspod expect method. If not, the return value represents this failure in some way appropriate to the return type (a null value if the expect method returns a value, a boolean true/false if the expect method is a void method). Examples: tryString, tryInt, tryArray.
check methods checks whether the next value is of the expected type, but does not consume (or parse) it. There are no checkInt or checkDouble methods, only a checkNum, because distinguishing the two will require parsing.

Methods may throw a FormatException. If that happens, the state of the reader is unspecified, and it should not be used again.

The expect functions will throw if the next value is not of the expected kind. Both expect and try functions, and the iteration functions, may throw if the input is not valid JSON. Some errors prevent further progress, others may be ignored. The check functions never throw.

When an array has been entered using expectArray or tryArray, the individual elements should be iterated using hasNext. Example:

var json = JsonReader.fromString(source);
// I know it's a list of strings.
var result = <String>[];
json.expectArray();
while (json.hasNext()) {
  result.add(json.expectString());
}

When hasNext returns true, the reader is in position to read the next value in the array. When hasNext returns false, the reader has exited the array. You can also stop the array iteration at any time by calling endArray. This will ignore any further values in the array and exit it.

When an object has been entered using expectObject or tryObject, it can be iterated using nextKey. Example:

var json = JsonReader.fromString(source);
// I know it's an object with string values
var result = <String, String>{};
json.expectObject();
String key;
while ((key = json.nextKey()) != null) {
  result[key] = json.expectString();
}

When nextKey returns a string, the reader is in position to read the corresponding value in the object. When nextKey returns null, the reader has exited the object. The tryKey method can check the next key against a number of known keys. If the next key is not one of the candidates passed to the method, nothing happens. Then the skipMapEntry method can be used to ignore the following key/value pair. You can also stop the array iteration at any time by calling endObject. This will ignore any further keys or values in the object and exit it.

Correct nesting of arrays or objects is handled by the caller. The reader may not maintain any state except how far it has come in the input. Calling methods out of order will cause unspecified behavior.

The skipAnyValue will skip the next value completely, even if it's an object or array. The expectAnyValueSource will skip the next value completely, but return a representation of the source of that value in a format corresponding to the original source, as determined by the reader implementation.

A reader is not necessarily validating. If the input is not valid JSON, the behavior is unspecified.

Constructors

JsonReader()

Properties

hashCode → int: The hash code for this object.
no setterinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

checkArray() → bool: Whether the next value is an array.
checkBool() → bool: Whether the next value is a boolean.
checkNull() → bool: Whether the next value is null.
checkNum() → bool: Whether the next value is a number.
checkObject() → bool: Whether the next value is an object.
checkString() → bool: Whether the next value is a string.
copy() → JsonReader: Creates a copy of the state of the current reader.
endArray() → void: Skips the remainder of the current object.
endObject() → void: Skips the remainder of the current object.
expectAnyValue(JsonSink sink) → Null: Skips the next value.
expectAnyValueSource() → SourceSlice: Skips the next value.
expectArray() → void: Enters the next value, which must be an array.
expectBool() → bool: Consumes the next value which must be true or false.
expectDouble() → double: The next value, which must be a number.
expectInt() → int: Return the next value which must be an integer.
expectNull() → Null: Consumes the next value which must be null.
expectNum() → num: The next value, which must be a number.
expectObject() → void: Enters the next value, which must be an object.
expectString([List<String>? candidates]) → String: The next value, which must be a string.
expectStringIndex(List<String> candidates) → int: The index of the next value, which must be a string, in candidates.
fail(String message) → FormatException: Creates a FormatException at the current point in the input.
hasNext() → bool: Find the next array element in the current array.
hasNextKey() → bool: Check whether there is a next key, close object if not.
nextKey() → String?: The next key of the current object.
nextKeySource() → SourceSlice?: The source of the nex key of the current object.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
skipAnyValue() → Null: Skips the next value.
skipObjectEntry() → bool: Skips the next map entry, if there is one.
toString() → String: A string representation of this object.
inherited
tryArray() → bool: Enters the next value if it is an array.
tryBool() → bool?: The next value, if it is true or false.
tryDouble() → double?: The next value, if it is a number.
tryInt() → int?: Return the next value if it is an integer.
tryKey(List<String> candidates) → String?: The next object key, if it is in the list of candidates.
tryKeyIndex(List<String> candidates) → int?: The index of the next object key in candidates, if it is there.
tryNull() → bool: Consumes the next value if it is null.
tryNum() → num?: The next value, if it is a number.
tryObject() → bool: Enters the next value if it is an object.
tryString([List<String>? candidates]) → String?: The next value, if it is a string.
tryStringIndex(List<String> candidates) → int?: The index of the next value in candidates, if it is there.

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Methods

fromObject(Object? source) → JsonReader<Object?>: Creates a JSON reader from a JSON-like object structure.
fromString(String source) → JsonReader<StringSlice>: Creates a JSON reader from a string containing JSON source.
fromUtf8(Uint8List source) → JsonReader<Uint8List>: Creates a JSON reader from a UTF-8 encoded JSON source