fieldpath

package
v1.31.0 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 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 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