Doc: little changes

doc/Expr.adoc

@@ -20,10 +20,12 @@ Expressions calculator
 :rouge-style: gruvbox
 // :rouge-style: colorful
 //:rouge-style: monokay
+// Work around to manage double-column in back-tick quotes
+:2c: ::
 
 toc::[]
 
-#TODO: Work in progress (last update on 2024/06/17, 16:31 a.m.)#
+#TODO: Work in progress (last update on 2024/06/21, 05:40 a.m.)#
 
 == Expr
 _Expr_ is a GO package capable of analysing, interpreting and calculating expressions.
@@ -554,7 +556,7 @@ NOTE: The assign operator [blue]`=` returns the value assigned to the variable.
 `>>>` [blue]`a_b` +
 [green]`3`
 
-`>>>` [blue]`x = 5.2 * (9-3)`  [gray]_// The assigned value has the approximation error typical of the float data-type_ +
+`>>>` [blue]`x = 5.2 * (9-3)`  [gray]_// The assigned value has the typical approximation error of the float data-type_ +
 [green]`31.200000000000003`
 
 `>>>` [blue]`x = 1; y = 2*x` +
@@ -572,6 +574,11 @@ NOTE: The assign operator [blue]`=` returns the value assigned to the variable.
 === [blue]`;` operator
 The semicolon operator [blue]`;` is an infixed pseudo-operator. It evaluates the left expression first and then the right expression. The value of the latter is the final result.
 
+.Mult-expression syntax
+====
+*_multi-expression_* = _expression_ {"**;**" _expression_ }
+====
+
 An expression that contains [blue]`;` is called a _multi-expression_ and each component expressione is called a _sub-expression_.
 
 IMPORTANT: Technically [blue]`;` is not treated as a real operator. It acts as a separator in lists of expressions.
@@ -630,38 +637,47 @@ The [blue]`:` symbol (colon) is the separator of the selector-cases. Note that i
 
 .Examples
 `>>>` [blue]`1 ? {"a"} : {"b"}` +
-[green]`b` +
+[green]`b`
-`>>>` [blue]`10 ? {"a"} : {"b"} :: {"c"}` +
+
-[green]`c' +
+`>>>` [blue]`10 ? {"a"} : {"b"} {2c} {"c"}` +
-[green]`>>>` [blue]`10 ? {"a"} :[true, 2+8] {"b"} :: {"c"}` +
+[green]`c`
-[green]`b` +
+
-`>>>` [blue]`10 ? {"a"} :[true, 2+8] {"b"} ::[10] {"c"}` +
+`>>>` [blue]`10 ? {"a"} :[true, 2+8] {"b"} {2c} {"c"}` +
-[red]`Parse Error: [1:34] case list in default clause` +
+[green]`b`
-[green]`>>>` [blue]`10 ? {"a"} :[10] {x="b" but x} :: {"c"}` +
+
-[green]`b` +
+`>>>` [blue]`10 ? {"a"} :[true, 2+8] {"b"} {2c} [10] {"c"}` +
-`>>>` [blue]`10 ? {"a"} :[10] {x="b"; x} :: {"c"}` +
+[red]`Parse Error: [1:34] case list in default clause`
-[green]`b` +
+
+`>>>` [blue]`10 ? {"a"} :[10] {x="b" but x} {2c} {"c"}` +
+[green]`b`
+
+`>>>` [blue]`10 ? {"a"} :[10] {x="b"; x} {2c} {"c"}` +
+[green]`b`
+
 `>>>` [blue]`10 ? {"a"} : {"b"}` +
 [red]`Eval Error: [1:3] no case catches the value (10) of the selection expression`
 
 
 === Variable default value [blue]`??` and [blue]`?=`
-The left operand of these two operators must be a variable. The right operator can be any expression. They return the value of the variable if this is define; otherwise they return the value of the right expression.
+The left operand of these two operators 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.
 
-IMPORTANT: If the left variable is defined, the right expression is not evuated at all.
+IMPORTANT: If the left variable is defined, the right expression is not evaluated at all.
 
-The [blue]`??` do not change the status of the left variable.
+The [blue]`??` operator do not change the status of the left variable.
 
 The [blue]`?=` assigns the calculated value of the right expression to the left variable.
 
 .Examples
-`>>>` [blue]`var ?? (1+2)`'
+`>>>` [blue]`var ?? (1+2)`' +
-[green]`3` +
+[green]`3`
+
 `>>>` [blue]`var` +
-[red]`Eval Error: undefined variable or function "var"` +
+[red]`Eval Error: undefined variable or function "var"`
+
 `>>>` [blue]`var ?= (1+2)` +
-[green]`3` +
+[green]`3`
-`>>>` [blue]`var` +
+
+`>>>` [blue]`var`
 [green]`3`
 
 NOTE: These operators have a high priority, in particular higher than the operator [blue]`=`.
@@ -678,6 +694,9 @@ The table below shows all supported operators by decreasing priorities.
 | [blue]`[`...`]` | _Postfix_ | _Dict item_ | _dict_ `[` _any_ `]` -> _any_
 .2+|*INC*| [blue]`++` | _Postfix_ | _Post increment_| _integer-variable_ `++` -> _integer_
 | [blue]`++` | _Postfix_ | _Next item_ | _iterator_ `++` -> _any_
+.2+|*DEFAULT*| [blue]`??` | _Infix_ | _Default value_| _variable_ `??` _any-expr_ -> _any_
+| [blue]`?=` | _Infix_ | _Default/assign value_| _variable_ `?=` _any-expr_ -> _any_
+.1+| *ITER*^1^| [blue]`()` | _Prefix_ | _Iterator value_ | `()` _iterator_ -> _any_
 .1+|*FACT*| [blue]`!` | _Postfix_ | _Factorial_| _integer_ `!` -> _integer_
 .3+|*SIGN*| [blue]`+`, [blue]`-` | _Prefix_ | _Change-sign_| (`+`\|`-`) _number_ -> _number_
 | [blue]`#` | _Prefix_ | _Lenght-of_ | `#` _collection_ -> _integer_
