evaluator

package module
Version: v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Jun 23, 2020 License: MIT Imports: 8 Imported by: 0

README

Build Status Coverage Status GoDoc Go Report Card

It's very common to evaluate an expression dynamicly, so that's why we are here.

S-expression

We use s-epxression syntax to parse and evaluate.

In computing, s-expressions, sexprs or sexps (for "symbolic expression") are a notation for nested list (tree-structured) data, invented for and popularized by the programming language Lisp, which uses them for source code as well as data.

For example, for expression in common way: ​ ( (gender = "female") and
((age % 2) != 0) ) it's coresponding format in s-expression is: ​ (and (= gender "female") (!= (% age 2) 0 ) )

Element types within expression

  • number
    For convenience, we treat float64, int64 and so on as type of number. For example, float 100.0 is equal to int 100, but not euqal to string "100"

  • string
    character string quoted with `, ', or " are treated as type of string. You can convert type string to any other defined type you like by type convert functions which are mentioned later

  • function or variable
    character string without quotes are regarded as type of function or variable which depends on whether this function exists. For example in expression (age birthdate), both age and birthdate is unquoted. age is type of function because we have registered a function named age, while birthdate is type of variable for not found. The program will come to errors if there is neither parameter nor function named birthdate when evaluating

How to

You can evaluate directly:

params := evaluator.MapParams{
    "gender": "female",
}
res, err := evaluator.EvalBool(`(in gender ("female" "male"))`, params)
if err != nil {
    log.Fatal(err)
}
fmt.Println(res)
# true	

or you can reuse the Expression to evaluate multiple times:

params := evaluator.MapParams{
    "gender": "female",
}
exp, err := evaluator.New(`(in gender ("female" "male"))`)
if err != nil {
    log.Fatal(err)
}
res, err := exp.EvalBool(params)
if err != nil {
    log.Fatal(err)
}
fmt.Println(res)
# true

And you can write expressions like this

  • (in gender ("male", "female"))

  • (between now (td_time "2017-01-02 12:00:00") (td_time "2017-12-02 12:00:00"))

  • (ne (mod (age birthdate) 7) 5)

  • or multiple-line for clarity

    (and
    	(ne os "ios")
    	(eq gender "male")
    	(beteen version (t_version "2.7.1") (t_version "2.9.1"))
    )
    

Functions

Implemented functions

operand function example description
- in (in 1 (1 2)) also suport array like (in (1) ((1)))
- between (between age 18 20)
- overlap (overlap region (3142 1860))
& and (and (eq gender "femal") (between age 18 20))
` ` or
! not
= eq equal
!= ne not equal
> gt greater than
< lt less than
>= ge greater than or equal to
<= le less than or equal to
% mod
+ - plus
- - minus
* - multiply
/ - divide
- t_version convert type to version
- t_time (t_time "2006-01-02 15:04" "2017-09-09 12:00") convert type to time, first param must be the layout for the time
- td_time (td_time "2017:09:09 12:00:00) convert type to time of default layout format 2006-01-02 15:04:05
_ td_date (in (td_date now) (td_date ("2017-01-02" "2017-02-01")) ) convert type to time of default layout format 2006-01-02

p.s. either operand or function can be used in expression

How to use self-defined functions

Yes, you can write your own function by following thses steps:

  1. implement your function
  2. regist to functions
  3. enjoy it

here is an example:

package main


import (
	"errors"
	"log"
	"time"

	"github.com/nullne/evaluator"
	"github.com/nullne/evaluator/function"
)

// define your own function and don't forget to register
func age(params ...interface{}) (interface{}, error) {
	if len(params) != 1 {
		return nil, errors.New("only one params accepted")
	}
	birth, ok := params[0].(string)
	if !ok {
		return nil, errors.New("birth format need to be string")
	}
	r, err := time.Parse("2006-01-02", birth)
	if err != nil {
		return nil, err
	}
	now := time.Now()
	a := r.Year() - now.Year()
	if r.Month() < now.Month() {
		a--
	} else if r.Month() == now.Month() {
		if r.Day() < now.Day() {
			a--
		}
	}
	return a, nil
}

func main() {
	if err := function.Regist("age", age); err != nil {
		log.Print(err)
	}

	exp := `(not (between (age birthdate) 18 20))`
	vvf := evaluator.MapParams{
		"birthdate": "1980-02-01",
	}
	e, err := evaluator.New(exp)
	if err != nil {
		log.Print(err)
	}
	r, err := e.Eval(vvf)
	if err != nil {
		log.Print(err)
	}
	log.Printf("expression: `%s`, wanna: %+v, got: %+v\r", exp, true, r)
}

Params

  • Params interface, which has a method named Get to get all params needed
  • MapParams a simple implemented Params in map

Bench

BenchmarkEqualString-8   	 3000000	       473 ns/op
BenchmarkInString-8      	 2000000	       916 ns/op
BenchmarkBetweenInt-8    	 3000000	       467 ns/op
BenchmarkBetweenTime-8   	 1000000	      2089 ns/op
BenchmarkOverlapInt-8    	  500000	      2966 ns/op
BenchmarkTypeTime-8      	 2000000	       638 ns/op
BenchmarkTypeVersion-8   	 3000000	       539 ns/op

p.s. on MacBook Pro (Retina, 15-inch, Mid 2015), Memory: 16 GB 1600 MHz DDR3, Processor: 2.2 GHz Intel Core i7

Documentation

Overview

Package evaluator evaluates an expression in the form of s-expression

Package evaluator treats the element within expression with three types, each type has its own array form:

  • number For convenience, we treat float64, int64 and so on as type of number. For example, float 100.0 is equal to int 100, but not euqal to string "100"
  • string character string quoted with `, ', or " are treated as type of string. You can convert type string to any other defined type you like by type convert functions which are mentioned later
  • function or variable character string without quotes are regarded as type of function or variable which depends on whether this function exists. For example in expression (age birthdate), both age and birthdate is unquoted. age is type of function because we have registered a function named age, while birthdate is type of variable for not found. The program will come to errors if there is neither parameter nor function named birthdate when evaluating

