Expr

Table of Contents

• 1. Expr
  • 1.1. Usage
  • 1.2. Concepts and terminology
  • 1.3. Data types
    • 1.3.1. Numbers
    • 1.3.2. String
    • 1.3.3. Boolean
    • 1.3.4. List
  • 1.4. Variables
  • 1.5. Other operations
    • 1.5.1. ; operator
    • 1.5.2. but operator
    • 1.5.3. Assignment operator =
    • 1.5.4. Selector operator ? : ::
  • 1.6. Priorities of operators
  • 1.7. Functions
    • 1.7.1. Function calls
    • 1.7.2. Function definitions
  • 1.8. Builtins
    • 1.8.1. Builtin functions
    • 1.8.2. import()

1. Expr

Expr is a GO package capable of analysing, interpreting and calculating expressions.

A few examples to get started.

Examples taken from parser_test.go

`1.0 / 2`                      // 0.5
`435 + 105 * 2 - 1`            // 644
`4 == (3-1)*(10/5)`            // true
`"uno" * (2+1)`                // `unounouno`
`2+3 but 5*2`                  // 10 (1)
`add(add(1+4),3+2,5*(3-2))`    // 15 (2)
`a=5; b=2; add(a, b*3)`        // 11 (3)
`two=func(){2}; two()`         // 2  (4)
`double=func(x){2*x}; a=4+1; two=func() {2}; (double(3+a) + 1) * two()`  // 34
`import("./test-funcs.expr"); (double(3+a) + 1) * two()`  // 34 (5)
`[1,2,"hello"]`                // Mixed types list
`[1,2]+[3]`                    // append list, result: [1,2,3]
`add([1,[2,2],3,2])`           // Deep list sum, result: 10 (2)
`[a=1,b=2,c=3] but a+b+c`      // 6

1	but operator.
2	The add() function definition may be changed in the future.
3	Multiple expression. Only the last expression value will returned.
4	Simple function definition: two() returns 2.
5	import() function imports expressions from the specified files. See file test-funcs.expr.

1.1. Usage

package main

import (
	"fmt"
	"strings"
	"git.portale-stac.it/go-pkg/expr"
)

func main() {
	ctx := expr.NewSimpleVarStore()
	ctx.SetVar("var", 4)

	source := `(3-1)*(10/5) == var`

	r := strings.NewReader(source)
	scanner := expr.NewScanner(r, expr.DefaultTranslations())
	parser := expr.NewParser(ctx)

	if ast, err := parser.Parse(scanner); err == nil {
		if result, err := ast.Eval(ctx); err == nil {
			fmt.Printf("%q -> %v [%T]\n", source, result, result)
		} else {
			fmt.Println("Error calculating the expression:", err)
		}
	} else {
		fmt.Println("Error parsing the expression:", err)
	}
}

The above program is equivalent to the following one.

package main

import (
	"fmt"
	"git.portale-stac.it/go-pkg/expr"
)

func main() {
	ctx := expr.NewSimpleVarStore()
	ctx.SetVar("var", 4)

	source := `(3-1)*(10/5) == var`

	if result, err := expr.EvalString(ctx, source); err == nil {
		fmt.Printf("%q -> %v [%T]\n", source, result, result)
	} else {
		fmt.Println("Error calculating the expression:", err)
	}
}

Here is another equivalent version.

package main

import (
	"fmt"
	"git.portale-stac.it/go-pkg/expr"
)

func main() {
	source := `(3-1)*(10/5) == var`

	if result, err := expr.EvalStringA(source, expr.Arg{"var", 4}); err == nil {
		fmt.Printf("%q -> %v [%T]\n", source, result, result)
	} else {
		fmt.Println("Error calculating the expression:", err)
	}
}

1.2. Concepts and terminology

TODO

1.3. Data types

Expr supports numerical, string, relational, boolean expressions, and mixed-type lists.

1.3.1. Numbers

