From 7b93c5b4ac91d9b99b7baf0dbc828554f0bfdef1 Mon Sep 17 00:00:00 2001 From: Celestino Amoroso Date: Thu, 16 Apr 2026 10:13:41 +0200 Subject: [PATCH] doc: begin of iterators description --- doc/Expr.adoc | 76 +++++++++++++++++++++++++++++++++- doc/Expr.html | 110 ++++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 182 insertions(+), 4 deletions(-) diff --git a/doc/Expr.adoc b/doc/Expr.adoc index 0962bd9..fadcf97 100644 --- a/doc/Expr.adoc +++ b/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 `$()` 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]`` + +`>>>` [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# diff --git a/doc/Expr.html b/doc/Expr.html index 3269649..658bad0 100644 --- a/doc/Expr.html +++ b/doc/Expr.html @@ -590,7 +590,16 @@ pre.rouge .ss {
  • 6.4. Function context
    • -
  • 7. Iterators
    • +
  • 7. Iterators + +
  • 8. Builtins
    • 8.1. Builtin functions
      • @@ -2572,7 +2581,102 @@ The clone modifier @ does not make a variable a refere

      7. 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, 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.

      +
      +
      +
      Example 16. 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
      +

      >>> it = $(["one", "two", "three"])
      +$(#3)
      +>>> it++
      +"one"
      +>>> it++
      +"two"
      +>>> it++
      +"three"
      +>>> it++
      +Eval Error: EOF

      +
      +
      +

      7.1. Operators on iterators

      +
      +

      The above example shows the use of the ++ operator to get the next element of an iterator. The ++ 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 Eval Error: EOF.

      +
      +
      +

      After the first use of the ++ operator, the prefixed operato * 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 Eval Error: EOF. Same error is returned if the * operator is used before the first use of the ++ operator.

      +
      +
      +
      Example: using the * operator
      +

      >>> it = $(["one", "two", "three"])
      +$(#3)
      +>>> *it
      +Eval Error: EOF
      +>>> it++
      +"one"
      +>>> *it
      +"one"

      +
      +
      +

      7.1.1. 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 ++ has the equivalent named operator .next.

      +
      +
      +
      Available named operators
      +
        +
      • +

        .next: same as ++.

        +
        • +
      • +

        .current: same as *.

        +
        • +
      • +

        .reset: resets the state of the iterator to the initial state.

        +
        • +
      +
      +
      +
      Example: using the named operators
      +

      >>> it = $(["one", "two", "three"])
      +$(#3)
      +>>> it.next
      +"one"
      +>>> it.current
      +"one"
      +>>> it.next
      +"two"
      +>>> it.reset
      +<nil>
      +>>> it.current
      +Eval Error: EOF
      +>>> it.next
      +"one"

      +
      +
      +
      +
      +

      7.2. 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

      +
      @@ -2605,7 +2709,7 @@ The clone modifier @ does not make a variable a refere