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::[] toc::[]
#TODO: Work in progress (last update on 2026/05/08)# #TODO: Work in progress#
== Expr == Expr
_Expr_ is a GO package that can analyze, interpret and calculate expressions. _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]`{2sp}}` +
[green]`}` [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 === `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. 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"] [cols="^1,^2,6,4"]
|=== |===
| Symbol | Operation | Description | Examples | 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]`-` | _Subtraction_ | Subtract the right value from the left one | [blue]`3 - 1` -> _2_
| [blue]`*` | _Product_ | Multiply two values | [blue]`-1 * 2` -> _-2_ | [blue]`*` | _Product_ | Multiply two values^(<<note_string_repl,2>>)^ | [blue]`-1 * 2` -> _-2_
| [blue]`/` | _Integer division_ | Divide the left value by the right one^(*)^ | [blue]`-11 / 2` -> _-5_ | [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_ | [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 ==== Floats
@@ -268,12 +295,14 @@ _dec-seq_ = _see-integer-literal-syntax_
[cols="^1,^2,6,4"] [cols="^1,^2,6,4"]
|=== |===
| Symbol | Operation | Description | Examples | 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]`-` | _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]`*` | _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]`/` | _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 | [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 ==== Fractions
_Expr_ also supports fractions. Fraction literals are made with two integers separated by a colon character `:`. _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_ .6+|*ITER-OP*| [blue]`digest` | _Infix_ | _Item-digesting_ | _iterable_ `digest` _expr_ -> _any_
| [blue]`filter` | _Infix_ | _Item-filtering_ | _iterable_ `filter` _expr_ -> _list_ | [blue]`filter` | _Infix_ | _Item-filtering_ | _iterable_ `filter` _expr_ -> _list_
| [blue]`groupby` | _Infix_ | _Dict-grouping_ | _iterable_ `groupby` _key-expr_ -> _dict_ | [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_ | [blue]`map` | _Infix_ | _Item-mapping_ | _iterable_ `map` _-expr_ -> _list_
4+| _See iterators section for examples_ 4+| _See iterators section for examples_
.1+|*RANGE*| [blue]`:` | _Infix_ | _Index-range_ | _integer_ `:` _integer_ -> _integer-pair_ .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# #to-do#
===== fileByteIterator() ===== 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() ===== 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" ==== Module "string"
@@ -1775,6 +1850,54 @@ TIP: Iterators built on custom data-sources can provide additional named operato
`>>>` [blue]`it.next` + `>>>` [blue]`it.next` +
[green]`"one"` [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 === 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. 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.
doc/Expr.html
+460 -30
View File
@@ -581,7 +581,11 @@ pre.rouge .ss {
<li><a href="#_operator">4.1. <code class="blue">;</code> operator</a></li> <li><a href="#_operator">4.1. <code class="blue">;</code> operator</a></li>
<li><a href="#_but_operator">4.2. <code class="blue">but</code> operator</a></li> <li><a href="#_but_operator">4.2. <code class="blue">but</code> operator</a></li>
<li><a href="#_assignment_operator">4.3. Assignment operator <code class="blue">=</code></a></li> <li><a href="#_assignment_operator">4.3. Assignment operator <code class="blue">=</code></a></li>
<li><a href="#_selector_operator">4.4. Selector operator <code class="blue">? : ::</code></a></li> <li><a href="#_selector_operator">4.4. Selector operator <code class="blue">? : ::</code></a>
<ul class="sectlevel3">
<li><a href="#_triple_special_case_of_the_selector_operator">4.4.1. Triple special case of the selector operator</a></li>
</ul>
</li>
<li><a href="#_variable_default_value_and">4.5. Variable default value <code class="blue">??</code>, <code class="blue">?=</code>, and <code class="blue">?!</code></a></li> <li><a href="#_variable_default_value_and">4.5. Variable default value <code class="blue">??</code>, <code class="blue">?=</code>, and <code class="blue">?!</code></a></li>
</ul> </ul>
</li> </li>
@@ -613,8 +617,10 @@ pre.rouge .ss {
<li><a href="#_dec">dec()</a></li> <li><a href="#_dec">dec()</a></li>
<li><a href="#_string">string()</a></li> <li><a href="#_string">string()</a></li>
<li><a href="#_fract">fract()</a></li> <li><a href="#_fract">fract()</a></li>
<li><a href="#_char">char()</a></li>
<li><a href="#_eval">eval()</a></li> <li><a href="#_eval">eval()</a></li>
<li><a href="#_var">var()</a></li> <li><a href="#_var">var()</a></li>
<li><a href="#_set">set</a></li>
</ul> </ul>
</li> </li>
<li><a href="#_module_fmt">7.1.2. Module "fmt"</a> <li><a href="#_module_fmt">7.1.2. Module "fmt"</a>
@@ -649,6 +655,8 @@ pre.rouge .ss {
<li><a href="#_filewritetext">fileWriteText()</a></li> <li><a href="#_filewritetext">fileWriteText()</a></li>
<li><a href="#_filereadtext">fileReadText()</a></li> <li><a href="#_filereadtext">fileReadText()</a></li>
<li><a href="#_filereadtextall">fileReadTextAll()</a></li> <li><a href="#_filereadtextall">fileReadTextAll()</a></li>
<li><a href="#_filebyteiterator">fileByteIterator()</a></li>
<li><a href="#_filelineiterator">fileLineIterator()</a></li>
</ul> </ul>
</li> </li>
<li><a href="#_module_string">7.1.7. Module "string"</a> <li><a href="#_module_string">7.1.7. Module "string"</a>
@@ -674,7 +682,15 @@ pre.rouge .ss {
<li><a href="#_named_operators">8.1.1. Named operators</a></li> <li><a href="#_named_operators">8.1.1. Named operators</a></li>
</ul> </ul>
</li> </li>
<li><a href="#_iterator_over_custom_data_sources">8.2. Iterator over custom data-sources</a></li> <li><a href="#_infixed_operators_on_iterators">8.2. Infixed operators on iterators</a>
<ul class="sectlevel3">
<li><a href="#_cat_operator">8.2.1. <code class="blue">cat</code> operator</a></li>
<li><a href="#_filter_operator">8.2.2. <code class="blue">filter</code> operator</a></li>
<li><a href="#_groupby_operator">8.2.3. <code class="blue">groupby</code> operator</a></li>
<li><a href="#_map_operator">8.2.4. <code class="blue">map</code> operator</a></li>
</ul>
</li>
<li><a href="#_iterator_over_custom_data_sources">8.3. Iterator over custom data-sources</a></li>
</ul> </ul>
</li> </li>
<li><a href="#_plugins">9. Plugins</a></li> <li><a href="#_plugins">9. Plugins</a></li>
@@ -686,7 +702,7 @@ pre.rouge .ss {
<div class="sectionbody"> <div class="sectionbody">
<!-- toc disabled --> <!-- toc disabled -->
<div class="paragraph"> <div class="paragraph">
<p><mark>TODO: Work in progress (last update on 2026/04/15, 6:02 p.m.)</mark></p> <p><mark>TODO: Work in progress (last update on 2026/05/08)</mark></p>
</div> </div>
</div> </div>
</div> </div>
@@ -788,7 +804,26 @@ pre.rouge .ss {
<code class="green">}</code></p> <code class="green">}</code></p>
</div> </div>
<div class="paragraph"> <div class="paragraph">
<p>In order to inspect the global context issue the <code class="blue">$$global</code> operator.</p> <p>In order to inspect the global context issue the <code class="blue">$$ global</code> operation.</p>
</div>
<div class="paragraph">
<div class="title">Example: list all functions whose name starts with "str"</div>
<p><code>&gt;&gt;&gt;</code> <code class="blue">builtin "string</code> <em class="gray">// most function in the builtin module <strong>string</strong> have names starting with "str".</em><br>
<code class="green">1</code></p>
</div>
<div class="paragraph">
<p><code>&gt;&gt;&gt;</code> <code class="blue">($$$global).functions) filter strStartsWith($_, "str"</code><br>
<code class="green">[</code><br>
<code class="green">&#160;&#160;"strEndsWith",</code><br>
<code class="green">&#160;&#160;"strJoin",</code><br>
<code class="green">&#160;&#160;"strLower",</code><br>
<code class="green">&#160;&#160;"strSplit",</code><br>
<code class="green">&#160;&#160;"strStartsWith",</code><br>
<code class="green">&#160;&#160;"strSub",</code><br>
<code class="green">&#160;&#160;"strTrim",</code><br>
<code class="green">&#160;&#160;"strUpper",</code><br>
<code class="green">&#160;&#160;"string"</code><br>
<code class="green">]</code></p>
</div> </div>
</div> </div>
</div> </div>
@@ -1880,10 +1915,10 @@ Technically <code class="blue">;</code> is not treated as a real operator. It ac
<p>The <em>selector operator</em> is very similar to the <em>switch/case/default</em> statement available in many programming languages.</p> <p>The <em>selector operator</em> is very similar to the <em>switch/case/default</em> statement available in many programming languages.</p>
</div> </div>
<div class="exampleblock"> <div class="exampleblock">
<div class="title">Example 13. Selector literal Syntax</div> <div class="title">Example 13. Selector literal syntax</div>
<div class="content"> <div class="content">
<div class="paragraph"> <div class="paragraph">
<p><em>selector-operator</em> = <em>select-expression</em> "<strong>?</strong>" <em>selector-case</em> { "<strong>:</strong>" <em>selector-case</em> } ["<strong>::</strong>" <em>default-multi-expression</em>]<br> <p><strong><em>selector-operator</em></strong> = <em>select-expression</em> "<strong>?</strong>" <em>selector-case</em> { "<strong>:</strong>" <em>selector-case</em> } ["<strong>::</strong>" <em>default-multi-expression</em>]<br>
<em>selector-case</em> = [<em>match-list</em>] <em>case-value</em><br> <em>selector-case</em> = [<em>match-list</em>] <em>case-value</em><br>
<em>match-list</em> = "<strong>[</strong>" <em>item</em> {"<strong>,</strong>" <em>items</em>} "<strong>]</strong>"<br> <em>match-list</em> = "<strong>[</strong>" <em>item</em> {"<strong>,</strong>" <em>items</em>} "<strong>]</strong>"<br>
<em>item</em> = <em>expression</em><br> <em>item</em> = <em>expression</em><br>
@@ -1931,11 +1966,45 @@ Technically <code class="blue">;</code> is not treated as a real operator. It ac
<p><code>&gt;&gt;&gt;</code> <code class="blue">10 ? {"a"} : {"b"}</code><br> <p><code>&gt;&gt;&gt;</code> <code class="blue">10 ? {"a"} : {"b"}</code><br>
<code class="red">Eval Error: [1:3] no case catches the value (10) of the selection expression</code></p> <code class="red">Eval Error: [1:3] no case catches the value (10) of the selection expression</code></p>
</div> </div>
<div class="sect3">
<h4 id="_triple_special_case_of_the_selector_operator"><a class="anchor" href="#_triple_special_case_of_the_selector_operator"></a><a class="link" href="#_triple_special_case_of_the_selector_operator">4.4.1. Triple special case of the selector operator</a></h4>
<div class="paragraph">
<p>If the <em>select-expression</em> is a boolean expression, the selector operator can be used as a sort of <em>if-then-else</em> statement. In this case, the first case is evaluated if the <em>select-expression</em> is true, and the second case is evaluated if the <em>select-expression</em> is false. In this special case, the <em>match-list</em> of both cases must be empty.</p>
</div>
<div class="paragraph">
<div class="title">Example</div>
<p><code>&gt;&gt;&gt;</code> <code class="blue">(true) ? {"T"}: {"F"}</code><br>
<code class="green">T</code><br>
<code>&gt;&gt;&gt;</code> <code class="blue">(2 &gt; 1) ? {"a"} : {"b"}</code><br>
<code class="green">a</code><br>
<code>&gt;&gt;&gt;</code> <code class="blue">(2 &lt; 1) ? {"a"} : {"b"}</code><br>
<code class="green">b</code></p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
<div class="paragraph">
<p>The triple special case of the selector operator is very useful, but it only works with boolean expressions.</p>
</div>
<div class="paragraph">
<div class="title">Example of confusion</div>
<p><code>&gt;&gt;&gt;</code> <code class="blue">int(true) ? {"T"}: {"F"}</code><br>
<code class="green">F</code></p>
</div>
</td>
</tr>
</table>
</div>
</div>
</div> </div>
<div class="sect2"> <div class="sect2">
<h3 id="_variable_default_value_and"><a class="anchor" href="#_variable_default_value_and"></a><a class="link" href="#_variable_default_value_and">4.5. Variable default value <code class="blue">??</code>, <code class="blue">?=</code>, and <code class="blue">?!</code></a></h3> <h3 id="_variable_default_value_and"><a class="anchor" href="#_variable_default_value_and"></a><a class="link" href="#_variable_default_value_and">4.5. Variable default value <code class="blue">??</code>, <code class="blue">?=</code>, and <code class="blue">?!</code></a></h3>
<div class="paragraph"> <div class="paragraph">
<p>The left operand of the first two operators, <code class="blue">??</code> and <code class="blue">?=</code>, 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.</p> <p>The left operand of the first two operators, <code class="blue">??</code> and <code class="blue">?=</code>, must be a variable. The right operatand can be any expression. They return the value of the variable if this is defined; otherwise they return the value of the right expression.</p>
</div> </div>
<div class="admonitionblock important"> <div class="admonitionblock important">
<table> <table>
@@ -1953,7 +2022,7 @@ If the left variable is defined, the right expression is not evaluated at all.
<p>The <code class="blue">??</code> operator do not change the status of the left variable.</p> <p>The <code class="blue">??</code> operator do not change the status of the left variable.</p>
</div> </div>
<div class="paragraph"> <div class="paragraph">
<p>The <code class="blue">?=</code> assigns the calculated value of the right expression to the left variable.</p> <p>The <code class="blue">?=</code> assigns the calculated value of the right expression to the variable on the left side.</p>
</div> </div>
<div class="paragraph"> <div class="paragraph">
<p>The third one, <code class="blue">?!</code>, is the alternate operator. If the variable on the left size is not defined, it returns <em class="blue">nil</em>. Otherwise it returns the result of the expressione on the right side.</p> <p>The third one, <code class="blue">?!</code>, is the alternate operator. If the variable on the left size is not defined, it returns <em class="blue">nil</em>. Otherwise it returns the result of the expressione on the right side.</p>
@@ -1965,7 +2034,7 @@ If the left variable is defined, the right expression is not evaluated at all.
<i class="fa icon-important" title="Important"></i> <i class="fa icon-important" title="Important"></i>
</td> </td>
<td class="content"> <td class="content">
If the left variable is NOT defined, the right expression is not evaluated at all. If the variable <code class="blue">?!</code> is NOT defined, the expression is not evaluated at all.
</td> </td>
</tr> </tr>
</table> </table>
@@ -2371,7 +2440,7 @@ These operators have a high priority, in particular higher than the operator <co
<td class="tableblock halign-center valign-top"><p class="tableblock"><em>identifier</em> <code>=</code> <em>any</em> &#8594; <em>any</em></p></td> <td class="tableblock halign-center valign-top"><p class="tableblock"><em>identifier</em> <code>=</code> <em>any</em> &#8594; <em>any</em></p></td>
</tr> </tr>
<tr> <tr>
<td class="tableblock halign-center valign-top" colspan="4"><p class="tableblock"><em>See also the table of special allocation operators below</em></p></td> <td class="tableblock halign-center valign-top" colspan="4"><p class="tableblock"><em>See also the table of special assignment operators below</em></p></td>
</tr> </tr>
<tr> <tr>
<td class="tableblock halign-center valign-top"><p class="tableblock"><strong>BUT</strong></p></td> <td class="tableblock halign-center valign-top"><p class="tableblock"><strong>BUT</strong></p></td>
@@ -2381,6 +2450,40 @@ These operators have a high priority, in particular higher than the operator <co
<td class="tableblock halign-center valign-top"><p class="tableblock"><em>any</em> <code>but</code> <em>any</em> &#8594; <em>any</em></p></td> <td class="tableblock halign-center valign-top"><p class="tableblock"><em>any</em> <code>but</code> <em>any</em> &#8594; <em>any</em></p></td>
</tr> </tr>
<tr> <tr>
<td class="tableblock halign-center valign-top" rowspan="6"><p class="tableblock"><strong>ITER-OP</strong></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><code class="blue">digest</code></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><em>Infix</em></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><em>Item-digesting</em></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><em>iterable</em> <code>digest</code> <em>expr</em> &#8594; <em>any</em></p></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock"><code class="blue">filter</code></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><em>Infix</em></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><em>Item-filtering</em></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><em>iterable</em> <code>filter</code> <em>expr</em> &#8594; <em>list</em></p></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock"><code class="blue">groupby</code></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><em>Infix</em></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><em>Dict-grouping</em></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><em>iterable</em> <code>groupby</code> <em>key-expr</em> &#8594; <em>dict</em></p></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock"><code class="blue">cat</code></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><em>Infix</em></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><em>Item-concatenation</em></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><em>iterable</em> `cat ` <em>iterable</em> &#8594; <em>list</em></p></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock"><code class="blue">map</code></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><em>Infix</em></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><em>Item-mapping</em></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><em>iterable</em> <code>map</code> <em>-expr</em> &#8594; <em>list</em></p></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top" colspan="4"><p class="tableblock"><em>See iterators section for examples</em></p></td>
</tr>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock"><strong>RANGE</strong></p></td> <td class="tableblock halign-center valign-top"><p class="tableblock"><strong>RANGE</strong></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><code class="blue">:</code></p></td> <td class="tableblock halign-center valign-top"><p class="tableblock"><code class="blue">:</code></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><em>Infix</em></p></td> <td class="tableblock halign-center valign-top"><p class="tableblock"><em>Infix</em></p></td>
@@ -2536,14 +2639,14 @@ short for<br>
</div> </div>
<div class="paragraph"> <div class="paragraph">
<p><code>&gt;&gt;&gt;</code> <em class="gray">// Required and optional parameters</em><br> <p><code>&gt;&gt;&gt;</code> <em class="gray">// Required and optional parameters</em><br>
<code>&gt;&gt;&gt;</code> <code class="blue">measure = func(value, unit="meter"){ value + " " + unit + (value &gt; 1) ? [true] {"s"} :: {""}}</code><br> <code>&gt;&gt;&gt;</code> <code class="blue">measure = func(value, unit="meter"){ value + " " + unit + (value &gt; 1) ? {"s"} :: {""}}</code><br>
<code class="green">measure(value, unit="meter"):any{}</code></p> <code class="green">measure(value, unit="meter"):any{}</code></p>
</div> </div>
</div> </div>
<div class="sect2"> <div class="sect2">
<h3 id="_golang_function_definition"><a class="anchor" href="#_golang_function_definition"></a><a class="link" href="#_golang_function_definition">6.2. <em>Golang</em> function definition</a></h3> <h3 id="_golang_function_definition"><a class="anchor" href="#_golang_function_definition"></a><a class="link" href="#_golang_function_definition">6.2. <em>Golang</em> function definition</a></h3>
<div class="paragraph"> <div class="paragraph">
<p>Description of how to define Golang functions and how to bind them to <em>Expr</em> are topics covered in another document that I&#8217;ll write, one day, maybe.</p> <p>Description of how to define Golang functions and how to bind them to <em>Expr</em> are topics covered in another documents that I&#8217;ll write, one day, maybe.</p>
</div> </div>
</div> </div>
<div class="sect2"> <div class="sect2">
@@ -2642,7 +2745,7 @@ short for<br>
<div class="title">Example</div> <div class="title">Example</div>
<p><code>&gt;&gt;&gt;</code> <code class="blue">f = func() { @x = 3; x = 5 }</code> <em class="gray">// f() declares two <strong>different</strong> local variables: <code>@x</code> and <code>x</code></em><br> <p><code>&gt;&gt;&gt;</code> <code class="blue">f = func() { @x = 3; x = 5 }</code> <em class="gray">// f() declares two <strong>different</strong> local variables: <code>@x</code> and <code>x</code></em><br>
<code class="green">f():any{}</code><br> <code class="green">f():any{}</code><br>
<code>&gt;&gt;&gt;</code> <code class="blue">f()</code> <em class="gray">// The multi-expression (two) in f() is calculated and the last result is returned</em><br> <code>&gt;&gt;&gt;</code> <code class="blue">f()</code> <em class="gray">// The multi-expression (two expressions) in f() is calculated and the last result is returned</em><br>
<code class="green">5</code><br> <code class="green">5</code><br>
<code>&gt;&gt;&gt;</code> <code class="blue">x</code> <em class="gray">// The <code>x</code> variable was not defined in the main context before the f() invocation. It appears in the main context by cloning the <code>@x</code> variable, local to f() after its termnation.</em><br> <code>&gt;&gt;&gt;</code> <code class="blue">x</code> <em class="gray">// The <code>x</code> variable was not defined in the main context before the f() invocation. It appears in the main context by cloning the <code>@x</code> variable, local to f() after its termnation.</em><br>
<code class="green">3</code></p> <code class="green">3</code></p>
@@ -2727,7 +2830,7 @@ The clone modifier <code class="blue">@</code> does not make a variable a refere
<div class="title">Example 16. Builtin activation syntax</div> <div class="title">Example 16. Builtin activation syntax</div>
<div class="content"> <div class="content">
<div class="paragraph"> <div class="paragraph">
<p><strong><em>builtin-activation</em></strong> = <code class="blue">BUILTIN</code> (<em>builtin-name</em> | <em>list-of-builtin-names</em>)<br> <p><strong><em>builtin-activation</em></strong> = <code class="blue">BUILTIN</code> (<em>builtin-name</em> | <em>list-of-builtin-names</em> | <strong>"*"</strong>)<br>
<em>builtin-name</em> = <em>string</em><br> <em>builtin-name</em> = <em>string</em><br>
<em>list-of-builtin-names</em> = <strong>[</strong> <em>string</em> { "<strong>,</strong>" <em>string</em> } <strong>]</strong></p> <em>list-of-builtin-names</em> = <strong>[</strong> <em>string</em> { "<strong>,</strong>" <em>string</em> } <strong>]</strong></p>
</div> </div>
@@ -2815,9 +2918,15 @@ To avoid the need to activate builtin modules one by one, it is possible to acti
<div class="title">Other functions</div> <div class="title">Other functions</div>
<ul> <ul>
<li> <li>
<p><a href="#_char">char()</a></p>
</li>
<li>
<p><a href="#_eval">eval()</a></p> <p><a href="#_eval">eval()</a></p>
</li> </li>
<li> <li>
<p><a href="#_set">set()</a></p>
</li>
<li>
<p><a href="#_var">var()</a></p> <p><a href="#_var">var()</a></p>
</li> </li>
</ul> </ul>
@@ -2833,7 +2942,9 @@ Returns <em>true</em> if the value type of <em>&lt;expr&gt;</em> is boolean, fal
<p><code>&gt;&gt;&gt;</code> <code class="blue">isBool(true)</code><br> <p><code>&gt;&gt;&gt;</code> <code class="blue">isBool(true)</code><br>
<code class="green">true</code><br> <code class="green">true</code><br>
<code>&gt;&gt;&gt;</code> <code class="blue">isBool(3==2)</code><br> <code>&gt;&gt;&gt;</code> <code class="blue">isBool(3==2)</code><br>
<code class="green">true</code></p> <code class="green">true</code><br>
<code>&gt;&gt;&gt;</code> <code class="blue">isBool(3 + 2)</code><br>
<code class="green">false</code></p>
</div> </div>
</div> </div>
<div class="sect4"> <div class="sect4">
@@ -2938,7 +3049,7 @@ Returns <em>true</em> if the value type of <em>&lt;expr&gt;</em> is fraction or
<h5 id="_isstring"><a class="anchor" href="#_isstring"></a><a class="link" href="#_isstring">isString()</a></h5> <h5 id="_isstring"><a class="anchor" href="#_isstring"></a><a class="link" href="#_isstring">isString()</a></h5>
<div class="paragraph"> <div class="paragraph">
<p>Syntax: <code>isString(&lt;expr&gt;) &#8594; bool</code><br> <p>Syntax: <code>isString(&lt;expr&gt;) &#8594; bool</code><br>
Returns a boolean value , false otherwise.</p> Returns <em>true</em> if the value type of <em>&lt;expr&gt;</em> is string, false otherwise.</p>
</div> </div>
<div class="paragraph"> <div class="paragraph">
<div class="title">Examples</div> <div class="title">Examples</div>
@@ -2954,7 +3065,7 @@ Returns a boolean value , false otherwise.</p>
<h5 id="_bool"><a class="anchor" href="#_bool"></a><a class="link" href="#_bool">bool()</a></h5> <h5 id="_bool"><a class="anchor" href="#_bool"></a><a class="link" href="#_bool">bool()</a></h5>
<div class="paragraph"> <div class="paragraph">
<p>Syntax: <code>bool(&lt;expr&gt;) &#8594; bool</code><br> <p>Syntax: <code>bool(&lt;expr&gt;) &#8594; bool</code><br>
Returns a <em>boolean</em> value consisent to the value of the expression.</p> Returns a <em>boolean</em> value consisent with the value of the expression.</p>
</div> </div>
<div class="paragraph"> <div class="paragraph">
<div class="title">Examples</div> <div class="title">Examples</div>
@@ -3077,6 +3188,20 @@ Returns a <em>fraction</em> value consistent with the value of the expression.</
</div> </div>
</div> </div>
<div class="sect4"> <div class="sect4">
<h5 id="_char"><a class="anchor" href="#_char"></a><a class="link" href="#_char">char()</a></h5>
<div class="paragraph">
<p>Syntax: <code>char(&lt;intexpr&gt;) &#8594; string</code><br>
Returns the character whose ASCII (soon Unicode too) code point is specified by the integer expression.</p>
</div>
<div class="paragraph">
<div class="title">Examples</div>
<p><code>&gt;&gt;&gt;</code> <code class="blue">char(65)</code><br>
<code class="green">"A"</code><br>
<code>&gt;&gt;&gt;</code> <code class="blue">char(97)</code><br>
<code class="green">"a"</code></p>
</div>
</div>
<div class="sect4">
<h5 id="_eval"><a class="anchor" href="#_eval"></a><a class="link" href="#_eval">eval()</a></h5> <h5 id="_eval"><a class="anchor" href="#_eval"></a><a class="link" href="#_eval">eval()</a></h5>
<div class="paragraph"> <div class="paragraph">
<p>Syntax: <code>eval(&lt;string-expr&gt;) &#8594; any</code><br> <p>Syntax: <code>eval(&lt;string-expr&gt;) &#8594; any</code><br>
@@ -3096,13 +3221,13 @@ Computes and returns the value of the <span class="underline">string</span> expr
<code>&#160;&#160;&#160;&#160;var(&lt;string-expr&gt;) &#8594; any</code></p> <code>&#160;&#160;&#160;&#160;var(&lt;string-expr&gt;) &#8594; any</code></p>
</div> </div>
<div class="paragraph"> <div class="paragraph">
<p>This function allows you to define variables whose names must include special characters. The first form of the function allows you to define a variable with a name specified by the first parameter and assign it the value of the second parameter. The second form only returns the value of the variable with the specified name.</p> <p>This function allows you to define variables whose names can include special characters. The first form of the function allows you to define a variable with a name specified by the first parameter and assign it the value of the second parameter. The second form only returns the value of the variable with the specified name.</p>
</div> </div>
<div class="paragraph"> <div class="paragraph">
<div class="title">Examples</div> <div class="title">Examples</div>
<p><code>&gt;&gt;&gt;</code> <code class="blue">var("$x", 3+9)</code><br> <p><code>&gt;&gt;&gt;</code> <code class="blue">var("$x", 3+9)</code><br>
<code class="green">12</code><br> <code class="green">12</code><br>
<code>&gt;&gt;&gt;</code> <code class="blue">var("$x")</code><br> <code>&gt;&gt;&gt;</code> <code class="blue">var("$"+"x")</code><br>
<code class="green">12</code><br> <code class="green">12</code><br>
<code>&gt;&gt;&gt;</code> <code class="blue">var("gain%", var("$x"))</code><br> <code>&gt;&gt;&gt;</code> <code class="blue">var("gain%", var("$x"))</code><br>
<code class="green">12</code><br> <code class="green">12</code><br>
@@ -3110,9 +3235,32 @@ Computes and returns the value of the <span class="underline">string</span> expr
<code class="green">13</code></p> <code class="green">13</code></p>
</div> </div>
</div> </div>
<div class="sect4">
<h5 id="_set"><a class="anchor" href="#_set"></a><a class="link" href="#_set">set</a></h5>
<div class="paragraph">
<p>Syntax:<br>
<code>&#160;&#160;&#160;&#160;set(&lt;string-expr&gt;, &lt;expr&gt;) &#8594; any</code></p>
</div>
<div class="paragraph">
<p>This function allows you to set the value of a variable whose name can include special characters. The first parameter is the name of the variable and the second parameter is the new value to assign to that variable.</p>
</div>
<div class="paragraph">
<p>It is equivalent to the first form of the var() function, but it is more explicit about the intent of changing the value of an existing variable.</p>
</div>
<div class="paragraph">
<div class="title">Examples</div>
<p><code>&gt;&gt;&gt;</code> <code class="blue">set("$x", 100)</code><br>
<code class="green">100</code><br>
<code>&gt;&gt;&gt;</code> <code class="blue">var("$x")</code><br>
<code class="green">100</code><br></p>
</div>
</div>
</div> </div>
<div class="sect3"> <div class="sect3">
<h4 id="_module_fmt"><a class="anchor" href="#_module_fmt"></a><a class="link" href="#_module_fmt">7.1.2. Module "fmt"</a></h4> <h4 id="_module_fmt"><a class="anchor" href="#_module_fmt"></a><a class="link" href="#_module_fmt">7.1.2. Module "fmt"</a></h4>
<div class="paragraph">
<p><mark>to-do</mark></p>
</div>
<div class="sect4"> <div class="sect4">
<h5 id="_print"><a class="anchor" href="#_print"></a><a class="link" href="#_print">print()</a></h5> <h5 id="_print"><a class="anchor" href="#_print"></a><a class="link" href="#_print">print()</a></h5>
@@ -3124,10 +3272,18 @@ Computes and returns the value of the <span class="underline">string</span> expr
</div> </div>
<div class="sect3"> <div class="sect3">
<h4 id="_module_import"><a class="anchor" href="#_module_import"></a><a class="link" href="#_module_import">7.1.3. Module "import"</a></h4> <h4 id="_module_import"><a class="anchor" href="#_module_import"></a><a class="link" href="#_module_import">7.1.3. Module "import"</a></h4>
<div class="paragraph">
<p>Module activation:<br>
<code>&#160;&#160;&#160;&#160;BUILTIN "import"</code></p>
</div>
<div class="sect4"> <div class="sect4">
<h5 id="_import"><a class="anchor" href="#_import"></a><a class="link" href="#_import"><em>import()</em></a></h5> <h5 id="_import"><a class="anchor" href="#_import"></a><a class="link" href="#_import"><em>import()</em></a></h5>
<div class="paragraph"> <div class="paragraph">
<p><em class="blue">import(<span class="grey">&lt;source-file&gt;</span>)</em>&#8201;&#8212;&#8201;loads the multi-expression contained in the specified source and returns its value.</p> <p>Syntax:<br>
<code>&#160;&#160;&#160;&#160;import(&lt;source-file&gt;)</code></p>
</div>
<div class="paragraph">
<p>Loads the multi-expression contained in the specified source and returns its value.</p>
</div> </div>
</div> </div>
<div class="sect4"> <div class="sect4">
@@ -3137,16 +3293,40 @@ Computes and returns the value of the <span class="underline">string</span> expr
</div> </div>
<div class="sect3"> <div class="sect3">
<h4 id="_module_iterator"><a class="anchor" href="#_module_iterator"></a><a class="link" href="#_module_iterator">7.1.4. Module "iterator"</a></h4> <h4 id="_module_iterator"><a class="anchor" href="#_module_iterator"></a><a class="link" href="#_module_iterator">7.1.4. Module "iterator"</a></h4>
<div class="paragraph">
<p>Module activation:<br>
<code>&#160;&#160;&#160;&#160;BUILTIN "iterator"</code></p>
</div>
<div class="sect4"> <div class="sect4">
<h5 id="_run"><a class="anchor" href="#_run"></a><a class="link" href="#_run">run()</a></h5> <h5 id="_run"><a class="anchor" href="#_run"></a><a class="link" href="#_run">run()</a></h5>
<div class="paragraph">
<p>Syntax:<br>
<code>&#160;&#160;&#160;&#160;run(&lt;iterator&gt;, &lt;operator&gt;, &lt;vars&gt;) &#8594; any</code></p>
</div>
<div class="paragraph">
<p>Iterates over the specified iterator and applies the specified operator to the current value of the iterator.</p>
</div>
</div> </div>
</div> </div>
<div class="sect3"> <div class="sect3">
<h4 id="_module_math_arith"><a class="anchor" href="#_module_math_arith"></a><a class="link" href="#_module_math_arith">7.1.5. Module "math.arith"</a></h4> <h4 id="_module_math_arith"><a class="anchor" href="#_module_math_arith"></a><a class="link" href="#_module_math_arith">7.1.5. Module "math.arith"</a></h4>
<div class="paragraph"> <div class="paragraph">
<p>Module activation:<br>
<code>&#160;&#160;&#160;&#160;BUILTIN "math.arith"</code></p>
</div>
<div class="paragraph">
<p>Currently, the "math.arith" module provides two functions, add() and mul(), that perform addition and multiplication of an arbitrary number of parameters. More functions will be added in the future.</p> <p>Currently, the "math.arith" module provides two functions, add() and mul(), that perform addition and multiplication of an arbitrary number of parameters. More functions will be added in the future.</p>
</div> </div>
<div class="ulist">
<ul>
<li>
<p><a href="#_add">add()</a></p>
</li>
<li>
<p><a href="#_mul">mul()</a></p>
</li>
</ul>
</div>
<div class="sect4"> <div class="sect4">
<h5 id="_add"><a class="anchor" href="#_add"></a><a class="link" href="#_add">add()</a></h5> <h5 id="_add"><a class="anchor" href="#_add"></a><a class="link" href="#_add">add()</a></h5>
<div class="paragraph"> <div class="paragraph">
@@ -3202,37 +3382,213 @@ Computes and returns the value of the <span class="underline">string</span> expr
</div> </div>
<div class="sect3"> <div class="sect3">
<h4 id="_module_os_file"><a class="anchor" href="#_module_os_file"></a><a class="link" href="#_module_os_file">7.1.6. Module "os.file"</a></h4> <h4 id="_module_os_file"><a class="anchor" href="#_module_os_file"></a><a class="link" href="#_module_os_file">7.1.6. Module "os.file"</a></h4>
<div class="paragraph">
<p>Module activation:<br>
<code>&#160;&#160;&#160;&#160;BUILTIN "os.file"</code></p>
</div>
<div class="paragraph">
<p>The "os.file" module provides functions for working with files.</p>
</div>
<div class="ulist">
<div class="title">File related functions</div>
<ul>
<li>
<p><a href="#_fileOpen">fileOpen()</a></p>
</li>
<li>
<p><a href="#_fileAppend">fileAppend()</a></p>
</li>
<li>
<p><a href="#_fileCreate">fileCreate()</a></p>
</li>
<li>
<p><a href="#_fileClose">fileClose()</a></p>
</li>
<li>
<p><a href="#_fileWriteText">fileWriteText()</a></p>
</li>
<li>
<p><a href="#_fileReadText">fileReadText()</a></p>
</li>
<li>
<p><a href="#_fileReadTextAll">fileReadTextAll()</a></p>
</li>
</ul>
</div>
<div class="ulist">
<div class="title">Iterator functions for files</div>
<ul>
<li>
<p><a href="#_fileByteIterator">fileByteIterator()</a></p>
</li>
<li>
<p><a href="#_fileLineIterator">fileLineIterator()</a></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>More functions will be added in the future.</p>
</div>
<hr>
<div class="sect4"> <div class="sect4">
<h5 id="_fileopen"><a class="anchor" href="#_fileopen"></a><a class="link" href="#_fileopen">fileOpen()</a></h5> <h5 id="_fileopen"><a class="anchor" href="#_fileopen"></a><a class="link" href="#_fileopen">fileOpen()</a></h5>
<div class="paragraph">
<p>Syntax:<br>
<code>&#160;&#160;&#160;&#160;fileOpen(&lt;file-path&gt;) &#8594; file-handle</code></p>
</div>
<div class="paragraph">
<p>Returns a file handle for the specified file path. The file is opened in read-write mode. If the file does not exist, it is created.</p>
</div>
</div> </div>
<div class="sect4"> <div class="sect4">
<h5 id="_fileappend"><a class="anchor" href="#_fileappend"></a><a class="link" href="#_fileappend">fileAppend()</a></h5> <h5 id="_fileappend"><a class="anchor" href="#_fileappend"></a><a class="link" href="#_fileappend">fileAppend()</a></h5>
<div class="paragraph">
<p>Syntax:<br>
<code>&#160;&#160;&#160;&#160;fileAppend(&lt;file-path&gt;) &#8594; any</code></p>
</div>
<div class="paragraph">
<p>Like <a href="#_fileCreate">fileCreate()</a> but write operations happen at the end of the file.</p>
</div>
</div> </div>
<div class="sect4"> <div class="sect4">
<h5 id="_filecreate"><a class="anchor" href="#_filecreate"></a><a class="link" href="#_filecreate">fileCreate()</a></h5> <h5 id="_filecreate"><a class="anchor" href="#_filecreate"></a><a class="link" href="#_filecreate">fileCreate()</a></h5>
<div class="paragraph">
<p>Syntax:<br>
<code>&#160;&#160;&#160;&#160;fileCreate(&lt;file-path&gt;) &#8594; file-handle</code></p>
</div>
<div class="paragraph">
<p>Creates or truncates the named <em>&lt;file-path&gt;</em>. If the file already exists, it is truncated. If the file does not exist, it is created with mode 0o666 (before umask). The associated file descriptor has mode [O_RDWR]. The directory containing the file must already exist.</p>
</div>
</div> </div>
<div class="sect4"> <div class="sect4">
<h5 id="_fileclose"><a class="anchor" href="#_fileclose"></a><a class="link" href="#_fileclose">fileClose()</a></h5> <h5 id="_fileclose"><a class="anchor" href="#_fileclose"></a><a class="link" href="#_fileclose">fileClose()</a></h5>
<div class="paragraph">
<p><mark>to-do</mark></p>
</div>
</div> </div>
<div class="sect4"> <div class="sect4">
<h5 id="_filewritetext"><a class="anchor" href="#_filewritetext"></a><a class="link" href="#_filewritetext">fileWriteText()</a></h5> <h5 id="_filewritetext"><a class="anchor" href="#_filewritetext"></a><a class="link" href="#_filewritetext">fileWriteText()</a></h5>
<div class="paragraph">
<p><mark>to-do</mark></p>
</div>
</div> </div>
<div class="sect4"> <div class="sect4">
<h5 id="_filereadtext"><a class="anchor" href="#_filereadtext"></a><a class="link" href="#_filereadtext">fileReadText()</a></h5> <h5 id="_filereadtext"><a class="anchor" href="#_filereadtext"></a><a class="link" href="#_filereadtext">fileReadText()</a></h5>
<div class="paragraph">
<p><mark>to-do</mark></p>
</div>
</div> </div>
<div class="sect4"> <div class="sect4">
<h5 id="_filereadtextall"><a class="anchor" href="#_filereadtextall"></a><a class="link" href="#_filereadtextall">fileReadTextAll()</a></h5> <h5 id="_filereadtextall"><a class="anchor" href="#_filereadtextall"></a><a class="link" href="#_filereadtextall">fileReadTextAll()</a></h5>
<div class="paragraph">
<p><mark>to-do</mark></p>
</div>
</div>
<div class="sect4">
<h5 id="_filebyteiterator"><a class="anchor" href="#_filebyteiterator"></a><a class="link" href="#_filebyteiterator">fileByteIterator()</a></h5>
<div class="paragraph">
<p>Syntax:<br>
<code>&#160;&#160;&#160;&#160;fileByteIterator(handle-or-path) &#8594; iterator</code></p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<div class="title">Examples</div>
<p>&gt;&gt;&gt; builtin "os.file"<br>
<code class="green">1</code><br>
<code>&gt;&gt;&gt;</code> <code class="blue">fileByteIterator("test-file.txt") map $_</code><br>
<code class="green">[
117,
110,
111,
10,
100,
117,
101,
10
]</code></p>
</div>
<div class="paragraph">
<p>&gt;&gt;&gt; builtin ["os.file", "string"]<br>
<code class="green">2</code><br>
<code>&gt;&gt;&gt;</code> <code class="blue">fileByteIterator("test-file.txt") map char($_)</code><br>
<code class="green">[
"u",
"n",
"o",
"
",
"d",
"u",
"e",
"
",
]</code></p>
</div>
</div>
<div class="sect4">
<h5 id="_filelineiterator"><a class="anchor" href="#_filelineiterator"></a><a class="link" href="#_filelineiterator">fileLineIterator()</a></h5>
<div class="paragraph">
<p>Syntax:<br>
<code>&#160;&#160;&#160;&#160;fileLineIterator(handle-or-path) &#8594; iterator</code></p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<div class="title">Examples</div>
<p><code>&gt;&gt;&gt;</code> <code class="blue">builtin "os.file"</code><br>
<code class="green">1</code><br>
<code>&gt;&gt;&gt;</code> <code class="blue">fileLineIterator("test-file.txt") map $_</code><br>
<code class="green">[
"uno",
"due"
]</code></p>
</div>
</div> </div>
</div> </div>
<div class="sect3"> <div class="sect3">
<h4 id="_module_string"><a class="anchor" href="#_module_string"></a><a class="link" href="#_module_string">7.1.7. Module "string"</a></h4> <h4 id="_module_string"><a class="anchor" href="#_module_string"></a><a class="link" href="#_module_string">7.1.7. Module "string"</a></h4>
<div class="paragraph">
<p>Module activation:<br>
<code>&#160;&#160;&#160;&#160;BUILTIN "string"</code></p>
</div>
<div class="paragraph">
<p>This module provides functions for working with strings.</p>
</div>
<div class="paragraph">
<p>Currently available functions:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="#_strJoin">strJoin()</a></p>
</li>
<li>
<p><a href="#_strSub">strSub()</a></p>
</li>
<li>
<p><a href="#_strSplit">strSplit()</a></p>
</li>
<li>
<p><a href="#_strTrim">strTrim()</a></p>
</li>
<li>
<p><a href="#_strStartsWith">strStartsWith()</a></p>
</li>
<li>
<p><a href="#_strEndsWith">strEndsWith()</a></p>
</li>
<li>
<p><a href="#_strUpper">strUpper()</a></p>
</li>
<li>
<p><a href="#_strLower">strLower()</a></p>
</li>
</ul>
</div>
<hr>
<div class="sect4"> <div class="sect4">
<h5 id="_strjoin"><a class="anchor" href="#_strjoin"></a><a class="link" href="#_strjoin">strJoin()</a></h5> <h5 id="_strjoin"><a class="anchor" href="#_strjoin"></a><a class="link" href="#_strjoin">strJoin()</a></h5>
<div class="paragraph"> <div class="paragraph">
@@ -3589,7 +3945,81 @@ Iterators built on custom data-sources can provide additional named operators, d
</div> </div>
</div> </div>
<div class="sect2"> <div class="sect2">
<h3 id="_iterator_over_custom_data_sources"><a class="anchor" href="#_iterator_over_custom_data_sources"></a><a class="link" href="#_iterator_over_custom_data_sources">8.2. Iterator over custom data-sources</a></h3> <h3 id="_infixed_operators_on_iterators"><a class="anchor" href="#_infixed_operators_on_iterators"></a><a class="link" href="#_infixed_operators_on_iterators">8.2. Infixed operators on iterators</a></h3>
<div class="paragraph">
<p>There are also some infixed operators that can be used with iterators. They are defined as follows.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="#_cat">cat operator</a></p>
</li>
<li>
<p><a href="#_diget">digest operator</a></p>
</li>
<li>
<p><a href="#_filter">filter operator</a></p>
</li>
<li>
<p><a href="#_groupby">groupby operator</a></p>
</li>
<li>
<p><a href="#_map">map operator</a></p>
</li>
</ul>
</div>
<hr>
<div class="sect3">
<h4 id="_cat_operator"><a class="anchor" href="#_cat_operator"></a><a class="link" href="#_cat_operator">8.2.1. <code class="blue">cat</code> operator</a></h4>
<div class="paragraph">
<p>Syntax:<br>
<code>&#160;&#160;&#160;&#160;&lt;iterable&gt; cat &lt;iterable&gt; &#8594; &lt;iterator&gt;&#160;&#160;&#160;&#160;</code></p>
</div>
<div class="paragraph">
<p><code class="blue">cat</code> 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.</p>
</div>
</div>
<div class="sect3">
<h4 id="_filter_operator"><a class="anchor" href="#_filter_operator"></a><a class="link" href="#_filter_operator">8.2.2. <code class="blue">filter</code> operator</a></h4>
<div class="paragraph">
<div class="title">Examples</div>
<p>Syntax:<br>
<code>&#160;&#160;&#160;&#160;&lt;iterable&gt; filter &lt;expr&gt; &#8594; &lt;iterator&gt;&#160;&#160;&#160;&#160;</code></p>
</div>
<div class="paragraph">
<p><code class="blue">filter</code> applies a boolean expression to each element of the iterator and returns a list of the elements for which the expression evaluates to true.</p>
</div>
</div>
<div class="sect3">
<h4 id="_groupby_operator"><a class="anchor" href="#_groupby_operator"></a><a class="link" href="#_groupby_operator">8.2.3. <code class="blue">groupby</code> operator</a></h4>
<div class="paragraph">
<p>Syntax:<br>
<code>&#160;&#160;&#160;&#160;&lt;dict&gt; groupby &lt;key&gt; &#8594; &lt;dict&gt;&#160;&#160;&#160;&#160;</code></p>
</div>
<div class="paragraph">
<p><code class="blue">groupby</code> 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.</p>
</div>
</div>
<div class="sect3">
<h4 id="_map_operator"><a class="anchor" href="#_map_operator"></a><a class="link" href="#_map_operator">8.2.4. <code class="blue">map</code> operator</a></h4>
<div class="paragraph">
<p>Syntax:<br>
<code>&#160;&#160;&#160;&#160;&lt;iterable&gt; map &lt;expr&gt; &#8594; &lt;list&gt;&#160;&#160;&#160;&#160;</code></p>
</div>
<div class="paragraph">
<p><code class="blue">map</code> 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 <code>$_</code>.</p>
</div>
<div class="paragraph">
<div class="title">Example: using the <code class="blue">map</code> operator</div>
<p><code>&gt;&gt;&gt;</code> <code class="blue">it = $(["one", "two", "three"])</code><br>
<code class="green">$(#3)</code><br>
<code>&gt;&gt;&gt;</code> <code class="blue">it map $_ + "!"</code><br>
<code class="green">["one!", "two!", "three!"]</code></p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_iterator_over_custom_data_sources"><a class="anchor" href="#_iterator_over_custom_data_sources"></a><a class="link" href="#_iterator_over_custom_data_sources">8.3. Iterator over custom data-sources</a></h3>
<div class="paragraph"> <div class="paragraph">
<p>It is possible to create iterators over custom data-sources by defining a dictionary that has the key <code>next</code> 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.</p> <p>It is possible to create iterators over custom data-sources by defining a dictionary that has the key <code>next</code> 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.</p>
</div> </div>
@@ -3610,7 +4040,7 @@ Iterators built on custom data-sources can provide additional named operators, d
</div> </div>
<div id="footer"> <div id="footer">
<div id="footer-text"> <div id="footer-text">
Last updated 2026-04-21 06:35:14 +0200 Last updated 2026-05-12 16:25:27 +0200
</div> </div>
</div> </div>
</body> </body>