diff --git a/doc/Expr.adoc b/doc/Expr.adoc index 5e1da70..3907183 100644 --- a/doc/Expr.adoc +++ b/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 __ 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() -> bool` + @@ -1178,7 +1205,7 @@ Returns _true_ if the value type of __ is fraction or int, false otherwise ===== isString() Syntax: `isString() -> bool` + -Returns a boolean value , false otherwise. +Returns _true_ if the value type of __ is string, false otherwise. .Examples `>>>` [blue]`isString("ciao")` + @@ -1190,7 +1217,7 @@ Returns a boolean value , false otherwise. ===== bool() Syntax: `bool() -> 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() -> 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() -> any` + Computes and returns the value of the [.underline]#string# expression. @@ -1308,12 +1345,12 @@ Syntax: + `{4sp}var(, ) -> any` + `{4sp}var() -> 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() -> 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() -> 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 __. 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()>>