Documentation
¶
Overview ¶
Package jsonpath/paths provides a parser for JSONpaths, a syntax for expressing queries and locations in a JSON structure.
The JSONpath syntax is often defined by providing a set of sample paths. Following https://github.com/dchester/jsonpath/, this package instead is based on a grammar, Briefly, a JSONpath gives a dot-separated path through a JSON structure, with nested expressions providing dynamic values and filters. For the detailed syntax, run
go doc jsonpath/syntax
ParsePath returns a Path that represents the JSONpath provided as text. That result Path, and the Steps and Expr trees it contains, can then be evaluated against a subject JSON structure ("document").
ParseScriptExpression parses a string that contains only a script expression (not a path) and returns the Expr tree. It is not normally needed, because ParsePath will parse any script expressions in a path string, but might be useful for calculating using values in a JSON structure.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrUnclosedString = errors.New("unclosed string literal") ErrBadEscape = errors.New("unknown character escape sequence") ErrShortEscape = errors.New("unicode escape needs 4 hex digits") ErrIntOverflow = errors.New("overflow of negative integer literal") ErrBadReal = errors.New("invalid floating-point literal syntax") ErrCtrlChar = errors.New("must use escape to encode ctrl character") )
var (
ErrUnclosedRE = errors.New("unclosed regular expression literal")
)
Functions ¶
This section is empty.
Types ¶
type Expr ¶
type Expr interface {
// Opcode gives the node's operator, which determines the detailed structure.
// Useful to avoid .(type) for simple routing.
Opcode() Op
// IsLeaf is Opcode().IsLeaf() for convenience. If !IsLeaf(), it's an Inner operator.
IsLeaf() bool
String() string
}
Expr represents an arbitrary expression tree; it can be converted to one of the ...Leaf types or Inner, depending on Opcode, or using a type switch on an Expr value. Note that Expr satisfies Val, and can appear directly as a value or argument in a Path. Since it is not a constant value, it is not a Valuer.
func ParseScriptExpression ¶
ParseScriptExpression gives direct access to the secondary parser for expressions, returning an Expr tree representing the expression in s.
type Inner ¶
Inner represents an interior operation with one or more operands.
type JSON ¶
type JSON = interface{}
JSON is a synonym for the interface{} structures returned by encoding/json, used as values in the JSON machine, to make it clear that's what they are.
type Loc ¶
type Loc struct {
// contains filtered or unexported fields
}
Loc is a location (line and byte offset)
type NameLeaf ¶
NameLeaf represents a user-defined name (OpID), "@" (OpCurrent) and "$" (OpRoot) in an Expr tree.
type NameVal ¶
type NameVal string
NameVal represents a key or JSON member name as a value, satisfying Val.
type Op ¶
type Op int
const ( OpError Op = iota // illegal token, deliberately the same as the zero value OpInt // integer OpBool // true, false OpID // identifier OpReal // real number (might be used in expressions) OpString // single- or double-quoted string OpRE // /re/ OpNull // JS "null" OpBounds // [lb: ub: stride] // path operators OpMember // . used for path selection (single int, key or expr) OpSelect // [] for path selection (single int, string, expr or filter OpUnion // [union-element, union-element ...] OpWild // * OpFilter // ?(...) OpExp // (...) // path iteration operators OpFor // start of OpFilter sequence, selecting on output candidates OpNest // start of OpNest* sequence, selecting on dot OpRep // repeat sequence if values left // path nest operators OpNestMember // .. member OpNestSelect // .. [subscript] OpNestUnion // .. [key1, key2, ...] OpNestWild // .. [*] OpNestFilter // .. [?(expr)] // expression operators, in both filters and "expression engines" OpRoot // $ (use root as operand) OpCurrent // @ (use current candidate as operand) OpDot // . field selection (in an expression) OpIndex // [] indexing an array OpSlice // [lb: ub: stride] slice operator on array value OpLT // < OpLE // <= OpEQ // = or == OpNE // != OpGE // >= OpGT // > OpAnd // && OpOr // || OpMul // * OpDiv // / OpMod // % OpNeg // unary - OpAdd // + OpSub // binary - OpCall // function call id(args) OpArray // [e-list] OpIn // "in" OpNin // "nin", not in OpMatch // =~ (why not just ~) OpNot // unary ! )
type Path ¶
type Path []*Step
Path is a sequence of Steps, starting from "$" (the document root), following the grammar. The initial "$" has no explicit representation in the Path: it's the starting point.
type RegexpLeaf ¶
type RegexpLeaf struct {
Op
Pattern string // Pattern is the text of the expression.
Prog *regexp.Regexp // Prog is the compiled version of the same.
}
RegexpLeaf represents the text of a regular expression in an Expr tree.
func (*RegexpLeaf) String ¶
func (l *RegexpLeaf) String() string
type Slice ¶
type Slice struct {
Start Val // optional starting offset
End Val // optional end offset (exclusive)
Stride Val // optional value selecting every n array elements.
}
Slice represents a JavaScript slice with [start: end: stride], where any of them might be optional (nil). *Slice satisfies Val.
type Step ¶
type Step struct {
Op Op // Op is the action to take at this step. Not all Ops are valid Steps (eg, expression operators).
Args []Val // Zero or more arguments to the operation (eg, integer and string values, an identifier, a Slice or a filter or other Expr).
}
Step represents a single step in the path: an operation with zero or more parameters, each represented by a Val, which is either a constant (signed integer, string, or member name) or an Expr to be evaluated.
type StringLeaf ¶
StringLeaf represents the value of a single- or double-quoted string in an Expr tree.
func (*StringLeaf) String ¶
func (l *StringLeaf) String() string
type Val ¶
type Val interface {
String() string // String returns a text representation, mainly for tracing and testing.
}
Val is an int64, float64, string literal, name, bool?, *Slice or Expr as a value (see IntVal etc below), or nil as a missing value. It represents a parameter to a Path Step, or a value compiled into a Program from a leaf of an expression tree. Types that satisfy Val correspond to elements in the JsonPath grammar (ie, a union type in its abstract syntax tree):
Val = Int | String | Name | Slice | Float | Regexp Slice = Lb: Val? Ub: Val? Stride: Val?
Originally, it was also the memory type for the Program machine, but because that also includes JSON trees, it was clearer just to use the JSON type (ie, interface{}) directly, hence the addition of Valuer, satisfied by constant values.
Other files in this package add their own Val variants.
type Valuer ¶
type Valuer interface {
Value() JSON // Value returns a suitable internal representation for use by the machine.
}
Valuer instances return an underlying constant value boxed as JSON (which can then be inspected by type switch). Note that the JSON returned by Value either wraps an ordinary Go type (eg, int64, string), or is simply the original value, boxed, allowing it to continue to be distinguished by type switch. See NameVal for an example. Not all Vals are Valuers: for instance, Expr has no underlying constant value.
Source Files