Doc: little changes

doc/Expr.adoc

@@ -20,10 +20,12 @@ Expressions calculator
 :rouge-style: gruvbox
 // :rouge-style: colorful
 //:rouge-style: monokay
+// Work around to manage double-column in back-tick quotes
+:2c: ::
 
 toc::[]
 
-#TODO: Work in progress (last update on 2024/06/17, 16:31 a.m.)#
+#TODO: Work in progress (last update on 2024/06/21, 05:40 a.m.)#
 
 == Expr
 _Expr_ is a GO package capable of analysing, interpreting and calculating expressions.
@@ -554,7 +556,7 @@ NOTE: The assign operator [blue]`=` returns the value assigned to the variable.
 `>>>` [blue]`a_b` +
 [green]`3`
 
-`>>>` [blue]`x = 5.2 * (9-3)`  [gray]_// The assigned value has the approximation error typical of the float data-type_ +
+`>>>` [blue]`x = 5.2 * (9-3)`  [gray]_// The assigned value has the typical approximation error of the float data-type_ +
 [green]`31.200000000000003`
 
 `>>>` [blue]`x = 1; y = 2*x` +
@@ -572,6 +574,11 @@ NOTE: The assign operator [blue]`=` returns the value assigned to the variable.
 === [blue]`;` operator
 The semicolon operator [blue]`;` is an infixed pseudo-operator. It evaluates the left expression first and then the right expression. The value of the latter is the final result.
 
+.Mult-expression syntax
+====
+*_multi-expression_* = _expression_ {"**;**" _expression_ }
+====
+
 An expression that contains [blue]`;` is called a _multi-expression_ and each component expressione is called a _sub-expression_.
 
 IMPORTANT: Technically [blue]`;` is not treated as a real operator. It acts as a separator in lists of expressions.
@@ -630,38 +637,47 @@ The [blue]`:` symbol (colon) is the separator of the selector-cases. Note that i
 
 .Examples
 `>>>` [blue]`1 ? {"a"} : {"b"}` +
