doc: begin of iterators description

doc/Expr.adoc

@@ -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#