386 lines
13 KiB
Plaintext
386 lines
13 KiB
Plaintext
= Expr
|
|
Expressions calculator
|
|
:authors: Celestino Amoroso
|
|
:docinfo: shared
|
|
:encoding: utf-8
|
|
:toc: right
|
|
:toclevels: 4
|
|
//:toc-title: Indice Generale
|
|
:icons: font
|
|
:icon-set: fi
|
|
:numbered:
|
|
//:table-caption: Tabella
|
|
//:figure-caption: Diagramma
|
|
:docinfo1:
|
|
:sectlinks:
|
|
:sectanchors:
|
|
:source-highlighter: rouge
|
|
// :rouge-style: ThankfulEyes
|
|
:rouge-style: gruvbox
|
|
// :rouge-style: colorful
|
|
//:rouge-style: monokay
|
|
|
|
toc::[]
|
|
|
|
== 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
|
|
[source,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> [blue]`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_.
|
|
|
|
|
|
=== Usage
|
|
|
|
|
|
[source,go]
|
|
----
|
|
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.
|
|
|
|
[source,go]
|
|
----
|
|
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.
|
|
|
|
[source,go]
|
|
----
|
|
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)
|
|
}
|
|
}
|
|
----
|
|
|
|
=== Concepts and terminology
|
|
#TODO#
|
|
|
|
=== Data types
|
|
_Expr_ supports numerical, string, relational, boolean expressions, and mixed-type lists.
|
|
|
|
==== Numbers
|
|
Numbers can be integers (GO int64) or float (GO float64). In mixed operations involving integers and floats, integers are automatically promoted to floats.
|
|
|
|
.Arithmetic operators
|
|
[cols="^1,^2,6,4"]
|
|
|===
|
|
| Symbol | Operation | Description | Examples
|
|
|
|
| [blue]`+` / [blue]`-` | _change sign_ | Change the sign of values | [blue]`-1` _[-1]_ +
|
|
[blue]`-(+2)` _[-2]_
|
|
|
|
| [blue]`+` | _sum_ | Add two values | [blue]`-1 + 2` _[1]_ +
|
|
[blue]`4 + 0.5` _[4.5]_
|
|
|
|
| [blue]`-` | _subtraction_ | Subtract the right value from the left one | [blue]`3 - 1` _[2]_ +
|
|
[blue]`4 - 0.5` _[3.5]_
|
|
|
|
| [blue]`*` | _product_ | Multiply two values | `-1 * 2` _[-2]_ +
|
|
[blue]`4 * 0.5` _[2.0]_
|
|
|
|
| [blue]`/` | _Division_ | Divide the left value by the right one | [blue]`-1 / 2` _[0]_ +
|
|
[blue]`1.0 / 2` _[0.5]_
|
|
|
|
| [blue]`./` | _Float division_ | Force float division | [blue]`-1 ./ 2` _[-0.5]_
|
|
|
|
| [blue]`%` | _Modulo_ | Remainder of the integer division | [blue]`5 % 2` _[1]_
|
|
|
|
|===
|
|
|
|
==== String
|
|
Strings are character sequences enclosed between two double quote [blue]`"`. Example: [blue]`"I'm a string"`.
|
|
|
|
Some arithmetic operators can also be used with strings.
|
|
|
|
.String operators
|
|
[cols="^1,^2,6,4"]
|
|
|===
|
|
| Symbol | Operation | Description | Examples
|
|
|
|
| [blue]`+` | _concatenation_ | Join two strings or two _stringable_ values | [blue]`"one" + "two"` _["onetwo"]_ +
|
|
[blue]`"one" + 2` _["one2"]_
|
|
|
|
| [blue]`*` | _repeat_ | Make _n_ copy of a string | [blue]`"one" * 2` _["oneone"]_
|
|
|===
|
|
|
|
|
|
==== Boolean
|
|
Boolean data type has two values only: _true_ and _false_. Relational and Boolean expressions produce Boolean values.
|
|
|
|
|
|
.Relational operators
|
|
[cols="^1,^2,6,4"]
|
|
|===
|
|
| Symbol | Operation | Description | Examples
|
|
|
|
| [blue]`==` | _Equal_ | True if the left value is equal to the right one | [blue]`5 == 2` _[false]_ +
|
|
[blue]`"a" == "a"` _[true]_
|
|
| [blue]`!=` | _Not Equal_ | True if the left value is NOT equal to the right one | [blue]`5 != 2` _[true]_ +
|
|
[blue]`"a" != "a"` _[false]_
|
|
| [blue]`<` | _Less_ | True if the left value is less than the right one | [blue]`5 < 2` _[false]_ +
|
|
[blue]`"a" < "b"` _[true]_
|
|
| [blue]`\<=` | _Less or Equal_ | True if the left value is less than or equal to the right one | [blue]`5 \<= 2` _[false]_ +
|
|
[blue]`"b" \<= "b"` _[true]_
|
|
| [blue]`>` | _Greater_ | True if the left value is greater than the right one | [blue]`5 > 2` _[true]_ +
|
|
[blue]`"a" < "b"` _[false]_
|
|
| [blue]`>=` | _Greater or Equal_ | True if the left value is greater than or equal to the right one | [blue]`5 >= 2` _[true]_ +
|
|
[blue]`"b" \<= "b"` _[true]_
|
|
|===
|
|
|
|
|
|
.Boolean operators
|
|
[cols="^2,^2,5,4"]
|
|
|===
|
|
| Symbol | Operation | Description | Examples
|
|
|
|
| [blue]`NOT` | _Not_ | True if the right value is false | [blue]`NOT true` _[false]_ +
|
|
[blue]`NOT (2 < 1)` _[true]_
|
|
|
|
| [blue]`AND` / [blue]`&&` | _And_ | True if both left and right values are true | [blue]`false && true` _[false]_ +
|
|
[blue]`"a" < "b" AND NOT (2 < 1)` _[true]_
|
|
|
|
| [blue]`OR` / [blue]`\|\|` | _Or_ | True if at least one of the left and right values integers true| [blue]`false or true` _[true]_ +
|
|
[blue]`"a" == "b" OR (2 == 1)` _[false]_
|
|
|===
|
|
|
|
[CAUTION]
|
|
====
|
|
Currently, boolean operations are evaluated using _short cut evaluation_. This means that, if the left expression of operators [blue]`and` and [blue]`or` is sufficient to establish the result of the whole operation, the right expression would not evaluated at all.
|
|
|
|
.Example
|
|
[source,go]
|
|
----
|
|
2 > (a=1) or (a=8) > 0; a // <1>
|
|
----
|
|
<1> This multi-expression returns _1_ because in the first expression the left value of [blue]`or` is _true_ and as a conseguence its right value is not computed. Therefore the _a_ variable only receives the integer _1_.
|
|
====
|
|
|
|
==== List
|
|
_Expr_ supports list of mixed-type values, also specified by normal expressions.
|
|
|
|
.List examples
|
|
[source,go]
|
|
----
|
|
[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
|
|
----
|
|
|
|
|
|
.List operators
|
|
[cols="^2,^2,5,4"]
|
|
|===
|
|
| Symbol | Operation | Description | Examples
|
|
|
|
| [blue]`+` | _Join_ | Joins two lists | [blue]`[1,2] + [3]` _[ [1,2,3] ]_
|
|
|
|
| [blue]`-` | _Difference_ | Left list without elements in the right list | [blue]`[1,2,3] - [2]` _[ [1,3] ]_
|
|
|===
|
|
|
|
=== Variables
|
|
A variable is an identifier with an assigned value. Variables are stored in the object that implements the _ExprContext_ interface.
|
|
|
|
.Examples
|
|
[source,go]
|
|
----
|
|
a=1
|
|
x = 5.2 * (9-3)
|
|
x = 1; y = 2*x
|
|
----
|
|
|
|
=== Other operations
|
|
|
|
==== [blue]`;` operator
|
|
The semicolon operator [blue]`;` is an infixed operator. It evaluates the left expression first and then the right expression. The latter is the final result.
|
|
|
|
IMPORTANT: Technically [blue]`;` is not treated as a real operator. It acts as a separator in lists of expressions.
|
|
|
|
TIP: [blue]`;` can be used to set some variables before the final calculation.
|
|
|
|
.Example
|
|
[source,go]
|
|
----
|
|
a=1; b=2; c=3; a+b+c // returns 6
|
|
----
|
|
|
|
==== [blue]`but` operator
|
|
[blue]`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: [blue]`5 but 2` returns 2, [blue]`x=2*3 but x-1` returns 5.
|
|
|
|
[blue]`but` is very similar to [blue]`;`. The only difference is that [blue]`;` can't be used inside parenthesis [blue]`;(` and [blue]`)`.
|
|
|
|
==== Assignment operator [blue]`=`
|
|
The assignment operator [blue]`=` is used to define variable in the evaluation context or to change their value (see _ExprContext_).
|
|
The value on the left side of [blue]`=` must be an identifier. The value on the right side can be any expression and it becomes the result of the assignment operation.
|
|
|
|
.Example
|
|
[source,go]
|
|
----
|
|
a=15+1 // returns 16
|
|
----
|
|
|
|
==== Selector operator [blue]`? : ::`
|
|
The _selector operator_ is very similar to the _switch/case/default_ statement available in many programming languages.
|
|
|
|
.Syntax
|
|
[source,bnf]
|
|
----
|
|
<selector-operator> ::= <expression> "?" <selector-case> { ":" <selector-case> } ["::" <case-value>]
|
|
<selector-case> ::= [<list>] <case-value>
|
|
<case-value> ::= "{" <multi-expr> "}"
|
|
<multi-expr> ::= <expr> {";" <expr>}
|
|
----
|
|
|
|
.Example
|
|
[source,go]
|
|
----
|
|
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
|
|
----
|
|
|
|
=== Priorities of operators
|
|
The table below shows all supported operators by decreasing priorities.
|
|
|
|
.Operators priorities
|
|
[cols="^2,^2,^2,^5,<5"]
|
|
|===
|
|
| Priority | Operators | Position | Operation | Operands and results
|
|
|
|
1+|*FACT*| [blue]`!` | _Postfix_ | _Factorial_| _integer_ "!" -> _integer_
|
|
1+|*SIGN*| [blue]`+`, [blue]`-` | _Prefix_ | _Change-sign_| ("+"\|"-") _number_ -> _number_
|
|
.5+|*PROD*| [blue]`*` | _Infix_ | _Product_ | _number_ "*" _number_ -> _number_
|
|
| [blue]`*` | _Infix_ | _String-repeat_ | _string_ "*" _integer_ -> _string_
|
|
| [blue]`/` | _Infix_ | _Division_ | _number_ "/" _number_ -> _number_
|
|
| [blue]`./` | _Infix_ | _Float-division_ | __number__ "./" _number_ -> _float_
|
|
| [blue]`%` | _Infix_ | _Integer-remainder_ | _integer_ "%" _integer_ -> _integer_
|
|
.5+|*SUM*| [blue]`+` | _Infix_ | _Sum_ | _number_ "+" _number_ -> _number_
|
|
| [blue]`+` | _Infix_ | _String-concat_ | (_string_\|_number_) "+" (_string_\|_number_) -> _string_
|
|
| [blue]`+` | _Infix_ | _List-join_ | _list_ "+" _list_ -> _list_
|
|
| [blue]`-` | _Infix_ | _Subtraction_ | _number_ "-" _number_ -> _number_
|
|
| [blue]`-` | _Infix_ | _List-difference_ | _list_ "-" _list_ -> _list_
|
|
.6+|*RELATION*| [blue]`<` | _Infix_ | _less_ | _comparable_ "<" _comparable_ -> _boolean_
|
|
| [blue]`\<=` | _Infix_ | _less-equal_ | _comparable_ "\<=" _comparable_ -> _boolean_
|
|
| [blue]`>` | _Infix_ | _greater_ | _comparable_ ">" _comparable_ -> _boolean_
|
|
| [blue]`>=` | _Infix_ | _greater-equal_ | _comparable_ ">=" _comparable_ -> _boolean_
|
|
| [blue]`==` | _Infix_ | _equal_ | _comparable_ "==" _comparable_ -> _boolean_
|
|
| [blue]`!=` | _Infix_ | _not-equal_ | _comparable_ "!=" _comparable_ -> _boolean_
|
|
.1+|*NOT*| [blue]`not` | _Prefix_ | _not_ | "not" _boolean_ -> _boolean_
|
|
.2+|*AND*| [blue]`and` | _Infix_ | _and_ | _boolean_ "and" _boolean_ -> _boolean_
|
|
| [blue]`&&` | _Infix_ | _and_ | _boolean_ "&&" _boolean_ -> _boolean_
|
|
.2+|*OR*| [blue]`or` | _Infix_ | _or_ | _boolean_ "or" _boolean_ -> _boolean_
|
|
| [blue]`\|\|` | _Infix_ | _or_ | _boolean_ "\|\|" _boolean_ -> _boolean_
|
|
.1+|*ASSIGN*| [blue]`=` | _Infix_ | _assignment_ | _identifier_ "=" _any_ -> _any_
|
|
.1+|*BUT*| [blue]`but` | _Infix_ | _but_ | _any_ "but" _any_ -> _any_
|
|
|===
|
|
|
|
=== 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 [blue]`@` it is possibile to export local definition to the calling context.
|
|
|
|
==== Function calls
|
|
#TODO: function calls operations#
|
|
|
|
==== Function definitions
|
|
#TODO: function definitions operations#
|
|
|
|
=== Builtins
|
|
#TODO: builtins#
|
|
|
|
==== Builtin functions
|
|
|
|
==== [blue]_import()_
|
|
[blue]_import([grey]#<source-file>#)_ loads the multi-expression contained in the specified source and returns its value.
|
|
|
|
|
|
|