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
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.
func Keys ¶
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 )
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 ¶
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.