README
¶
Expr 
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
- Symfony's The ExpressionLanguage component,
- Rob Pike's talk Lexical Scanning in Go.
Features
- Works with any valid Go object (structs, maps, etc)
- Static and dynamic typing (example)
code := "groups[0].Title + user.Age" p, err := expr.Parse(code, expr.Define("groups", []Group{}), expr.Define("user", User{})) // err: invalid operation: groups[0].Name + user.Age (mismatched types string and int) - 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
- See
for developer documentation, - See The Expression Syntax page to learn the syntax of the Expr expressions.
Examples
Executing arbitrary expressions.
env := map[string]interface{}{
"foo": 1,
"bar": struct{Value int}{1},
}
out, err := expr.Eval("foo + bar.Value", env)
Static type checker with struct as environment.
type env struct {
Foo int
Bar bar
}
type bar struct {
Value int
}
p, err := expr.Parse("Foo + Bar.Value", expr.Env(env{}))
out, err := expr.Run(p, env{1, bar{2}})
Using env's methods as functions inside expressions.
type env struct {
Name string
}
func (e env) Title() string {
return strings.Title(e.Name)
}
p, err := expr.Parse("'Hello ' ~ Title()", expr.Env(env{}))
out, err := expr.Run(p, env{"world"})
Using embedded structs to construct env.
type env struct {
helpers
Name string
}
type helpers struct{}
func (h helpers) Title(s string) string {
return strings.Title(s)
}
p, err := expr.Parse("'Hello ' ~ Title(Name)", expr.Env(env{}))
out, err := expr.Run(p, env{"world"})
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)
All methods of passed struct also available as functions inside expr:
type Env struct {
value int
}
func (e Env) Value() int {
return e.value
}
v, err := expr.Eval(`Value()`, Env{1})
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.Env and struct:
type MyEnv struct {
Embedded
Request *Request
Url string
//...
}
func (e MyEnv) Values(xs []Cookie) []string {
//...
}
node, err := expr.Parse(expression, expr.Env(MyEnv{}))
Or with map:
data := map[string]interface{}{
"Request": req,
"Values": func(xs []Cookie) []string {...},
}
node, err := expr.Parse(expression, expr.Env(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 ¶
Eval parses and evaluates 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("err: %v", err)
return
}
fmt.Printf("%v", output)
}
Output: err: unclosed "(" (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("err: %v", err)
return
}
fmt.Printf("%v", output)
}
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("err: %v", err)
return
}
fmt.Printf("%v", output)
}
Output: err: error parsing regexp: missing closing ): `a(` "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("err: %v", err)
return
}
fmt.Printf("%v", output)
}
Output: 42
func Run ¶
Run evaluates given ast.
Example ¶
package main
import (
"fmt"
"github.com/antonmedv/expr"
)
func main() {
env := map[string]interface{}{
"foo": 1,
"bar": 99,
}
ast, err := expr.Parse("foo + bar not in 99..100")
if err != nil {
fmt.Printf("err: %v", err)
return
}
output, err := expr.Run(ast, env)
if err != nil {
fmt.Printf("err: %v", err)
return
}
fmt.Printf("%v", output)
}
Output: false
Types ¶
type Node ¶
type Node interface {
Type(table typesTable) (reflect.Type, error)
Eval(env interface{}) (interface{}, error)
}
Node represents items of abstract syntax tree.
Example ¶
package main
import (
"fmt"
"github.com/antonmedv/expr"
)
func main() {
node, err := expr.Parse("foo.bar")
if err != nil {
fmt.Printf("err: %v", err)
return
}
fmt.Printf("%v", node)
}
Output: foo.bar
func Parse ¶
Parse parses input into ast.
Example ¶
package main
import (
"fmt"
"github.com/antonmedv/expr"
)
func main() {
env := map[string]interface{}{
"foo": 1,
"bar": 99,
}
ast, err := expr.Parse("foo in 1..99 and bar in 1..99")
if err != nil {
fmt.Printf("err: %v", err)
return
}
output, err := expr.Run(ast, env)
if err != nil {
fmt.Printf("err: %v", err)
return
}
fmt.Printf("%v", output)
}
Output: true
type OptionFn ¶
type OptionFn func(p *parser)
OptionFn for configuring parser.
func Define ¶ added in v1.0.0
Define sets variable for type checks during parsing.
Example ¶
package main
import (
"fmt"
"github.com/antonmedv/expr"
)
func main() {
type Group struct {
Name string
}
type User struct {
Age int
}
_, err := expr.Parse("groups[0].Name + user.Age", expr.Define("groups", []Group{}), expr.Define("user", User{}))
if err != nil {
fmt.Printf("err: %v", err)
return
}
}
Output: err: invalid operation: groups[0].Name + user.Age (mismatched types string and int)
func Env ¶ added in v1.0.7
func Env(i interface{}) OptionFn
Env sets variables for type checks during parsing. 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 (key as name, value as type).
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"]`
ast, err := expr.Parse(code, expr.Env(&Request{}))
if err != nil {
fmt.Printf("err: %v", err)
return
}
r := &Request{
Segments: []*Segment{
{Origin: "MOW"},
},
Passengers: &Passengers{
Adults: 2,
},
Marker: "test",
Meta: map[string]interface{}{"accept": true},
}
output, err := expr.Run(ast, r)
if err != nil {
fmt.Printf("err: %v", err)
return
}
fmt.Printf("%v", output)
}
Output: true
Source Files