From ac3e690f872dd8b53379b35f623c57b683d46a3e Mon Sep 17 00:00:00 2001 From: Celestino Amoroso Date: Fri, 17 May 2024 07:31:13 +0200 Subject: [PATCH] Doc: more details on the syntax of the dictionaries, variables and multi-expressions --- doc/Expr.adoc | 125 +++++++++++++++++++----------- doc/Expr.html | 205 +++++++++++++++++++++++++++++++++----------------- 2 files changed, 215 insertions(+), 115 deletions(-) diff --git a/doc/Expr.adoc b/doc/Expr.adoc index 9f6e273..7f44809 100644 --- a/doc/Expr.adoc +++ b/doc/Expr.adoc @@ -22,7 +22,7 @@ Expressions calculator toc::[] -#TODO: Work in progress (last update on 2024/05/16, 7:08 a.m.)# +#TODO: Work in progress (last update on 2024/05/17, 7:30 a.m.)# == Expr _Expr_ is a GO package capable of analysing, interpreting and calculating expressions. @@ -44,7 +44,7 @@ Here are some examples of execution. .Run `dev-expr` in REPL mode and ask for help [source,shell] ---- -# Assume the expr source directory. Type 'exit' or Ctrl+D to quit the program. +# Type 'exit' or Ctrl+D to quit the program. [user]$ ./dev-expr expr -- Expressions calculator v1.7.1(build 2),2024/05/16 (celestino.amoroso@portale-stac.it) @@ -235,6 +235,7 @@ _digit-seq_ = _see-integer-literal-syntax_ + Fractions can be used together with integers and floats in expressions. +.Examples `>>>` [blue]`1|2 + 5` + [green]`11|2` + `>>>` [blue]`4 - 1|2` + @@ -290,7 +291,7 @@ _item_ = _string-expr_ "**.**" _integer-expr_ `>>>` [blue]`#"abc"` [gray]_number of chars_ + [green]`3` + -=== Boolean +=== Booleans Boolean data type has two values only: [blue]_true_ and [blue]_false_. Relational and boolean expressions result in boolean values. .Relational operators @@ -341,35 +342,42 @@ Currently, boolean operations are evaluated using _short cut evaluation_. This m ==== === Lists -_Expr_ supports list of mixed-type values, also specified by normal expressions. +_Expr_ supports list of mixed-type values, also specified by normal expressions. Internally, _Expr_'s lists are Go arrays. -.List examples -[source,go] ----- -[1, 2, 3] // List of integers -["one", "two", "three"] // List of strings -["one", 2, false, 4.1] // List of mixed-types -["one"+1, 2.0*(9-2)] // List of expressions -[ [1,"one"], [2,"two"]] // List of lists ----- +.List literal syntax +==== +*_list_* = _empty-list_ | _non-empty-list_ + +_empty-list_ = "**[]**" + +_non-empty-list_ = "**[**" _any-value_ {"**,**" _any-value} "**]**" + +==== + +.Examples +`>>>` [blue]`[1,2,3]` [gray]_// List of integers_ + +[green]`[1, 2, 3]` + +`>>>` [blue]`["one", "two", "three"]` [gray]_// List of strings_ + +[green]`["one", "two", "three"]` + +`>>>` [blue]`["one", 2, false, 4.1]` [gray]_// List of mixed-types_ + +[green]`["one", 2, false, 4.1]` + +`>>>` [blue]`["one"+1, 2.0*(9-2)]` [gray]_// List of expressions_ + +[green]`["one1", 14]` + +`>>>` [blue]`[ [1,"one"], [2,"two"]]` [gray]_// List of lists_ + +[green]`[[1, "one"], [2, "two"]]` .List operators [cols="^2,^2,5,4"] |=== | Symbol | Operation | Description | Examples -| [blue]`+` | _Join_ | Joins two lists | [blue]`[1,2] + [3]` _[ [1,2,3] ]_ - -| [blue]`-` | _Difference_ | Left list without elements in the right list | [blue]`[1,2,3] - [2]` _[ [1,3] ]_ +| [blue]`+` | _Join_ | Joins two lists | [blue]`[1,2] + [3]` -> _[1,2,3]_ +| [blue]`-` | _Difference_ | Left list without elements in the right list | [blue]`[1,2,3] - [2]` -> _[1,3]_ |=== The items of array can be accessed using the dot `.` operator. .Item access syntax -[source,bnf] ----- - ::= "." ----- +==== +_item_ = _list-expr_ "**.**" _list-expr_ +==== .Items of list `>>>` [blue]`[1,2,3].1` + @@ -389,44 +397,73 @@ The items of array can be accessed using the dot `.` operator. -== Dictionaries -The _dictionary_ data-type is set of pairs _key/value_. It is also known as _map_ or _associative array_. Dictionary literals are sequences of pairs separated by comma `,`; sequences are enclosed between brace brackets. - -.Dictionary examples -[source,go] ----- -{1:"one", 2:"two"} -{"one":1, "two": 2} -{"sum":1+2+3, "prod":1*2*3} ----- - +=== Dictionaries WARNING: Support for dictionaries is still ongoing. -== Variables -A variable is an identifier with an assigned value. Variables are stored in the object that implements the Go _ExprContext_ interface, e.g. _SimpleVarStore_ or _SimpleFuncStore_. +The _dictionary_, or _dict_, data-type is set of pairs _key/value_. It is also known as _map_ or _associative array_. Dictionary literals are sequences of pairs separated by comma `,`; sequences are enclosed between brace brackets. + +.Dict literal syntax +==== +*_dict_* = _empty-dict_ | _non-empty-dict_ + +_empty-dict_ = "**{}**" + +_non-empty-dict_ = "**{**" _key-scalar_ "**:**" _any-value_ {"**,**" _key-scalar_ "**:**" _any-value} "**}**" + +==== .Examples -[source,go] ----- -a=1 -x = 5.2 * (9-3) -x = 1; y = 2*x ----- +`>>>` [blue]`{1:"one", 2:"two"}` + +`>>>` [blue]`{"one":1, "two": 2}` + +`>>>` [blue]`{"sum":1+2+3, "prod":1*2*3}` + +== Variables +_Expr_ supports variables like most programming languages. A variable is an identifier with an assigned value. Variables are stored in _contexts_. + +.Variable literal syntax +==== +*_variable_* = _identifier_ "*=*" _any-value_ + +_identifier_ = _alpha_ {(_alpha_)|_dec-digit_|"*_*"} + +__alpha__ = "*a*"|"*b*"|..."*z*"|"*A*"|"*B*"|..."*Z*" +==== + +NOTE: The assign operator [blue]`=` returns the value assigned to the variable. + +.Examples +`>>>` [blue]`a=1` + +[green]`1` + +`>>>` [blue]`a_b=1+2` + +[green]`1+2` + +`>>>` [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_ + +[green]`31.200000000000003` + +`>>>` [blue]`x = 1; y = 2*x` + +[green]`2` + +`>>>` [blue]`_a=2` + +[red]`Parse Error: [1:2] unexpected token "_"` + +`>>>` [blue]`1=2` + +[red]`Parse Error: assign operator ("=") must be preceded by a variable` + == Other operations === [blue]`;` operator -The semicolon operator [blue]`;` is an infixed pseudo-operator. It evaluates the left expression first and then the right expression. The latter is the final result. +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. + +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. TIP: [blue]`;` can be used to set some variables before the final calculation. .Example -[source,go] ----- -a=1; b=2; c=3; a+b+c // returns 6 ----- +`>>>` [blue]`a=1; b=2; c=3; a+b+c` + +[green]`6` + +The value of each sub-expression is stored in the automatica variable _last_. + +.Example +`>>>` [blue]`2+3; b=last+10; last` + +[green]`15` + === [blue]`but` operator [blue]`but` is an infixed operator. Its operands can be expressions of any type. It evaluates the left expression first, then the right expression. The value of the right expression is the final result. Examples: [blue]`5 but 2` returns 2, [blue]`x=2*3 but x-1` returns 5. diff --git a/doc/Expr.html b/doc/Expr.html index 8e67358..2083ed1 100644 --- a/doc/Expr.html +++ b/doc/Expr.html @@ -549,31 +549,31 @@ pre.rouge .ss {
  • 2.2. Strings
    • -
  • 2.3. Boolean
    • +
  • 2.3. Booleans
  • 2.4. Lists
    • +
  • 2.5. Dictionaries
    • -
  • 3. Dictionaries
    • -
  • 4. Variables
    • -
  • 5. Other operations +
  • 3. Variables
    • +
  • 4. Other operations
    • -
  • 6. Priorities of operators
    • -
  • 7. Functions +
  • 5. Priorities of operators
    • +
  • 6. Functions
    • -
  • 8. Builtins +
  • 7. Builtins
    • @@ -584,7 +584,7 @@ pre.rouge .ss {
    -

    TODO: Work in progress (last update on 2024/05/16, 7:08 a.m.)

    +

    TODO: Work in progress (last update on 2024/05/17, 7:30 a.m.)

    @@ -622,7 +622,7 @@ pre.rouge .ss {
    Run dev-expr in REPL mode and ask for help
    -
    # Assume the expr source directory. Type 'exit' or Ctrl+D to quit the program.
+
    # Type 'exit' or Ctrl+D to quit the program.
 
 [user]$ ./dev-expr
 expr -- Expressions calculator v1.7.1(build 2),2024/05/16 (celestino.amoroso@portale-stac.it)
@@ -947,6 +947,7 @@ pre.rouge .ss {
 
    Fractions can be used together with integers and floats in expressions.
    +
    Examples

    >>> 1|2 + 5
    11|2
    >>> 4 - 1|2
    @@ -1034,7 +1035,7 @@ pre.rouge .ss {

    -

    2.3. Boolean

    +

    2.3. Booleans

    Boolean data type has two values only: true and false. Relational and boolean expressions result in boolean values.

    @@ -1171,18 +1172,31 @@ pre.rouge .ss {

    2.4. Lists

    -

    Expr supports list of mixed-type values, also specified by normal expressions.

    +

    Expr supports list of mixed-type values, also specified by normal expressions. Internally, Expr's lists are Go arrays.

    -
    -
    List examples
    +
    +
    Example 5. List literal syntax
    -
    [1, 2, 3]                   // List of integers
-["one", "two", "three"]     // List of strings
-["one", 2, false, 4.1]      // List of mixed-types
-["one"+1, 2.0*(9-2)]        // List of expressions
-[ [1,"one"], [2,"two"]]     // List of lists
    +
    +

    list = empty-list | non-empty-list
    +empty-list = "[]"
    +non-empty-list = "[" any-value {"," _any-value} "]"

    +
    +
    +
    Examples
    +

    >>> [1,2,3] // List of integers
    +[1, 2, 3]
    +>>> ["one", "two", "three"] // List of strings
    +["one", "two", "three"]
    +>>> ["one", 2, false, 4.1] // List of mixed-types
    +["one", 2, false, 4.1]
    +>>> ["one"+1, 2.0*(9-2)] // List of expressions
    +["one1", 14]
    +>>> [ [1,"one"], [2,"two"]] // List of lists
    +[[1, "one"], [2, "two"]]

    +
    @@ -1204,23 +1218,25 @@ pre.rouge .ss { - + - +
    Table 6. List operators

    +

    Join

    Joins two lists

    [1,2] + [3] [ [1,2,3] ]

    [1,2] + [3] → [1,2,3]

    -

    Difference

    Left list without elements in the right list

    [1,2,3] - [2] [ [1,3] ]

    [1,2,3] - [2] → [1,3]

    The items of array can be accessed using the dot . operator.

    -
    -
    Item access syntax
    +
    +
    Example 6. Item access syntax
    -
    <item> ::= <list-expr>"."<index-expr>
    +
    +

    item = list-expr "." list-expr

    +
    @@ -1241,22 +1257,8 @@ pre.rouge .ss { 3

    -
    -
    -
    -

    3. Dictionaries

    -
    -
    -

    The dictionary data-type is set of pairs key/value. It is also known as map or associative array. Dictionary literals are sequences of pairs separated by comma ,; sequences are enclosed between brace brackets.

    -
    -
    -
    Dictionary examples
    -
    -
    {1:"one", 2:"two"}
-{"one":1, "two": 2}
-{"sum":1+2+3, "prod":1*2*3}
    -
    -
    +
    +

    2.5. Dictionaries

    @@ -1269,31 +1271,85 @@ Support for dictionaries is still ongoing.
    +
    +

    The dictionary, or dict, data-type is set of pairs key/value. It is also known as map or associative array. Dictionary literals are sequences of pairs separated by comma ,; sequences are enclosed between brace brackets.

    +
    +
    +
    Example 7. Dict literal syntax
    +
    +
    +

    dict = empty-dict | non-empty-dict
    +empty-dict = "{}"
    +non-empty-dict = "{" key-scalar ":" any-value {"," key-scalar ":" _any-value} "}"

    +
    +
    +
    +
    +
    Examples
    +

    >>> {1:"one", 2:"two"}
    +>>> {"one":1, "two": 2}
    +>>> {"sum":1+2+3, "prod":1*2*3}

    +
    +
    -

    4. Variables

    +

    3. Variables

    -

    A variable is an identifier with an assigned value. Variables are stored in the object that implements the Go ExprContext interface, e.g. SimpleVarStore or SimpleFuncStore.

    +

    Expr supports variables like most programming languages. A variable is an identifier with an assigned value. Variables are stored in contexts.

    -
    -
    Examples
    +
    +
    Example 8. Variable literal syntax
    -
    a=1
-x = 5.2 * (9-3)
-x = 1; y = 2*x
    +
    +

    variable = identifier "=" any-value
    +identifier = alpha {(alpha)|dec-digit|"_"}
    +alpha = "a"|"b"|…​"z"|"A"|"B"|…​"Z"

    +
    + + + + + +
    + + +The assign operator = returns the value assigned to the variable. +
    +
    +
    +
    Examples
    +

    >>> a=1
    +1
    +>>> a_b=1+2
    +1+2
    +>>> a_b
    +3
    +>>> x = 5.2 * (9-3) // The assigned value has the approximation error typical of the float data-type
    +31.200000000000003
    +>>> x = 1; y = 2*x
    +2
    +>>> a=2
    +Parse Error: [1:2] unexpected token "    "
    +>>> 1=2
    +Parse Error: assign operator ("=") must be preceded by a variable

    +
    +
    -

    5. Other operations

    +

    4. Other operations

    -

    5.1. ; operator

    +

    4.1. ; operator

    -

    The semicolon operator ; is an infixed pseudo-operator. It evaluates the left expression first and then the right expression. The latter is the final result.

    +

    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.

    +
    +
    +

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

    @@ -1319,15 +1375,22 @@ Technically ; is not treated as a real operator. It ac
    -
    +
    Example
    -
    -
    a=1; b=2; c=3; a+b+c    // returns 6
    +

    >>> a=1; b=2; c=3; a+b+c
    +6

    +
    +

    The value of each sub-expression is stored in the automatica variable last.

    +
    +
    +
    Example
    +

    >>> 2+3; b=last+10; last
    +15

    -

    5.2. but operator

    +

    4.2. but operator

    but is an infixed operator. Its operands can be expressions of any type. It evaluates the left expression first, then the right expression. The value of the right expression is the final result. Examples: 5 but 2 returns 2, x=2*3 but x-1 returns 5.

    @@ -1336,7 +1399,7 @@ Technically ; is not treated as a real operator. It ac
    -

    5.3. Assignment operator =

    +

    4.3. Assignment operator =

    The assignment operator = is used to define variables in the evaluation context or to change their value (see ExprContext). The value on the left side of = must be an identifier. The value on the right side can be any expression and it becomes the result of the assignment operation.

    @@ -1349,7 +1412,7 @@ The value on the left side of = must be an identifier.
    -

    5.4. Selector operator ? : ::

    +

    4.4. Selector operator ? : ::

    The selector operator is very similar to the switch/case/default statement available in many programming languages.

    @@ -1397,7 +1460,7 @@ The value on the left side of = must be an identifier.
    -

    6. Priorities of operators

    +

    5. Priorities of operators

    The table below shows all supported operators by decreasing priorities.

    @@ -1618,7 +1681,7 @@ The value on the left side of = must be an identifier.
    -

    7. Functions

    +

    6. Functions

    Functions in Expr are very similar to functions in many programming languages.

    @@ -1627,13 +1690,13 @@ The value on the left side of = must be an identifier.

    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.

    -

    7.1. Function calls

    +

    6.1. Function calls

    TODO: function calls operations

    -

    7.2. Function definitions

    +

    6.2. Function definitions

    TODO: function definitions operations

    @@ -1641,17 +1704,17 @@ The value on the left side of = must be an identifier.
    -

    8. Builtins

    +

    7. Builtins

    TODO: builtins

    -

    8.1. Builtin functions

    +

    7.1. Builtin functions

    -

    8.2. import()

    +

    7.2. import()

    import(<source-file>) loads the multi-expression contained in the specified source and returns its value.

    @@ -1661,7 +1724,7 @@ The value on the left side of = must be an identifier.