jmespath

README

go-jmespath-plus - A JMESPath implementation in Go

See http://jmespath.org for more info.

Enhancements

Recursive Descent Operator

A new .. recursive descent operator is supported. It will recursively traverse all objects and arrays to create a new projection. For example, given:

{
  "foo": {
    "bar": 1,
    "baz": [
      {
        "bar": 2
      },
      {
        "bar": 3
      }
    ]
  }
}

Then you can see the difference between the a wildcard and recursive descent:

# Wildcard key, selects only the first `bar`.
$ jpgo '*.bar' <input
[1]

# Recursive descent, selects *all* the `bar` entries.
$ jpgo '..bar' <input
[1, 2, 3]

Multi-select Hash Shorthand

Selecting a single key from an object is now possible with a property shorthand syntax borrowed from modern Javascript. Given:

{
  "foo": {
    "bar": 1,
    "baz": [true, false]
  }
}

Then you can select via the shorthand:

# Shorthand example.
$ jpgo 'foo.{bar}' <input
{"bar": 1}

# Mixing shorthand and long-form.
$ jpgo 'foo.{bar, first_baz: baz[0]}' <input
{"bar": 1, "first_baz": true}

Group By Function

The group_by function from jq is borrowed to generate a list of grouped objects based on the result of an expression executed on each item in the incoming array. The output is sorted in ascending order.

group_by(array $elements, expression->number|expression->string field)

Given:

{
  "foo": [
    {
      "id": 1,
      "type": "red"
    },
    {
      "id": 2,
      "type": "blue"
    },
    {
      "id": 3,
      "type": "red"
    }
  ]
}

Then you can group the items by their type:

# Group the inputs by the type of item.
$ jpgo 'group_by(foo, &type)' <input

The result:

[
  [
    {
      "id": 2,
      "type": "blue"
    }
  ],
  [
    {
      "id": 1,
      "type": "red"
    },
    {
      "id": 3,
      "type": "red"
    }
  ]
]

Pivot Function

The pivot function is a convenience wrapper around group_by(...) that also pivots the data to return an object where the keys are the grouping value and the values are the groups of objects with the given projection expression applied to each object.

pivot(array $elements, expression->number|expression->string field, expression projection)

Given:

{
  "foo": [
    {
      "id": 1,
      "type": "red"
    },
    {
      "id": 2,
      "type": "blue"
    },
    {
      "id": 3,
      "type": "red"
    }
  ]
}

Then you can pivot the items by their type:

# Pivot items by their type
$ jpgo 'pivot(foo, &type, &id)' <input

The result:

{
  "blue": [2],
  "red": [1, 3]
}

You can also use the identity to keep the full objects:

# Pivot items by their type and keep each original item.
$ jpgo 'pivot(foo, &type, &@)' <input

The result:

{
  "blue": [
    {
      "id": 2,
      "type": "blue"
    }
  ],
  "red": [
    {
      "id": 1,
      "type": "red"
    },
    {
      "id": 3,
      "type": "red"
    }
  ]
}

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
	ASTRecursiveProjection
)

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 epresentation 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.