doc: more details about iterators over dicts

doc/Expr.adoc

@@ -1419,7 +1419,8 @@ Lists and, soon, dictionaries, are implicit data-sources. The syntax for creatin
 *_iterator_* = "**$(**" _data-source_ "**)**" +
 _data-source_ = _explicit_ | _list-spec_ | _dict-spec_ | _custom-data-source_
 
-_explicit_ = _any-expr_ { "," _any-expr_ } +
+_explicit_ = _any-expr_ { "," _any-expr_ }
+
 _list-spec_ = _list_  _range-options_ +
 _list_ = "**[**" _any-expr_ { "," _any-expr_ } "**]**" +
 _range-options_ = [ "," _start-index_ [ "," _end-index_ [ "," _step_ ]]] +
@@ -1429,11 +1430,25 @@ _dict-spec_ = _dict_  _dict-options_ +
 _dict_ = "**{**" _key-value-pair_ { "," _key-value-pair_ } "**}**" +
 _key-value-pair_ = _scalar-value_ ":" _any-expr_ +
 _scalar-value_ = _string_ | _number_ | _boolean_ +
-_dict-options_ = [ "," _to-be-defined_ ]
+_dict-options_ = [ "," _sort-order_ [ "," _iter-mode_ ] ] +
+_sort-order_ = _asc-order_ | _desc-order_ | _no-sort_ | _default-order_ +
+_asc-order_ = "**asc**" | "**a**" +
+_desc-order_ = "**desc**" | "**d**" +
+_no-sort_ = "**none**" | "**nosort**" | "**no-sort**" | "**n**" +
+_default-order_ = "**default**" | "" +
+_iter-mode_ = _keys-iter_ | _values-iter_ | _items-iter_ | _default-iter_ +
+_keys-iter_ = "**key**" | "**keys**" | "**k**" +
+_values-iter_ = "**value**" | "**values**" | "**v**" +
+_items-iter_ = "**item**" | "**items**" | "**i**" +
+_default-iter_ = "**default**" | ""
 
 _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.
 ====
 
+NOTE: Currently, _default-order_ is the same as _asc-order_. In the future, it will be possible to specify a custom sorting function to define the default order.
+
+NOTE: Currently, _default-iter_ is the same as _keys-iter_. In the future, it will be possible to specify a custom iteration function to define the default iteration mode.
+
 .Example: iterator over an explicit list of elements
 `>>>` [blue]`it = $("A", "B", "C")` +
 [green]`$(#3)` +
@@ -1512,7 +1527,7 @@ Named operators are operators that are identified by a name instead of a symbol.
 * *_.next_*: same as [blue]`{plusplus}`.
 * *_.current_*: same as [blue]`{star}`.
 * *_.reset_*: resets the state of the iterator to the initial state.
-* *_.count_*: returns the number of elements in the iterator, if it can be determined.
+* *_.count_*: returns the number of elements in the iterator already visited.
 * *_.index_*: returns the index of the current element in the iterator. Before the first use of the [blue]`{plusplus}` operator, it returns the error [red]_-1_.
 
 TIP: Iterators built on custom data-sources can provide additional named operators, depending on the functionality they want to expose. For example, an iterator over a list could provide a named operator called [blue]`.reverse` that returns the next element of the collection in reverse order.

doc/Expr.html

@@ -3280,8 +3280,10 @@ Eval Error: add(): param nr 2 (2 in 0) has wrong type string, number expected<br
 <em>data-source</em> = <em>explicit</em> | <em>list-spec</em> | <em>dict-spec</em> | <em>custom-data-source</em></p>
 </div>
 <div class="paragraph">