Index

Examples

Constants

This section is empty.

Variables

View Source
var (
	// ErrNotFound means the unknow string within the expression cannot be Get from neither functions or params
	ErrNotFound = errors.New("neither function not variable found")
	// ErrInvalidResult means the invalid result type expected with the real output
	ErrInvalidResult = errors.New("invalid result type")
)
View Source
var (
	// ErrUnexpectedEnd occurs most time with the missing parenthesis
	ErrUnexpectedEnd = errors.New("unexpected end")
	// ErrNilInput means the input is nil
	ErrNilInput = errors.New("nil input")
	// ErrLeftOverText indicates there are some of the expression are left pared
	ErrLeftOverText = errors.New("left over text")
	// ErrUnmatchedParenthesis indicated the mismatching parenthesis
	ErrUnmatchedParenthesis = errors.New("unmatched parenthesis")
)

Functions

func Eval

func Eval(expr string, params Params) (interface{}, error)

Eval is a handy encapsulation to parse the expression and evaluate it

func EvalBool

func EvalBool(expr string, params Params) (bool, error)

EvalBool is same as Eval but return a boolean result instead of interface type

Types

type Expression

type Expression struct {
	// contains filtered or unexported fields
}

Expression stands for an expression which can be evaluated by passing required params

Example
exp, err := New(`(eq gender 'male')`)
if err != nil {
	log.Fatal(err)
}
params := MapParams{"gender": "male"}
res, err := exp.Eval(params)
if err != nil {
	log.Fatal(err)
}
fmt.Println(res)
res, err = exp.EvalBool(params)
if err != nil {
	log.Fatal(err)
}
fmt.Println(res)
Output:

true
true
Example (Ignore)
s := `(!(a b )())`
exp, err := parse(s)
if err != nil {
	return
}
exp.dump(0)
Output:

evaluator.list: 3 elements: [! [a b] []]
   evaluator.varString: !
   evaluator.list: 2 elements: [a b]
      evaluator.varString: a
      evaluator.varString: b
   evaluator.list: 0 elements: []

func New

func New(expr string) (Expression, error)

New will return a Expression by parsing the given expression string

func (Expression) Eval

func (e Expression) Eval(params Params) (interface{}, error)

Eval evaluates the Expression with params and return the real value in the type of interface

func (Expression) EvalBool

func (e Expression) EvalBool(params Params) (bool, error)

EvalBool invokes method Eval and does boolean type assertion, return ErrInvalidResult if the type of result is not boolean

func (Expression) Properties

func (e Expression) Properties() []string

Properties returns the field names in an Expression. e.g. Expression constructed by `(or (and (between age 18 80) (eq gender "male") )` returns "age", "gender" by calling Properties.

type MapParams

type MapParams map[string]interface{}

MapParams is a simple map implementation of Params interface

func (MapParams) Get

func (p MapParams) Get(name string) (interface{}, error)

Get is the only method required by Params interface

type Params

type Params interface {
	Get(name string) (interface{}, error)
}

Params defines a Get method which gets required param for the expression

Directories

Path Synopsis
Package function provides basic functions which implement Funcer interface
Package function provides basic functions which implement Funcer interface

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL