fieldpath

package
v1.92.0 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: Apache-2.0 Imports: 5 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

View Source
var ErrEmptyPath = errors.New("fieldpath: a write needs at least one segment")

ErrEmptyPath is returned for a write or removal with no segments: it would replace or delete the whole document, which no field mapping means.

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. The differential test against GetNestedField lives in rest-dynamic-controller's own package (go/rest-dynamic-controller/internal/tools/pathparsing/differential_test.go, merged in oasgen-provider#544). Set and Remove (write.go) are its writers, in the same dialect.

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.

func Remove added in v1.92.0

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

Remove deletes the value at segs in obj and returns the root and whether there was one.

The same three-way contract as Get: found=false with a nil error means the path does not resolve against this data, so there was nothing to remove (a no-op); an error means the path cannot APPLY to it (a contradicting Kind, an ambiguous selector, a scalar or null mid-path), and the document is unchanged. Removing an array element shifts the ones after it.

func Set added in v1.92.0

func Set(obj any, segs []Segment, value any) (any, error)

Set writes value at segs in obj and returns the root. obj may be nil, in which case the root is created by the first segment's Kind. On error the document is 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