Documentation
¶
Overview ¶
Package spec provides object definitions and execution for RFC 9535 JSONPath query expressions. It remains under active development therefore should generally not be used directly except for experimental purposes.
Index ¶
- Variables
- type BasicExpr
- type CompOp
- type CompVal
- type ComparisonExpr
- type ExistExpr
- type FilterQueryExpr
- type FilterSelector
- type FuncType
- type FunctionExpr
- type FunctionExprArg
- type Index
- type JSONPathValue
- type LiteralArg
- type LocatedNode
- type LogicalAnd
- type LogicalOr
- type LogicalType
- type Name
- type NodesType
- type NonExistExpr
- type NormalSelector
- type NormalizedPath
- type NotFuncExpr
- type NotParenExpr
- type ParenExpr
- type PathFunction
- type PathQuery
- func (q *PathQuery) Expression() FunctionExprArg
- func (q *PathQuery) Segments() []*Segment
- func (q *PathQuery) Select(current, root any) []any
- func (q *PathQuery) SelectLocated(current, root any, parent NormalizedPath) []*LocatedNode
- func (q *PathQuery) Singular() *SingularQueryExpr
- func (q *PathQuery) String() string
- type PathType
- type Segment
- type Selector
- type SingularQueryExpr
- type SliceSelector
- func (s SliceSelector) Bounds(length int) (int, int)
- func (s SliceSelector) End() int
- func (s SliceSelector) Select(input, _ any) []any
- func (s SliceSelector) SelectLocated(input, _ any, parent NormalizedPath) []*LocatedNode
- func (s SliceSelector) Start() int
- func (s SliceSelector) Step() int
- func (s SliceSelector) String() string
- type ValueType
- type WildcardSelector
Constants ¶
This section is empty.
Variables ¶
var Wildcard = WildcardSelector{}
Wildcard is a wildcard selector, e.g., * or [*].
Functions ¶
This section is empty.
Types ¶
type BasicExpr ¶
type BasicExpr interface {
// contains filtered or unexported methods
}
BasicExpr defines the interface for filter expressions.
type CompVal ¶
type CompVal interface {
// contains filtered or unexported methods
}
CompVal defines the interface for comparable values in filter expressions.
type ComparisonExpr ¶
type ComparisonExpr struct {
// An expression that produces the JSON value for the left side of the
// comparison.
Left CompVal
// The comparison operator.
Op CompOp
// An expression that produces the JSON value for the right side of the
// comparison.
Right CompVal
}
ComparisonExpr represents the comparison of two values, which themselves may be the output of expressions.
func Comparison ¶
func Comparison(left CompVal, op CompOp, right CompVal) *ComparisonExpr
Comparison creates and returns a new ComparisonExpr.
type FilterQueryExpr ¶
type FilterQueryExpr struct {
*PathQuery
}
FilterQueryExpr represents a JSONPath Query used in a filter expression.
func FilterQuery ¶
func FilterQuery(q *PathQuery) *FilterQueryExpr
FilterQuery creates and returns a new FilterQueryExpr.
func (*FilterQueryExpr) ResultType ¶
func (fq *FilterQueryExpr) ResultType() FuncType
ResultType returns FuncSingularQuery if fq is a singular query, and FuncNodeList if it is not. Defined by the FunctionExprArg interface.
type FilterSelector ¶
type FilterSelector struct {
LogicalOr
}
FilterSelector is a filter selector, e.g., ?().
func (*FilterSelector) Eval ¶ added in v0.2.0
func (f *FilterSelector) Eval(node, root any) bool
Eval evaluates the f's logical expression against node and root. Used [Select] as it iterates over nodes, and always passes the root value($) for filter expressions that reference it.
func (*FilterSelector) Select ¶
func (f *FilterSelector) Select(current, root any) []any
Select selects and returns values that f filters from current. Filter expressions may evaluate the current value (@), the root value ($), or any path expression. Defined by the Selector interface.
func (*FilterSelector) SelectLocated ¶ added in v0.3.0
func (f *FilterSelector) SelectLocated(current, root any, parent NormalizedPath) []*LocatedNode
SelectLocated selects and returns LocatedNode structs with values that f filters from current. Filter expressions may evaluate the current value (@), the root value ($), or any path expression. Defined by the Selector interface.
func (*FilterSelector) String ¶
func (f *FilterSelector) String() string
String returns a string representation of f.
type FuncType ¶
type FuncType uint8
FuncType defines the function argument expressions and return types defined by RFC 9535. Function extensions check that these types can be converted to spec.PathType values for evaluation.
const ( // FuncLiteral represents a literal JSON value. FuncLiteral FuncType = iota + 1 // FuncLiteral // FuncSingularQuery represents a value from a singular query. FuncSingularQuery // FuncSingularQuery // FuncValue represents a JSON value, used to represent functions that // return [ValueType]. FuncValue // FuncValue // FuncNodeList represents a node list, either from a filter query argument, or a function that // returns [NodesType]. FuncNodeList // FuncNodeList // FuncLogical represents a logical, either from a logical expression, or // from a function that returns [LogicalType]. FuncLogical // FuncLogical )
func (FuncType) ConvertsTo ¶
ConvertsTo returns true if a function argument of type ft can be converted to pv.
type FunctionExpr ¶
type FunctionExpr struct {
// contains filtered or unexported fields
}
FunctionExpr represents a function expression, consisting of a named function and its arguments.
func Function ¶
func Function(fn PathFunction, args []FunctionExprArg) *FunctionExpr
Function creates an returns a new function expression that will execute fn against the return values of args.
func (*FunctionExpr) ResultType ¶
func (fe *FunctionExpr) ResultType() FuncType
ResultType returns the result type of the registered function named fe.name. Defined by the FunctionExprArg interface.
type FunctionExprArg ¶
type FunctionExprArg interface {
// ResultType returns the FuncType that defines the type of the return
// value of JSONPathValue.
ResultType() FuncType
// contains filtered or unexported methods
}
FunctionExprArg defines the interface for function argument expressions.
type Index ¶
type Index int
Index is an array index selector, e.g., [3].
func (Index) Select ¶
Select selects i from input and returns it as a single value in a slice. Returns an empty slice if input is not a slice or if i it outside the bounds of input. Defined by the Selector interface.
func (Index) SelectLocated ¶ added in v0.3.0
func (i Index) SelectLocated(input, _ any, parent NormalizedPath) []*LocatedNode
SelectLocated selects i from input and returns it with its normalized path as a single LocatedNode in a slice. Returns an empty slice if input is not a slice or if i it outside the bounds of input. Defined by the Selector interface.
type JSONPathValue ¶
type JSONPathValue interface {
// PathType returns the JSONPathValue's PathType.
PathType() PathType
// FuncType returns the JSONPathValue's FuncType.
FuncType() FuncType
// contains filtered or unexported methods
}
JSONPathValue defines the interface for JSON path values.
type LiteralArg ¶
type LiteralArg struct {
// contains filtered or unexported fields
}
LiteralArg represents a literal JSON value, excluding objects and arrays.
func (*LiteralArg) ResultType ¶
func (la *LiteralArg) ResultType() FuncType
ResultType returns FuncLiteral. Defined by the FunctionExprArg interface.
func (*LiteralArg) Value ¶
func (la *LiteralArg) Value() any
Value returns the underlying value of la.
type LocatedNode ¶ added in v0.3.0
type LocatedNode struct {
// Node is the value selected from a JSON query argument.
Node any `json:"node"`
// Path is the normalized path that uniquely identifies the location of
// Node in a JSON query argument.
Path NormalizedPath `json:"path"`
}
LocatedNode pairs a value with its location within the JSON query argument from which it was selected.
type LogicalAnd ¶
type LogicalAnd []BasicExpr
LogicalAnd represents a list of one or more expressions ANDed together by the && operator.
type LogicalOr ¶
type LogicalOr []LogicalAnd
LogicalOr represents a list of one or more expressions ORed together by the || operator.
func (LogicalOr) ResultType ¶
ResultType returns FuncLogical. Defined by the FunctionExprArg interface.
type LogicalType ¶
type LogicalType uint8
LogicalType is a JSONPath type that represents true or false.
const ( LogicalFalse LogicalType = iota // false LogicalTrue // true )
func LogicalFrom ¶
func LogicalFrom(value any) LogicalType
LogicalFrom attempts to convert value to a LogicalType and panics if it cannot.
func (LogicalType) Bool ¶
func (lt LogicalType) Bool() bool
Bool returns the boolean equivalent to lt.
func (LogicalType) FuncType ¶
func (LogicalType) FuncType() FuncType
FuncType returns FuncLogical. Defined by the JSONPathValue interface.
func (LogicalType) PathType ¶
func (LogicalType) PathType() PathType
PathType returns PathLogical. Defined by the JSONPathValue interface.
func (LogicalType) String ¶
func (i LogicalType) String() string
type Name ¶
type Name string
Name is a key name selector, e.g., .name or ["name"].
func (Name) Select ¶
Select selects n from input and returns it as a single value in a slice. Returns an empty slice if input is not a map[string]any or if it does not contain n. Defined by the Selector interface.
func (Name) SelectLocated ¶ added in v0.3.0
func (n Name) SelectLocated(input, _ any, parent NormalizedPath) []*LocatedNode
SelectLocated selects n from input and returns it with its normalized path as a single LocatedNode in a slice. Returns an empty slice if input is not a map[string]any or if it does not contain n. Defined by the Selector interface.
type NodesType ¶
type NodesType []any
NodesType defines the JSONPath type representing a node list; in other words, a list of JSON values.
func NodesFrom ¶
func NodesFrom(value JSONPathValue) NodesType
NodesFrom attempts to convert value to a NodesType and panics if it cannot.
type NonExistExpr ¶
type NonExistExpr struct {
*PathQuery
}
NonExistExpr represents a nonexistence expression.
func Nonexistence ¶
func Nonexistence(q *PathQuery) *NonExistExpr
Nonexistence returns a new NonExistExpr.
type NormalSelector ¶ added in v0.3.0
type NormalSelector interface {
// contains filtered or unexported methods
}
NormalSelector represents a single selector in a normalized path. Implemented by Name and Index.
type NormalizedPath ¶ added in v0.3.0
type NormalizedPath []NormalSelector
NormalizedPath represents a normalized path identifying a single value in a JSON query argument, as defined by RFC 9535.
func (NormalizedPath) Compare ¶ added in v0.3.0
func (np NormalizedPath) Compare(np2 NormalizedPath) int
Compare compares np to np2 and returns -1 if np is less than np2, 1 if it's greater than np2, and 0 if they're equal. Indexes are always considered less than names.
func (NormalizedPath) MarshalText ¶ added in v0.3.0
func (np NormalizedPath) MarshalText() ([]byte, error)
MarshalText marshals np into text. It implements encoding.TextMarshaler.
func (NormalizedPath) Pointer ¶ added in v0.4.0
func (np NormalizedPath) Pointer() string
Pointer returns an RFC 6901 JSON Pointer string representation of np.
func (NormalizedPath) String ¶ added in v0.3.0
func (np NormalizedPath) String() string
String returns the string representation of np.
type NotFuncExpr ¶
type NotFuncExpr struct {
*FunctionExpr
}
NotFuncExpr represents a "!func()" expression. It reverses the result of the return value of a function expression.
func NotFunction ¶
func NotFunction(fn *FunctionExpr) NotFuncExpr
NotFunction creates an returns a new NotFuncExpr that will execute fn against the return values of args and return the inverses of its return value.
type NotParenExpr ¶
type NotParenExpr struct {
LogicalOr
}
NotParenExpr represents a parenthesized expression preceded with a !.
type ParenExpr ¶
type ParenExpr struct {
LogicalOr
}
ParenExpr represents a parenthesized expression.
type PathFunction ¶
type PathFunction interface {
Name() string
ResultType() FuncType
Evaluate(args []JSONPathValue) JSONPathValue
}
PathFunction represents a JSONPath function. See github.com/theory/jsonpath/registry for the implementation.
type PathQuery ¶
type PathQuery struct {
// contains filtered or unexported fields
}
PathQuery represents a JSONPath expression.
func (*PathQuery) Expression ¶
func (q *PathQuery) Expression() FunctionExprArg
Expression returns a singularQuery variant of q if q [isSingular] returns true, and otherwise returns a filterQuery.
func (*PathQuery) Select ¶
Select selects q.segments from current or root and returns the result. Returns just current if q has no segments. Defined by the Selector interface.
func (*PathQuery) SelectLocated ¶ added in v0.3.0
func (q *PathQuery) SelectLocated(current, root any, parent NormalizedPath) []*LocatedNode
SelectLocated selects q.segments from current or root and returns the resulting values as LocatedNode structs. Returns just current if q has no segments. Defined by the Selector interface.
func (*PathQuery) Singular ¶
func (q *PathQuery) Singular() *SingularQueryExpr
Singular returns a singularQuery variant of q if q [isSingular] returns true.
type Segment ¶
type Segment struct {
// contains filtered or unexported fields
}
Segment represents a single segment in an RFC 9535 JSONPath query, consisting of a list of Selectors and child Segments.
func Child ¶
Child creates and returns a Segment that uses one or more Selectors to select the children of a JSON value.
func Descendant ¶
Descendant creates and returns a Segment that uses one or more Selectors to select the children of a JSON value, together with the children of its children, and so forth recursively.
func (*Segment) IsDescendant ¶ added in v0.2.0
IsDescendant returns true if the segment is a descendant selector that recursively select the children of a JSON value.
func (*Segment) Select ¶
Select selects and returns values from current or root for each of seg's selectors. Defined by the Selector interface.
func (*Segment) SelectLocated ¶ added in v0.3.0
func (s *Segment) SelectLocated(current, root any, parent NormalizedPath) []*LocatedNode
SelectLocated selects and returns values as LocatedNode structs from current or root for each of seg's selectors. Defined by the Selector interface.
type Selector ¶
type Selector interface {
fmt.Stringer
// Select selects values from current and/or root and returns them.
Select(current, root any) []any
// SelectLocated selects values from current and/or root and returns them
// in [LocatedNode] structs with their located normalized paths
SelectLocated(current, root any, parent NormalizedPath) []*LocatedNode
// contains filtered or unexported methods
}
Selector represents a single Selector in an RFC 9535 JSONPath query.
type SingularQueryExpr ¶
type SingularQueryExpr struct {
// contains filtered or unexported fields
}
SingularQueryExpr represents a query that produces a single node (JSON value), or nothing.
func SingularQuery ¶
func SingularQuery(root bool, selectors []Selector) *SingularQueryExpr
SingularQuery creates and returns a SingularQueryExpr.
func (*SingularQueryExpr) ResultType ¶
func (*SingularQueryExpr) ResultType() FuncType
ResultType returns FuncSingularQuery. Defined by the FunctionExprArg interface.
type SliceSelector ¶
type SliceSelector struct {
// contains filtered or unexported fields
}
SliceSelector is a slice selector, e.g., [0:100:5].
func Slice ¶
func Slice(args ...any) SliceSelector
Slice creates a new SliceSelector. Pass up to three integers or nils for the start, end, and step arguments. Subsequent arguments are ignored.
func (SliceSelector) Bounds ¶ added in v0.2.0
func (s SliceSelector) Bounds(length int) (int, int)
Bounds returns the lower and upper bounds for selecting from a slice of length.
func (SliceSelector) Select ¶
func (s SliceSelector) Select(input, _ any) []any
Select selects and returns the values from input for the indexes specified by s. Returns an empty slice if input is not a slice. Indexes outside the bounds of input will not be included in the return value. Defined by the Selector interface.
func (SliceSelector) SelectLocated ¶ added in v0.3.0
func (s SliceSelector) SelectLocated(input, _ any, parent NormalizedPath) []*LocatedNode
SelectLocated selects values from input for the indexes specified by s and returns thm with their normalized paths as LocatedNode structs. Returns an empty slice if input is not a slice. Indexes outside the bounds of input will not be included in the return value. Defined by the Selector interface.
func (SliceSelector) String ¶
func (s SliceSelector) String() string
String returns a quoted string representation of s.
type ValueType ¶
type ValueType struct {
// contains filtered or unexported fields
}
ValueType encapsulates a JSON value, which should be a string, integer, float, nil, true, false, []any, or map[string]any. A nil ValueType pointer indicates no value.
func ValueFrom ¶
func ValueFrom(value JSONPathValue) *ValueType
ValueFrom attempts to convert value to a ValueType and panics if it cannot.
type WildcardSelector ¶ added in v0.2.0
type WildcardSelector struct{}
WildcardSelector is the underlying nil value used by Wildcard.
func (WildcardSelector) Select ¶ added in v0.2.0
func (WildcardSelector) Select(input, _ any) []any
Select selects the values from input and returns them in a slice. Returns an empty slice if input is not []any map[string]any. Defined by the Selector interface.
func (WildcardSelector) SelectLocated ¶ added in v0.3.0
func (WildcardSelector) SelectLocated(input, _ any, parent NormalizedPath) []*LocatedNode
SelectLocated selects the values from input and returns them with their normalized paths in a slice of LocatedNode structs. Returns an empty slice if input is not []any map[string]any. Defined by the Selector interface.
func (WildcardSelector) String ¶ added in v0.2.0
func (WildcardSelector) String() string
String returns "*".
Source Files