jsonata

Documentation

Overview

Package jsonata is a query and transformation language for JSON. It's a Go port of the JavaScript library JSONata. Please use the official JSONata site as a language reference.

http://jsonata.org/

Index

• Variables
• func IsUndefined(value []byte) bool
• func MakeError(code string, message string) error
• func RegisterExts(exts map[string]Extension) error
• func RegisterVars(vars map[string]interface{}) error
• func Version() string
• type ArgCountError
  • func (e ArgCountError) Error() string
• type ArgTypeError
  • func (e ArgTypeError) Error() string
• type ErrType
• type EvalError
  • func (e EvalError) Error() string
• type Expr
  • func Compile(expr string) (*Expr, error)
  • func MustCompile(expr string) *Expr
  • func (e *Expr) Eval(data interface{}) (interface{}, error)
  • func (e *Expr) EvalBytes(data []byte) ([]byte, error)
  • func (e *Expr) RegisterExts(exts map[string]Extension) error
  • func (e *Expr) RegisterVars(vars map[string]interface{}) error
  • func (e *Expr) String() string
• type Extension

Examples

• Expr.Eval
• Expr.RegisterExts

Variables

var ErrUndefined = errors.New("no results found")

ErrUndefined is returned by the evaluation methods when a JSONata expression yields no results. Unlike most errors, ErrUndefined does not mean that evaluation failed.

The simplest way to trigger ErrUndefined is to look up a field that is not present in the JSON data. Many JSONata operators and functions also return ErrUndefined when called with undefined inputs.

Functions

func IsUndefined

func IsUndefined(value []byte) bool

See if this is an undefined value

func MakeError

func MakeError(code string, message string) error

func RegisterExts

func RegisterExts(exts map[string]Extension) error

RegisterExts registers custom functions for use in JSONata expressions. It is designed to be called once on program startup (e.g. from an init function).

Custom functions registered at the package level will be available to all Expr objects. To register custom functions with specific Expr objects, use the RegisterExts method.

func RegisterVars

func RegisterVars(vars map[string]interface{}) error

RegisterVars registers custom variables for use in JSONata expressions. It is designed to be called once on program startup (e.g. from an init function).

Custom variables registered at the package level will be available to all Expr objects. To register custom variables with specific Expr objects, use the RegisterVars method.

func Version

func Version() string

Version returns the current version of the JSONata Go implementation

Types

type ArgCountError

type ArgCountError struct {
	Func     string
	Expected int
	Received int
}

ArgCountError is returned by the evaluation methods when an expression contains a function call with the wrong number of arguments.

func (ArgCountError) Error

func (e ArgCountError) Error() string

type ArgTypeError

type ArgTypeError struct {
	Func  string
	Which int
}

ArgTypeError is returned by the evaluation methods when an expression contains a function call with the wrong argument type.

func (ArgTypeError) Error

func (e ArgTypeError) Error() string

type ErrType

type ErrType uint

ErrType indicates the reason for an error.

const (
	ErrNonIntegerLHS ErrType = iota
	ErrNonIntegerRHS
	ErrNonNumberLHS
	ErrNonNumberRHS
	ErrNonComparableLHS
	ErrNonComparableRHS
	ErrTypeMismatch
	ErrNonCallable
	ErrNonCallableApply
	ErrNonCallablePartial
	ErrNumberInf
	ErrNumberNaN
	ErrMaxRangeItems
	ErrIllegalKey
	ErrDuplicateKey
	ErrClone
	ErrIllegalUpdate
	ErrIllegalDelete
	ErrNonSortable
	ErrSortMismatch
)

Types of errors that may be encountered by JSONata.

type EvalError

type EvalError struct {
	Type  ErrType
	Token string
	Value string
}

An EvalError represents an error during evaluation of a JSONata expression.

func (EvalError) Error

func (e EvalError) Error() string

type Expr

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

An Expr represents a JSONata expression.

func Compile

func Compile(expr string) (*Expr, error)

