From d7dd628fc9ae65cd4360e6e722512f2669d9fd77 Mon Sep 17 00:00:00 2001 From: Celestino Amoroso Date: Sun, 19 Apr 2026 08:20:40 +0200 Subject: [PATCH] doc: further details about iterator definition --- doc/Expr.adoc | 60 +++++++++++++++++++++++++- doc/Expr.html | 115 +++++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 167 insertions(+), 8 deletions(-) diff --git a/doc/Expr.adoc b/doc/Expr.adoc index facf747..4e46ef4 100644 --- a/doc/Expr.adoc +++ b/doc/Expr.adoc @@ -1410,17 +1410,42 @@ Same as add() but returns the product of the values of the parameters. == Iterators 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. +In general, 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_ + +_data-source_ = _explicit_ | _list-spec_ | _dict-spec_ | _custom-data-source_ + +_explicit_ = _any-expr_ { "," _any-expr_ } + +_list-spec_ = _list_ _range-options_ + +_list_ = "**[**" _any-expr_ { "," _any-expr_ } "**]**" + +_range-options_ = [ "," _start-index_ [ "," _end-index_ [ "," _step_ ]]] + +_start-index_, _end-index_, _step_ = _integer-expr_ + +_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_ ] + _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 an explicit list of elements +`>>>` [blue]`it = $("A", "B", "C")` + +[green]`$(#3)` + +`>>>` [blue]`it{plusplus}` + +[green]`"A"` + +`>>>` [blue]`it{plusplus}` + +[green]`"B"` + +`>>>` [blue]`it{plusplus}` + +[green]`"C"` + +`>>>` [blue]`it{plusplus}` + +[red]`Eval Error: EOF` + .Example: iterator over a list `>>>` [blue]`it = $(["one", "two", "three"])` + [green]`$(#3)` + @@ -1433,6 +1458,37 @@ _custom-data-source_ = _dict_ having the key `next` whose value is a function th `>>>` [blue]`it{plusplus}` + [red]`Eval Error: EOF` +On a list-type iterator creation expression, it is possible to specify an index range and a step to iterate over a subset of the list. + +Indexing starts at 0. If the start index is not specified, it defaults to 0. If the end index is not specified, it defaults to the index of the last element of the list. If the step is not specified, it defaults to 1. + +Negative indexes are allowed. They are interpreted as offsets from the end of the list. For example, an end index of -1 means the index of the last element of the list, an end index of -2 means the index of the second to last element of the list, and so on. + +Negative steps are also allowed. They are interpreted as reverse iteration. For example, a step of -1 means to iterate over the list in reverse order. + +.Example: iterator over a list with index range and step +`>>>` [blue]`it = $([1, 2, 3, 4, 5], 1, 4, 2)` + +[green]`$(#5)` + +`>>>` [blue]`it{plusplus}` + +[green]`2` + +`>>>` [blue]`it{plusplus}` + +[green]`4` + +`>>>` [blue]`it{plusplus}` + +[red]`Eval Error: EOF` + +.Example: iterator over a list in reverse order +`>>>` [blue]`it = $([1, 2, 3], -1, 0, -1)` + +[green]`$(#3)` + +`>>>` [blue]`it{plusplus}` + +[green]`3` + +`>>>` [blue]`it{plusplus}` + +[green]`2` + +`>>>` [blue]`it{plusplus}` + +[green]`1` + +`>>>` [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_. diff --git a/doc/Expr.html b/doc/Expr.html index 9b62e0e..b587922 100644 --- a/doc/Expr.html +++ b/doc/Expr.html @@ -3144,13 +3144,51 @@ Computes and returns the value of the string expr

7.1.5. Module "math.arith"

+
+

Currently, the "math.arith" module provides two functions, add() and mul(), that perform addition and multiplication of an arbitrary number of parameters. More functions will be added in the future.

+
add()
- +
+

Syntax:
+    add(<num-expr1>, <num-expr2>, …​) → any
+    add(<list-of-num-expr>]) → any
+    add(<iterator-over-num-values>) → any

+
+
+

Returns the sum of the values of the parameters. The parameters can be of any numeric type for which the + operator is defined. The result type depends on the types of the parameters. If all parameters are of the same type, the result is of that type. If the parameters are of different types, the result is of the type that can represent all the parameter types without loss of information. For example, if the parameters are a mix of integers and floats, the result is a float. If the parameters are a mix of number types, the result has the type of the most general one.

+
+
+
Examples
+

>>> add(1,2,3)
+6 +>>> add(1.1,2.1,3.1)
+6.300000000000001
+>>> add("1","2","3")
+Eval Error: add(): param nr 1 (1 in 0) has wrong type string, number expected
+>>> add(1:3, 2:3, 3:3)
+2:1
+>>> add(1, "2")
+Eval Error: add(): param nr 2 (2 in 0) has wrong type string, number expected
+>>> add([1,2,3])
+6
+>>> iterator=$([1,2,3]); add(iterator)
+6
+>>> add($([1,2,3]))
+6

+
mul()
- +
+

Syntax:
+    mul(<num-expr1>, <num-expr2>, …​) → any
+    mul(<list-of-num-expr>]) → any
+    mul(<iterator-over-num-values>) → any

+
+
+

Same as add() but returns the product of the values of the parameters.

+
@@ -3229,7 +3267,7 @@ Computes and returns the value of the string expr

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.

+

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

@@ -3239,12 +3277,41 @@ Computes and returns the value of the string expr

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.

+data-source = explicit | list-spec | dict-spec | custom-data-source

+
+
+

explicit = any-expr { "," any-expr }
+list-spec = list range-options
+list = "[" any-expr { "," any-expr } "]"
+range-options = [ "," start-index [ "," end-index [ "," step ]]]
+start-index, end-index, step = integer-expr

+
+
+

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 ]

+
+
+

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 an explicit list of elements
+

>>> it = $("A", "B", "C")
+$(#3)
+>>> it++
+"A"
+>>> it++
+"B"
+>>> it++
+"C"
+>>> it++
+Eval Error: EOF

+
+
Example: iterator over a list

>>> it = $(["one", "two", "three"])
$(#3)
@@ -3257,6 +3324,42 @@ Computes and returns the value of the string expr >>> it++
Eval Error: EOF

+
+

On a list-type iterator creation expression, it is possible to specify an index range and a step to iterate over a subset of the list.

+
+
+

Indexing starts at 0. If the start index is not specified, it defaults to 0. If the end index is not specified, it defaults to the index of the last element of the list. If the step is not specified, it defaults to 1.

+
+
+

Negative indexes are allowed. They are interpreted as offsets from the end of the list. For example, an end index of -1 means the index of the last element of the list, an end index of -2 means the index of the second to last element of the list, and so on.

+
+
+

Negative steps are also allowed. They are interpreted as reverse iteration. For example, a step of -1 means to iterate over the list in reverse order.

+
+
+
Example: iterator over a list with index range and step
+

>>> it = $([1, 2, 3, 4, 5], 1, 4, 2)
+$(#5)
+>>> it++
+2
+>>> it++
+4
+>>> it++
+Eval Error: EOF

+
+
+
Example: iterator over a list in reverse order
+

>>> it = $([1, 2, 3], -1, 0, -1)
+$(#3)
+>>> it++
+3
+>>> it++
+2
+>>> it++
+1
+>>> it++
+Eval Error: EOF

+

8.1. Operators on iterators

@@ -3354,7 +3457,7 @@ Iterators built on custom data-sources can provide additional named operators, d