jmespath

README

go-jmespath - A JMESPath implementation in Go

go-jmespath is a GO implementation of JMESPath, which is a query language for JSON. It will take a JSON document and transform it into another JSON document through a JMESPath expression.

Using go-jmespath is really easy. There's a single function you use, jmespath.search:

> import "github.com/jmespath/go-jmespath"
>
> var jsondata = []byte(`{"foo": {"bar": {"baz": [0, 1, 2, 3, 4]}}}`) // your data
> var data interface{}
> err := json.Unmarshal(jsondata, &data)
> result, err := jmespath.Search("foo.bar.baz[2]", data)
result = 2

In the example we gave the search function input data of {"foo": {"bar": {"baz": [0, 1, 2, 3, 4]}}} as well as the JMESPath expression foo.bar.baz[2], and the search function evaluated the expression against the input data to produce the result 2.

The JMESPath language can do a lot more than select an element from a list. Here are a few more examples:

> var jsondata = []byte(`{"foo": {"bar": {"baz": [0, 1, 2, 3, 4]}}}`) // your data
> var data interface{}
> err := json.Unmarshal(jsondata, &data)
> result, err := jmespath.search("foo.bar", data)
result = { "baz": [ 0, 1, 2, 3, 4 ] }


> var jsondata  = []byte(`{"foo": [{"first": "a", "last": "b"},
                           {"first": "c", "last": "d"}]}`) // your data
> var data interface{}
> err := json.Unmarshal(jsondata, &data)
> result, err := jmespath.search({"foo[*].first", data)
result [ 'a', 'c' ]


> var jsondata = []byte(`{"foo": [{"age": 20}, {"age": 25},
                           {"age": 30}, {"age": 35},
                           {"age": 40}]}`) // your data
> var data interface{}
> err := json.Unmarshal(jsondata, &data)
> result, err := jmespath.search("foo[?age > `30`]")
result = [ { age: 35 }, { age: 40 } ]

You can also pre-compile your query. This is usefull if you are going to run multiple searches with it:

	> var jsondata = []byte(`{"foo": "bar"}`)
	> var data interface{}
    > err := json.Unmarshal(jsondata, &data)
	> precompiled, err := Compile("foo")
	> if err != nil{
    >   // ... handle the error
    > }
    > result, err := precompiled.Search(data)
	result = "bar"

More Resources

The example above only show a small amount of what a JMESPath expression can do. If you want to take a tour of the language, the best place to go is the JMESPath Tutorial.

One of the best things about JMESPath is that it is implemented in many different programming languages including python, ruby, php, lua, etc. To see a complete list of libraries, check out the JMESPath libraries page.

And finally, the full JMESPath specification can be found on the JMESPath site.

Documentation

Index

• Constants
• func Search(expression string, data interface{}) (interface{}, error)
• type ASTNode
  • func (node ASTNode) PrettyPrint(indent int) string
  • func (node ASTNode) String() string
• type JMESPath
  • func Compile(expression string) (*JMESPath, error)
  • func MustCompile(expression string) *JMESPath
  • func (jp *JMESPath) Search(data interface{}) (interface{}, error)
• type Lexer
  • func NewLexer() *Lexer
• type Parser
  • func NewParser() *Parser
  • func (p *Parser) Parse(expression string) (ASTNode, error)
• type SyntaxError
  • func (e SyntaxError) Error() string
  • func (e SyntaxError) HighlightLocation() string

Constants

const (
	ASTEmpty astNodeType = iota
	ASTComparator
	ASTCurrentNode
	ASTExpRef
	ASTFunctionExpression
	ASTField
	ASTFilterProjection
	ASTFlatten
	ASTIdentity
	ASTIndex
	ASTIndexExpression
	ASTKeyValPair
	ASTLiteral
	ASTMultiSelectHash
	ASTMultiSelectList
	ASTOrExpression
	ASTAndExpression
	ASTNotExpression
	ASTPipe
	ASTProjection
	ASTSubexpression
	ASTSlice
	ASTValueProjection
)

Functions

func Search

func Search(expression string, data interface{}) (interface{}, error)

Search evaluates a JMESPath expression against input data and returns the result.

Types

type ASTNode

type ASTNode struct {
	// contains filtered or unexported fields
}

ASTNode represents the abstract syntax tree of a JMESPath expression.

func (ASTNode) PrettyPrint

func (node ASTNode) PrettyPrint(indent int) string

PrettyPrint will pretty print the parsed AST. The AST is an implementation detail and this pretty print function is provided as a convenience method to help with debugging. You should not rely on its output as the internal structure of the AST may change at any time.

func (ASTNode) String

func (node ASTNode) String() string

type JMESPath

type JMESPath struct {
	// contains filtered or unexported fields
}

JMESPath is the representation of a compiled JMES path query. A JMESPath is safe for concurrent use by multiple goroutines.

func Compile

func Compile(expression string) (*JMESPath, error)

Compile parses a JMESPath expression and returns, if successful, a JMESPath object that can be used to match against data.

func MustCompile

func MustCompile(expression string) *JMESPath

MustCompile is like Compile but panics if the expression cannot be parsed. It simplifies safe initialization of global variables holding compiled JMESPaths.

func (*JMESPath) Search

func (jp *JMESPath) Search(data interface{}) (interface{}, error)

Search evaluates a JMESPath expression against input data and returns the result.

type Lexer

type Lexer struct {
	// contains filtered or unexported fields
}

Lexer contains information about the expression being tokenized.

func NewLexer

func NewLexer() *Lexer

NewLexer creates a new JMESPath lexer.

type Parser

type Parser struct {
	// contains filtered or unexported fields
}

Parser holds state about the current expression being parsed.

func NewParser

func NewParser() *Parser

NewParser creates a new JMESPath parser.

func (*Parser) Parse

func (p *Parser) Parse(expression string) (ASTNode, error)

Parse will compile a JMESPath expression.

type SyntaxError

type SyntaxError struct {
	Expression string // Expression that generated a SyntaxError
	Offset     int    // The location in the string where the error occurred
	// contains filtered or unexported fields
}

SyntaxError is the main error used whenever a lexing or parsing error occurs.

func (SyntaxError) Error

func (e SyntaxError) Error() string

func (SyntaxError) HighlightLocation

func (e SyntaxError) HighlightLocation() string

HighlightLocation will show where the syntax error occurred. It will place a "^" character on a line below the expression at the point where the syntax error occurred.