mach

Documentation

Overview

Package mach implements a small abstract machine for path expressions, based on the representation produced by the sibling package paths.

mach.Compile compiles a parsed paths.Path into a Program for a small abstract machine.

Program.Run runs the program with a JSON structure as input ("the root document", or "$"), yielding the collection of JSON structures selected by the original path expression. Several threads can Run the same Program simultaneously, since each Run gets its own abstract machine state.

The semantics and built-in functions are generally those of https://danielaparker.github.io/JsonCons.Net/articles/JsonPath/Specification.html — a rare example of specifying JSONpath systematically instead of providing a few examples — although the grammar above is more restrictive (eg, as regards the content of a union expression). Some of Parker's extensions (eg, the parent operator) are also not provided.

Index

• Constants
• Variables
• func IsArray(j JSON) bool
• func IsObject(j JSON) bool
• func IsStructure(j JSON) bool
• type Function
• type JSON
• type Program
  • func Compile(path paths.Path) (*Program, error)
  • func (p *Program) Run(root JSON) ([]JSON, error)
  • func (prog *Program) String() string

Constants

const (
	Undefined jsType = iota
	Null
	Number
	String
	Boolean
	Object
)

const AnyNumber = -1

AnyNumber as Function.na means any number of args.

Variables

var (
	ErrNoKey     = errors.New("no such key")
	ErrBadIndex  = errors.New("invalid array index")
	ErrNotArray  = errors.New("not an array")
	ErrNotObject = errors.New("not an object")
	ErrFailure   = errors.New("failed")
	ErrType      = errors.New("operand or parameter has wrong type")
	ErrOverflow  = errors.New("arithmetic overflow")
)

var (
	ErrTooManyVals = errors.New("program has too many values")
)

Functions

func IsArray

func IsArray(j JSON) bool

IsArray returns true if j is a JSON array or list.

func IsObject

func IsObject(j JSON) bool

IsObject returns true if j is a JSON object (map).

func IsStructure

func IsStructure(j JSON) bool

IsStructure returns true if j is a JSON object or array.

Types

type Function

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

Function represents a predefined function with na args (or AnyNumber) with body fn.

type JSON

type JSON = paths.JSON // temporary, during the renaming

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 Program

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

Program is the compiled form of a Path and associated expressions. It is a program for a simple stack machine, although the details are hidden.

func Compile

func Compile(path paths.Path) (*Program, error)

Compile compiles a Path into a Program for a small abstract machine that evaluates paths and expressions.

func (*Program) Run

func (p *Program) Run(root JSON) ([]JSON, error)

Run applies the current Program to the root of a JSON structure, returning a collection of JSON structures from it (which might be empty) as selected by the original path expression, or a run-time error. Run-time errors include call of an unknown function, an invalid dynamic regular expression (ie, a regular expression as a string variable) and invalid operand types for "~" and "in" ("nin"). Following the usual JavaScript conventions, many other errors do not stop evaluation, but yield a null result, detectable using || and &&.

func (*Program) String

func (prog *Program) String() string

String returns a representation of the text of the abstract machine program.