-<p><em>explicit</em> = <em>any-expr</em> { "," <em>any-expr</em> }<br>
+<p><em>explicit</em> = <em>any-expr</em> { "," <em>any-expr</em> }</p>
-<em>list-spec</em> = <em>list</em>  <em>range-options</em><br>
+</div>
+<div class="paragraph">
+<p><em>list-spec</em> = <em>list</em>  <em>range-options</em><br>
 <em>list</em> = "<strong>[</strong>" <em>any-expr</em> { "," <em>any-expr</em> } "<strong>]</strong>"<br>
 <em>range-options</em> = [ "," <em>start-index</em> [ "," <em>end-index</em> [ "," <em>step</em> ]]]<br>
 <em>start-index</em>, <em>end-index</em>, <em>step</em> = <em>integer-expr</em></p>
@@ -3291,13 +3293,47 @@ Eval Error: add(): param nr 2 (2 in 0) has wrong type string, number expected<br
 <em>dict</em> = "<strong>{</strong>" <em>key-value-pair</em> { "," <em>key-value-pair</em> } "<strong>}</strong>"<br>
 <em>key-value-pair</em> = <em>scalar-value</em> ":" <em>any-expr</em><br>
 <em>scalar-value</em> = <em>string</em> | <em>number</em> | <em>boolean</em><br>
-<em>dict-options</em> = [ "," <em>to-be-defined</em> ]</p>
+<em>dict-options</em> = [ "," <em>sort-order</em> [ "," <em>iter-mode</em> ] ]<br>
+<em>sort-order</em> = <em>asc-order</em> | <em>desc-order</em> | <em>no-sort</em> | <em>default-order</em><br>
+<em>asc-order</em> = "<strong>asc</strong>" | "<strong>a</strong>"<br>
+<em>desc-order</em> = "<strong>desc</strong>" | "<strong>d</strong>"<br>
+<em>no-sort</em> = "<strong>none</strong>" | "<strong>nosort</strong>" | "<strong>no-sort</strong>" | "<strong>n</strong>"<br>
+<em>default-order</em> = "<strong>default</strong>" | ""<br>
+<em>iter-mode</em> = <em>keys-iter</em> | <em>values-iter</em> | <em>items-iter</em> | <em>default-iter</em><br>
+<em>keys-iter</em> = "<strong>key</strong>" | "<strong>keys</strong>" | "<strong>k</strong>"<br>
+<em>values-iter</em> = "<strong>value</strong>" | "<strong>values</strong>" | "<strong>v</strong>"<br>
+<em>items-iter</em> = "<strong>item</strong>" | "<strong>items</strong>" | "<strong>i</strong>"<br>
+<em>default-iter</em> = "<strong>default</strong>" | ""</p>
 </div>
 <div class="paragraph">
 <p><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="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+Currently, <em>default-order</em> is the same as <em>asc-order</em>. In the future, it will be possible to specify a custom sorting function to define the default order.
+</td>
+</tr>
+</table>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+Currently, <em>default-iter</em> is the same as <em>keys-iter</em>. In the future, it will be possible to specify a custom iteration function to define the default iteration mode.
+</td>
+</tr>
+</table>
+</div>
 <div class="paragraph">
 <div class="title">Example: iterator over an explicit list of elements</div>
 <p><code>&gt;&gt;&gt;</code> <code class="blue">it = $("A", "B", "C")</code><br>
@@ -3397,7 +3433,7 @@ Eval Error: add(): param nr 2 (2 in 0) has wrong type string, number expected<br
 <p><strong><em>.reset</em></strong>: resets the state of the iterator to the initial state.</p>
 </li>
 <li>
-<p><strong><em>.count</em></strong>: returns the number of elements in the iterator, if it can be determined.</p>
+<p><strong><em>.count</em></strong>: returns the number of elements in the iterator already visited.</p>
 </li>
 <li>
 <p><strong><em>.index</em></strong>: returns the index of the current element in the iterator. Before the first use of the <code class="blue">++</code> operator, it returns the error <em class="red">-1</em>.</p>
@@ -3457,7 +3493,7 @@ Iterators built on custom data-sources can provide additional named operators, d
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2026-04-19 08:18:50 +0200
+Last updated 2026-04-19 15:03:48 +0200
 </div>
 </div>
 </body>