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.
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 ¶
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 tolerated and ignored, for compatibility: paths of the form ".id" exist in the wild because two documented dialects disagreed, and rejecting them now would break definitions that work today. Do not tighten this without a migration.