Doc: added more details and new functions and operators (iterator operators)

doc/Expr.adoc

@@ -34,7 +34,7 @@ Expressions calculator
 
 toc::[]
 
-#TODO: Work in progress (last update on 2026/04/21, 6:49 p.m.)#
+#TODO: Work in progress (last update on 2026/05/08)#
 
 == Expr
 _Expr_ is a GO package that can analyze, interpret and calculate expressions.
@@ -698,9 +698,9 @@ The value on the left side of [blue]`=` must be a variable identifier or an expr
 === Selector operator [blue]`? : ::`
 The _selector operator_ is very similar to the _switch/case/default_ statement available in many programming languages.
 
-.Selector literal Syntax
+.Selector literal syntax
 ====
-_selector-operator_ = _select-expression_ "*?*" _selector-case_ { "*:*" _selector-case_ } ["*::*" _default-multi-expression_] +
+*_selector-operator_* = _select-expression_ "*?*" _selector-case_ { "*:*" _selector-case_ } ["*::*" _default-multi-expression_] +
 _selector-case_ = [_match-list_] _case-value_ +
 _match-list_ = "*[*" _item_ {"*,*" _items_} "*]*" +
 _item_ = _expression_ +
@@ -737,19 +737,38 @@ The [blue]`:` symbol (colon) is the separator of the selector-cases. Note that i
 `>>>` [blue]`10 ? {"a"} : {"b"}` +
 [red]`Eval Error: [1:3] no case catches the value (10) of the selection expression`
 
+==== Triple special case of the selector operator
+If the _select-expression_ is a boolean expression, the selector operator can be used as a sort of _if-then-else_ statement. In this case, the first case is evaluated if the _select-expression_ is true, and the second case is evaluated if the _select-expression_ is false. In this special case, the _match-list_ of both cases must be empty.
+
+.Example
+`>>>` [blue]`(true) ? {"T"}: {"F"}` +
+[green]`T` +
+`>>>` [blue]`(2 > 1) ? {"a"} : {"b"}` +
+[green]`a` +
+`>>>` [blue]`(2 < 1) ? {"a"} : {"b"}` +
+[green]`b`
+
+[WARNING]
+====
+The triple special case of the selector operator is very useful, but it only works with boolean expressions.
+
+.Example of confusion
+`>>>` [blue]`int(true) ? {"T"}: {"F"}` +
+[green]`F`
+====
 
 === Variable default value [blue]`??`, [blue]`?=`, and [blue]`?!`
-The left operand of the first two operators, [blue]`??` and [blue]`?=`, 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.
+The left operand of the first two operators, [blue]`??` and [blue]`?=`, must be a variable. The right operatand 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 evaluated at all.
 
 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.
+The [blue]`?=` assigns the calculated value of the right expression to the variable on the left side.
 
 The third one, [blue]`?!`, is the alternate operator. If the variable on the left size is not defined, it returns [blue]_nil_. Otherwise it returns the result of the expressione on the right side.
 
-IMPORTANT: If the left variable is NOT defined, the right expression is not evaluated at all.
+IMPORTANT: If the variable [blue]`?!` is NOT defined, the expression is not evaluated at all.
 
 .Examples
 `>>>` [blue]`var ?? (1+2)` +
@@ -836,8 +855,14 @@ The table below shows all supported operators by decreasing priorities.
 .2+|*INSERT*| [blue]`+>` | _Infix_ | _Prepend_ | _any_ `+>` _list_ -> _list_
 | [blue]`<+` | _Infix_ | _Append_ | _list_ `<+` _any_ -> _list_
 .2+|*ASSIGN*| [blue]`=` | _Infix_ | _Assignment_ | _identifier_ `=` _any_ -> _any_
-4+| _See also the table of special allocation operators below_
+4+| _See also the table of special assignment operators below_
 .1+|*BUT*| [blue]`but` | _Infix_ | _But_ | _any_ `but` _any_ -> _any_
+.6+|*ITER-OP*| [blue]`digest` | _Infix_ | _Item-digesting_ | _iterable_ `digest` _expr_ -> _any_
+| [blue]`filter` | _Infix_ | _Item-filtering_ | _iterable_ `filter` _expr_ -> _list_
+| [blue]`groupby` | _Infix_ | _Dict-grouping_ | _iterable_ `groupby` _key-expr_ -> _dict_
+| [blue]`join` | _Infix_ | _Item-joining_ | _iterable_ `join` _iterable_ -> _list_
+| [blue]`map` | _Infix_ | _Item-mapping_ | _iterable_ `map` _-expr_ -> _list_
+4+| _See iterators section for examples_
 .1+|*RANGE*| [blue]`:` | _Infix_ | _Index-range_ | _integer_ `:` _integer_ -> _integer-pair_
 |===
 