Compile parses a JSONata expression and returns an Expr that can be evaluated against JSON data. If the input is not a valid JSONata expression, Compile returns an error of type jparse.Error.

func MustCompile

func MustCompile(expr string) *Expr

MustCompile is like Compile except it panics if given an invalid expression.

func (*Expr) Eval

func (e *Expr) Eval(data interface{}) (interface{}, error)

Eval executes a JSONata expression against the given data source. The input is typically the result of unmarshaling a JSON string. The output is an object suitable for marshaling into a JSON string. Use EvalBytes to skip the unmarshal/marshal steps and work solely with JSON strings.

Eval can be called multiple times, with different input data if required.

Example

package main

import (
	"encoding/json"
	"fmt"
	"log"

	jsonata "github.com/blues/jsonata-golang/v154"
)

const jsonString = `
    {
        "orders": [
            {"price": 10, "quantity": 3},
            {"price": 0.5, "quantity": 10},
            {"price": 100, "quantity": 1}
        ]
    }
`

func main() {

	var data interface{}

	// Decode JSON.
	err := json.Unmarshal([]byte(jsonString), &data)
	if err != nil {
		log.Fatal(err)
	}

	// Create expression.
	e := jsonata.MustCompile("$sum(orders.(price*quantity))")

	// Evaluate.
	res, err := e.Eval(data)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(res)
}

Output:

135

func (*Expr) EvalBytes

func (e *Expr) EvalBytes(data []byte) ([]byte, error)

EvalBytes is like Eval but it accepts and returns byte slices instead of objects.

func (*Expr) RegisterExts

func (e *Expr) RegisterExts(exts map[string]Extension) error

RegisterExts registers custom functions for use during evaluation. Custom functions registered with this method are only available to this Expr object. To make custom functions available to all Expr objects, use the package level RegisterExts function.

Example

package main

import (
	"fmt"
	"log"

	"golang.org/x/text/cases"
	"golang.org/x/text/language"

	jsonata "github.com/blues/jsonata-golang/v154"
)

//
// This example demonstrates how to extend JSONata with
// custom functions.
//

// exts defines a function named "titlecase" which maps to
// the golang.org/x/text/cases Title function. Any function,
// from the standard library or otherwise, can be used to
// extend JSONata, as long as it returns either one or two
// arguments (the second argument must be an error).
var exts = map[string]jsonata.Extension{
	"titlecase": {
		Func: func(s string) string {
			return cases.Title(language.English).String(s)
		},
	},
}

func main() {

	// Create an expression that uses the titlecase function.
	e := jsonata.MustCompile(`$titlecase("beneath the underdog")`)

	// Register the titlecase function.
	err := e.RegisterExts(exts)
	if err != nil {
		log.Fatal(err)
	}

	// Evaluate.
	res, err := e.Eval(nil)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(res)
}

Output:

Beneath The Underdog

func (*Expr) RegisterVars

func (e *Expr) RegisterVars(vars map[string]interface{}) error

RegisterVars registers custom variables for use during evaluation. Custom variables registered with this method are only available to this Expr object. To make custom variables available to all Expr objects, use the package level RegisterVars function.

func (*Expr) String

func (e *Expr) String() string

String returns a string representation of an Expr.

type Extension

type Extension struct {

	// Func is a Go function that implements the custom
	// functionality and returns either one or two values.
	// The second return value, if provided, must be an
	// error.
	Func interface{}

	// UndefinedHandler is a function that determines how
	// this extension handles undefined arguments. If
	// UndefinedHandler is non-nil, it is called before
	// Func with the same arguments. If the handler returns
	// true, Func is not called and undefined is returned
	// instead.
	UndefinedHandler jtypes.ArgHandler

	// EvalContextHandler is a function that determines how
	// this extension handles missing arguments. If
	// EvalContextHandler is non-nil, it is called before
	// Func with the same arguments. If the handler returns
	// true, the evaluation context is inserted as the first
	// argument when Func is called.
	EvalContextHandler jtypes.ArgHandler
}

An Extension describes custom functionality added to a JSONata expression.