From 02ea20cdb5a1bda91f4fc8ef8db22a214de2c715 Mon Sep 17 00:00:00 2001
From: Celestino Amoroso <celestino.amoroso@gmail.com>
Date: Tue, 2 Jun 2026 11:02:04 +0200
Subject: [PATCH] Expr.adoc: $$() for iterator and better explanation of infix
 iterator operator

---
 doc/Expr.adoc | 53 +++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 43 insertions(+), 10 deletions(-)

diff --git a/doc/Expr.adoc b/doc/Expr.adoc
index c3dc806..5567ef2 100644
--- a/doc/Expr.adoc
+++ b/doc/Expr.adoc
@@ -599,7 +599,7 @@ _item-expr_ = _any-value_
 `>>>` [blue]`ls=[<1,2,3,4>]` +
 [green]`[<1, 2, 3, 4>]`
 
-#to be completed#
+#todo: to be completed#
 
 === Dictionaries
 The _dictionary_, or _dict_, data-type represents sets  of pairs _key/value_. It is also known as _map_ or _associative array_.
@@ -1838,6 +1838,11 @@ After the first use of the [blue]`{plusplus}` operator, the prefixed operator [b
 `>>>` [blue]`{star}it` +
 [green]`"one"`
 
+==== [blue]*`$$()`* -- Expansion special function for iterators
+The [blue]`$$()` operator is a special function already seen applied to contexts. It can also be applied that can be used with iterators. When applied to an iterator, it returns a _linked list_ of all the remaining elements of the collection. The state of the iterator is updated to the end of the collection. If there are no more elements to iterate over, it returns an empty list.
+
+#todo: examples#
+
 ==== 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`.
 
@@ -1886,33 +1891,61 @@ Syntax: +
 [blue]`cat` 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.
 
 .Examples
-
+#todo: examples#
 
 ==== [blue]`filter` operator
 Syntax: +
 `{4sp}<iterable> filter <expr> -> <iterator>{4sp}`
 
-[blue]`filter` applies a boolean expression to each element of the iterator and returns a list of the elements for which the expression evaluates to true.
+[blue]`filter` applies a boolean expression to each element of the iterator and returns a new iterator that only produces the elements of the first iterator for which the expression evaluates to true.
+
+.Examples
+#todo: examples#
 
 
 ==== [blue]`groupby` operator
 Syntax: +
-`{4sp}<dict> groupby <key> -> <dict>{4sp}`
+`{4sp}<list-of-dicts> groupby <key> -> <dict>{4sp}`
 
-[blue]`groupby` 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.
+The left side of [blue]`groupby` operator is a list ofdictionaries or an iterator over a list of dictionaries. It takes a key and returns a dictionary where the keys are the unique values of the specified key in the dictionaries and the values are lists of dictionaries that have that key value. In other words, it groups the dictionaries by the specified key value.
+
+.Examples
+`>>>` [blue]`[{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}, {"name": "Charlie", "age": 30}] groupby "age"` +
+[source,json]
+----
+{
+  25: [
+    {
+      "name": "Bob",
+      "age": 25
+    }
+  ],
+  30: [
+    {
+      "name": "Alice",
+      "age": 30
+    },
+    {
+      "name": "Charlie",
+      "age": 30
+    }
+  ]
+}
+----
 
 ==== [blue]`map` operator
 Syntax: +
-`{4sp}<iterable> map <expr> -> <list>{4sp}`
+`{4sp}<iterable> map <expr> -> <iterator>{4sp}`
 
-
-[blue]`map` 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 `$_`.
+[blue]`map` operator iterates over the elements of the iterator and evaluates the expressions provided on the right side for each element. Its result is a new iterator over the computed values of the that expression. The current element of the iterator is available in the expression as the variable `$_`.
 
 .Example: using the [blue]`map` operator
 `>>>` [blue]`it = $(["one", "two", "three"])` +
 [green]`$(#3)` +
-`>>>` [blue]`it map $_ + "!"` +
-[green]`["one!", "two!", "three!"]`
+`>>>` [blue]`excl_it = it map $_ + "!"` +
+[green]`$($([#3]))` +
+`>>>` [blue]`$$(excl_it)` +
+[green]`[<"one!", "two!", "three!">]`
 
 === 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.