expr

package module
v0.0.0-...-8d12124 Latest Latest
Warning

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

 Go to latest Published: Oct 10, 2023 License: MIT Imports: 10 Imported by: 1

README

Expr

test Go Report Card GoDoc Fuzzing Status

Expr is a Go-centric expression language designed to deliver dynamic configurations with unparalleled accuracy, safety, and speed.

expr logo 
// Allow only admins and moderators to moderate comments.
user.Group in ["admin", "moderator"] || user.Id == comment.UserId

// Ensure all tweets are less than 240 characters.
all(Tweets,.Size <= 240
)

Features

Expr is a safe, fast, and intuitive expression evaluator optimized for the Go language. Here are its standout features:

Safety and Isolation
  • Memory-Safe: Expr is designed with a focus on safety, ensuring that programs do not access unrelated memory or introduce memory vulnerabilities.
  • Side-Effect-Free: Expressions evaluated in Expr only compute outputs from their inputs, ensuring no side-effects that can change state or produce unintended results.
  • Always Terminating: Expr is designed to prevent infinite loops, ensuring that every program will conclude in a reasonable amount of time.
Go Integration
  • Seamless with Go: Integrate Expr into your Go projects without the need to redefine types.
Static Typing
  • Ensures type correctness and prevents runtime type errors. 
    out, err := expr.Compile(`name + age`)
// err: invalid operation + (mismatched types string and int)
// | name + age
// | .....^
User-Friendly
  • Provides user-friendly error messages to assist with debugging and development.
Flexibility and Utility
  • Rich Operators: Offers a reasonable set of basic operators for a variety of applications.
  • Built-in Functions: Functions like all, none, any, one, filter, and map are provided out-of-the-box.

Install

go get github.com/sqjian/expr

License

MIT

Documentation

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

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/sqjian/expr"
)

