expr

README

Expr

Expr package provides an engine that can compile and evaluate expressions. An expression is a one-liner that returns a value (mostly, but not limited to, booleans). It is designed for simplicity, speed and safety.

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

Features

• Seamless integration with Go (no need to redefine types)
• Static typing (example).

  out, err := expr.Compile(`name + age`)
  // err: invalid operation + (mismatched types string and int)
  // | name + age
  // | .....^
  

• User-friendly error messages.
• Reasonable set of basic operators.
• Builtins all, none, any, one, filter, map.

  all(Tweets, {.Size <= 280})
  

• Fast (benchmarks): uses bytecode virtual machine and optimizing compiler.

Install

go get github.com/antonmedv/expr

Documentation

• See Getting Started page for developer documentation.
• See Language Definition page to learn the syntax.

Expr Code Editor

Also, I have an embeddable code editor written in JavaScript which allows editing expressions with syntax highlighting and autocomplete based on your types declaration.

Learn more →

Examples

demo.go

package main

import (
	"fmt"
	"time"

	"github.com/antonmedv/expr"
)

var expressions = []string{
	"foo > 0",
	"bar.Value in ['a', 'b', 'c']",
	"name matches '^hello.+$'",
	"now().Sub(startedAt).String()",
	"all(tweets, {len(.Message) <= 280}) ? '👍' : '👎'",
}

var environment = map[string]interface{}{
	"foo":       1,
	"bar":       struct{ Value string }{"c"},
	"name":      "hello world",
	"startedAt": time.Now(),
	"now":       func() time.Time { return time.Now() },
	"tweets":    []tweet{{"first tweet"}},
}

type tweet struct {
	Message string
}

func main() {
	for _, input := range expressions {
		program, err := expr.Compile(input, expr.Env(environment))
		if err != nil {
			panic(err)
		}

		output, err := expr.Run(program, environment)
		if err != nil {
			panic(err)
		}

		fmt.Println(output)
	}
}

Contributing

Expr consist of a few packages for parsing source code to AST, type checking AST, compiling to bytecode and VM for running bytecode program.

Also expr provides powerful tool exe for debugging. It has interactive terminal debugger for our bytecode virtual machine.

Who is using Expr?

• Aviasales are actively using Expr for different parts of the search engine.
• Mystery Minds uses Expr to allow easy yet powerful customization of its matching algorithm.

License

MIT

Documentation

Index

• func Compile(input string, ops ...Option) (*vm.Program, error)
• func Eval(input string, env interface{}) (interface{}, error)
• func Parse(input string, ops ...Option) (*vm.Program, error)
• func Run(program *vm.Program, env interface{}) (interface{}, error)
• type Option
  • func AllowUndefinedVariables() Option
  • func AsBool() Option
  • func AsFloat64() Option
  • func AsInt64() Option
  • func Env(i interface{}) Option
  • func Operator(operator string, fn ...string) Option
  • func Optimize(b bool) Option

Examples

• AsBool
• AsFloat64
• AsInt64
• Compile
• Env
• Env (Allow_undefined_variables)
• Env (With_undefined_variables)
• Eval
• Eval (Error)
• Eval (Map)
• Eval (Map_method)
• Eval (Matches)
• Eval (Struct)
• Operator
• Operator (Time)

Functions

func Compile

func Compile(input string, ops ...Option) (*vm.Program, error)

Compile parses and compiles given input expression to bytecode program.

Example

package main

import (
	"fmt"

	"github.com/antonmedv/expr"
)

func main() {
	env := map[string]interface{}{
		"foo": 1,
		"bar": 99,
	}

	program, err := expr.Compile("foo in 1..99 and bar in 1..99", expr.Env(env))
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	output, err := expr.Run(program, env)
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	fmt.Printf("%v", output)

}

Output:

true

func Eval

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

Eval parses, compiles and runs given input.

Example

package main

import (
	"fmt"

	"github.com/antonmedv/expr"
)

func main() {
	output, err := expr.Eval("'hello world'", nil)
	if err != nil {
		fmt.Printf("err: %v", err)
		return
	}

	fmt.Printf("%v", output)

}

