Package ca.marcusdunn.jsonlens.pointer

@NullMarked package ca.marcusdunn.jsonlens.pointer

RFC 6901 JSON Pointer: JsonPointer and its errors, PointerError.

JsonNode document = JsonMapper.builder().build().readTree("""
        {"foo": ["bar", "baz"], "a/b": 1}""");

// Parse a pointer. A '/' in a name is written as "~1".
JsonPointer pointer = JsonPointer.parse("/a~1b").orElse(JsonPointer.root());

// Resolve it with the model of your JSON library. The result is your own node.
switch (pointer.resolve(document, JacksonJsonModel.INSTANCE)) {
    case Result.Ok<JsonNode, PointerError>(JsonNode value) -> lines.add("value: " + value);
    case Result.Err<JsonNode, PointerError>(PointerError error) -> lines.add(error.message());
}
// value: 1

// An error is a value, not an exception.
Result<JsonNode, PointerError> missing =
        JsonPointer.parse("/foo/2").orElse(JsonPointer.root()).resolve(document, JacksonJsonModel.INSTANCE);
// missing: Err[error=IndexOutOfRange[parent=/foo, token=2]]

// The URI fragment form has percent-encoding.
Maybe<String> fragment = JsonPointer.of(List.of("c%d")).toFragment(); // Some[value=#/c%25d]

Class	Description
JsonPointer	A JSON Pointer (RFC 6901): a sequence of reference tokens that identifies a value in a JSON document.
PointerError	An error of a JSON Pointer (RFC 6901, Section 7): invalid syntax, or a pointer that does not reference a value.
PointerError.DuplicateName	An object has more than one member with the name of a token.
PointerError.IndexOutOfRange	An array index is not less than the length of the array.
PointerError.InvalidEscape	A ~ is not followed by 0 or 1 (RFC 6901, Section 3).
PointerError.InvalidFragment	A URI fragment identifier is not a valid JSON Pointer (RFC 6901, Section 6): it does not start with #, it has a character that a fragment does not permit, a percent-encoding is not complete, or the bytes are not UTF-8.
PointerError.InvalidIndex	A token for an array is not an array index: digits without a leading zero (RFC 6901, Section 4).
PointerError.MemberNotFound	An object has no member with the name of a token.
PointerError.MissingSlash	A pointer that is not empty does not start with / (RFC 6901, Section 3).
PointerError.NotAContainer	A token follows a value that is not an object or an array.