Doc: added more details and new functions and operators (iterator operators)
This commit is contained in:
+87
-38
@@ -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: +
|
||||
`{4sp}builtin "os.file"`
|
||||
|
||||
Currently available functions:
|
||||
|
||||
.File related 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()>>
|
||||
|
||||
Reference in New Issue
Block a user