Output:

hello world

Example (Error)

package main

import (
	"fmt"

	"github.com/antonmedv/expr"
)

func main() {
	output, err := expr.Eval("(boo + bar]", nil)
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	fmt.Printf("%v", output)

}

Output:

syntax error: mismatched input ']' expecting ')' (1:11)
 | (boo + bar]
 | ..........^

Example (Map)

package main

import (
	"fmt"
	"strings"

	"github.com/antonmedv/expr"
)

func main() {
	env := map[string]interface{}{
		"foo": 1,
		"bar": []string{"zero", "hello world"},
		"swipe": func(in string) string {
			return strings.Replace(in, "world", "user", 1)
		},
	}

	output, err := expr.Eval("swipe(bar[foo])", env)
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	fmt.Printf("%v", output)

}

Output:

hello user

Example (Map_method)

package main

import (
	"fmt"
	"strings"

	"github.com/antonmedv/expr"
)

func main() {
	env := mockMapEnv{
		"foo": 1,
		"bar": []string{"zero", "hello world"},
	}

	program, err := expr.Compile("Swipe(bar[foo])", expr.Env(env))
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	output, err := expr.Run(program, env)
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	fmt.Printf("%v", output)

}

type mockMapEnv map[string]interface{}

func (mockMapEnv) Swipe(in string) string {
	return strings.Replace(in, "world", "user", 1)
}

Output:

hello user

Example (Matches)

package main

import (
	"fmt"

	"github.com/antonmedv/expr"
)

func main() {
	output, err := expr.Eval(`"a" matches "a("`, nil)
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	fmt.Printf("%v", output)

}

Output:

error parsing regexp: missing closing ): `a(` (1:13)
 | "a" matches "a("
 | ............^

Example (Struct)

package main

import (
	"fmt"

	"github.com/antonmedv/expr"
)

func main() {
	type C struct{ C int }
	type B struct{ B *C }
	type A struct{ A B }

	env := A{B{&C{42}}}

	output, err := expr.Eval("A.B.C", env)

	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	fmt.Printf("%v", output)

}

Output:

42

func Parse

func Parse(input string, ops ...Option) (*vm.Program, error)

Parse parses input string to a program.

Deprecated: use expr.Compile instead.

func Run

func Run(program *vm.Program, env interface{}) (interface{}, error)

Run evaluates given bytecode program.

Types

type Option

type Option func(c *conf.Config)

Option for configuring config.

func AllowUndefinedVariables

func AllowUndefinedVariables() Option

AllowUndefinedVariables allows to use undefined variables inside expressions. This can be used with expr.Env option to partially define a few variables. Note what this option is only works in map environment are used, otherwise runtime.fetch will panic as there is no way to get missing field zero value.

func AsBool

func AsBool() Option

AsBool tells the compiler to expect boolean result.

Example

package main

import (
	"fmt"

	"github.com/antonmedv/expr"
)

func main() {
	env := map[string]int{
		"foo": 0,
	}

	program, err := expr.Compile("foo >= 0", expr.Env(env), expr.AsBool())
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	output, err := expr.Run(program, env)
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	fmt.Printf("%v", output.(bool))

}

Output:

true

func AsFloat64

func AsFloat64() Option

AsFloat64 tells the compiler to expect float64 result.

Example

package main

import (
	"fmt"

	"github.com/antonmedv/expr"
)

func main() {
	program, err := expr.Compile("42", expr.AsFloat64())
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	output, err := expr.Run(program, nil)
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	fmt.Printf("%v", output.(float64))

}

Output:

42

func AsInt64

func AsInt64() Option

AsInt64 tells the compiler to expect int64 result.

Example

package main

import (
	"fmt"

	"github.com/antonmedv/expr"
)

func main() {
	env := map[string]float64{
		"foo": 3,
	}

	program, err := expr.Compile("foo + 2", expr.Env(env), expr.AsInt64())
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	output, err := expr.Run(program, env)
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	fmt.Printf("%v", output.(int64))

}

Output:

5

func Env

func Env(i interface{}) Option