Numbers can be integers (GO int64) or float (GO float64). In mixed operations involving integers and floats, integers are automatically promoted to floats.

Table 1. Arithmetic operators

Symbol	Operation	Description	Examples
+ / -	change sign	Change the sign of values	-1 [-1] -(+2) [-2]
+	sum	Add two values	-1 + 2 [1] 4 + 0.5 [4.5]
-	subtraction	Subtract the right value from the left one	3 - 1 [2] 4 - 0.5 [3.5]
*	product	Multiply two values	-1 * 2 [-2] 4 * 0.5 [2.0]
/	Division	Divide the left value by the right one	-1 / 2 [0] 1.0 / 2 [0.5]
./	Float division	Force float division	-1 ./ 2 [-0.5]
%	Modulo	Remainder of the integer division	5 % 2 [1]

1.3.2. String

Strings are character sequences enclosed between two double quote ". Example: "I’m a string".

Some arithmetic operators can also be used with strings.

Table 2. String operators

Symbol	Operation	Description	Examples
+	concatenation	Join two strings or two stringable values	"one" + "two" ["onetwo"] "one" + 2 ["one2"]
*	repeat	Make n copy of a string	"one" * 2 ["oneone"]

1.3.3. Boolean

Boolean data type has two values only: true and false. Relational and Boolean expressions produce Boolean values.

Table 3. Relational operators

Symbol	Operation	Description	Examples
==	Equal	True if the left value is equal to the right one	5 == 2 [false] "a" == "a" [true]
!=	Not Equal	True if the left value is NOT equal to the right one	5 != 2 [true] "a" != "a" [false]
<	Less	True if the left value is less than the right one	5 < 2 [false] "a" < "b" [true]
<=	Less or Equal	True if the left value is less than or equal to the right one	5 <= 2 [false] "b" <= "b" [true]
>	Greater	True if the left value is greater than the right one	5 > 2 [true] "a" < "b" [false]
>=	Greater or Equal	True if the left value is greater than or equal to the right one	5 >= 2 [true] "b" <= "b" [true]

Table 4. Boolean operators

Symbol	Operation	Description	Examples
NOT	Not	True if the right value is false	NOT true [false] NOT (2 < 1) [true]
AND / &&	And	True if both left and right values are true	false && true [false] "a" < "b" AND NOT (2 < 1) [true]
OR / ||	Or	True if at least one of the left and right values integers true	false or true [true] "a" == "b" OR (2 == 1) [false]

Currently, boolean operations are evaluated using short cut evaluation. This means that, if the left expression of operators and and or is sufficient to establish the result of the whole operation, the right expression would not evaluated at all. Example 2 > (a=1) or (a=8) > 0; a (1) 1 This multi-expression returns 1 because in the first expression the left value of or is true and as a conseguence its right value is not computed. Therefore the a variable only receives the integer 1.

1.3.4. List

Expr supports list of mixed-type values, also specified by normal expressions.

List examples

[1, 2, 3]                   // List of integers
["one", "two", "three"]     // List of strings
["one", 2, false, 4.1]      // List of mixed-types
["one"+1, 2.0*(9-2)]        // List of expressions
[ [1,"one"], [2,"two"]]     // List of lists

Table 5. List operators

Symbol	Operation	Description	Examples
+	Join	Joins two lists	[1,2] + [3] [ [1,2,3] ]
-	Difference	Left list without elements in the right list	[1,2,3] - [2] [ [1,3] ]

1.4. Variables

A variable is an identifier with an assigned value. Variables are stored in the object that implements the ExprContext interface.

Examples

a=1
x = 5.2 * (9-3)
x = 1; y = 2*x

1.5. Other operations

1.5.1. ; operator

The semicolon operator ; is an infixed operator. It evaluates the left expression first and then the right expression. The latter is the final result.

Technically ; is not treated as a real operator. It acts as a separator in lists of expressions.

; can be used to set some variables before the final calculation.

