gojsonpath

README

JSONPath

This is a Go implementation of JSONPath introduced in:

https://goessner.net/articles/JsonPath/

as well as JSON path expressions of the form:

/key1/index/*/key2

with the following exceptions:

• If a path component is a it should be a valid identifier or number. If that is not the case, it should be a string literal, that is, quoted.

  For example: $.dash-key is invalid. You must quote it: $."dash-key" or $.'dash-key'.

• Function and method calls must have a possibly empty argument list.

  For example: length(@) and @.length() are valid, but @.length will look for a length key under the current node.

• Decimals cannot start with a period, that is .5 is invalid. Use 0.5 instead. Decimal starting with a period confuses the lexer.

• Regular expressions are not supported yet.

Using JSONPath

First, compile the path:

path, err:= gojsonpath.Parse("$.store.book[*].author")

Then you can use:

results, err:= gojsonpath.Find(doc,path)

or you can capture the full-path for the nodes that match:

result:=make([]any,0)
err := gojsonpath.Search(doc,path,func(elem []gojsonpath.Element) {
  result=append(result,elem[len(elem)-1].Node)
})

You can use the simple path parser to compile '/' separated paths:

path, err := gojsonpath.Parse("/store/book/*/author")

Simple paths must start with '/', and may contain object keys, array indexes, or '*' to match anything, separated by '/'.

Document model

This implementation of JSONPath works with a flexible document model. To use the familiar map[string]any implementation of JSON, use:

var jsonDoc any
json.Unmarshal(jsonBytes,&jsonDoc)
doc := gojsonpath.MapModel{Doc:jsonDoc}

The DocModel interface provides a view of the underlying model, so the JSON document does not have to be a map[string]any. Any hierarchical document model supporting key-value, array, and value nodes can be used.

Documentation

Index

• Variables
• func Find(doc DocModel, path Path) ([]any, error)
• func Join(parts ...string) string
• func MakeKeyString(input string) string
• func ParseAndFind(doc DocModel, path string) ([]any, error)
• func Search(doc DocModel, path Path, capture func(DocPath)) error
• type DocModel
• type DocPath
  • func (path DocPath) Index(index int, value any, valueType NodeType) DocPath
  • func (path DocPath) Key(key string, value any, valueType NodeType) DocPath
  • func (path DocPath) Last() Segment
  • func (path DocPath) Len() int
  • func (path DocPath) Pop() DocPath
  • func (path DocPath) Push(seg Segment) DocPath
• type ErrInvalidExpression
  • func (e ErrInvalidExpression) Error() string
• type ErrSyntax
  • func (e ErrSyntax) Error() string
• type MapModel
  • func (MapModel) Elem(in any, index int) any
  • func (MapModel) Key(in any, key string) (any, bool)
  • func (MapModel) Keys(in any) []string
  • func (MapModel) Len(in any) int
  • func (m MapModel) Root() any
  • func (MapModel) Type(in any) NodeType
  • func (MapModel) Value(in any) any
• type NodeType
• type Path
  • func Append(p ...Path) Path
  • func IndexSelectorPath(index int) Path
  • func KeySelectorPath(key string) Path
  • func Parse(input string) (Path, error)
  • func RecursiveDescent(p Path) Path
• type Segment

Variables

var (
	ErrNoCurrentElement = errors.New("No current element")
	ErrInvalidAST       = errors.New("Invalid AST")
)

var (
	SelectRootPath = Path{
					// contains filtered or unexported fields
	}
	SelectCurrentPath = Path{
						// contains filtered or unexported fields
	}
	WildcardPath = Path{
					// contains filtered or unexported fields
	}
)

Common path definitions

Functions

func Find

func Find(doc DocModel, path Path) ([]any, error)

Finds all document elements addressed by the path

func Join

func Join(parts ...string) string

Joins strings to build a path, escaping them as necessary

func MakeKeyString

func MakeKeyString(input string) string

MakeKeyString quotes or escapes the input string if necessary to be used in a path expression

func ParseAndFind

func ParseAndFind(doc DocModel, path string) ([]any, error)

ParseAndFind parses the path and finds matching nodes in the doc

func Search

func Search(doc DocModel, path Path, capture func(DocPath)) error

Search iterates all document nodes depth-first, and calls `capture` for those document nodes that `path` matches.

Types

type DocModel

type DocModel interface {
	// Return the root node
	Root() any
	// Return the type of the given node
	Type(any) NodeType

	// Works on object and array nodes
	Len(any) int
	// Lookup a key in an object node
	Key(any, string) (any, bool)
	// Keys of an object node
	Keys(any) []string
	// Lookup and item in an array node
	Elem(any, int) any
	// The input is a value node. Return the value of that node
	Value(any) any
}

DocModel represents the underlying hierarchical document model.

type DocPath

type DocPath struct {
	P []Segment
}

DocPath is a list of nodes of the document

func (DocPath) Index

func (path DocPath) Index(index int, value any, valueType NodeType) DocPath

Add an array index-value to the path. The value is of type valueType. Returns the new path

func (DocPath) Key

func (path DocPath) Key(key string, value any, valueType NodeType) DocPath

Add a key-value to the path. The value is of type valueType. Returns the new path

func (DocPath) Last

func (path DocPath) Last() Segment

Last returns the last element in the path

func (DocPath) Len

func (path DocPath) Len() int

func (DocPath) Pop

func (path DocPath) Pop() DocPath

Returns a new path by removing the last element from the path

func (DocPath) Push

func (path DocPath) Push(seg Segment) DocPath

type ErrInvalidExpression

type ErrInvalidExpression string

func (ErrInvalidExpression) Error

func (e ErrInvalidExpression) Error() string

type ErrSyntax

type ErrSyntax string

func (ErrSyntax) Error

func (e ErrSyntax) Error() string

type MapModel

type MapModel struct {
	Doc any
}

map[string]any model

func (MapModel) Elem

func (MapModel) Elem(in any, index int) any

func (MapModel) Key

func (MapModel) Key(in any, key string) (any, bool)

func (MapModel) Keys

func (MapModel) Keys(in any) []string

func (MapModel) Len

func (MapModel) Len(in any) int

func (MapModel) Root

func (m MapModel) Root() any

func (MapModel) Type

func (MapModel) Type(in any) NodeType

func (MapModel) Value

func (MapModel) Value(in any) any

type NodeType

type NodeType int

const (
	ValueNode NodeType = iota
	ObjectNode
	ArrayNode
)

type Path

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

A Path is a compiled JSONPath object.

func Append

func Append(p ...Path) Path

Append paths one after the other

func IndexSelectorPath

func IndexSelectorPath(index int) Path

Returns a path that selects an index

func KeySelectorPath

func KeySelectorPath(key string) Path

Returns a path that selects a key

func Parse

func Parse(input string) (Path, error)

func RecursiveDescent

func RecursiveDescent(p Path) Path

Returns a new path that is a copy of p but recursively descends

type Segment

type Segment struct {
	Node any
	Type NodeType
	// if previous element is an object, name is set
	Name string
	// If previous element is an array, name is set
	Index int
}

A Segment is a node in a document path