expr-lang/expr

To use Expr in your Go project, install it using go get:

go get github.com/expr-lang/expr

You can provide variables to an expression by passing a map[string]any as the environment to both expr.Compile and expr.Run. To enable type safety and allow Expr to infer types, you must pass the environment to expr.Compile using the expr.Env(env) option.

env := map[string]any{
    "foo": 100,
    "bar": 200,
}

// Pass env to Compile via expr.Env for type checking
program, err := expr.Compile(`foo + bar`, expr.Env(env))
if err != nil {
    panic(err)
}

// Pass the actual data to Run
output, err := expr.Run(program, env)
if err != nil {
    panic(err)
}

fmt.Print(output) // 300

To generate documentation as a Markdown string, call the .Markdown() method on the documentation object returned by docgen.CreateDoc(env).

package main

import "github.com/expr-lang/expr/docgen"

func main() {
	// TODO: Replace env with your own types.
	doc := docgen.CreateDoc(env)

	print(doc.Markdown())
}

The $env variable is a map containing all variables passed to the expression. It can be used to check if a variable is defined or to access variables with special names (like those containing spaces).

foo.Name == $env["foo"].Name
$env["var with spaces"]

// Check if a variable is defined
'foo' in $env

Predicates are expressions used in functions like filter, all, any, one, and none.

• Use {} braces to define a predicate block.
• Use # to refer to the current item in a predicate (e.g., {# % 2 == 0}).
• If items are structs/maps, you can omit # and use . (e.g., .Value).
• In nested predicates, use let to capture the outer scope variable.

// Filter even numbers from a range
filter(0..9, {# % 2 == 0})

// Accessing fields in a collection of structs
filter(tweets, len(.Content) > 240)

// Nested predicate using let to capture outer scope
filter(posts, {
    let post = #; 
    any(.Comments, .Author == post.Author)
})

Use the docgen.CreateDoc(env) function to generate documentation for your Expr environment. Pass your environment type (the object used in your Expr expressions) to CreateDoc. The resulting documentation object can then be marshaled into JSON using standard Go encoding packages.

package main

import (
	"encoding/json"
	"fmt"
  
	"github.com/expr-lang/expr/docgen"
)

func main() {
	// TODO: Replace env with your own types.
	doc := docgen.CreateDoc(env)
  
	buf, err := json.MarshalIndent(doc, "", "  ")
	if err != nil {
		panic(err)
	}
	fmt.Println(string(buf))
}

You can traverse the Abstract Syntax Tree (AST) of an expression before compilation using the Visitor interface. To use it, implement the Visit(*ast.Node) method. This method is called for every node in the AST, allowing you to collect information, modify the expression, or generate new ones.

To traverse the tree, use the ast.Walk function, passing a pointer to the root node and your Visitor implementation.

type Visitor struct {
    Identifiers []string
}

func (v *Visitor) Visit(node *ast.Node) {
    if n, ok := (*node).(*ast.IdentifierNode); ok {
        v.Identifiers = append(v.Identifiers, n.Value)
    }
}

tree, err := parser.Parse(`foo + bar`)
if err != nil {
    panic(err)
}

v := &Visitor{}
ast.Walk(&tree.Node, v)

fmt.Println(v.Identifiers) // [foo, bar]

The simplest way to add custom functions to Expr is by including them in the environment map passed to the evaluator. You can map a string name to a Go function.

env := map[string]any{
    "add": func(a, b int) int {
        return a + b
    },
}

Optional Chaining (?.)

Access a field or map item without checking for nil. If the parent is nil, the expression returns nil instead of an error.

Nil Coalescing (??)

Returns the left-hand side if it is not nil; otherwise, returns the right-hand side.

Use the . operator for struct fields or the [] operator for map items. They are equivalent for field access.

For arrays and slices, use []. Negative indices are supported (e.g., -1 for the last element).

user.Name
user["Name"]

array[0]   // first element
array[-1]  // last element