@@ -716,19 +735,38 @@ The table below shows all supported operators by decreasing priorities.
 .1+|*RANGE*| [blue]`:` | _Infix_ | _Index-range_ | _integer_ `:` _integer_ -> _integer-pair_
 |===
 
+^1^ Experimental
+
+
 == Functions
 Functions in _Expr_ are very similar to functions available in many programming languages. Actually, _Expr_ supports two types of function, _expr-functions_ and _go-functions_.
 
 * _expr-functions_ are defined using _Expr_'s syntax. They can be passed as arguments to other functions and can be returned from functions. Moreover, they bind themselves to the defining context, thus becoming closures.
 * _go-functions_ are regular Golang functions callable from _Expr_ expressions. They are defined in Golang source files called _modules_ and compiled within the _Expr_ package. To make Golang functions available in _Expr_ contextes, it is required to _import_ the module in which they are defined.
 
-In _Expr_ functions compute values in a local context (scope) that do not make effects on the calling context. This is the normal behavior. Using the reference operator [blue]`@` it is possibile to export local definition to the calling context.
+
+=== _Expr_ function definition
+A function is identified and referenced by its name. It can have zero or more parameter. _Expr_ functions also support optional parameters.
+
+. Expr's function definition syntax
+====
+*_function-definition_* = _identifier_ "**=**"  "**func(**" [_param-list_] "**)**"  "**{**" _multi-expression_ "**}**"
+_param_list_ = _required-param-list_ [ "**,**" _optional-param-list_ ]
+_required-param-list_ = _identifier_ { "**,**" _identifier_ }
+_optional-param-list_ = _optional-parm_ { "**,**" _optional-param_ }
+_optional-param_ = _identifier_ "**=**" _any-expr_
+====
+
+.Examples
+#TODO#
+
+=== _Golang_ function definition
+Description of how to define Golan functions and how to bind them to _Expr_ are topics treated in another document that I'll write, one day, maybe.
 
 === Function calls
 #TODO: function calls operations#
 
-=== Function definitions
+Functions compute values in a local context (scope) that do not make effects on the calling context. This is the normal behavior. Using the reference operator [blue]`@` it is possibile to export local definition to the calling context.
-#TODO: function definitions operations#
 
 
 == Iterators

doc/Expr.html

