Documentation
¶
Overview ¶
Package jpath implements JSONPath parsing, compilation, and execution
Queries compile to composed function chains The same compiled path can execute against different JSON documents
Index ¶
- Variables
- func MustQuery(query string, document any) []any
- func Query(query string, document any) ([]any, error)
- type BinaryExpr
- type Compiler
- type Evaluator
- type FilterCtx
- type FilterExpr
- type FilterFunc
- func And(left, right FilterFunc) FilterFunc
- func Call(evaluator Evaluator, args ...FilterFunc) FilterFunc
- func Eq(left, right FilterFunc) FilterFunc
- func Ge(left, right FilterFunc) FilterFunc
- func Gt(left, right FilterFunc) FilterFunc
- func Le(left, right FilterFunc) FilterFunc
- func Literal(value any) FilterFunc
- func Lt(left, right FilterFunc) FilterFunc
- func Ne(left, right FilterFunc) FilterFunc
- func Not(expr FilterFunc) FilterFunc
- func Or(left, right FilterFunc) FilterFunc
- func PathCurrent(path Path) FilterFunc
- func PathRoot(path Path) FilterFunc
- type FuncExpr
- type Function
- type FunctionDefinition
- type FunctionUse
- type LiteralExpr
- type Parser
- type Path
- type PathExpr
- type PathValueExpr
- type Registry
- func (r *Registry) Clone() *Registry
- func (r *Registry) Compile(path *PathExpr) (Path, error)
- func (r *Registry) MustCompile(path *PathExpr) Path
- func (r *Registry) MustParse(query string) *PathExpr
- func (r *Registry) MustQuery(query string, document any) []any
- func (r *Registry) MustRegisterDefinition(name string, def *FunctionDefinition) *Registry
- func (r *Registry) MustRegisterFunction(name string, arity int, fn Function) *Registry
- func (r *Registry) Parse(query string) (*PathExpr, error)
- func (r *Registry) Query(query string, document any) ([]any, error)
- func (r *Registry) RegisterDefinition(name string, def *FunctionDefinition) error
- func (r *Registry) RegisterFunction(name string, arity int, fn Function) error
- type SegmentExpr
- type SegmentFunc
- type SelectorExpr
- type SelectorFunc
- func MakeSelectorArrayAll(_ *SlicePlan) SelectorFunc
- func MakeSelectorB00(plan *SlicePlan) SelectorFunc
- func MakeSelectorB01N(plan *SlicePlan) SelectorFunc
- func MakeSelectorB01P(plan *SlicePlan) SelectorFunc
- func MakeSelectorB10N(plan *SlicePlan) SelectorFunc
- func MakeSelectorB10P(plan *SlicePlan) SelectorFunc
- func MakeSelectorB11NN(plan *SlicePlan) SelectorFunc
- func MakeSelectorB11NP(plan *SlicePlan) SelectorFunc
- func MakeSelectorB11PN(plan *SlicePlan) SelectorFunc
- func MakeSelectorB11PP(plan *SlicePlan) SelectorFunc
- func MakeSelectorF00(plan *SlicePlan) SelectorFunc
- func MakeSelectorF01N(plan *SlicePlan) SelectorFunc
- func MakeSelectorF01P(plan *SlicePlan) SelectorFunc
- func MakeSelectorF10N(plan *SlicePlan) SelectorFunc
- func MakeSelectorF10P(plan *SlicePlan) SelectorFunc
- func MakeSelectorF11NN(plan *SlicePlan) SelectorFunc
- func MakeSelectorF11NP(plan *SlicePlan) SelectorFunc
- func MakeSelectorF11PN(plan *SlicePlan) SelectorFunc
- func MakeSelectorF11PP(plan *SlicePlan) SelectorFunc
- func SelectFilter(filter FilterFunc) SelectorFunc
- func SelectIndex(index int) SelectorFunc
- func SelectName(name string) SelectorFunc
- func SelectSlice(s *SliceExpr) SelectorFunc
- func SelectWildcard() SelectorFunc
- type SelectorKind
- type SliceExpr
- type SlicePlan
- type UnaryExpr
- type Validator
- type Value
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidPath is raised when a JSONPath query cannot be parsed ErrInvalidPath = errors.New("invalid JSONPath query") // ErrExpectedRoot indicates the query does not start with `$` ErrExpectedRoot = errors.New("expected root selector '$'") // ErrUnexpectedToken indicates invalid token ordering or placement ErrUnexpectedToken = errors.New("unexpected token") // ErrUnterminatedString indicates a quoted string was not closed ErrUnterminatedString = errors.New("unterminated string") // ErrBadEscape indicates an invalid escape sequence in a string literal ErrBadEscape = errors.New("invalid escape sequence") // ErrBadNumber indicates an invalid numeric literal ErrBadNumber = errors.New("invalid number") // ErrBadSlice indicates an invalid array slice selector ErrBadSlice = errors.New("invalid slice selector") // ErrBadFunc indicates an invalid function invocation in a filter ErrBadFunc = errors.New("invalid function call") )
var ( // ErrUnknownFunc indicates a function name is not registered ErrUnknownFunc = errors.New("unknown function") // ErrBadFuncName indicates a function name is invalid ErrBadFuncName = errors.New("invalid function name") // ErrBadFuncDefinition indicates a function definition is invalid ErrBadFuncDefinition = errors.New("invalid function definition") // ErrFuncExists indicates a function was already registered ErrFuncExists = errors.New("function already registered") )
var ( // ErrLiteralMustBeCompared is raised for bare literals in logical context ErrLiteralMustBeCompared = errors.New("literal must be compared") // ErrCompRequiresSingularQuery is raised for non-singular comparisons ErrCompRequiresSingularQuery = errors.New( "comparison requires singular query", ) // ErrInvalidFuncArity is raised when function arity is invalid ErrInvalidFuncArity = errors.New("invalid function arity") // ErrFuncResultMustBeCompared is raised for logical use without compare ErrFuncResultMustBeCompared = errors.New( "function result must be compared", ) // ErrFuncResultMustNotBeCompared is raised for prohibited comparisons ErrFuncResultMustNotBeCompared = errors.New( "function result must not be compared", ) // ErrFuncRequiresSingularQuery is raised for singular-path requirements ErrFuncRequiresSingularQuery = errors.New( "function requires singular query", ) // ErrFuncRequiresQueryArgument is raised for query-arg requirements ErrFuncRequiresQueryArgument = errors.New( "function requires query argument", ) )
Functions ¶
Types ¶
type BinaryExpr ¶
type BinaryExpr struct {
Op string
Left, Right FilterExpr
}
BinaryExpr is a binary filter expression
type Compiler ¶
type Compiler struct {
// contains filtered or unexported fields
}
Compiler compiles parsed JSONPath syntax trees into runnable programs
type Evaluator ¶
Evaluator evaluates wrapped arguments and returns a wrapped result
func WrapFunction ¶
WrapFunction wraps a scalar function as an evaluator
type FilterExpr ¶
type FilterExpr interface {
// contains filtered or unexported methods
}
FilterExpr is the marker interface for filter AST nodes
type FilterFunc ¶
func And ¶
func And(left, right FilterFunc) FilterFunc
And builds a logical-AND filter function with short-circuit behavior
func Call ¶
func Call(evaluator Evaluator, args ...FilterFunc) FilterFunc
Call builds a filter function from a function evaluator and arguments
func Eq ¶
func Eq(left, right FilterFunc) FilterFunc
Eq builds an equality comparison filter function
func Ge ¶
func Ge(left, right FilterFunc) FilterFunc
Ge builds a greater-than-or-equal comparison filter function
func Gt ¶
func Gt(left, right FilterFunc) FilterFunc
Gt builds a greater-than comparison filter function
func Le ¶
func Le(left, right FilterFunc) FilterFunc
Le builds a less-than-or-equal comparison filter function
func Literal ¶
func Literal(value any) FilterFunc
Literal builds a filter function that returns a scalar literal value
func Lt ¶
func Lt(left, right FilterFunc) FilterFunc
Lt builds a less-than comparison filter function
func Ne ¶
func Ne(left, right FilterFunc) FilterFunc
Ne builds an inequality comparison filter function
func Or ¶
func Or(left, right FilterFunc) FilterFunc
Or builds a logical-OR filter function with short-circuit behavior
func PathCurrent ¶
func PathCurrent(path Path) FilterFunc
PathCurrent builds a filter function that queries from the current node
func PathRoot ¶
func PathRoot(path Path) FilterFunc
PathRoot builds a filter function that queries from the root node
type FuncExpr ¶
type FuncExpr struct {
Name string
Args []FilterExpr
}
FuncExpr is a filter function call expression
type FunctionDefinition ¶
FunctionDefinition describes a filter function implementation
type FunctionUse ¶
type FunctionUse uint8
FunctionUse describes where a function appears in filter validation
const ( FunctionUseLogical FunctionUse = iota FunctionUseComparisonOperand FunctionUseArgument )
type LiteralExpr ¶
type LiteralExpr struct {
Value any
}
LiteralExpr is a scalar literal in a filter expression
type Parser ¶
type Parser struct {
// contains filtered or unexported fields
}
Parser parses JSONPath query strings into an inspectable syntax tree
type Path ¶
Path is a compiled query function chain. Calling it executes the query against a JSON document
func ComposePath ¶
func ComposePath(segments ...SegmentFunc) Path
ComposePath composes segment functions into an executable Path
func MustCompile ¶
MustCompile compiles a parsed PathExpr or panics
type PathExpr ¶
type PathExpr struct {
Segments []*SegmentExpr
}
PathExpr is a parsed JSONPath expression
type PathValueExpr ¶
PathValueExpr is a root or current-node relative path in a filter
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry stores function definitions and owns parse/compile/query methods
func NewRegistry ¶
func NewRegistry() *Registry
NewRegistry creates a registry with default JSONPath functions
func (*Registry) MustCompile ¶
MustCompile compiles a parsed syntax tree or panics
func (*Registry) MustRegisterDefinition ¶
func (r *Registry) MustRegisterDefinition( name string, def *FunctionDefinition, ) *Registry
MustRegisterDefinition registers a function definition or panics
func (*Registry) MustRegisterFunction ¶
MustRegisterFunction registers a scalar function or panics
func (*Registry) RegisterDefinition ¶
func (r *Registry) RegisterDefinition( name string, def *FunctionDefinition, ) error
RegisterDefinition registers a named function definition in this registry
type SegmentExpr ¶
type SegmentExpr struct {
Descendant bool
Selectors []*SelectorExpr
}
SegmentExpr is one child or descendant traversal segment
type SegmentFunc ¶
SegmentFunc processes input nodes and returns output nodes for one segment step
func ChildSegment ¶
func ChildSegment(selectors ...SelectorFunc) SegmentFunc
ChildSegment builds a non-descendant segment from selector functions
func DescendantSegment ¶
func DescendantSegment(selectors ...SelectorFunc) SegmentFunc
DescendantSegment builds a descendant segment from selector functions
type SelectorExpr ¶
type SelectorExpr struct {
Kind SelectorKind
Name string
Index int
Slice *SliceExpr
Filter FilterExpr
}
SelectorExpr is one bracket or dot selector operation
type SelectorFunc ¶
SelectorFunc appends selected output nodes for one input node
func MakeSelectorArrayAll ¶
func MakeSelectorArrayAll(_ *SlicePlan) SelectorFunc
MakeSelectorArrayAll builds a selector for selectorCaseArrayAll
func MakeSelectorB00 ¶
func MakeSelectorB00(plan *SlicePlan) SelectorFunc
MakeSelectorB00 builds a selector for selectorCaseB00
func MakeSelectorB01N ¶
func MakeSelectorB01N(plan *SlicePlan) SelectorFunc
MakeSelectorB01N builds a selector for selectorCaseB01N
func MakeSelectorB01P ¶
func MakeSelectorB01P(plan *SlicePlan) SelectorFunc
MakeSelectorB01P builds a selector for selectorCaseB01P
func MakeSelectorB10N ¶
func MakeSelectorB10N(plan *SlicePlan) SelectorFunc
MakeSelectorB10N builds a selector for selectorCaseB10N
func MakeSelectorB10P ¶
func MakeSelectorB10P(plan *SlicePlan) SelectorFunc
MakeSelectorB10P builds a selector for selectorCaseB10P
func MakeSelectorB11NN ¶
func MakeSelectorB11NN(plan *SlicePlan) SelectorFunc
MakeSelectorB11NN builds a selector for selectorCaseB11NN
func MakeSelectorB11NP ¶
func MakeSelectorB11NP(plan *SlicePlan) SelectorFunc
MakeSelectorB11NP builds a selector for selectorCaseB11NP
func MakeSelectorB11PN ¶
func MakeSelectorB11PN(plan *SlicePlan) SelectorFunc
MakeSelectorB11PN builds a selector for selectorCaseB11PN
func MakeSelectorB11PP ¶
func MakeSelectorB11PP(plan *SlicePlan) SelectorFunc
MakeSelectorB11PP builds a selector for selectorCaseB11PP
func MakeSelectorF00 ¶
func MakeSelectorF00(plan *SlicePlan) SelectorFunc
MakeSelectorF00 builds a selector for selectorCaseF00
func MakeSelectorF01N ¶
func MakeSelectorF01N(plan *SlicePlan) SelectorFunc
MakeSelectorF01N builds a selector for selectorCaseF01N
func MakeSelectorF01P ¶
func MakeSelectorF01P(plan *SlicePlan) SelectorFunc
MakeSelectorF01P builds a selector for selectorCaseF01P
func MakeSelectorF10N ¶
func MakeSelectorF10N(plan *SlicePlan) SelectorFunc
MakeSelectorF10N builds a selector for selectorCaseF10N
func MakeSelectorF10P ¶
func MakeSelectorF10P(plan *SlicePlan) SelectorFunc
MakeSelectorF10P builds a selector for selectorCaseF10P
func MakeSelectorF11NN ¶
func MakeSelectorF11NN(plan *SlicePlan) SelectorFunc
MakeSelectorF11NN builds a selector for selectorCaseF11NN
func MakeSelectorF11NP ¶
func MakeSelectorF11NP(plan *SlicePlan) SelectorFunc
MakeSelectorF11NP builds a selector for selectorCaseF11NP
func MakeSelectorF11PN ¶
func MakeSelectorF11PN(plan *SlicePlan) SelectorFunc
MakeSelectorF11PN builds a selector for selectorCaseF11PN
func MakeSelectorF11PP ¶
func MakeSelectorF11PP(plan *SlicePlan) SelectorFunc
MakeSelectorF11PP builds a selector for selectorCaseF11PP
func SelectFilter ¶
func SelectFilter(filter FilterFunc) SelectorFunc
SelectFilter builds a selector for filter-based child selection
func SelectIndex ¶
func SelectIndex(index int) SelectorFunc
SelectIndex builds a selector for array element lookup by index
func SelectName ¶
func SelectName(name string) SelectorFunc
SelectName builds a selector for object-member lookup by name
func SelectSlice ¶
func SelectSlice(s *SliceExpr) SelectorFunc
SelectSlice builds a selector for array slice selection
func SelectWildcard ¶
func SelectWildcard() SelectorFunc
SelectWildcard builds a selector for wildcard child selection
type SelectorKind ¶
type SelectorKind uint8
SelectorKind identifies the selector variant in SelectorExpr
const ( SelectorName SelectorKind = iota // object member by name SelectorIndex // array index SelectorWildcard // all direct child values SelectorSlice // array elements by slice bounds SelectorFilter // child values by filter predicate )
type UnaryExpr ¶
type UnaryExpr struct {
Op string
Expr FilterExpr
}
UnaryExpr is a unary filter expression
type Validator ¶
type Validator func(args []FilterExpr, use FunctionUse, inComparison bool) error
Validator validates function arguments for a call site