diff --git a/doc/Expr.adoc b/doc/Expr.adoc index 9cb7326..6759796 100644 --- a/doc/Expr.adoc +++ b/doc/Expr.adoc @@ -22,18 +22,45 @@ Expressions calculator toc::[] -#TODO: Work in progress (last update on 2024/06/02, 08:18 a.m.)# +#TODO: Work in progress (last update on 2024/06/17, 16:31 a.m.)# == Expr _Expr_ is a GO package capable of analysing, interpreting and calculating expressions. + === Concepts and terminology -#TODO# + +Expressions are texts containing sequences of operations represented by a syntax very similar to that of most programming languages. _Expr_ package provides these macro functions: + +* *_Scanner_* -- Its input is a text. It scans expression text characters to produce a flow of logical symbol and related attributes, aka tokens. +* *_Parser_* -- Parser input is the token flow coming from the scanner. It analyses the token flow verifyng if it complies with the _Expr_ syntax. If that is the case, the Parser generates the Abstract Syntax Tree (AST). This is tree data structure that represents the components of an expressions and how they are related one each other. +* *_Calculator_*. Its input is the AST. It computes the parsed expression contained in the AST and returns the result or an error. image::expression-diagram.png[] +==== Variables +_Expr_ supports variables. The result of an expression can be stored in a variable and reused in other espressions simply specifying the name of the variable as an operand. + +==== Multi-expression +An input text valid for _Expr_ can contain more than an expression. Expressions are separated by [blue]`;` (semicolon). When an input contains two or more expressions it is called _multi-expression_. + +_Expr_ parses and computes each expression of a multi-espression, from the left to the right. If all expressions are computed without errors, it only returns the value of the last, the right most. + +The result of each expression of a multi-expression is stored in an automatic variable named _last_. In this way, each expression can refer to the result of the previous one without the need to assign that value to a new dedicated variable. + +==== Calculation context +All objects, such as variables and functions, created during the calculation of an expression are stored in a memory called _context_. + +The expression context is analogous to the stack-frame of other programming languages. When a function is called, a new context is allocated to store local definitions. + +Function contexts are created by cloning the calling context. More details on this topic are given later in this document. + +_Expr_ creates and keeps a inner _global context_ where it stores imported functions, either from builtin or plugin modules. To perform calculations, the calling program must provide its own context; this is the _main context_. All calculations take place in this context. As mentioned eralier, when a function is called, a new context is created by cloning the calling context. The createt context can be called _function context_. + +Imported functions are registerd in the _global context_. When an expression first calls an imported function, that function is linked to the current context; this can be the _main context_ or a _function context_. + === `dev-expr` test tool -`dev-expr` is a simple program that can be used to evaluate expressions interactively. As its name suggests, it was created for testing purpose. In fact, in additon to the automatic verification test suite based on the Go test framework, `dev-expr` provides an important aid for quickly testing of new features during their development. +`dev-expr` is a simple program that can be used to evaluate expressions interactively. As its name suggests, it was created for testing purpose. In fact, in additon to the automatic verification test suite based on the Go test framework, `dev-expr` provided an important aid for quickly testing of new features during their development. `dev-expr` can work as a _REPL_, _**R**ead-**E**xecute-**P**rint-**L**oop_, or it can process expression acquired from files or standard input. @@ -47,11 +74,10 @@ Here are some examples of execution. # 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) - Based on the Expr package v0.10.0 +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 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 @@ -61,6 +87,7 @@ expr -- Expressions calculator v1.7.1(build 2),2024/05/16 (celestino.amoroso@por help -- Show command list ml -- Enable/Disable multi-line output mods -- List builtin modules + output -- Enable/Disable printing expression results. Options 'on', 'off', 'status' --- Command line options: -b Import builtin modules. @@ -70,9 +97,10 @@ expr -- Expressions calculator v1.7.1(build 2),2024/05/16 (celestino.amoroso@por -i Force REPL operation when all -e occurences have been processed -h, --help, help Show this help menu -m, --modules List all builtin modules + --noout Disable printing of expression results -p Print prefix form -t Print tree form <2> - + -v, --version Show program version >>> ---- @@ -83,8 +111,8 @@ expr -- Expressions calculator v1.7.1(build 2),2024/05/16 (celestino.amoroso@por [source,shell] ---- [user]$ ./dev-expr -expr -- Expressions calculator v1.7.1(build 2),2024/05/16 (celestino.amoroso@portale-stac.it) - Based on the Expr package v0.10.0 +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 Type help to get the list of available commands See also https://git.portale-stac.it/go-pkg/expr/src/branch/main/README.adoc @@ -101,21 +129,21 @@ expr -- Expressions calculator v1.7.1(build 2),2024/05/16 (celestino.amoroso@por 7 - 6 ->>> 1+2 but 5|2+0.5 <4> +>>> 4+2 but 5|2+0.5 <4> 3 ->>> 1+2; 5|2+0.5 <5> +>>> 4+2; 5|2+0.5 <5> 3 >>> ---- -<1> Number bases: 0x = hexadecimal, 0o = octal, 0b = binary. -<2> Fractions: numerator | denominator. +<1> Number bases: 0x = _hexadecimal_, 0o = _octal_, 0b = _binary_. +<2> Fractions: _numerator_ | _denominator_. <3> Activate multi-line output of fractions. <4> But operator, see <<_but_operator>>. <5> Multi-expression: the same result of the previous single expression but this it is obtained with two separated calculations. == Data types -_Expr_ supports numerical, string, relational, boolean expressions, and mixed-type lists. +_Expr_ has its type system which is a subset of Golang's type system. It supports numerical, string, relational, boolean expressions, and mixed-type lists and maps. === Numbers _Expr_ supports three type of numbers: @@ -272,25 +300,31 @@ Some arithmetic operators can also be used with strings. | [blue]`*` | _repeat_ | Make _n_ copy of a string | [blue]`"one" * 2` -> _"oneone"_ |=== -The items of strings can be accessed using the dot `.` operator. +The items of strings can be accessed using the square `[]` operator. .Item access syntax ==== -_item_ = _string-expr_ "**.**" _integer-expr_ +_item_ = _string-expr_ "**[**" _integer-expr_ "**]**" +==== + +.Sub string syntax +==== +_sub-string_ = _string-expr_ "**[**" _integer-expr_ "**:**" _integer-expr_ "**]**" ==== .String examples -`>>>` [blue]`s="abc"` [gray]_// assign the string to variable s_ + -[green]`abc` + -`>>>` [blue]`s.1` [gray]_// char at position 1 (starting from 0)_ + -[green]`b` + -`>>>` [blue]`s.(-1)` [gray]_// char at position -1, the rightmost one_ + -[green]`c` + +`>>>` [blue]`s="abcd"` [gray]_// assign the string to variable s_ + +[green]`"abcd"` + +`>>>` [blue]`s[1]` [gray]_// char at position 1 (starting from 0)_ + +[green]`"b"` + +`>>>` [blue]`s.[-1]` [gray]_// char at position -1, the rightmost one_ + +[green]`"d"` + `>>>` [blue]`\#s` [gray]_// number of chars_ + -[gren]`3` + -`>>>` [blue]`#"abc"` [gray]_// number of chars_ + -[green]`3` - +[gren]`4` + +`>>>` [blue]`#"abc"` [gray]_// number of chars_ + +[green]`3` + +`>>>` [blue]`s[1:3]` [gray]_// chars from position 1 to position 3 excluded_ + +[grean]`"bc"` === Booleans Boolean data type has two values only: [blue]_true_ and [blue]_false_. Relational and boolean expressions result in boolean values. diff --git a/doc/Expr.html b/doc/Expr.html index 12fe570..f085196 100644 --- a/doc/Expr.html +++ b/doc/Expr.html @@ -535,7 +535,13 @@ pre.rouge .ss { -
  • 3. Variables
    • +
  • 3. Variables
  • 4. Other operations