@@ -921,12 +946,12 @@ _param-name_ = _identifier_
 [green]`fib(n):any{}`
 
 `>>>` [gray]_// Required and optional parameters_ +
-`>>>` [blue]`measure = func(value, unit="meter"){ value + " " + unit + (value > 1) ? [true] {"s"} :: {""}}` +
+`>>>` [blue]`measure = func(value, unit="meter"){ value + " " + unit + (value > 1) ? {"s"} :: {""}}` +
 [green]`measure(value, unit="meter"):any{}`
 
 
 === _Golang_ function definition
-Description of how to define Golang functions and how to bind them to _Expr_ are topics covered in another document that I'll write, one day, maybe.
+Description of how to define Golang functions and how to bind them to _Expr_ are topics covered in another documents that I'll write, one day, maybe.
 
 === Function calls
 To call a function, either Expr or Golang type, it is necessary to specify its name and, at least, its required parameters.
@@ -1010,7 +1035,7 @@ Clone variables are normal local variables. The only diffence will appear when t
 .Example
 `>>>` [blue]`f = func() { @x = 3; x = 5 }` [gray]_// f() declares two *different* local variables: ``@x`` and ``x``_ +
 [green]`f():any{}` +
-`>>>` [blue]`f()` [gray]_// The multi-expression (two) in f() is calculated and the last result is returned_ +
+`>>>` [blue]`f()` [gray]_// The multi-expression (two expressions) in f() is calculated and the last result is returned_ +
 [green]`5` +
 `>>>` [blue]`x` [gray]_// The `x` variable was not defined in the main context before the f() invocation. It appears in the main context by cloning the `@x` variable, local to f() after its termnation._ +
 [green]`3`
@@ -1048,7 +1073,7 @@ Builtins activation is done by using the [blue]`BUILTIN` operator. All modules e
 
 .Builtin activation syntax
 ====
-*_builtin-activation_* = [blue]`BUILTIN` (_builtin-name_ | _list-of-builtin-names_) +
+*_builtin-activation_* = [blue]`BUILTIN` (_builtin-name_ | _list-of-builtin-names_ | **"*"**) +
 _builtin-name_ = _string_ +
 _list-of-builtin-names_ = **[** _string_ { "**,**" _string_ } **]**
 ====
@@ -1086,9 +1111,9 @@ The "base" builtin module provides functions for type checking and type conversi
 * <<_fract,fract()>>
 
 .Other functions
+* <<_char,char()>>
 * <<_eval,eval()>>
 * <<_set,set()>>
-* <<_unset,unset()>>
 * <<_var,var()>>
 
 
@@ -1100,7 +1125,9 @@ Returns _true_ if the value type of _<expr>_ is boolean, false otherwise.
 `>>>` [blue]`isBool(true)` +
 [green]`true` +
 `>>>` [blue]`isBool(3==2)` +
-[green]`true`
+[green]`true` +
+`>>>` [blue]`isBool(3 + 2)` +
+[green]`false`
 
 ===== isDict()
 Syntax: `isDict(<expr>) -> bool` +
@@ -1178,7 +1205,7 @@ Returns _true_ if the value type of _<expr>_ is fraction or int, false otherwise
 
 ===== isString()
 Syntax: `isString(<expr>) -> bool` +
-Returns a boolean value , false otherwise.
+Returns _true_ if the value type of _<expr>_ is string, false otherwise.
 
 .Examples
 `>>>` [blue]`isString("ciao")` +
@@ -1190,7 +1217,7 @@ Returns a boolean value , false otherwise.
 
 ===== bool()
 Syntax: `bool(<expr>) -> bool` +
-Returns a _boolean_ value consisent to the value of the expression.
+Returns a _boolean_ value consisent with the value of the expression.
 
 .Examples
 `>>>` [blue]`bool(1)` +
@@ -1295,6 +1322,16 @@ Returns a _fraction_ value consistent with the value of the expression.
 `>>>` [blue]`fract(true)` +
 [green]`1:1`
 
+===== char()
+Syntax: `char(<intexpr>) -> string` +
+Returns the character whose ASCII (soon Unicode too) code point is specified by the integer expression.
+
+.Examples
+`>>>` [blue]`char(65)` +
+[green]`"A"` +
+`>>>` [blue]`char(97)` +
+[green]`"a"`
+
 ===== eval()
 Syntax: `eval(<string-expr>) -> any` +
 Computes and returns the value of the [.underline]#string# expression.
