Merge branch 'main' of ssh://git.portale-stac.it:3022/go-pkg/expr

README.adoc

@@ -25,6 +25,62 @@ toc::[]
 == Expr
 _Expr_ is a GO package capable of analysing, interpreting and calculating expressions.
 
+=== Usage
+
+
+[source,go]
+----
+import (
+	"fmt"
+	"strings"
+
+	"git.portale-stac.it/go-pkg/expr"
+)
+
+func main() {
+	ctx := expr.NewSimpleVarStore()
+	ctx.SetValue("var", int64(4))
+
+	source := `(3-1)*(10/5) == var`
+
+    r := strings.NewReader(source)
+    scanner := expr.NewScanner(r, 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]
+----
+import (
+	"fmt"
+	"git.portale-stac.it/go-pkg/expr"
+)
+
+func main() {
+	ctx := expr.NewSimpleVarStore()
+	ctx.SetValue("var", int64(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)
+    }
+}
+----
+
 === Data types
 _Expr_ supports numerical, string, relational, and boolean expressions.
 
@@ -32,18 +88,51 @@ _Expr_ supports numerical, string, relational, and boolean expressions.
 Numbers can be integers (GO int64) and float (GO float64). In mixed operations involving integers and floats, integers are automatically promoted to floats.
 
 .Arithmetic operators
-[cols="1,2,4,4"]
+[cols="^1,^2,6,4"]
 |===
 | Symbol    | Operation     | Description               | Examples
 
-| `+` / `-` | _change sign_ | Change the sign of values | `-1` [-1], `-(+2)` [-2]
+| `+` / `-` | _change sign_ | Change the sign of values | `-1` _[-1]_, `-(+2)` _[-2]_
 
-| `+` | _sum_ | Add two values | `-1 + 2` [1], `4 + 0.5` [4.5]
+| `+` | _sum_ | Add two values | `-1 + 2` _[1]_, `4 + 0.5` _[4.5]_
 
-| `-` | _subtracion_ | Subtract the right value from the left one | `3 - 1` [2], `4 - 0.5` [3.5]
+| `-` | _subtracion_ | Subtract the right value from the left one | `3 - 1` _[2]_, `4 - 0.5` _[3.5]_
 
-| `*` | _product_ | Multiply two values | `-1 * 2` [-1], `4 * 0.5` [2.0]
+| `*` | _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]_
 
 |=== 
 
 ==== String
+Strings are character sequences enclosed between two double quote `"`.
+
+==== Boolean
+Boolean data type has two values only: _true_ and _false_. Relational and Boolean expressions produce a Boolean values.
+
+
+.Relational operators
+[cols="^1,^2,6,4"]
+|===
+| Symbol    | Operation     | Description               | Examples
+
+| `<` | _Less_ | True if the left value is less than the right one | `5 < 2` _[false]_, `"a" < "b"` [true]
+| `\<=` | _Less or Greater_ | True if the left value is less or greater than the right one | `5 <= 2` _[false]_, `"b" <= "b"` [true]
+|===
+
+
+.Boolean operators
+[cols="^1,^2,6,4"]
+|===
+| 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]_
+|===