Env specifies expected input of env for type checks. If struct is passed, all fields will be treated as variables, as well as all fields of embedded structs and struct itself. If map is passed, all items will be treated as variables. Methods defined on this type will be available as functions.

Example

package main

import (
	"fmt"

	"github.com/antonmedv/expr"
)

func main() {
	type Segment struct {
		Origin string
	}
	type Passengers struct {
		Adults int
	}
	type Request struct {
		Segments   []*Segment
		Passengers *Passengers
		Marker     string
		Meta       map[string]interface{}
	}

	code := `Segments[0].Origin == "MOW" && Passengers.Adults == 2 && Marker == "test" && Meta["accept"]`

	program, err := expr.Compile(code, expr.Env(&Request{}))
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	request := &Request{
		Segments: []*Segment{
			{Origin: "MOW"},
		},
		Passengers: &Passengers{
			Adults: 2,
		},
		Marker: "test",
		Meta:   map[string]interface{}{"accept": true},
	}

	output, err := expr.Run(program, request)
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	fmt.Printf("%v", output)

}

Output:

true

Example (Allow_undefined_variables)

package main

import (
	"fmt"

	"github.com/antonmedv/expr"
)

func main() {
	env := map[string]string{
		"greet": "",
	}

	program, err := expr.Compile(`greet + name`, expr.Env(env), expr.AllowUndefinedVariables())
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	params := map[string]string{
		"greet": "hello, ",
		"name":  "world",
	}

	output, err := expr.Run(program, params)
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	fmt.Printf("%v", output)

}

Output:

hello, world

Example (With_undefined_variables)

package main

import (
	"fmt"

	"github.com/antonmedv/expr"
)

func main() {
	env := map[string]interface{}{
		"foo": 0,
		"bar": 0,
	}

	program, err := expr.Compile(`foo + (bar != nil ? bar : 2)`, expr.Env(env))
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	request := map[string]interface{}{
		"foo": 3,
	}

	output, err := expr.Run(program, request)
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	fmt.Printf("%v", output)

}

Output:

5

func Operator

func Operator(operator string, fn ...string) Option

Operator allows to override binary operator with function.

Example

package main

import (
	"fmt"

	"github.com/antonmedv/expr"
)

func main() {
	type Place struct {
		Code string
	}
	type Segment struct {
		Origin Place
	}
	type Helpers struct {
		PlaceEq func(p Place, s string) bool
	}
	type Request struct {
		Segments []*Segment
		Helpers
	}

	code := `Segments[0].Origin == "MOW" && PlaceEq(Segments[0].Origin, "MOW")`

	program, err := expr.Compile(code, expr.Env(&Request{}), expr.Operator("==", "PlaceEq"))
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	request := &Request{
		Segments: []*Segment{
			{Origin: Place{Code: "MOW"}},
		},
		Helpers: Helpers{PlaceEq: func(p Place, s string) bool {
			return p.Code == s
		}},
	}

	output, err := expr.Run(program, request)
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	fmt.Printf("%v", output)

}

Output:

true

Example (Time)

package main

import (
	"fmt"
	"time"

	"github.com/antonmedv/expr"
)

func main() {
	type Segment struct {
		Date time.Time
	}
	type Request struct {
		Segments []Segment
		Before   func(a, b time.Time) bool
		Date     func(s string) time.Time
	}

	code := `Date("2001-01-01") < Segments[0].Date`

	program, err := expr.Compile(code, expr.Env(&Request{}), expr.Operator("<", "Before"))
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	request := &Request{
		Segments: []Segment{
			{Date: time.Date(2019, 7, 1, 0, 0, 0, 0, time.UTC)},
		},
		Before: func(a, b time.Time) bool {
			return a.Before(b)
		},
		Date: func(s string) time.Time {
			date, err := time.Parse("2006-01-02", s)
			if err != nil {
				panic(err)
			}
			return date
		},
	}

	output, err := expr.Run(program, request)
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	fmt.Printf("%v", output)

}

Output:

true

func Optimize

func Optimize(b bool) Option

Optimize turns optimizations on or off.