Doc: more details on the syntax of the dictionaries, variables and multi-expressions
This commit is contained in:
+81
-44
@@ -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>"."<index-expr>
|
||||
----
|
||||
====
|
||||
_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.
|
||||
|
||||
Reference in New Issue
Block a user