expr

README

Expr

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

The purpose of the package is to allow users to use expressions for fast vector math operations. It is a perfect candidate for the foundation of a time series database and machine learning feature engineering. The idea is to let configure things in a dynamic way without recompile of a program:

# Get a new vector from the addition of cos() and sin() of other variables
cos(X) + 0.33 * sin(Y)

# Get a new norm vector from vector X
(X - nanmin(X)) / (nanmax(X) - nanmin(X))

Features

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

  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.
• Dozens of Numpy-like builtin math functions: abs, acos, acosh, asin, asinh, atan, atanh, cbrt, ceil, cos, cosh, erf, erfc, erfcinv, erfinv, exp, exp2, expm1, floor, gamma, j0, j1, log, log10, log1p, log2, logb, round, roundtoeven, sin, sinh, sqrt, tan, tanh, trunc, y0, y1, maximum, minimum, mod, pow, remainder, nanmin, nanmax, nanmean, nanstd, nansum, nanprod.

  2 * (nanmean(Scores) - minimum(Elevation, Temp))
  

Install

go get github.com/regel/expr

Examples

package main

import (
	"fmt"
	"github.com/regel/expr"
	"github.com/regel/expr/ast"
)

func main() {
	code := `1 + (sum(Features) / 2)`

	program, err := expr.Compile(code)
	if err != nil {
		panic(err)
	}

	env := &ast.Env{
		"Features": []float64{0.5, 1.0, 1.5},
	}
	output, err := expr.Run(program, env)
	if err != nil {
		panic(err)
	}

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

Who is using Expr?

Add your company too

License

MIT

Documentation

Overview

Package expr provides a framework for parsing and evaluating mathematical expressions.

Index

• func Compile(input string) (node *ast.AST, err error)
• func Evaluate(input string, env *ast.Env) (v interface{}, err error)
• func Run(node *ast.AST, env *ast.Env) (v interface{}, err error)
• type EvaluateError
  • func (e *EvaluateError) Error() string

Functions

func Compile

func Compile(input string) (node *ast.AST, err error)

Compile parses and compiles a given input expression. The input expression is parsed into an AST (Abstract Syntax Tree) node, which is then returned along with any errors that occurred during the parsing process.

Parameters:

• input (string): The input expression to be compiled.

Returns:

• node (*ast.AST): The root node of the compiled AST.
• err (error): Any error that occurred during parsing, or nil if no errors occurred.

If a panic occurs during parsing, it is caught and an error is returned with a message describing the cause of the panic. If the panic is not a string or an error, an "unknown panic" error is returned.

Example usage:

node, err := ast.Compile("1 + 2 * 3")

func Evaluate

func Evaluate(input string, env *ast.Env) (v interface{}, err error)

Evaluate parses and evaluates a given input string using the provided environment.

Parameters:

• input (string): the input string to be evaluated.
• env (*ast.Env): the environment to be used for evaluating the input string.

Return values:

• v (interface{}): the result of evaluating the input string.
• err (error): an error, if one occurred during evaluation.

If a panic occurs during evaluation, it is caught and an error is returned with a message describing the cause of the panic.

func Run

func Run(node *ast.AST, env *ast.Env) (v interface{}, err error)

Run executes the given AST in the provided environment.

Parameters:

• node (*ast.AST): the AST to be executed.
• env (*ast.Env): the environment to be used for execution.

Return values:

• v (interface{}): the result of executing the AST.
• err (error): an error, if one occurred during execution.

If a panic occurs during execution, it is caught and an error is returned with a message describing the cause of the panic. If the panic is not a string or an error, an "unknown panic" error is returned.

Example:

package main
import (
  "fmt"
  "github.com/regel/expr/ast"
)
func main() {
  env := ast.NewEnv()
  env.Set("x", 2.0)
  env.Set("y", 3.0)
  input := "x + y"
  node, err := ast.ParseExpr(input)
  if err != nil {
    fmt.Println(err)
  } else {
    result, err := expr.Run(node, env)
    if err != nil {
      fmt.Println(err)
    } else {
      fmt.Println(result)
    }
  }
}

Types

type EvaluateError

type EvaluateError struct {
	Message string
}

func (*EvaluateError) Error

func (e *EvaluateError) Error() string