yamlpath

README

YAMLPath

An implementation of the JSONPath query language, built for YAML and the gopkg.in/yaml.v3 package.

This package makes it easy to query [*yaml.Node] objects to do complex queries and operations, such as validation, while still preserving source-location information -- which is useful for providing diagnostics.

Quickstart

• 📦 Installation
• 🧾 Features
• 🚂 Example Use
• 📚 Documentation
  • 📄 Grammar
  • 🔗 Extensions
• ⚖️ MIT or APACHE-2

Installation

To install the package, use the following go get command:

go get rodusek.dev/pkg/yamlpath

Features

The following features of JSONPath are supported and thoroughly tested.

• Root and Current node selection ($ and @)
• Child node selection (.<name>)
• Recursive descent (..)
• Array index selection ([<number>])
• Array slice selection ([<start>:<end>:<step>])
• Union selection (<path>,<path>)
• Filter selection ([?(<sub-expression>)])
  • Existence and field filters ([?(@.key)])
  • Comparison filters ==, !=, <, >, <=, >= (e.g. [?(@.key == "value")])
  • Containment filters in, nin, subsetof (e.g. [?(@.entry in $.keys])
  • Regular expression filters (e.g. [?(@.key =~ /pattern/)])
  • Logical expressions &&, || ([?(@.key && @.key2)])
  • Function filters ([?(@.key.function() == "value")])
• Script selection ([<expression>])
  • Field access ([(@.key)])
  • Arithmetic expressions ([(@.key + 1)])
  • String concatenation ([(@.key + "string")])
  • Function calls ([(@.key.function()))

Example Use

This illustrates a simple example using this library to validate configurations, with output diagnostics appearing in GitHub annotation format. This validates some criteria on a book yaml object:

path := yamlpath.MustCompile("$.store.book[?(@.price < 10.00)]")

filepath := ... // Some filepath to the YAML file
file := ...     // some file handle to the YAML file
var node yaml.Node
if err := yaml.NewDecoder(file).Decode(&node); err != nil {
  log.Fatal(err)
}

result, err := path.Eval(data)
if err != nil {
  log.Fatal(err)
}

for _, node := range result {
  if err := validateBook(result); err != nil {
    // This is in GitHub annotation format
    fmt.Println("::error file=%s,line=%d,title=Book validation failed::%v",
      filepath,
      result.Line,
      err,
    )
  }
}

Documentation

Overview

Package yamlpath provides an implementation of the JSONPath specification for YAML, leveraging the go-yaml library.

Index

• Variables
• type Collection
  • func Match(path string, node *yaml.Node) (Collection, error)
  • func MustMatch(path string, node *yaml.Node) Collection
  • func (c Collection) Bools() ([]bool, error)
  • func (c Collection) Decimals() ([]decimal.Decimal, error)
  • func (c Collection) Decoder() *Decoder
  • func (c Collection) Equal(other Collection) bool
  • func (c Collection) Float64s() ([]float64, error)
  • func (c Collection) Ints() ([]int, error)
  • func (c Collection) IsEmpty() bool
  • func (c Collection) IsTruthy() bool
  • func (c Collection) Nodes() []*yaml.Node
  • func (c Collection) Singleton() (*yaml.Node, error)
  • func (c Collection) SingletonBool() (v bool, err error)
  • func (c Collection) SingletonDecimal() (v decimal.Decimal, err error)
  • func (c Collection) SingletonFloat64() (v float64, err error)
  • func (c Collection) SingletonInt() (v int, err error)
  • func (c Collection) SingletonString() (v string, err error)
  • func (c Collection) Strings() ([]string, error)
• type CompileError
• type Decoder
  • func NewDecoder(collection Collection) *Decoder
  • func (d *Decoder) Decode(out any) error
• type KindError
• type NotSingletonError
• type TagError
• type YAMLPath
  • func Compile(path string) (*YAMLPath, error)
  • func MustCompile(str string) *YAMLPath
  • func (yp *YAMLPath) Equal(other *YAMLPath) bool
  • func (yp *YAMLPath) MarshalText() ([]byte, error)
  • func (yp *YAMLPath) Match(node *yaml.Node) (Collection, error)
  • func (yp *YAMLPath) MustMatch(node *yaml.Node) Collection
  • func (yp *YAMLPath) String() string
  • func (yp *YAMLPath) UnmarshalText(text []byte) error

Variables

var (
	// ErrSyntax is returned when an error occurs during parsing.
	ErrSyntax = compile.ErrSyntax

	// ErrCompile is returned when an error occurs during compilation.
	ErrCompile = compile.ErrCompile

	// ErrEval is returned when an error occurs during evaluation.
	ErrEval = errs.ErrEval

	// ErrNotSingleton is returned when a collection is expected to contain
	// only a single node, but contains more or less than one node.
	//
	// More details can be retrieved from these errors by using [errors.As] with
	// [NotSingletonError].
	ErrNotSingleton = errs.ErrNotSingleton

	// ErrBadKind is returned when an error occurs during evaluation due to
	// a bad YAML node kind.
	//
	// More details can be retrieved from these errors by using [errors.As] with
	// [KindError].
	ErrBadKind = errs.ErrBadKind

	// ErrBadTag is returned when an error occurs during evaluation due to
	// a bad YAML node tag.
	//
	// More details can be retrieved from these errors by using [errors.As] with
	// [TagError].
	ErrBadTag = errs.ErrBadTag
)

Types

type Collection

type Collection []*yaml.Node

Collection represents a collection of YAML nodes that can be retrieved from a YAMLPath evaluation result.

func Match

func Match(path string, node *yaml.Node) (Collection, error)

Match evaluates the YAMLPath expression against the given YAML node.

func MustMatch

func MustMatch(path string, node *yaml.Node) Collection

MustMatch evaluates the YAMLPath expression against the given YAML node. It panics if an error occurs.

func (Collection) Bools

func (c Collection) Bools() ([]bool, error)

Bools decodes all nodes in the collection into a slice of booleans. If any of the nodes are unable to be marshaled into a boolean, an error is returned.

func (Collection) Decimals

func (c Collection) Decimals() ([]decimal.Decimal, error)

Decimals decodes all nodes in the collection into a slice of decimals. If any of the nodes are unable to be marshaled into a decimal, an error is returned.

func (Collection) Decoder

func (c Collection) Decoder() *Decoder

Decoder returns a new Decoder that can be used to decode the collection into target objects.

func (Collection) Equal

func (c Collection) Equal(other Collection) bool

Equal compares this collection to another collection for equality.

This does a deep comparison of the YAML nodes, and introspects into whether the semantic values of the nodes are equal (e.g. YAML scalar floats may be in various notations, but represent the same value).

This comparison follows the same behavior as the `==` operator.

func (Collection) Float64s

func (c Collection) Float64s() ([]float64, error)

Float64s decodes all nodes in the collection into a slice of floats. If any of the nodes are unable to be marshaled into a float, an error is returned.

func (Collection) Ints

func (c Collection) Ints() ([]int, error)

Ints decodes all nodes in the collection into a slice of integers. If any of the nodes are unable to be marshaled into an integer, an error is returned.

func (Collection) IsEmpty

func (c Collection) IsEmpty() bool

IsEmpty returns true if the collection is empty.

func (Collection) IsTruthy

func (c Collection) IsTruthy() bool

IsTruthy evaluates whether this collection may be considered as having a truthful representation.

Truthiness of a collection is determined by the following rules:

• An empty collection is considered falsy
• A collection with multiple nodes is considered truthy
• A collection with a single node that is not a boolean is considered truthy
• A collection with a single node that is a boolean is considered truthy if the boolean value is true

func (Collection) Nodes

func (c Collection) Nodes() []*yaml.Node

Nodes converts this Collection into a slice of yaml.Node objects.

func (Collection) Singleton

func (c Collection) Singleton() (*yaml.Node, error)

Singleton evaluates whether the collection contains only a single node, and returns that node if it does. If it does not, an ErrNotSingleton error is raised.

func (Collection) SingletonBool

func (c Collection) SingletonBool() (v bool, err error)

SingletonBool evaluates whether the collection contains only a single node, and returns the boolean value of that node if it does. If it does not, an ErrNotSingleton error is raised.

func (Collection) SingletonDecimal

func (c Collection) SingletonDecimal() (v decimal.Decimal, err error)

SingletonDecimal evaluates whether the collection contains only a single node, and returns the decimal value of that node if it does. If it does not, an ErrNotSingleton error is raised.

func (Collection) SingletonFloat64

func (c Collection) SingletonFloat64() (v float64, err error)

SingletonFloat64 evaluates whether the collection contains only a single node, and returns the float value of that node if it does. If it does not, an ErrNotSingleton error is raised.

func (Collection) SingletonInt

func (c Collection) SingletonInt() (v int, err error)

SingletonInt evaluates whether the collection contains only a single node, and returns the integer value of that node if it does. If it does not, an ErrNotSingleton error is raised.

func (Collection) SingletonString

func (c Collection) SingletonString() (v string, err error)

SingletonString evaluates whether the collection contains only a single node, and returns the string value of that node if it does. If it does not, an ErrNotSingleton error is raised.

func (Collection) Strings

func (c Collection) Strings() ([]string, error)

Strings decodes all nodes in the collection into a slice of strings. If any of the nodes are unable to be marshaled into a string, an error is returned.

type CompileError

type CompileError = compile.CompileError

CompileError represents an error that occurs during compilation.

type Decoder

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

Decoder provides a mechanism for decoding a collection of YAML nodes into target objects.

func NewDecoder

func NewDecoder(collection Collection) *Decoder

NewDecoder creates a new Decoder that can be used to decode a collection of YAML nodes into target objects.

func (*Decoder) Decode

func (d *Decoder) Decode(out any) error

Decode decodes the next YAML node in the collection into the target object, and then advances the decoder to the next node. If the collection is exhausted, this will return an io.EOF error.

If the target object cannot be decoded, the underlying error will be returned, and the decoder will not advance to the next node.

type KindError

type KindError = errs.KindError

KindError is an evaluation error returned when an expression is expecting a specific YAML node kind, but receives a node with a different kind.

This error can be tested for with errors.Is and retrieved for with errors.As. Errors of this type will also satisfy ErrBadKind and ErrEval.

type NotSingletonError

type NotSingletonError = errs.NotSingletonError

NotSingletonError is an evaluation error returned when an expression is expecting a singleton value, but receives a collection with more or less than one node.

This error can be tested for with errors.Is and retrieved for with errors.As. Errors of this type will also satisfy ErrNotSingleton and ErrEval.

type TagError

type TagError = errs.TagError

TagError is an evaluation error returned when an expression is expecting a specific YAML node tag, but receives a node with a different tag.

This error can be tested for with errors.Is and retrieved for with errors.As. Errors of this type will also satisfy ErrBadTag and ErrEval.

type YAMLPath

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

YAMLPath is the representation of a compiled YAMLPath expression.

A YAMLPath is safe for concurrent use by multiple goroutines, except for if custom functions have been provided that are themselves unsuafe for concurrent use.

func Compile

func Compile(path string) (*YAMLPath, error)

Compile parses a YAMLPath expressions and returns, if successful, a YAMLPath object that can be used to match against [yaml.Node]s.

On error, this will return a CompileError that can be used to determine the cause of the error, and the location where the error occurs.

func MustCompile

func MustCompile(str string) *YAMLPath

MustCompile compiles a YAMLPath expression. It panics if an error occurs.

This is a convenience wrapper around Compile.

func (*YAMLPath) Equal

func (yp *YAMLPath) Equal(other *YAMLPath) bool

Equal returns true if the two YAMLPath expressions are equal.

Equality is determined by evaluating whether the two paths are equal. This makes nil YAMLPath equivalent to zero value YAMLPath objects.

func (*YAMLPath) MarshalText

func (yp *YAMLPath) MarshalText() ([]byte, error)

MarshalText marshals the YAMLPath expression to text.

func (*YAMLPath) Match

func (yp *YAMLPath) Match(node *yaml.Node) (Collection, error)

Match evaluates the YAMLPath expression against the given YAML node, returning all matching subnodes found. If an evaluation error occurs during the matching process, it is returned and the collection will be nil.

func (*YAMLPath) MustMatch

func (yp *YAMLPath) MustMatch(node *yaml.Node) Collection

MustMatch evaluates the YAMLPath expression against the given YAML node, returning all matches. It panics if an error occurs.

func (*YAMLPath) String

func (yp *YAMLPath) String() string

String returns the string representation of the YAMLPath.

func (*YAMLPath) UnmarshalText

func (yp *YAMLPath) UnmarshalText(text []byte) error

UnmarshalText unmarshals the YAMLPath expression from text.

This enables YAMLPath to be used as a field in structs that may be unmarshaled in configs like YAML or JSON.