-[green]`b` +
-`>>>` [blue]`10 ? {"a"} : {"b"} :: {"c"}` +
-[green]`c' +
-[green]`>>>` [blue]`10 ? {"a"} :[true, 2+8] {"b"} :: {"c"}` +
-[green]`b` +
-`>>>` [blue]`10 ? {"a"} :[true, 2+8] {"b"} ::[10] {"c"}` +
-[red]`Parse Error: [1:34] case list in default clause` +
-[green]`>>>` [blue]`10 ? {"a"} :[10] {x="b" but x} :: {"c"}` +
-[green]`b` +
-`>>>` [blue]`10 ? {"a"} :[10] {x="b"; x} :: {"c"}` +
-[green]`b` +
+[green]`b`
+
+`>>>` [blue]`10 ? {"a"} : {"b"} {2c} {"c"}` +
+[green]`c`
+
+`>>>` [blue]`10 ? {"a"} :[true, 2+8] {"b"} {2c} {"c"}` +
+[green]`b`
+
+`>>>` [blue]`10 ? {"a"} :[true, 2+8] {"b"} {2c} [10] {"c"}` +
+[red]`Parse Error: [1:34] case list in default clause`
+
+`>>>` [blue]`10 ? {"a"} :[10] {x="b" but x} {2c} {"c"}` +
+[green]`b`
+
+`>>>` [blue]`10 ? {"a"} :[10] {x="b"; x} {2c} {"c"}` +
+[green]`b`
+
 `>>>` [blue]`10 ? {"a"} : {"b"}` +
 [red]`Eval Error: [1:3] no case catches the value (10) of the selection expression`
 
 
 === Variable default value [blue]`??` and [blue]`?=`
-The left operand of these two operators must be a variable. The right operator can be any expression. They return the value of the variable if this is define; otherwise they return the value of the right expression.
+The left operand of these two operators must be a variable. The right operator can be any expression. They return the value of the variable if this is defined; otherwise they return the value of the right expression.
 
-IMPORTANT: If the left variable is defined, the right expression is not evuated at all.
+IMPORTANT: If the left variable is defined, the right expression is not evaluated at all.
 
-The [blue]`??` do not change the status of the left variable.
+The [blue]`??` operator do not change the status of the left variable.
 
 The [blue]`?=` assigns the calculated value of the right expression to the left variable.
 
 .Examples
-`>>>` [blue]`var ?? (1+2)`'
-[green]`3` +
+`>>>` [blue]`var ?? (1+2)`' +
+[green]`3`
+
 `>>>` [blue]`var` +
-[red]`Eval Error: undefined variable or function "var"` +
+[red]`Eval Error: undefined variable or function "var"`
+
 `>>>` [blue]`var ?= (1+2)` +
-[green]`3` +
-`>>>` [blue]`var` +
+[green]`3`
+
+`>>>` [blue]`var`
 [green]`3`
 
 NOTE: These operators have a high priority, in particular higher than the operator [blue]`=`.
@@ -678,6 +694,9 @@ The table below shows all supported operators by decreasing priorities.
 | [blue]`[`...`]` | _Postfix_ | _Dict item_ | _dict_ `[` _any_ `]` -> _any_
 .2+|*INC*| [blue]`++` | _Postfix_ | _Post increment_| _integer-variable_ `++` -> _integer_
 | [blue]`++` | _Postfix_ | _Next item_ | _iterator_ `++` -> _any_
+.2+|*DEFAULT*| [blue]`??` | _Infix_ | _Default value_| _variable_ `??` _any-expr_ -> _any_
+| [blue]`?=` | _Infix_ | _Default/assign value_| _variable_ `?=` _any-expr_ -> _any_
+.1+| *ITER*^1^| [blue]`()` | _Prefix_ | _Iterator value_ | `()` _iterator_ -> _any_
 .1+|*FACT*| [blue]`!` | _Postfix_ | _Factorial_| _integer_ `!` -> _integer_
 .3+|*SIGN*| [blue]`+`, [blue]`-` | _Prefix_ | _Change-sign_| (`+`\|`-`) _number_ -> _number_
 | [blue]`#` | _Prefix_ | _Lenght-of_ | `#` _collection_ -> _integer_
@@ -716,19 +735,38 @@ The table below shows all supported operators by decreasing priorities.
 .1+|*RANGE*| [blue]`:` | _Infix_ | _Index-range_ | _integer_ `:` _integer_ -> _integer-pair_
 |===
 
+^1^ Experimental
+
+
 == Functions
 Functions in _Expr_ are very similar to functions available in many programming languages. Actually, _Expr_ supports two types of function, _expr-functions_ and _go-functions_.
 
 * _expr-functions_ are defined using _Expr_'s syntax. They can be passed as arguments to other functions and can be returned from functions. Moreover, they bind themselves to the defining context, thus becoming closures.
 * _go-functions_ are regular Golang functions callable from _Expr_ expressions. They are defined in Golang source files called _modules_ and compiled within the _Expr_ package. To make Golang functions available in _Expr_ contextes, it is required to _import_ the module in which they are defined.
 
-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.
+
+=== _Expr_ function definition
+A function is identified and referenced by its name. It can have zero or more parameter. _Expr_ functions also support optional parameters.
+
+. Expr's function definition syntax
+====
+*_function-definition_* = _identifier_ "**=**"  "**func(**" [_param-list_] "**)**"  "**{**" _multi-expression_ "**}**"
+_param_list_ = _required-param-list_ [ "**,**" _optional-param-list_ ]
+_required-param-list_ = _identifier_ { "**,**" _identifier_ }
+_optional-param-list_ = _optional-parm_ { "**,**" _optional-param_ }
+_optional-param_ = _identifier_ "**=**" _any-expr_
+====
+
+.Examples
+#TODO#
+
+=== _Golang_ function definition
+Description of how to define Golan functions and how to bind them to _Expr_ are topics treated in another document that I'll write, one day, maybe.
 
 === Function calls
 #TODO: function calls operations#
 
-=== Function definitions
-#TODO: function definitions operations#
+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.
 
 
 == Iterators