Example

a=1; b=2; c=3; a+b+c    // returns 6

1.5.2. but operator

but is an infixed operator. Its operands can be any type of expression. It evaluates the left expression first, then the right expression. The value of the right expression is the final result. Examples: 5 but 2 returns 2, x=2*3 but x-1 returns 5.

but is very similar to ;. The only difference is that ; can’t be used inside parenthesis ;( and ).

1.5.3. Assignment operator =

The assignment operator = is used to define variable in the evaluation context or to change their value (see ExprContext). The value on the left side of = must be an identifier. The value on the right side can be any expression and it becomes the result of the assignment operation.

Example

a=15+1    // returns 16

1.5.4. Selector operator ? : ::

The selector operator is very similar to the switch/case/default statement available in many programming languages.

Syntax

<selector-operator> ::= <expression> "?" <selector-case> { ":" <selector-case> } ["::" <case-value>]
<selector-case> ::= [<list>] <case-value>
<case-value> ::= "{" <multi-expr> "}"
<multi-expr> ::= <expr> {";" <expr>}

Example

1 ? {"a"} : {"b"}                           // returns "b"
10 ? {"a"} : {"b"} :: {"c"}                 // returns "c"
10 ? {"a"} :[true, 2+8] {"b"} :: {"c"}      // returns "b"
10 ? {"a"} :[true, 2+8] {"b"} ::[10] {"c"}  // error:  "... case list in default clause"
10 ? {"a"} :[10] {x="b" but x} :: {"c"}     // returns "b"
10 ? {"a"} :[10] {x="b"; x} :: {"c"}        // returns "b"
10 ? {"a"} : {"b"}                          // error:  "... no case catches the value (10) of the selection expression

1.6. Priorities of operators

The table below shows all supported operators by decreasing priorities.

Table 6. Operators priorities

Priority	Operators	Position	Operation	Operands and results
FACT	!	Postfix	Factorial	integer "!" → integer
SIGN	+, -	Prefix	Change-sign	("+"|"-") number → number
PROD	*	Infix	Product	number "*" number → number
	*	Infix	String-repeat	string "*" integer → string
	/	Infix	Division	number "/" number → number
	./	Infix	Float-division	number "./" number → float
	%	Infix	Integer-remainder	integer "%" integer → integer
SUM	+	Infix	Sum	number "+" number → number
	+	Infix	String-concat	(string|number) "+" (string|number) → string
	+	Infix	List-join	list "+" list → list
	-	Infix	Subtraction	number "-" number → number
	-	Infix	List-difference	list "-" list → list
RELATION	<	Infix	less	comparable "<" comparable → boolean
	<=	Infix	less-equal	comparable "<=" comparable → boolean
	>	Infix	greater	comparable ">" comparable → boolean
	>=	Infix	greater-equal	comparable ">=" comparable → boolean
	==	Infix	equal	comparable "==" comparable → boolean
	!=	Infix	not-equal	comparable "!=" comparable → boolean
NOT	not	Prefix	not	"not" boolean → boolean
AND	and	Infix	and	boolean "and" boolean → boolean
	&&	Infix	and	boolean "&&" boolean → boolean
OR	or	Infix	or	boolean "or" boolean → boolean
	||	Infix	or	boolean "||" boolean → boolean
ASSIGN	=	Infix	assignment	identifier "=" any → any
BUT	but	Infix	but	any "but" any → any

1.7. Functions

Functions in Expr are very similar to functions in many programming languages.

In Expr functions compute values in a local context (scope) that do not make effects on the calling context. This is the normal behavior. Using the reference operator @ it is possibile to export local definition to the calling context.

1.7.1. Function calls

TODO: function calls operations

1.7.2. Function definitions

TODO: function definitions operations

1.8. Builtins

TODO: builtins

1.8.1. Builtin functions

1.8.2. import()

import(<source-file>) loads the multi-expression contained in the specified source and returns its value.