@@ -1308,12 +1345,12 @@ Syntax: +
  `{4sp}var(<string-expr>, <expr>) -> any` +
  `{4sp}var(<string-expr>) -> any`
 
-This function allows you to define variables whose names must include special characters. The first form of the function allows you to define a variable with a name specified by the first parameter and assign it the value of the second parameter. The second form only returns the value of the variable with the specified name.
+This function allows you to define variables whose names can include special characters. The first form of the function allows you to define a variable with a name specified by the first parameter and assign it the value of the second parameter. The second form only returns the value of the variable with the specified name.
 
 .Examples
 `>>>` [blue]`var("$x", 3+9)` +
 [green]`12` +
-`>>>` [blue]`var("$x")` +
+`>>>` [blue]`var("$"+"x")` +
 [green]`12` +
 `>>>` [blue]`var("gain%", var("$x"))` +
 [green]`12` +
@@ -1334,26 +1371,17 @@ It is equivalent to the first form of the var() function, but it is more explici
 `>>>` [blue]`var("$x")` +
 [green]`100` +
 
-===== unset()
-Syntax: +
- `{4sp}unset(<string-expr>) -> any`
-
-This function allows you to unset a variable whose name can include special characters. The parameter is the name of the variable to unset.
-
-.Examples
-`>>>` [blue]`unset("$x")` +
-[green]`nil` +
-`>>>` [blue]`var("$x")` +
-[red]`Eval Error: var(): unknown variable "$x"`
 
 ==== Module "fmt"
+#to-do#
 
 ===== print()
 
 ===== println()
 
 ==== Module "import"
-Module actiovation: +
+Module activation: +
+`{4sp}BUILTIN "import"`
 
 ===== _import()_
 Syntax: +
@@ -1364,6 +1392,8 @@ Loads the multi-expression contained in the specified source and returns its val
 ===== _importAll()_
 
 ==== Module "iterator"
+Module activation: +
+`{4sp}BUILTIN "iterator"`
 
 ===== run()
 Syntax: +
@@ -1372,6 +1402,9 @@ Syntax: +
 Iterates over the specified iterator and applies the specified operator to the current value of the iterator.
 
 ==== Module "math.arith"
+Module activation: +
+`{4sp}BUILTIN "math.arith"`
+
 Currently, the "math.arith" module provides two functions, add() and mul(), that perform addition and multiplication of an arbitrary number of parameters. More functions will be added in the future.
 
 * <<_add,add()>>
@@ -1421,13 +1454,12 @@ Same as <<_add,add()>> but returns the product of the values of the parameters.
 [green]`24`
 
 ==== Module "os.file"
+Module activation: +
+`{4sp}BUILTIN "os.file"`
+
 The "os.file" module provides functions for working with files.
 
-Activation: +
+.File related functions
-`{4sp}builtin "os.file"`
-
-Currently available functions:
-
 * <<_fileOpen,fileOpen()>>
 * <<_fileAppend,fileAppend()>>
 * <<_fileCreate,fileCreate()>>
@@ -1436,6 +1468,10 @@ Currently available functions:
 * <<_fileReadText,fileReadText()>>
 * <<_fileReadTextAll,fileReadTextAll()>>
 
+.Iterator functions for files
+* <<_fileByteIterator,fileByteIterator()>>
+* <<_fileLineIterator,fileLineIterator()>>
+
 More functions will be added in the future.
 
 ---
@@ -1447,6 +1483,10 @@ Syntax: +
 Returns a file handle for the specified file path. The file is opened in read-write mode. If the file does not exist, it is created.
 
 ===== fileAppend()
+Syntax: +
+`{4sp}fileAppend(<file-path>) -> any`
+
+Like <<_fileCreate,fileCreate()>> but write operations happen at the end of the file.
 
 ===== fileCreate()
 Syntax: +
@@ -1455,21 +1495,30 @@ Syntax: +
 Creates or truncates the named _<file-path>_. If the file already exists, it is truncated. If the file does not exist, it is created with mode 0o666 (before umask). The associated file descriptor has mode [O_RDWR]. The directory containing the file must already exist.
 
 ===== fileClose()
+#to-do#
 
 ===== fileWriteText()
+#to-do#
 
 ===== fileReadText()
+#to-do#
 
 ===== fileReadTextAll()
+#to-do#
+
+===== fileByteIterator()
+#to-do#
+
+===== fileLineIterator()
+#to-do#
 
 
 ==== Module "string"
+Module activation: +
+`{4sp}BUILTIN "string"`
+
 This module provides functions for working with strings.
 
-Activation: +
-`{4sp}builtin "string"`
-
-
 Currently available functions:
 
 * <<_strJoin,strJoin()>>