expr

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 8, 2018 License: MIT Imports: 8 Imported by: 0

README

Expr Build Status Go Report Card Code Coverage Sparkline

Expr is an engine that can evaluate expressions.

The purpose of the package is to allow users to use expressions inside configuration for more complex logic. It is a perfect candidate for the foundation of a business rule engine. The idea is to let configure things in a dynamic way without recompile of a program:

# Get the special price if
user.Group in ["good_customers", "collaborator"]

# Promote article to the homepage when
len(article.Comments) > 100 and article.Category not in ["misc"]

# Send an alert when
product.Stock < 15

Inspired by

Features

  • Works with any valid Go object (structs, maps, etc)
  • Strict mode with type checks
  • User-friendly error messages
    unclosed "("
    (boo + bar]
    ----------^
    
  • Reasonable set of basic operators
  • Fast (faster otto and goja, see bench)

Install

go get -u github.com/antonmedv/expr

Documentation

License

MIT

Documentation

Overview

Package expr is an engine that can evaluate expressions.

// Evaluate expression on data.
result, err := expr.Eval("expression", data)

// Or precompile expression to ast first.
node, err := expr.Parse("expression")

// And run later.
result, err := expr.Run(node, data)

Passing in Variables

You can pass variables into the expression, which can be of any valid Go type (including structs):

// Maps
data := map[string]interface{}{
	"Foo": ...
	"Bar": ...
}

// Structs
data := Payload{
	Foo: ...
	Bar: ...
}

// Pass object
result, err := expr.Eval("Foo == Bar", data)

Expr uses reflection for accessing and iterating passed data. For example you can pass nested structures without any modification or preparation:

type Cookie struct {
	Key   string
	Value string
}
type User struct {
	UserAgent string
	Cookies   []Cookie
}
type Request struct {
	User *user
}

req := Request{&User{
	Cookies:   []Cookie{{"origin", "www"}},
	UserAgent: "Firefox",
}}

ok, err := expr.Eval(`User.UserAgent matches "Firefox" and User.Cookies[0].Value == "www"`, req)

Passing in Functions

You can also pass functions into the expression:

data := map[string]interface{}{
	"Request": req,
	"Values": func(xs []Cookie) []string {
		vs := make([]string, 0)
		for _, x := range xs {
			vs = append(vs, x.Value)
		}
		return vs
	},
}

ok, err := expr.Eval(`"www" in Values(Request.User.Cookies)`, data)

Parsing and caching

If you planning to execute some expression lots times, it's good to parse it first and only one time:

// Parse expression to AST.
ast, err := expr.Parse(expression)

// Run given AST
ok, err := expr.Run(ast, data)

Strict mode

Expr package support strict parse mode in which some type checks performed during parsing. To parse expression in strict mode, define all of used variables:

expression := `Request.User.UserAgent matches "Firefox"`
node, err := expr.Parse(expression, expr.Define("Request", request{}))

Parse function will check used variables, accessed filed, logical operators and some other type checks.

If you try to use some undeclared variables, or access unknown field, an error will be returned during paring:

expression := `Request.User.Cookies[0].Timestamp`
node, err := expr.Parse(expression, expr.Define("Request", request{}))

// err: Request.User.Cookies[0].Timestamp undefined (type expr_test.cookie has no field Timestamp)

Also it's possible to define all used variables and functions using expr.With and struct:

type payload struct {
	Request *Request
	Values  func(xs []Cookie) []string
}

node, err := expr.Parse(expression, expr.With(payload{}))

Or with map:

data := map[string]interface{}{
	"Request": req,
	"Values": func(xs []Cookie) []string {...},
}

node, err := expr.Parse(expression, expr.With(data))

Printing

Compiled ast can be compiled back to string expression using stringer fmt.Stringer interface:

node, err := expr.Parse(expression)
code := fmt.Sprintf("%v", node)

Number type

Inside Expr engine there is no distinguish between int, uint and float types (as in JavaScript). All numbers inside Expr engine represented as `float64`. You should remember about it if you use any of binary operators (`+`, `-`, `/`, `*`, etc). Otherwise type remain unchanged.

data := map[string]int{
	"Foo": 1,
	"Bar": 2,
}

out, err := expr.Eval(`Foo`, data) // int

out, err := expr.Eval(`Foo + Bar`, data) // float64

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Eval

func Eval(input string, env interface{}) (interface{}, error)

Eval parses and evaluates given input.

Example
Output:

hello world
Example (Error)
Output:

err: unclosed "("
(boo + bar]
----------^
Example (Map)
Output:

hello user
Example (Matches)
Output:

err: error parsing regexp: missing closing ): `a(`
"a" matches "a("
----------------^
Example (Struct)
Output:

42

func Run

func Run(node Node, env interface{}) (out interface{}, err error)

Run evaluates given ast.

Example
Output:

false

Types

type Node

type Node interface {
	Type(table typesTable) (Type, error)
	Eval(env interface{}) (interface{}, error)
}

Node represents items of abstract syntax tree.

Example
Output:

foo.bar

func Parse

func Parse(input string, ops ...OptionFn) (Node, error)

Parse parses input into ast.

Example
Output:

true

type OptionFn

type OptionFn func(p *parser)

OptionFn for configuring parser.

func Define added in v1.0.0

func Define(name string, t interface{}) OptionFn

Define sets variable for type checks during parsing.

Example
Output:

err: unknown name baz

func With added in v1.0.0

func With(i interface{}) OptionFn

With sets variables for type checks during parsing. If struct is passed, all fields will be treated as variables. If map is passed, all items will be treated as variables (key as name, value as type).

Example
Output:

true

type Type added in v1.0.0

type Type = reflect.Type

Type is a reflect.Type alias.

Directories

Path Synopsis
debug module
repl module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL