From ba3dbb7f02910186bc1c395d2b03db67776cb19a Mon Sep 17 00:00:00 2001 From: Celestino Amoroso Date: Mon, 16 Sep 2024 06:52:29 +0200 Subject: [PATCH] Doc: continuation --- doc/Expr.adoc | 86 +++++++++++++++++++++++----------- doc/Expr.html | 127 +++++++++++++++++++++++++++++++++++++------------- 2 files changed, 155 insertions(+), 58 deletions(-) diff --git a/doc/Expr.adoc b/doc/Expr.adoc index 7a5ba16..16f5ecf 100644 --- a/doc/Expr.adoc +++ b/doc/Expr.adoc @@ -79,20 +79,20 @@ Here are some examples of execution. # Type 'exit' or Ctrl+D to quit the program. [user]$ ./dev-expr -dev-expr -- Expressions calculator v1.10.0(build 14),2024/06/17 (celestino.amoroso@portale-stac.it) - Based on the Expr package v0.19.0 +dev-expr -- Expressions calculator v1.12.0(build 1),2024/09/14 (celestino.amoroso@portale-stac.it) + Based on the Expr package v0.26.0 Type help to get the list of available commands See also https://git.portale-stac.it/go-pkg/expr/src/branch/main/README.adoc >>> help --- REPL commands: - source -- Load a file as input - tty -- Enable/Disable ansi output <1> base -- Set the integer output base: 2, 8, 10, or 16 exit -- Exit the program help -- Show command list ml -- Enable/Disable multi-line output mods -- List builtin modules output -- Enable/Disable printing expression results. Options 'on', 'off', 'status' + source -- Load a file as input + tty -- Enable/Disable ansi output <1> --- Command line options: -b Import builtin modules. @@ -155,9 +155,9 @@ _Expr_ supports three type of numbers: . [blue]#Integers# . [blue]#Floats# -. [blue]#Factions# +. [blue]#Fractions# -In mixed operations involving integers, fractions and floats, automatic type promotion to the largest type take place. +In mixed operations involving integers, fractions and floats, automatic type promotion to the largest type is performed. ==== Integers __Expr__'s integers are a subset of the integer set. Internally they are stored as Golang _int64_ values. @@ -183,11 +183,11 @@ Value range: *-9223372036854775808* to *9223372036854775807* [cols="^1,^2,6,4"] |=== | Symbol | Operation | Description | Examples -| [blue]`+` | _sum_ | Add two values | [blue]`-1 + 2` -> 1 -| [blue]`-` | _subtraction_ | Subtract the right value from the left one | [blue]`3 - 1` -> 2 -| [blue]`*` | _product_ | Multiply two values | [blue]`-1 * 2` -> -2 -| [blue]`/` | _Division_ | Divide the left value by the right one^(*)^ | [blue]`-10 / 2` -> 5 -| [blue]`%` | _Modulo_ | Remainder of the integer division | [blue]`5 % 2` -> 1 +| [blue]`+` | _Sum_ | Add two values | [blue]`-1 + 2` -> _1_ +| [blue]`-` | _Subtraction_ | Subtract the right value from the left one | [blue]`3 - 1` -> _2_ +| [blue]`*` | _Product_ | Multiply two values | [blue]`-1 * 2` -> _-2_ +| [blue]`/` | _Integer division_ | Divide the left value by the right one^(*)^ | [blue]`-11 / 2` -> _-5_ +| [blue]`%` | _Modulo_ | Remainder of the integer division | [blue]`5 % 2` -> _1_ |=== ^(*)^ See also the _float division_ [blue]`./` below. @@ -228,11 +228,11 @@ _dec-seq_ = _see-integer-literal-syntax_ [cols="^1,^2,6,4"] |=== | Symbol | Operation | Description | Examples -| [blue]`+` | _sum_ | Add two values | [blue]`4 + 0.5` -> 4.5 -| [blue]`-` | _subtraction_ | Subtract the right value from the left one | [blue]`4 - 0.5` -> 3.5 -| [blue]`*` | _product_ | Multiply two values | [blue]`4 * 0.5` -> 2.0 -| [blue]`/` | _Division_ | Divide the left value by the right one | [blue]`1.0 / 2` -> 0.5 -| [blue]`./`| _Float division_ | Force float division | [blue]`-1 ./ 2` -> -0.5 +| [blue]`+` | _Sum_ | Add two values | [blue]`4 + 0.5` -> 4.5 +| [blue]`-` | _Subtraction_ | Subtract the right value from the left one | [blue]`4 - 0.5` -> 3.5 +| [blue]`*` | _Product_ | Multiply two values | [blue]`4 * 0.5` -> 2.0 +| [blue]`/` | _Float division_ | Divide the left value by the right one | [blue]`1.0 / 2` -> 0.5 +| [blue]`./`| _Forced float division_ | Force float division | [blue]`-1 ./ 2` -> -0.5 |=== ==== Fractions @@ -308,7 +308,7 @@ Strings are character sequences enclosed between two double quote [blue]`"`. `>>>` [blue]`"123\tabc"` + [green]`123{nbsp}{nbsp}{nbsp}{nbsp}abc` -Some arithmetic operators can also be used with strings. +Some arithmetic operators also apply to strings. .String operators [cols="^1,^2,6,4"] @@ -444,6 +444,7 @@ _non-empty-list_ = "**[**" _any-value_ {"**,**" _any-value_} "**]**" + | [blue]`[]` | _Item at index_ | Item at given position | [blue]`[1,2,3][1]` -> _2_ | [blue]`in` | _Item in list_ | True if item is in list | [blue]`2 in [1,2,3]` -> _true_ + [blue]`6 in [1,2,3]` -> _false_ +| [blue]`#` | _Size_ | Number of items in a list | [blue]`#[1,2,3]` -> _3_ |=== Array's items can be accessed using the index `[]` operator. @@ -458,10 +459,16 @@ Array's items can be accessed using the index `[]` operator. *_slice_* = _string-expr_ "**[**" _integer-expr_ "**:**" _integer-expr_ "**]**" ==== -.Items of list +.Examples: Getting items from lists `>>>` [blue]`[1,2,3][1]` + [green]`2` +`>>>` [blue]`index=2; ["a", "b", "c", "d"][index]` + +[green]`c` + +`>>>` [blue]`["a", "b", "c", "d"][2:]` + +[green]`["c", "d"]` + `>>>` [blue]`list=[1,2,3]; list[1]` + [green]`2` @@ -471,25 +478,44 @@ Array's items can be accessed using the index `[]` operator. `>>>` [blue]`list=["one","two","three"]; list[2-1]` + [green]`two` +`>>>` [blue]`list[1]="six"; list` + +[green]`["one", "six", "three"]` + `>>>` [blue]`list[-1]` + [green]`three` `>>>` [blue]`list[10]` + [red]`Eval Error: [1:9] index 10 out of bounds` +.Example: Number of elements in a list `>>>` [blue]`#list` + [green]`3` -`>>>` [blue]`index=2; ["a", "b", "c", "d"][index]` + -[green]`c` +.Examples: Element insertion +`>>>` [blue]`"first" >> list` + +[green]`["first", "one", "six", "three"]` +`>>>` [blue]`list << "last"` + +[green]`["first", "one", "six", "three", "last"]` + +.Examples: Element in list +`>>>` [blue]`"six" in list` + +[green]`true` + +`>>>` [blue]`"ten" in list` + +[green]`false` + +.Examples: Concatenation and filtering +`>>>` [blue]`[1,2,3] + ["one", "two", "three"]` + +[green]`[1, 2, 3, "one", "two", "three"]` + +`>>>` [blue]`[1,2,3,4] - [2,4]` + +[green]`[1, 3]` -`>>>` [blue]`["a", "b", "c", "d"][2:]` + -[green]`["c", "d"]` === Dictionaries -The _dictionary_, or _dict_, data-type is set of pairs _key/value_. It is also known as _map_ or _associative array_. +The _dictionary_, or _dict_, data-type represents sets of pairs _key/value_. It is also known as _map_ or _associative array_. Dictionary literals are sequences of pairs separated by comma [blue]`,` enclosed between brace brackets. @@ -515,6 +541,7 @@ _non-empty-dict_ = "**{**" _key-scalar_ "**:**" _any-value_ {"**,**" _key-scalar | [blue]`[]` | _Dict item value_ | Item value of given key | [blue]`{"one":1, "two":2}["two"]` -> _2_ | [blue]`in` | _Key in dict_ | True if key is in dict | [blue]`"one" in {"one":1, "two":2}` -> _true_ + [blue]`"six" in {"one":1, "two":2}` -> _false_ +| [blue]`#` | _Size_ | Number of items in a dict | [blue]`#{1:"a",2:"b",3:"c"}` -> _3_ |=== .Examples @@ -533,6 +560,9 @@ _non-empty-dict_ = "**{**" _key-scalar_ "**:**" _any-value_ {"**,**" _key-scalar `>>>` [blue]`d={"one":1, "two":2}; d["six"]=6; d` + [green]`{"two": 2, "one": 1, "six": 6}` +`>>>` [blue]`#d` + +[green]`3` + == Variables _Expr_, like most programming languages, supports variables. A variable is an identifier with an assigned value. Variables are stored in _contexts_. @@ -556,7 +586,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 typical approximation error of the float data-type_ + +`>>>` [blue]`x = 5.2 * (9-3)` [gray]_// The assigned value here has the typical approximation error of the float data-type_ + [green]`31.200000000000003` `>>>` [blue]`x = 1; y = 2*x` + @@ -664,8 +694,8 @@ The [blue]`:` symbol (colon) is the separator of the selector-cases. Note that i [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 defined; otherwise they return the value of the right expression. +=== Variable default value [blue]`??`, [blue]`?=`, and [blue]`?!` +The left operand of 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. IMPORTANT: If the left variable is defined, the right expression is not evaluated at all. @@ -673,6 +703,10 @@ 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 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. + .Examples `>>>` [blue]`var ?? (1+2)` + [green]`3` diff --git a/doc/Expr.html b/doc/Expr.html index f7024c8..be79850 100644 --- a/doc/Expr.html +++ b/doc/Expr.html @@ -567,7 +567,7 @@ pre.rouge .ss {
  • 4.2. but operator
  • 4.3. Assignment operator =
  • 4.4. Selector operator ? : ::
    • -
  • 4.5. Variable default value ?? and ?=
    • +
  • 4.5. Variable default value ??, ?=, and ?!
  • 5. Priorities of operators
    • @@ -687,20 +687,20 @@ pre.rouge .ss { 
    # Type 'exit' or Ctrl+D to quit the program.
 
 [user]$ ./dev-expr
-dev-expr -- Expressions calculator v1.10.0(build 14),2024/06/17 (celestino.amoroso@portale-stac.it)
-	Based on the Expr package v0.19.0
+dev-expr -- Expressions calculator v1.12.0(build 1),2024/09/14 (celestino.amoroso@portale-stac.it)
+	Based on the Expr package v0.26.0
 	Type help to get the list of available commands
 	See also https://git.portale-stac.it/go-pkg/expr/src/branch/main/README.adoc
 >>> help
 --- REPL commands:
-      source -- Load a file as input
-         tty -- Enable/Disable ansi output (1)
         base -- Set the integer output base: 2, 8, 10, or 16
         exit -- Exit the program
         help -- Show command list
           ml -- Enable/Disable multi-line output
         mods -- List builtin modules
       output -- Enable/Disable printing expression results. Options 'on', 'off', 'status'
+      source -- Load a file as input
+         tty -- Enable/Disable ansi output (1)
 
 --- Command line options:
     -b <builtin>       Import builtin modules.
@@ -805,12 +805,12 @@ dev-expr -- Expressions calculator v1.10.0Floats
    
 
 
  • 
-
    Factions
    
+
    Fractions
    
 
    • 
 
 
 
    
-
    In mixed operations involving integers, fractions and floats, automatic type promotion to the largest type take place.
    
+
    In mixed operations involving integers, fractions and floats, automatic type promotion to the largest type is performed.
    
 
    
 
    
 
    2.1.1. Integers
    
@@ -855,33 +855,33 @@ dev-expr -- Expressions calculator v1.10.0
    +
    
-
    sum
    
+
    Sum
    
 
    Add two values
    
-
    -1 + 2 → 1
    
+
    -1 + 2 → 1
    
 
 
 
    -
    
-
    subtraction
    
+
    Subtraction
    
 
    Subtract the right value from the left one
    
-
    3 - 1 → 2
    
+
    3 - 1 → 2
    
 
 
 
    *
    
-
    product
    
+
    Product
    
 
    Multiply two values
    
-
    -1 * 2 → -2
    
+
    -1 * 2 → -2
    
 
 
 
    /
    
-
    Division
    
+
    Integer division
    
 
    Divide the left value by the right one(*)
    
-
    -10 / 2 → 5
    
+
    -11 / 2 → -5
    
 
 
 
    %
    
 
    Modulo
    
 
    Remainder of the integer division
    
-
    5 % 2 → 1
    
+
    5 % 2 → 1
    
 
 
 
@@ -946,31 +946,31 @@ dev-expr -- Expressions calculator v1.10.0
    +
    
-
    sum
    
+
    Sum
    
 
    Add two values
    
 
    4 + 0.5 → 4.5
    
 
 
 
    -
    
-
    subtraction
    
+
    Subtraction
    
 
    Subtract the right value from the left one
    
 
    4 - 0.5 → 3.5
    
 
 
 
    *
    
-
    product
    
+
    Product
    
 
    Multiply two values
    
 
    4 * 0.5 → 2.0
    
 
 
 
    /
    
-
    Division
    
+
    Float division
    
 
    Divide the left value by the right one
    
 
    1.0 / 2 → 0.5
    
 
 
 
    ./
    
-
    Float division
    
+
    Forced float division
    
 
    Force float division
    
 
    -1 ./ 2 → -0.5
    
 
@@ -1074,7 +1074,7 @@ dev-expr -- Expressions calculator v1.10.0123    abc
    
 
    
 
    
-
    Some arithmetic operators can also be used with strings.
    
+
    Some arithmetic operators also apply to strings.
    
 
    
 
@@ -1393,6 +1393,12 @@ dev-expr -- Expressions calculator v1.10.0
    2 in [1,2,3] → true
    
 6 in [1,2,3] → false
    
 
+    
+
+
+
+
+
    
 Table 3. String operators
    #
    Size
    Number of items in a list
    #[1,2,3] → 3
    
     
 
    
 
    
@@ -1415,11 +1421,19 @@ dev-expr -- Expressions calculator v1.10.0
-
    Items of list
    
+
    Examples: Getting items from lists
    
 
    >>> [1,2,3][1]
    
 2
    
 
    
 
    
+
    >>> index=2; ["a", "b", "c", "d"][index]
    
+c
    
+
    
+
    
+
    >>> ["a", "b", "c", "d"][2:]
    
+["c", "d"]
    
+
    
+
    
 
    >>> list=[1,2,3]; list[1]
    
 2
    
 
    
@@ -1432,6 +1446,10 @@ dev-expr -- Expressions calculator v1.10.0two
    
 
 
    
+
    >>> list[1]="six"; list
    
+["one", "six", "three"]
    
+
    
+
    
 
    >>> list[-1]
    
 three
    
 
    
@@ -1440,22 +1458,42 @@ dev-expr -- Expressions calculator v1.10.0Eval Error: [1:9] index 10 out of bounds
    
 
 
    
+
    Example: Number of elements in a list
    
 
    >>> #list
    
 3
    
 
    
 
    
-
    >>> index=2; ["a", "b", "c", "d"][index]
    
-c
    
+
    Examples: Element insertion
    
+
    >>> "first" >> list
    
+["first", "one", "six", "three"]
    
 
    
 
    
-
    >>> ["a", "b", "c", "d"][2:]
    
-["c", "d"]
    
+
    >>> list << "last"
    
+["first", "one", "six", "three", "last"]
    
+
    
+
    
+
    Examples: Element in list
    
+
    >>> "six" in list
    
+true
    
+
    
+
    
+
    >>> "ten" in list
    
+false
    
+
    
+
    
+
    Examples: Concatenation and filtering
    
+
    >>> [1,2,3] + ["one", "two", "three"]
    
+[1, 2, 3, "one", "two", "three"]
    
+
    
+
    
+
    >>> [1,2,3,4] - [2,4]
    
+[1, 3]
    
 
    
 
 
    
 
    2.5. Dictionaries
    
 
    
-
    The dictionary, or dict, data-type is set of pairs key/value. It is also known as map or associative array.
    
+
    The dictionary, or dict, data-type represents sets  of pairs key/value. It is also known as map or associative array.
    
 
    
 
    
 
    Dictionary literals are sequences of pairs separated by comma , enclosed between brace brackets.
    
@@ -1514,6 +1552,12 @@ dev-expr -- Expressions calculator v1.10.0
    "one" in {"one":1, "two":2} → true
    
 "six" in {"one":1, "two":2} → false
    
 
+
+
    #
    
+
    Size
    
+
    Number of items in a dict
    
+
    #{1:"a",2:"b",3:"c"} → 3
    
+
 
 
 
    
@@ -1537,6 +1581,10 @@ dev-expr -- Expressions calculator v1.10.0d={"one":1, "two":2}; d["six"]=6; d
    
 {"two": 2, "one": 1, "six": 6}
    
 
    
+
    
+
    >>> #d
    
+3
    
+
    
 
    
 
    
 
@@ -1582,7 +1630,7 @@ The assign operator = returns the value assigned to th
 3
    
 
 
    
-
    >>> x = 5.2 * (9-3)  // The assigned value has the typical approximation error of the float data-type
    
+
    >>> x = 5.2 * (9-3)  // The assigned value here has the typical approximation error of the float data-type
    
 31.200000000000003
    
 
    
 
    
@@ -1751,9 +1799,9 @@ Technically ; is not treated as a real operator. It ac
 
    
 
 
    
-
    4.5. Variable default value ?? and ?=
    
+
    4.5. Variable default value ??, ?=, and ?!
    
 
    
-
    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.
    
+
    The left operand of first two operators, ?? and ?=, 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.
    
 
    
 
    
 
@@ -1774,6 +1822,21 @@ If the left variable is defined, the right expression is not evaluated at all.
 
    The ?= assigns the calculated value of the right expression to the left variable.
    
+
    The third one, ?!, is the alternate operator. If the variable on the left size is not defined, it returns nil. Otherwise it returns the result of the expressione on the right side.
    
+
    
+
    
+
    
 
 
    
+
+
+
+
+
    
+
+
+If the left variable is NOT defined, the right expression is not evaluated at all.
+
    
+
    
+
    
 
    Examples
    
 
    >>> var ?? (1+2)
    
 3
    
@@ -2204,7 +2267,7 @@ These operators have a high priority, in particular higher than the operator