func main() {
	env := map[string]any{
		"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 any) (any, error)

Eval parses, compiles and runs given input.

Example 
package main

import (
	"fmt"

	"github.com/sqjian/expr"
)

func main() {
	output, err := expr.Eval("greet + name", map[string]any{
		"greet": "Hello, ",
		"name":  "world!",
	})
	if err != nil {
		fmt.Printf("err: %v", err)
		return
	}

	fmt.Printf("%v", output)

}

Output:

Hello, world!
Example (Runtime_error) 
package main

import (
	"fmt"

	"github.com/sqjian/expr"
)

func main() {
	_, err := expr.Eval(`map(1..3, {1 % (# - 3)})`, nil)
	fmt.Print(err)

}

Output:

runtime error: integer divide by zero (1:14)
 | map(1..3, {1 % (# - 3)})
 | .............^

func Run 

func Run(program *vm.Program, env any) (any, 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.

Example 
package main

import (
	"fmt"

	"github.com/sqjian/expr"
)

func main() {
	code := `name == nil ? "Hello, world!" : sprintf("Hello, %v!", name)`

	env := map[string]any{
		"sprintf": fmt.Sprintf,
	}

	options := []expr.Option{
		expr.Env(env),
		expr.AllowUndefinedVariables(), // Allow to use undefined variables.
	}

	program, err := expr.Compile(code, options...)
	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\n", output)

	env["name"] = "you" // Define variables later on.

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

}

Output:

Hello, world!
Hello, you!
Example (Zero_value) 
package main

import (
	"fmt"

	"github.com/sqjian/expr"
)

func main() {
	code := `name == "" ? foo + bar : foo + name`

	// If environment has different zero values, then undefined variables
	// will have it as default value.
	env := map[string]string{}

	options := []expr.Option{
		expr.Env(env),
		expr.AllowUndefinedVariables(), // Allow to use undefined variables.
	}

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

	env = map[string]string{
		"foo": "Hello, ",
		"bar": "world!",
	}

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

}

Output:

Hello, world!
Example (Zero_value_functions) 
package main

import (
	"fmt"

	"github.com/sqjian/expr"
	"github.com/sqjian/expr/test/mock"
)

func main() {
	code := `words == "" ? Split("foo,bar", ",") : Split(words, ",")`

	// Env is map[string]string type on which methods are defined.
	env := mock.MapStringStringEnv{}

	options := []expr.Option{
		expr.Env(env),
		expr.AllowUndefinedVariables(), // Allow to use undefined variables.
	}

	program, err := expr.Compile(code, options...)
	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:

[foo bar]

func AsAny 

func AsAny() Option

AsAny tells the compiler to expect any result.

func AsBool 

func AsBool() Option

AsBool tells the compiler to expect a boolean result.

Example 
package main

import (
	"fmt"

	"github.com/sqjian/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
Example (Error) 
package main

import (
	"fmt"

	"github.com/sqjian/expr"
)

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

	_, err := expr.Compile("foo + 42", expr.Env(env), expr.AsBool())

	fmt.Printf("%v", err)

}

Output:

expected bool, but got int

func AsFloat64 

func AsFloat64() Option

AsFloat64 tells the compiler to expect a float64 result.

Example 
package main

import (
	"fmt"

	"github.com/sqjian/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
Example (Error) 
package main

import (
	"fmt"

	"github.com/sqjian/expr"
)

func main() {
	_, err := expr.Compile(`!!true`, expr.AsFloat64())

	fmt.Printf("%v", err)

}

Output:

expected float64, but got bool

func AsInt 

func AsInt() Option

AsInt tells the compiler to expect an int result.

Example 
package main

import (
	"fmt"

	"github.com/sqjian/expr"
)

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

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

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

}

Output:

int(42)

func AsInt64 

func AsInt64() Option

AsInt64 tells the compiler to expect an int64 result.

Example 
package main

import (
	"fmt"

	"github.com/sqjian/expr"
)

func main() {
	env := map[string]any{
		"rating": 5.5,
	}

	program, err := expr.Compile("rating", 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 AsKind 

func AsKind(kind reflect.Kind) Option

AsKind tells the compiler to expect kind of the result.

Example 
package main

import (
	"fmt"
	"reflect"

	"github.com/sqjian/expr"
)

func main() {
	program, err := expr.Compile("{a: 1, b: 2}", expr.AsKind(reflect.Map))
	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)

}

Output:

map[a:1 b:2]

func ConstExpr 

func ConstExpr(fn string) Option

ConstExpr defines func expression as constant. If all argument to this function is constants, then it can be replaced by result of this func call on compile step.

Example 
package main

import (
	"fmt"

	"github.com/sqjian/expr"
)

func fib(n int) int {
	if n <= 1 {
		return n
	}
	return fib(n-1) + fib(n-2)
}

func main() {
	code := `[fib(5), fib(3+3), fib(dyn)]`

	env := map[string]any{
		"fib": fib,
		"dyn": 0,
	}

	options := []expr.Option{
		expr.Env(env),
		expr.ConstExpr("fib"), // Mark fib func as constant expression.
	}

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

	// Only fib(5) and fib(6) calculated on Compile, fib(dyn) can be called at runtime.
	env["dyn"] = 7

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

	fmt.Printf("%v\n", output)

}

Output:

[5 8 13]

func DisableAllBuiltins 

func DisableAllBuiltins() Option

DisableAllBuiltins disables all builtins.

func DisableBuiltin 

func DisableBuiltin(name string) Option

DisableBuiltin disables builtin function.

func EnableBuiltin 

func EnableBuiltin(name string) Option

EnableBuiltin enables builtin function.

func Env 

func Env(env any) 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/sqjian/expr"
)

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

	code := `all(Segments, {.Origin == "MOW"}) && Passengers.Adults > 0 && Tags["foo"] startsWith "bar"`

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

	env := Env{
		Meta: Meta{
			Tags: map[string]string{
				"foo": "bar",
			},
		},
		Segments: []*Segment{
			{Origin: "MOW"},
		},
		Passengers: &Passengers{
			Adults: 2,
		},
		Marker: "test",
	}

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

	fmt.Printf("%v", output)

}

Output:

true
Example (Tagged_field_names) 
package main

import (
	"fmt"

	"github.com/sqjian/expr"
)

func main() {
	env := struct {
		FirstWord  string
		Separator  string `expr:"Space"`
		SecondWord string `expr:"second_word"`
	}{
		FirstWord:  "Hello",
		Separator:  " ",
		SecondWord: "World",
	}

	output, err := expr.Eval(`FirstWord + Space + second_word`, env)
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	fmt.Printf("%v", output)

	// Output : Hello World
}

Output:

func Function 

func Function(name string, fn func(params ...any) (any, error), types ...any) Option

Function adds function to list of functions what will be available in expressions.

func Operator 

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

Operator allows to replace a binary operator with a function.

Example 
package main

import (
	"fmt"
	"time"

	"github.com/sqjian/expr"
)

func main() {
	code := `
		Now() > CreatedAt &&
		(Now() - CreatedAt).Hours() > 24
	`

	type Env struct {
		CreatedAt time.Time
		Now       func() time.Time
		Sub       func(a, b time.Time) time.Duration
		After     func(a, b time.Time) bool
	}

	options := []expr.Option{
		expr.Env(Env{}),
		expr.Operator(">", "After"),
		expr.Operator("-", "Sub"),
	}

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

	env := Env{
		CreatedAt: time.Date(2018, 7, 14, 0, 0, 0, 0, time.UTC),
		Now:       func() time.Time { return time.Now() },
		Sub:       func(a, b time.Time) time.Duration { return a.Sub(b) },
		After:     func(a, b time.Time) bool { return a.After(b) },
	}

	output, err := expr.Run(program, env)
	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.

func Patch 

func Patch(visitor ast.Visitor) Option

Patch adds visitor to list of visitors what will be applied before compiling AST to bytecode.

Example 
package main

import (
	"fmt"

	"github.com/sqjian/expr"
	"github.com/sqjian/expr/ast"
)

type patcher struct{}

func (p *patcher) Visit(node *ast.Node) {
	switch n := (*node).(type) {
	case *ast.MemberNode:
		ast.Patch(node, &ast.CallNode{
			Callee:    &ast.IdentifierNode{Value: "get"},
			Arguments: []ast.Node{n.Node, n.Property},
		})
	}
}

func main() {
	/*
		type patcher struct{}

		func (p *patcher) Visit(node *ast.Node) {
			switch n := (*node).(type) {
			case *ast.MemberNode:
				ast.Patch(node, &ast.CallNode{
					Callee:    &ast.IdentifierNode{Value: "get"},
					Arguments: []ast.Node{n.Node, n.Property},
				})
			}
		}
	*/

	program, err := expr.Compile(
		`greet.you.world + "!"`,
		expr.Patch(&patcher{}),
	)
	if err != nil {
		fmt.Printf("%v", err)
		return
	}

	env := map[string]any{
		"greet": "Hello",
		"get": func(a, b string) string {
			return a + ", " + b
		},
	}

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

	// Output : Hello, you, world!
}

Output:

Source Files

View all Source files

Directories

Path Synopsis
lexer
operator
utils
test
coredns
crowdsec
fuzz
gen
mock
playground
real_world
real_world/real_docs
vm
func_types
runtime
runtime/helpers

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.