From 3b641ac7931655bf86a882b72ea2f64035695332 Mon Sep 17 00:00:00 2001 From: Celestino Amoroso Date: Fri, 21 Jun 2024 09:06:25 +0200 Subject: [PATCH] Doc: little changes --- doc/Expr.adoc | 86 +++++++++++++++++++++--------- doc/Expr.html | 144 ++++++++++++++++++++++++++++++++++++++------------ 2 files changed, 173 insertions(+), 57 deletions(-) diff --git a/doc/Expr.adoc b/doc/Expr.adoc index 9cc90c7..a579344 100644 --- a/doc/Expr.adoc +++ b/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 diff --git a/doc/Expr.html b/doc/Expr.html index 33b15af..a36166c 100644 --- a/doc/Expr.html +++ b/doc/Expr.html @@ -573,8 +573,9 @@ pre.rouge .ss {
  • 5. Priorities of operators
  • 6. Functions
  • 7. Iterators
    • @@ -593,7 +594,7 @@ pre.rouge .ss {
    -

    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.)

    @@ -1581,7 +1582,7 @@ The assign operator = returns the value assigned to th 3

    -

    >>> x = 5.2 * (9-3) // The assigned value has the approximation error typical of the float data-type
    +

    >>> x = 5.2 * (9-3) // The assigned value has the typical approximation error of the float data-type
    31.200000000000003

    @@ -1606,6 +1607,14 @@ The assign operator = returns the value assigned to th

    The semicolon operator ; 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.

    +
    +
    Example 12. Mult-expression syntax
    +
    +
    +

    multi-expression = expression {";" expression }

    +
    +
    +

    An expression that contains ; is called a multi-expression and each component expressione is called a sub-expression.

    @@ -1704,25 +1713,37 @@ Technically ; is not treated as a real operator. It ac
    Examples

    >>> 1 ? {"a"} : {"b"}
    -b
    ->>> 10 ? {"a"} : {"b"} :: {"c"}
    -c'
    -[green]    >>>` 10 ? {"a"} :[true, 2+8] {"b"} :: {"c"}
    -b
    ->>> 10 ? {"a"} :[true, 2+8] {"b"} ::[10] {"c"}
    -Parse Error: [1:34] case list in default clause
    ->>> 10 ? {"a"} :[10] {x="b" but x} :: {"c"}
    -b
    ->>> 10 ? {"a"} :[10] {x="b"; x} :: {"c"}
    -b
    ->>> 10 ? {"a"} : {"b"}
    +b

    +
    +
    +

    >>> 10 ? {"a"} : {"b"} :: {"c"}
    +c

    +
    +
    +

    >>> 10 ? {"a"} :[true, 2+8] {"b"} :: {"c"}
    +b

    +
    +
    +

    >>> 10 ? {"a"} :[true, 2+8] {"b"} :: [10] {"c"}
    +Parse Error: [1:34] case list in default clause

    +
    +
    +

    >>> 10 ? {"a"} :[10] {x="b" but x} :: {"c"}
    +b

    +
    +
    +

    >>> 10 ? {"a"} :[10] {x="b"; x} :: {"c"}
    +b

    +
    +
    +

    >>> 10 ? {"a"} : {"b"}
    Eval Error: [1:3] no case catches the value (10) of the selection expression

    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 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.

    @@ -1731,26 +1752,32 @@ Technically ; is not treated as a real operator. It ac
    -If the left variable is defined, the right expression is not evuated at all. +If the left variable is defined, the right expression is not evaluated at all.
    -

    The ?? do not change the status of the left variable.

    +

    The ?? operator do not change the status of the left variable.

    The ?= assigns the calculated value of the right expression to the left variable.

    Examples
    -

    >>> var ?? (1+2)’ -[green]`3
    ->>> var
    -Eval Error: undefined variable or function "var"
    ->>> var ?= (1+2)
    -3
    ->>> var
    +

    >>> var ?? (1+2)’
    +[green]`3

    +
    +
    +

    >>> var
    +Eval Error: undefined variable or function "var"

    +
    +
    +

    >>> var ?= (1+2)
    +3

    +
    +
    +

    >>> var 3

    @@ -1820,6 +1847,26 @@ These operators have a high priority, in particular higher than the operator

    iterator ++ → any

    +

    DEFAULT

    +

    ??

    +

    Infix

    +

    Default value

    +

    variable ?? any-expr → any

    + + +

    ?=

    +

    Infix

    +

    Default/assign value

    +

    variable ?= any-expr → any

    + + +

    ITER1

    +

    ()

    +

    Prefix

    +

    Iterator value

    +

    () iterator → any

    + +

    FACT

    !

    Postfix

    @@ -2050,6 +2097,9 @@ These operators have a high priority, in particular higher than the operator +
    +

    1 Experimental

    +
    @@ -2068,19 +2118,47 @@ These operators have a high priority, in particular higher than the operator
    +
    +

    6.1. Expr function definition

    -

    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 @ it is possibile to export local definition to the calling context.

    +

    A function is identified and referenced by its name. It can have zero or more parameter. Expr functions also support optional parameters.

    +
    +
    +
      +
    1. +

      Expr’s function definition syntax

      +
      2. +
    +
    +
    +
    +
    +

    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

    +
    -

    6.1. Function calls

    +

    6.2. 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.

    +
    +
    +
    +

    6.3. Function calls

    TODO: function calls operations

    -
    -
    -

    6.2. 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 @ it is possibile to export local definition to the calling context.

    @@ -2122,7 +2200,7 @@ These operators have a high priority, in particular higher than the operator