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.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="#_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="#_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>
</ul>
</li>
@@ -613,8 +617,10 @@ pre.rouge .ss {
<li><a href="#_dec">dec()</a></li>
<li><a href="#_string">string()</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="#_var">var()</a></li>
<li><a href="#_set">set</a></li>
</ul>
</li>
<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="#_filereadtext">fileReadText()</a></li>
<li><a href="#_filereadtextall">fileReadTextAll()</a></li>
<li><a href="#_filebyteiterator">fileByteIterator()</a></li>
<li><a href="#_filelineiterator">fileLineIterator()</a></li>
</ul>
</li>
<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>
</ul>
</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>
</li>
<li><a href="#_plugins">9. Plugins</a></li>
@@ -686,7 +702,7 @@ pre.rouge .ss {
<div class="sectionbody">
<!-- toc disabled -->
<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>
@@ -788,7 +804,26 @@ pre.rouge .ss {
<code class="green">}</code></p>
</div>
<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>
@@ -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>
</div>
<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="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>match-list</em> = "<strong>[</strong>" <em>item</em> {"<strong>,</strong>" <em>items</em>} "<strong>]</strong>"<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>
<code class="red">Eval Error: [1:3] no case catches the value (10) of the selection expression</code></p>
</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 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>
<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 class="admonitionblock important">
<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>
</div>
<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 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>
@@ -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>
</td>
<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>
</tr>
</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>
</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>
<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>
</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"><code class="blue">:</code></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 class="paragraph">
<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>
</div>
</div>
<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>
<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 class="sect2">
@@ -2642,7 +2745,7 @@ short for<br>
<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>
<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>&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>
@@ -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="content">
<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>list-of-builtin-names</em> = <strong>[</strong> <em>string</em> { "<strong>,</strong>" <em>string</em> } <strong>]</strong></p>
</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>
<ul>
<li>
<p><a href="#_char">char()</a></p>
</li>
<li>
<p><a href="#_eval">eval()</a></p>
</li>
<li>
<p><a href="#_set">set()</a></p>
</li>
<li>
<p><a href="#_var">var()</a></p>
</li>
</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>
<code class="green">true</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 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>
<div class="paragraph">
<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 class="paragraph">
<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>
<div class="paragraph">
<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 class="paragraph">
<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 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>
<div class="paragraph">
<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>
</div>
<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 class="paragraph">
<div class="title">Examples</div>
<p><code>&gt;&gt;&gt;</code> <code class="blue">var("$x", 3+9)</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>&gt;&gt;&gt;</code> <code class="blue">var("gain%", var("$x"))</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>
</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 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>
<div class="paragraph">
<p><mark>to-do</mark></p>
</div>
<div class="sect4">
<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 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>
<div class="paragraph">
<p>Module activation:<br>
<code>&#160;&#160;&#160;&#160;BUILTIN "import"</code></p>
</div>
<div class="sect4">
<h5 id="_import"><a class="anchor" href="#_import"></a><a class="link" href="#_import"><em>import()</em></a></h5>
<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 class="sect4">
@@ -3137,16 +3293,40 @@ Computes and returns the value of the <span class="underline">string</span> expr
</div>
<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>
<div class="paragraph">
<p>Module activation:<br>
<code>&#160;&#160;&#160;&#160;BUILTIN "iterator"</code></p>
</div>
<div class="sect4">
<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 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>
<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>
</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">
<h5 id="_add"><a class="anchor" href="#_add"></a><a class="link" href="#_add">add()</a></h5>
<div class="paragraph">
@@ -3202,37 +3382,213 @@ Computes and returns the value of the <span class="underline">string</span> expr
</div>
<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>
<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">
<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 class="sect4">
<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 class="sect4">
<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 class="sect4">
<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 class="sect4">
<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 class="sect4">
<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 class="sect4">
<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 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>
<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">
<h5 id="_strjoin"><a class="anchor" href="#_strjoin"></a><a class="link" href="#_strjoin">strJoin()</a></h5>
<div class="paragraph">
@@ -3589,7 +3945,81 @@ Iterators built on custom data-sources can provide additional named operators, d
</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.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">
<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>
@@ -3610,7 +4040,7 @@ Iterators built on custom data-sources can provide additional named operators, d
</div>
<div id="footer">
<div id="footer-text">
Last updated 2026-04-21 06:35:14 +0200
Last updated 2026-05-12 16:25:27 +0200
</div>
</div>
</body>