Documentation
¶
Overview ¶
Package jsonptr implements RFC 6901 JSON Pointers over raw JSON bytes and arbitrary Go values.
A Pointer is a slash-separated sequence of reference tokens that identifies a location within a JSON document. The empty pointer "" refers to the root value; "/foo" refers to the value of object member "foo"; "/0" refers to the first element of an array; tokens use "~1" to encode "/" and "~0" to encode "~".
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Find ¶
Find returns the JSON value located at p within data. The returned value preserves the original byte representation (whitespace, number form, member order). Non-existent members, missing indices, and pointers that descend into a scalar all return errors. Caller-supplied options are forwarded to jsontext.NewDecoder.
func FindValue ¶
FindValue navigates to p within in by walking the Go value via reflection and returns both the JSON form at that location and the live Go value. Any json.Options are forwarded to every Marshal / decoder call the implementation makes — both when producing the returned bytes and when decoding through a json.Marshaler boundary.
Descent rules, in order of precedence:
- If the current value implements Walker, JSONPointerStep is called for the next token. Identity is preserved.
- Pointers and interfaces are dereferenced.
- Maps with string-kinded keys are looked up by token.
- Slices and arrays are indexed by integer token.
- Structs are looked up by `json:"name"` tag, falling back to the field name when the tag is absent. Unexported fields are skipped.
- When the current value implements json.Marshaler or jsontext.MarshalerTo, the remaining tokens are resolved by marshaling the value and calling Find on the bytes. Identity is lost across this boundary; the second return value is then a freshly decoded value: map[string]any for objects, []any for arrays, *big.Rat for every JSON number (callers convert to int / float64 themselves), and the natural Go counterpart for strings, booleans, and null.
The first return is the JSON encoding at the location (for the in-Go path, produced by json.Marshal of the live value).
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder constructs a Pointer by appending tokens to an underlying strings.Builder. The zero value is ready to use and produces "" until any token is appended; pass an existing prefix via NewBuilder.
func NewBuilder ¶
NewBuilder returns a Builder seeded with the given prefix (typically a parent Pointer or a free-form path used in error context).
func (*Builder) Raw ¶
Raw appends raw bytes to the builder without escaping or a leading slash. Use sparingly — it bypasses RFC 6901 escaping.
type Pointer ¶
type Pointer string
Pointer is an RFC 6901 JSON Pointer in string form.
The zero value, "", refers to the root of any JSON document. A non-empty Pointer must begin with "/" and is a sequence of "/"-separated reference tokens. Tokens are unescaped per RFC 6901 §4: "~1" -> "/", "~0" -> "~" (decoded in that order).
func (Pointer) Append ¶
Append returns a new Pointer that descends through token. The token is escaped per RFC 6901.
func (Pointer) Head ¶
Head splits p into its first token and the remaining Pointer. ok is false when p is the root pointer.
type Walker ¶
type Walker interface {
FindJSONPtrValue(ptr Pointer, opts ...json.Options) (rest Pointer, value any, err error)
}
Walker lets a type control how FindValue descends into it. The method receives the unconsumed Pointer and returns:
- rest: the tail the implementation did NOT consume — FindValue continues descending from value with rest. Return "" to indicate "I resolved the whole thing".
- value: the Go value reached after consuming the prefix of ptr.
- err: any error.
A type may consume one or several tokens per call. Returning the full input as rest signals "I don't know how to handle this prefix"; an error is the preferred signal.
Walker takes precedence over the json.Marshaler / jsontext.MarshalerTo fallback in FindValue, so types that implement Walker preserve Go identity across descent rather than round-tripping through JSON bytes.
Source Files