From aa195b9a682df79bab0d0cd4583aab632f3919af Mon Sep 17 00:00:00 2001
From: Celestino Amoroso <celestino.amoroso@gmail.com>
Date: Mon, 8 Apr 2024 23:14:25 +0200
Subject: [PATCH] README.adoc: section on selector operator

---
 README.adoc | 51 +++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 41 insertions(+), 10 deletions(-)

diff --git a/README.adoc b/README.adoc
index c55cc41..6eb665b 100644
--- a/README.adoc
+++ b/README.adoc
@@ -25,6 +25,8 @@ 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]
 ----
@@ -73,8 +75,8 @@ func main() {
     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 {
+	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)
@@ -99,7 +101,7 @@ func main() {
 
 	source := `(3-1)*(10/5) == var`
 
-    if result, err := expr.evalString(ctx, source); err == nil {
+    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)
@@ -111,7 +113,7 @@ func main() {
 _Expr_ supports numerical, string, relational, boolean expressions, and mixed-type lists.
 
 ==== Numbers
-Numbers can be integers (GO int64) and float (GO float64). In mixed operations involving integers and floats, integers are automatically promoted to floats.
+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"]
@@ -149,11 +151,10 @@ Some arithmetic operators can also be used with strings.
 |===
 | Symbol    | Operation     | Description               | Examples
 
-| [blue]`+` | _concatenation_ | Join to strings or _stringable_ values | [blue]`"one" + "two"` _["onetwo"]_ +
+| [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"]_
-
 |===
 
 
@@ -219,9 +220,9 @@ Currently, boolean operations are evaluated using _short cut evaluation_. This m
 ==== [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. Its role is as an expression separator in an expression list.
+IMPORTANT: Technically [blue]`;` is not treated as a real operator. It acts as a separator in lists of expressions.
 
-[blue]`;` can be used to set some variables before the final calculation.
+TIP: [blue]`;` can be used to set some variables before the final calculation.
 
 .Example
 [source,go]
@@ -232,12 +233,42 @@ 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]`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 context or to change their value.
+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.