go-pkg/expr
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc: added some details

Browse Source
This commit is contained in:
Celestino Amoroso
2026-05-16 17:33:45 +02:00
parent e6844ad1e8
commit 08617378e0
2 changed files with 593 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/Expr.adoc
+133 -10
View File
@@ -34,7 +34,7 @@ Expressions calculator
toc::[]
#TODO: Work in progress (last update on 2026/05/08)#
#TODO: Work in progress#
== Expr
_Expr_ is a GO package that can analyze, interpret and calculate expressions.
@@ -100,7 +100,28 @@ An interactive tool could like `dev-expr` (see <<_dev-expr_test_tool>>) can be u
[green]`{2sp}}` +
[green]`}`
In order to inspect the global context issue the [blue]`$$global` operator.
In order to inspect the global context issue the [blue]`$$ global` operation.
////
.Example: list all functions whose name starts with "str"
`>>>` [blue]`builtin "string` [gray]__// most function in the builtin module *string* have names starting with "str".__ +
[green]`1`
:dollar: $
:2dollars: $$
`>>>` [blue]`($(($$global).functions) filter strStartsWith($_, "str"))` +
[green]`[` +
[green]`{2sp}"strEndsWith",` +
[green]`{2sp}"strJoin",` +
[green]`{2sp}"strLower",` +
[green]`{2sp}"strSplit",` +
[green]`{2sp}"strStartsWith",` +
[green]`{2sp}"strSub",` +
[green]`{2sp}"strTrim",` +
[green]`{2sp}"strUpper",` +
[green]`{2sp}"string"` +
[green]`]`
////
=== `dev-expr` test tool
Before we begin to describe the syntax of _Expr_, it is worth introducing _dev-expr_ because it will be used to show many examples of expressions.
@@ -223,14 +244,20 @@ Value range: *-9223372036854775808* to *9223372036854775807*
[cols="^1,^2,6,4"]
|===
| Symbol | Operation | Description | Examples
| [blue]`+` | _Sum_ | Add two values | [blue]`-1 + 2` -> _1_
| [blue]`+` | _Sum_ | Add two values^(<<note_int_plus_string,1>>)^ | [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]`*` | _Product_ | Multiply two values^(<<note_string_repl,2>>)^ | [blue]`-1 * 2` -> _-2_
| [blue]`/` | _Integer division_ | Divide the left value by the right one^(<<note_float_division,3>>)^ | [blue]`-11 / 2` -> _-5_
| [blue]`%` | _Modulo_ | Remainder of the integer division | [blue]`5 % 2` -> _1_
|===
[[note_int_plus_string]]
^(1)^ The sum operator [blue]`+` also supports adding an integer number to a string. In this case, the number is converted to a string and prependend or appended to the string, e.g. `"x" + 48` results in `"x48"`.
^(*)^ See also the _float division_ [blue]`./` below.
[[note_string_repl]]
^(2)^ The product operator also supports multiplying a string by an integer. In this case, the number represents homw may times the string has to be repeated in the result, e.g. `"foo" * 3` returnsn `"foofoofoo"`.
[[note_float_division]]
^(3)^ See also the _float division_ [blue]`./` below.
==== Floats
@@ -268,12 +295,14 @@ _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]`+` | _Sum_ | Add two values^(<<note_float_plus_string,1>>)^ | [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
|===
[[note_float_plus_string]]
^(1)^ The sum operator [blue]`+` also supports adding a float number to a string. In this case, the number is converted to a string and prependend or appended to the string, e.g. `"x" + 1.2` results in `"x1.2"`.
==== Fractions
_Expr_ also supports fractions. Fraction literals are made with two integers separated by a colon character `:`.
@@ -860,7 +889,7 @@ The table below shows all supported operators by decreasing priorities.
.6+|*ITER-OP*| [blue]`digest` | _Infix_ | _Item-digesting_ | _iterable_ `digest` _expr_ -> _any_
| [blue]`filter` | _Infix_ | _Item-filtering_ | _iterable_ `filter` _expr_ -> _list_
| [blue]`groupby` | _Infix_ | _Dict-grouping_ | _iterable_ `groupby` _key-expr_ -> _dict_
| [blue]`join` | _Infix_ | _Item-joining_ | _iterable_ `join` _iterable_ -> _list_
| [blue]`cat` | _Infix_ | _Item-concatenation_ | _iterable_ `cat ` _iterable_ -> _list_
| [blue]`map` | _Infix_ | _Item-mapping_ | _iterable_ `map` _-expr_ -> _list_
4+| _See iterators section for examples_
.1+|*RANGE*| [blue]`:` | _Infix_ | _Index-range_ | _integer_ `:` _integer_ -> _integer-pair_
@@ -1507,10 +1536,56 @@ Creates or truncates the named _<file-path>_. If the file already exists, it is
#to-do#
===== fileByteIterator()
#to-do#
Syntax: +
`{4sp}fileByteIterator(handle-or-path) -> iterator`
Returns an iterator that produces the bytes of the specified file. The parameter can be either a file handle or a file path. If a file path is provided, the file is opened and closed automatically by the iterator.
.Examples
>>> builtin "os.file" +
[green]`1` +
`>>>` [blue]`fileByteIterator("test-file.txt") map $_` +
[green]`[
117,
110,
111,
10,
100,
117,
101,
10
]`
>>> builtin ["os.file", "string"] +
[green]`2` +
`>>>` [blue]`fileByteIterator("test-file.txt") map char($_)` +
[green]`[
"u",
"n",
"o",
"
",
"d",
"u",
"e",
"
",
]`
===== fileLineIterator()
#to-do#
Syntax: +
`{4sp}fileLineIterator(handle-or-path) -> iterator`
Returns an iterator that produces the lines of the specified file. The parameter can be either a file handle or a file path. If a file path is provided, the file is opened and closed automatically by the iterator.
.Examples
`>>>` [blue]`builtin "os.file"` +
[green]`1` +
`>>>` [blue]`fileLineIterator("test-file.txt") map $_` +
[green]`[
"uno",
"due"
]`
==== Module "string"
@@ -1775,6 +1850,54 @@ TIP: Iterators built on custom data-sources can provide additional named operato
`>>>` [blue]`it.next` +
[green]`"one"`
=== Infixed operators on iterators
There are also some infixed operators that can be used with iterators. They are defined as follows.
* <<_cat,cat operator>>
* <<_diget,digest operator>>
* <<_filter,filter operator>>
* <<_groupby,groupby operator>>
* <<_map,map operator>>
//* <<_reduce,reduce operator>>: applies a binary expression cumulatively to the elements of the iterator, from left to right, to reduce the iterator to a single value.
//* <<_zip,zip operator>>: takes two or more iterators and returns a list of tuples, where the i-th tuple contains the i-th element from each of the input iterators.
---
==== [blue]`cat` operator
Syntax: +
`{4sp}<iterable> cat <iterable> -> <iterator>{4sp}`
[blue]`cat` operator takes two iterators or iterables and returns a new iterator that produces the elements of the first iterator followed by the elements of the second iterator.
.Examples
==== [blue]`filter` operator
Syntax: +
`{4sp}<iterable> filter <expr> -> <iterator>{4sp}`
[blue]`filter` applies a boolean expression to each element of the iterator and returns a list of the elements for which the expression evaluates to true.
==== [blue]`groupby` operator
Syntax: +
`{4sp}<dict> groupby <key> -> <dict>{4sp}`
[blue]`groupby` operator groups the elements of the iterator based on the value of a specified expression and returns a dictionary where the keys are the group values and the values are lists of the elements in each group.
==== [blue]`map` operator
Syntax: +
`{4sp}<iterable> map <expr> -> <list>{4sp}`
[blue]`map` operator iterates over the elements of the iterator and evaluates the expressions provided on the right side for each element. Its result is a list of the computed values of the that expression. The current element of the iterator is available in the expression as the variable `$_`.
.Example: using the [blue]`map` operator
`>>>` [blue]`it = $(["one", "two", "three"])` +
[green]`$(#3)` +
`>>>` [blue]`it map $_ + "!"` +
[green]`["one!", "two!", "three!"]`
=== Iterator over custom data-sources
It is possible to create iterators over custom data-sources by defining a dictionary that has the key `next` whose value is a function that returns the next element of the collection and updates the state of the iterator. The syntax for creating an iterator over a custom data-source is as follows.