doc: begin of iterators description
This commit is contained in:
parent
3ba8194ddb
commit
7b93c5b4ac
@ -22,6 +22,11 @@ Expressions calculator
|
||||
//:rouge-style: monokay
|
||||
// Workaround to manage double-column in back-tick quotes
|
||||
:2c: ::
|
||||
// Workaround to manage double-plus in back-tick quotes
|
||||
:plusplus: ++
|
||||
// Workaround to manage asterisk in back-tick quotes
|
||||
:star: *
|
||||
|
||||
|
||||
toc::[]
|
||||
|
||||
@ -991,7 +996,76 @@ The clone modifier can also be used to declare the formal parameters of function
|
||||
====
|
||||
|
||||
== Iterators
|
||||
#TODO: function calls operations#
|
||||
Iterators are objects that can be used to traverse collections, such as lists and dictionaries. They are created by providing a _data-source_ object, the collection, in a `$(<data-source>)` expression. Once an iterator is created, it can be used to access the elements of the collection one by one.
|
||||
|
||||
Data-sources are objects that can be iterated over. They are defined as dictionaries having the key `next` whose value is a function that returns the next element of the collection and updates the state of the iterator. The _next_ function must return a special value, [blue]_nil_, when there are no more elements to iterate over.
|
||||
|
||||
Lists and, soon, dictionaries, are implicit data-sources. The syntax for creating an iterator is as follows.
|
||||
|
||||
.Iterator creation syntax
|
||||
====
|
||||
*_iterator_* = "**$(**" _data-source_ "**)**" +
|
||||
_data-source_ = _list_ | _dict_ | _custom-data-source_ +
|
||||
_custom-data-source_ = _dict_ having the key `next` whose value is a function that returns the next element of the collection and updates the state of the iterator.
|
||||
====
|
||||
|
||||
.Example: iterator over a list
|
||||
`>>>` [blue]`it = $(["one", "two", "three"])` +
|
||||
[green]`$(#3)` +
|
||||
`>>>` [blue]`it{plusplus}` +
|
||||
[green]`"one"` +
|
||||
`>>>` [blue]`it{plusplus}` +
|
||||
[green]`"two"` +
|
||||
`>>>` [blue]`it{plusplus}` +
|
||||
[green]`"three"` +
|
||||
`>>>` [blue]`it{plusplus}` +
|
||||
[red]`Eval Error: EOF`
|
||||
|
||||
=== Operators on iterators
|
||||
The above example shows the use of the [blue]`{plusplus}` operator to get the next element of an iterator. The [blue]`{plusplus}` operator is a postfix operator that can be used with iterators. It returns the next element of the collection and updates the state of the iterator. When there are no more elements to iterate over, it returns the error [red]_Eval Error: EOF_.
|
||||
|
||||
|
||||
After the first use of the [blue]`{plusplus}` operator, the prefixed operato [blue]`{star}` operator can be used to get the current element of the collection without updating the state of the iterator. When there are no more elements to iterate over, it returns the error [red]_Eval Error: EOF_. Same error is returned if the [blue]`{star}` operator is used before the first use of the [blue]`{plusplus}` operator.
|
||||
|
||||
.Example: using the [blue]`{star}` operator
|
||||
`>>>` [blue]`it = $(["one", "two", "three"])` +
|
||||
[green]`$(#3)` +
|
||||
`>>>` [blue]`{star}it` +
|
||||
[red]`Eval Error: EOF` +
|
||||
`>>>` [blue]`it{plusplus}` +
|
||||
[green]`"one"` +
|
||||
`>>>` [blue]`{star}it` +
|
||||
[green]`"one"`
|
||||
|
||||
==== Named operators
|
||||
Named operators are operators that are identified by a name instead of a symbol. They are implicitly defined and can be called using a special syntax. For example, the [blue]`{plusplus}` has the equivalent named operator [blue]`.next`.
|
||||
|
||||
.Available named operators
|
||||
* *_.next_*: same as [blue]`{plusplus}`.
|
||||
* *_.current_*: same as [blue]`{star}`.
|
||||
* *_.reset_*: resets the state of the iterator to the initial state.
|
||||
|
||||
.Example: using the named operators
|
||||
`>>>` [blue]`it = $(["one", "two", "three"])` +
|
||||
[green]`$(#3)` +
|
||||
`>>>` [blue]`it.next` +
|
||||
[green]`"one"` +
|
||||
`>>>` [blue]`it.current` +
|
||||
[green]`"one"` +
|
||||
`>>>` [blue]`it.next` +
|
||||
[green]`"two"` +
|
||||
`>>>` [blue]`it.reset` +
|
||||
[green]`<nil>` +
|
||||
`>>>` [blue]`it.current` +
|
||||
[red]`Eval Error: EOF` +
|
||||
`>>>` [blue]`it.next` +
|
||||
[green]`"one"`
|
||||
|
||||
=== 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.
|
||||
|
||||
#TODO: custom data-sources#
|
||||
|
||||
|
||||
== Builtins
|
||||
#TODO: builtins#
|
||||
|
||||
110
doc/Expr.html
110
doc/Expr.html
@ -590,7 +590,16 @@ pre.rouge .ss {
|
||||
<li><a href="#_function_context">6.4. Function context</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#_iterators">7. Iterators</a></li>
|
||||
<li><a href="#_iterators">7. Iterators</a>
|
||||
<ul class="sectlevel2">
|
||||
<li><a href="#_operators_on_iterators">7.1. Operators on iterators</a>
|
||||
<ul class="sectlevel3">
|
||||
<li><a href="#_named_operators">7.1.1. Named operators</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#_iterator_over_custom_data_sources">7.2. Iterator over custom data-sources</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#_builtins">8. Builtins</a>
|
||||
<ul class="sectlevel2">
|
||||
<li><a href="#_builtin_functions">8.1. Builtin functions</a></li>
|
||||
@ -2572,7 +2581,102 @@ The clone modifier <code class="blue">@</code> does not make a variable a refere
|
||||
<h2 id="_iterators"><a class="anchor" href="#_iterators"></a><a class="link" href="#_iterators">7. Iterators</a></h2>
|
||||
<div class="sectionbody">
|
||||
<div class="paragraph">
|
||||
<p><mark>TODO: function calls operations</mark></p>
|
||||
<p>Iterators are objects that can be used to traverse collections, such as lists and dictionaries. They are created by providing a <em>data-source</em> object, the collection, in a <code>$(<data-source>)</code> expression. Once an iterator is created, it can be used to access the elements of the collection one by one.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Data-sources are objects that can be iterated over. They are defined as dictionaries having 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 <em>next</em> function must return a special value, <em class="blue">nil</em>, when there are no more elements to iterate over.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Lists and, soon, dictionaries, are implicit data-sources. The syntax for creating an iterator is as follows.</p>
|
||||
</div>
|
||||
<div class="exampleblock">
|
||||
<div class="title">Example 16. Iterator creation syntax</div>
|
||||
<div class="content">
|
||||
<div class="paragraph">
|
||||
<p><strong><em>iterator</em></strong> = "<strong>$(</strong>" <em>data-source</em> "<strong>)</strong>"<br>
|
||||
<em>data-source</em> = <em>list</em> | <em>dict</em> | <em>custom-data-source</em><br>
|
||||
<em>custom-data-source</em> = <em>dict</em> having 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.</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<div class="title">Example: iterator over a list</div>
|
||||
<p><code>>>></code> <code class="blue">it = $(["one", "two", "three"])</code><br>
|
||||
<code class="green">$(#3)</code><br>
|
||||
<code>>>></code> <code class="blue">it++</code><br>
|
||||
<code class="green">"one"</code><br>
|
||||
<code>>>></code> <code class="blue">it++</code><br>
|
||||
<code class="green">"two"</code><br>
|
||||
<code>>>></code> <code class="blue">it++</code><br>
|
||||
<code class="green">"three"</code><br>
|
||||
<code>>>></code> <code class="blue">it++</code><br>
|
||||
<code class="red">Eval Error: EOF</code></p>
|
||||
</div>
|
||||
<div class="sect2">
|
||||
<h3 id="_operators_on_iterators"><a class="anchor" href="#_operators_on_iterators"></a><a class="link" href="#_operators_on_iterators">7.1. Operators on iterators</a></h3>
|
||||
<div class="paragraph">
|
||||
<p>The above example shows the use of the <code class="blue">++</code> operator to get the next element of an iterator. The <code class="blue">++</code> operator is a postfix operator that can be used with iterators. It returns the next element of the collection and updates the state of the iterator. When there are no more elements to iterate over, it returns the error <em class="red">Eval Error: EOF</em>.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>After the first use of the <code class="blue">++</code> operator, the prefixed operato <code class="blue">*</code> operator can be used to get the current element of the collection without updating the state of the iterator. When there are no more elements to iterate over, it returns the error <em class="red">Eval Error: EOF</em>. Same error is returned if the <code class="blue">*</code> operator is used before the first use of the <code class="blue">++</code> operator.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<div class="title">Example: using the <code class="blue">*</code> operator</div>
|
||||
<p><code>>>></code> <code class="blue">it = $(["one", "two", "three"])</code><br>
|
||||
<code class="green">$(#3)</code><br>
|
||||
<code>>>></code> <code class="blue">*it</code><br>
|
||||
<code class="red">Eval Error: EOF</code><br>
|
||||
<code>>>></code> <code class="blue">it++</code><br>
|
||||
<code class="green">"one"</code><br>
|
||||
<code>>>></code> <code class="blue">*it</code><br>
|
||||
<code class="green">"one"</code></p>
|
||||
</div>
|
||||
<div class="sect3">
|
||||
<h4 id="_named_operators"><a class="anchor" href="#_named_operators"></a><a class="link" href="#_named_operators">7.1.1. Named operators</a></h4>
|
||||
<div class="paragraph">
|
||||
<p>Named operators are operators that are identified by a name instead of a symbol. They are implicitly defined and can be called using a special syntax. For example, the <code class="blue">++</code> has the equivalent named operator <code class="blue">.next</code>.</p>
|
||||
</div>
|
||||
<div class="ulist">
|
||||
<div class="title">Available named operators</div>
|
||||
<ul>
|
||||
<li>
|
||||
<p><strong><em>.next</em></strong>: same as <code class="blue">++</code>.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p><strong><em>.current</em></strong>: same as <code class="blue">*</code>.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p><strong><em>.reset</em></strong>: resets the state of the iterator to the initial state.</p>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<div class="title">Example: using the named operators</div>
|
||||
<p><code>>>></code> <code class="blue">it = $(["one", "two", "three"])</code><br>
|
||||
<code class="green">$(#3)</code><br>
|
||||
<code>>>></code> <code class="blue">it.next</code><br>
|
||||
<code class="green">"one"</code><br>
|
||||
<code>>>></code> <code class="blue">it.current</code><br>
|
||||
<code class="green">"one"</code><br>
|
||||
<code>>>></code> <code class="blue">it.next</code><br>
|
||||
<code class="green">"two"</code><br>
|
||||
<code>>>></code> <code class="blue">it.reset</code><br>
|
||||
<code class="green"><nil></code><br>
|
||||
<code>>>></code> <code class="blue">it.current</code><br>
|
||||
<code class="red">Eval Error: EOF</code><br>
|
||||
<code>>>></code> <code class="blue">it.next</code><br>
|
||||
<code class="green">"one"</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">7.2. 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>
|
||||
<div class="paragraph">
|
||||
<p><mark>TODO: custom data-sources</mark></p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
@ -2605,7 +2709,7 @@ The clone modifier <code class="blue">@</code> does not make a variable a refere
|
||||
</div>
|
||||
<div id="footer">
|
||||
<div id="footer-text">
|
||||
Last updated 2026-04-15 18:14:50 +0200
|
||||
Last updated 2026-04-15 19:26:58 +0200
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user