@@ -573,8 +573,9 @@ pre.rouge .ss {
 <li><a href="#_priorities_of_operators">5. Priorities of operators</a></li>
 <li><a href="#_functions">6. Functions</a>
 <ul class="sectlevel2">
-<li><a href="#_function_calls">6.1. Function calls</a></li>
+<li><a href="#_expr_function_definition">6.1. <em>Expr</em> function definition</a></li>
-<li><a href="#_function_definitions">6.2. Function definitions</a></li>
+<li><a href="#_golang_function_definition">6.2. <em>Golang</em> function definition</a></li>
+<li><a href="#_function_calls">6.3. Function calls</a></li>
 </ul>
 </li>
 <li><a href="#_iterators">7. Iterators</a></li>
@@ -593,7 +594,7 @@ pre.rouge .ss {
 <div class="sectionbody">
 <!-- toc disabled -->
 <div class="paragraph">
-<p><mark>TODO: Work in progress (last update on 2024/06/17, 16:31 a.m.)</mark></p>
+<p><mark>TODO: Work in progress (last update on 2024/06/21, 05:40 a.m.)</mark></p>
 </div>
 </div>
 </div>
@@ -1581,7 +1582,7 @@ The assign operator <code class="blue">=</code> returns the value assigned to th
 <code class="green">3</code></p>
 </div>
 <div class="paragraph">
-<p><code>&gt;&gt;&gt;</code> <code class="blue">x = 5.2 * (9-3)</code>  <em class="gray">// The assigned value has the approximation error typical of the float data-type</em><br>
+<p><code>&gt;&gt;&gt;</code> <code class="blue">x = 5.2 * (9-3)</code>  <em class="gray">// The assigned value has the typical approximation error of the float data-type</em><br>
 <code class="green">31.200000000000003</code></p>
 </div>
 <div class="paragraph">
@@ -1606,6 +1607,14 @@ The assign operator <code class="blue">=</code> returns the value assigned to th
 <div class="paragraph">
 <p>The semicolon operator <code class="blue">;</code> is an infixed pseudo-operator. It evaluates the left expression first and then the right expression. The value of the latter is the final result.</p>
 </div>
+<div class="exampleblock">
+<div class="title">Example 12. Mult-expression syntax</div>
+<div class="content">
+<div class="paragraph">
+<p><strong><em>multi-expression</em></strong> = <em>expression</em> {"<strong>;</strong>" <em>expression</em> }</p>
+</div>
+</div>
+</div>
 <div class="paragraph">
 <p>An expression that contains <code class="blue">;</code> is called a <em>multi-expression</em> and each component expressione is called a <em>sub-expression</em>.</p>
 </div>
@@ -1704,25 +1713,37 @@ Technically <code class="blue">;</code> is not treated as a real operator. It ac
 <div class="paragraph">
 <div class="title">Examples</div>
 <p><code>&gt;&gt;&gt;</code> <code class="blue">1 ? {"a"} : {"b"}</code><br>
-<code class="green">b</code><br>
+<code class="green">b</code></p>
-<code>&gt;&gt;&gt;</code> <code class="blue">10 ? {"a"} : {"b"} :: {"c"}</code><br>
+</div>
-<code class="green">c'<br>
+<div class="paragraph">
-[green]</code>&gt;&gt;&gt;` <code class="blue">10 ? {"a"} :[true, 2+8] {"b"} :: {"c"}</code><br>
+<p><code>&gt;&gt;&gt;</code> <code class="blue">10 ? {"a"} : {"b"} :: {"c"}</code><br>
-<code class="green">b</code><br>
+<code class="green">c</code></p>
-<code>&gt;&gt;&gt;</code> <code class="blue">10 ? {"a"} :[true, 2+8] {"b"} ::[10] {"c"}</code><br>
+</div>
-<code class="red">Parse Error: [1:34] case list in default clause</code><br>
+<div class="paragraph">
-<code class="green">&gt;&gt;&gt;</code> <code class="blue">10 ? {"a"} :[10] {x="b" but x} :: {"c"}</code><br>
+<p><code>&gt;&gt;&gt;</code> <code class="blue">10 ? {"a"} :[true, 2+8] {"b"} :: {"c"}</code><br>
-<code class="green">b</code><br>
+<code class="green">b</code></p>
-<code>&gt;&gt;&gt;</code> <code class="blue">10 ? {"a"} :[10] {x="b"; x} :: {"c"}</code><br>
+</div>
-<code class="green">b</code><br>
+<div class="paragraph">
-<code>&gt;&gt;&gt;</code> <code class="blue">10 ? {"a"} : {"b"}</code><br>
+<p><code>&gt;&gt;&gt;</code> <code class="blue">10 ? {"a"} :[true, 2+8] {"b"} :: [10] {"c"}</code><br>
+<code class="red">Parse Error: [1:34] case list in default clause</code></p>
+</div>
+<div class="paragraph">
+<p><code>&gt;&gt;&gt;</code> <code class="blue">10 ? {"a"} :[10] {x="b" but x} :: {"c"}</code><br>
+<code class="green">b</code></p>
+</div>
+<div class="paragraph">
+<p><code>&gt;&gt;&gt;</code> <code class="blue">10 ? {"a"} :[10] {x="b"; x} :: {"c"}</code><br>
+<code class="green">b</code></p>
+</div>
+<div class="paragraph">
+<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>
 <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> and <code class="blue">?=</code></a></h3>
 <div class="paragraph">
-<p>The left operand of these two operators must be a variable. The right operator can be any expression. They return the value of the variable if this is define; otherwise they return the value of the right expression.</p>
+<p>The left operand of these two operators 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>
 </div>
 <div class="admonitionblock important">
 <table>
@@ -1731,26 +1752,32 @@ Technically <code class="blue">;</code> is not treated as a real operator. It ac
 <i class="fa icon-important" title="Important"></i>
 </td>
 <td class="content">
-If the left variable is defined, the right expression is not evuated at all.
+If the left variable is defined, the right expression is not evaluated at all.
 </td>
 </tr>
 </table>
 </div>
 <div class="paragraph">
-<p>The <code class="blue">??</code> 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 class="paragraph">
 <p>The <code class="blue">?=</code> assigns the calculated value of the right expression to the left variable.</p>
 </div>
 <div class="paragraph">
 <div class="title">Examples</div>
-<p><code>&gt;&gt;&gt;</code> <code class="blue">var ?? (1+2)&#8217;
+<p><code>&gt;&gt;&gt;</code> <code class="blue">var ?? (1+2)&#8217;<br>
-[green]`3</code><br>
+[green]`3</code></p>
-<code>&gt;&gt;&gt;</code> <code class="blue">var</code><br>
+</div>
-<code class="red">Eval Error: undefined variable or function "var"</code><br>
+<div class="paragraph">
-<code>&gt;&gt;&gt;</code> <code class="blue">var ?= (1+2)</code><br>
+<p><code>&gt;&gt;&gt;</code> <code class="blue">var</code><br>
-<code class="green">3</code><br>
+<code class="red">Eval Error: undefined variable or function "var"</code></p>
-<code>&gt;&gt;&gt;</code> <code class="blue">var</code><br>
+</div>
+<div class="paragraph">
+<p><code>&gt;&gt;&gt;</code> <code class="blue">var ?= (1+2)</code><br>
+<code class="green">3</code></p>
+</div>
+<div class="paragraph">
+<p><code>&gt;&gt;&gt;</code> <code class="blue">var</code>
 <code class="green">3</code></p>
 </div>
 <div class="admonitionblock note">
@@ -1820,6 +1847,26 @@ These operators have a high priority, in particular higher than the operator <co
 <td class="tableblock halign-center valign-top"><p class="tableblock"><em>iterator</em> <code>++</code> &#8594; <em>any</em></p></td>
 </tr>
 <tr>
+<td class="tableblock halign-center valign-top" rowspan="2"><p class="tableblock"><strong>DEFAULT</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>
+<td class="tableblock halign-center valign-top"><p class="tableblock"><em>Default value</em></p></td>
+<td class="tableblock halign-center valign-top"><p class="tableblock"><em>variable</em> <code>??</code> <em>any-expr</em> &#8594; <em>any</em></p></td>
+</tr>
+<tr>
+<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>Default/assign value</em></p></td>
+<td class="tableblock halign-center valign-top"><p class="tableblock"><em>variable</em> <code>?=</code> <em>any-expr</em> &#8594; <em>any</em></p></td>
+</tr>
+<tr>
+<td class="tableblock halign-center valign-top"><p class="tableblock"><strong>ITER</strong><sup>1</sup></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>Prefix</em></p></td>
+<td class="tableblock halign-center valign-top"><p class="tableblock"><em>Iterator value</em></p></td>
+<td class="tableblock halign-center valign-top"><p class="tableblock"><code>()</code> <em>iterator</em> &#8594; <em>any</em></p></td>
+</tr>
+<tr>
 <td class="tableblock halign-center valign-top"><p class="tableblock"><strong>FACT</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>Postfix</em></p></td>
@@ -2050,6 +2097,9 @@ These operators have a high priority, in particular higher than the operator <co
 </tr>
 </tbody>
 </table>
+<div class="paragraph">
+<p><sup>1</sup> Experimental</p>
+</div>
 </div>
 </div>
 <div class="sect1">
@@ -2068,19 +2118,47 @@ These operators have a high priority, in particular higher than the operator <co
 </li>
 </ul>
 </div>
+<div class="sect2">
+<h3 id="_expr_function_definition"><a class="anchor" href="#_expr_function_definition"></a><a class="link" href="#_expr_function_definition">6.1. <em>Expr</em> function definition</a></h3>
 <div class="paragraph">
-<p>In <em>Expr</em> functions compute values in a local context (scope) that do not make effects on the calling context. This is the normal behavior. Using the reference operator <code class="blue">@</code> it is possibile to export local definition to the calling context.</p>
+<p>A function is identified and referenced by its name. It can have zero or more parameter. <em>Expr</em> functions also support optional parameters.</p>
+</div>
+<div class="olist arabic">
+<ol class="arabic">
+<li>
+<p>Expr&#8217;s function definition syntax</p>
+</li>
+</ol>
+</div>
+<div class="exampleblock">
+<div class="content">
+<div class="paragraph">
+<p><strong><em>function-definition</em></strong> = <em>identifier</em> "<strong>=</strong>"  "<strong>func(</strong>" [<em>param-list</em>] "<strong>)</strong>"  "<strong>{</strong>" <em>multi-expression</em> "<strong>}</strong>"
+<em>param_list</em> = <em>required-param-list</em> [ "<strong>,</strong>" <em>optional-param-list</em> ]
+<em>required-param-list</em> = <em>identifier</em> { "<strong>,</strong>" <em>identifier</em> }
+<em>optional-param-list</em> = <em>optional-parm</em> { "<strong>,</strong>" <em>optional-param</em> }
+<em>optional-param</em> = <em>identifier</em> "<strong>=</strong>" <em>any-expr</em></p>
+</div>
+</div>
+</div>
+<div class="paragraph">
+<div class="title">Examples</div>
+<p><mark>TODO</mark></p>
+</div>
 </div>
 <div class="sect2">
-<h3 id="_function_calls"><a class="anchor" href="#_function_calls"></a><a class="link" href="#_function_calls">6.1. Function calls</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">
+<p>Description of how to define Golan functions and how to bind them to <em>Expr</em> are topics treated in another document that I&#8217;ll write, one day, maybe.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_function_calls"><a class="anchor" href="#_function_calls"></a><a class="link" href="#_function_calls">6.3. Function calls</a></h3>
 <div class="paragraph">
 <p><mark>TODO: function calls operations</mark></p>
 </div>
-</div>
-<div class="sect2">
-<h3 id="_function_definitions"><a class="anchor" href="#_function_definitions"></a><a class="link" href="#_function_definitions">6.2. Function definitions</a></h3>
 <div class="paragraph">
-<p><mark>TODO: function definitions operations</mark></p>
+<p>Functions compute values in a local context (scope) that do not make effects on the calling context. This is the normal behavior. Using the reference operator <code class="blue">@</code> it is possibile to export local definition to the calling context.</p>
 </div>
 </div>
 </div>
@@ -2122,7 +2200,7 @@ These operators have a high priority, in particular higher than the operator <co
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2024-06-20 07:07:23 +0200
+Last updated 2024-06-21 09:06:12 +0200
 </div>
 </div>
 </body>