fieldpath

package
v1.62.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 12, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

Documentation

Overview

Package fieldpath parses a field path into typed segments.

It exists because the same dialect was implemented three times, in three modules, with three different accepted grammars and no test comparing them:

oasgen-provider       dot notation only -- and its doc comment claimed bracket support it refused
rest-dynamic-controller  dots, quoted keys, array indices and [?key=value] predicates
unstructured-runtime  strings.Split(path, ".") -- silently mis-splits a quoted key containing a dot

This package is the superset (rest-dynamic-controller's grammar), with one correction: a segment's KIND is decided by HOW IT WAS WRITTEN, never by its content.

Why kind-by-syntax rather than kind-by-content

The previous implementation returned []string and the walker re-derived intent from each segment's text. That made two pairs of distinct paths indistinguishable:

a[0]  and a['0']    -> both "0"        a list index and a map key
a[?k=v] and a['?k=v'] -> both "?k=v"   a selector and a literal key

Reading, the data disambiguated the first pair -- a value is a map or a list, never both -- so it was never a live defect for that walker. The second pair is worse: quoting is what a user reaches for to escape a special meaning, and an escape that does not escape is worse than no escape at all. And neither pair can be recovered by a WRITER (create a map or a list?), a VALIDATOR, or a diagnostic: `a['0']` against a list reports "array requires a non-negative integer index", which does not mention that the author asked for a key.

Deciding kind at parse time, from syntax, removes the content sniffing entirely.

Limits of the grammar

There is no escape sequence. Inside a bracket group every quote character TOGGLES quoting until its match, which has these consequences, each pinned by a test:

  • a quoted key may contain the other quote character freely, and its own quote character only in balanced pairs: ["it's "x""] is the key it's "x". A key with a ' and an ODD number of " (or the reverse) cannot be written; String renders it, and the rendering is refused by Parse.
  • a predicate value may contain quote characters only in balanced pairs, and they are KEPT in the value: a[?name=say "hi"] selects name == say "hi". An unbalanced one, as in a[?name=O'Brien], leaves the bracket unterminated and the path is refused. A ']' cannot appear in a predicate value.

Refused paths are refused with an error, never mis-parsed into something else.

Whitespace

A bare name may not contain whitespace: a. b and "b " are refused, not read as the keys " b" and "b ". A key with whitespace is written quoted, a['my key']; a predicate value may contain it, a[?name=John Smith]. rest-dynamic-controller's parser refused every space anywhere, which also refused those two legitimate forms.

The parser/walker boundary

This package decides only what a path MEANS, never whether it applies to a document. A predicate against a non-list, a predicate matching no element, and a predicate matching more than one are all WALKER errors: the path was well-formed and the document did not satisfy it. Keeping that boundary is what stops content sniffing being reintroduced -- a parser that knew about documents would need it.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Get added in v1.33.0

func Get(obj any, segs []Segment) (any, bool, error)

The walker

Get is the WALKER beside this package's parser. Ported from oasgen-provider (feat/fieldpath-walker-for-plumbing, a2a8176), where it was staged beside rest-dynamic-controller's GetNestedField and checked against it by a differential test that stays there.

Why the walker belongs with the parser

The parser decides what a path MEANS; the walker decides what it SELECTS. For a predicate those are not separable -- the uniqueness rule that makes `[?type=otp]` safe lives in the walker, not the grammar. A grammar shared and a selection rule copied is not a shared dialect; it is the divergence with an extra step.

The concrete case: oasgen-provider's #510 collector resolves a Secret name out of a CR, and rest-dynamic-controller's resolver later reads that Secret. If the two disagree about which element a predicate selects, the provider grants a Role for one Secret and the controller reads another -- #510's original failure mode, one level down.

On []Segment rather than []string

rest-dynamic-controller's GetNestedField takes the flat form, so it re-derives intent from each segment's text: "0" might be an index or a map key, and it resolves them only because the DATA disambiguates. That is the content sniffing fieldpath's parser was built to remove, surviving one layer down.

Taking []Segment lets the walker dispatch on Kind. Two consequences, one of them a deliberate correction:

KindIndex on a map    an error. The author wrote an index; a map has none.
KindKey on a slice     an error. a['0'] against an array is refused -- a CORRECTION, see the table.

Get reads the value at segs from obj, which may nest through both map[string]interface{} and []interface{}.

It keeps unstructured.NestedFieldNoCopy's three-way contract, which every caller of the function this replaces already depends on:

found=false, err=nil   the path does not resolve against this data. ABSENT.
err != nil             the path cannot APPLY to this data -- a kind mismatch, or a predicate that
                       matched more than one element. An instrument failure, not a fact about the
                       document, and callers must not collapse it into "absent".

That distinction is the whole reason this signature is worth preserving: a caller that treats an error as absence turns "I could not read the field" into "the field is not there", which is how oasgen-provider #517 produced a controller that reported a resource missing while holding it.

ON ERROR, found IS ALWAYS false. So test err BEFORE found, or test !found && err == nil for absence. In the obvious order, `if !found { skip }` followed by `if err != nil { ... }`, the error arm is unreachable: every error has already been taken as absence. A mutant that disables the error arm then survives, as oasgen-provider's #510 collector found.

func Keys

func Keys(segs []Segment) []string

Keys returns the flat form every pre-existing caller used: each segment's text, with an index rendered as its decimal digits and a predicate as "?key=value". It is lossy by design -- a[0] and a['0'] produce the same slice -- and exists so callers that genuinely only need the text are unchanged.

Types

type Kind

type Kind int

Kind is how a segment was written, which is what decides its meaning.

const (
	// KindKey is a map key: a bare name (a.b), or a quoted bracket group (a['b.c'], a["b.c"]).
	KindKey Kind = iota
	// KindIndex is a list index: an UNQUOTED bracket group of canonical digits (a[0]).
	KindIndex
	// KindPredicate selects the single list element whose Key field equals Value (a[?name=admin]).
	KindPredicate
)

func (Kind) String

func (k Kind) String() string

type Segment

type Segment struct {
	Kind  Kind
	Key   string // a map key, or a predicate's field name
	Index int    // KindIndex only
	Value string // KindPredicate only; may be empty, which is accepted
}

Segment is one step of a path.

func Parse

func Parse(path string) ([]Segment, error)

Parse splits path into typed segments.

Leading dots are stripped. This is a FIX, not compatibility: rest-dynamic-controller's parser kept the dot, so ".id" named a property literally called ".id" and silently resolved to nothing. Paths of that form exist because two documented dialects disagreed (one wrote ".id" for "id"); stripping gives them the meaning their authors intended. Do not tighten this to an error without a migration.

func (Segment) String

func (s Segment) String() string

String renders the segment in a form Parse accepts, so a parsed path round-trips. A key that needs quoting is quoted with ' unless it contains one, then with ". See "Limits" for the keys no quoting can write.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL