From 382cb7aabdbfe367250afd4951b17a3dafe15385 Mon Sep 17 00:00:00 2001 From: Celestino Amoroso Date: Fri, 31 Jul 2026 08:01:13 +0200 Subject: [PATCH] Expr.doc: more details about the run() function from builtin iterator --- doc/Expr.adoc | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/doc/Expr.adoc b/doc/Expr.adoc index 8e36207..e3b643a 100644 --- a/doc/Expr.adoc +++ b/doc/Expr.adoc @@ -1583,7 +1583,33 @@ Module activation: + Syntax: + `{4sp}run(, , ) -> any` -Iterates over the specified iterator and applies the specified operator to the current value of the iterator. +where: +[horizontal] +iterator:: is any iterator. +operator:: is a function that accepts two optional parameters: _index_ and _item_. +vars:: is a dictionary defining a set of variables that are used to initialize the local context of run() and that will be inherited by each call to the operator. + +TIP: Instead of using _index_ and _item_ parameter, the operator function can refere the two automatic variables `$_` and `$__` respectively. + +_run()_ iterates over the specified iterator and applies the specified operator to the current value of the iterator. +It returns the value of the variable _status_ it defined, otherwise _nil_. + +In addition to the variables defined in vars, the local context includes the function _abort()_. The operator can call _abort()_ to terminate iterations. + +_abort()_ accepts the optional parameter _status_ used to change the value of of the variable of the same name and, therefore, of the value returned by _run()_. + +.Examples +`>>>` [blue]`builtin "iterator"` [gray]__// enable the iterator builtin module__ + +[green]`1` + +`>>>` [blue]`run($(10..15), func(){status = $\_})` [gray]__// returns the last iteration's index__ + +[green]`4` + +`>>>` [blue]`run($(10..15), func(){status = $__})` [gray]_// returns the last iteration's item_ + +[green]`14` + +`>>>` [blue]`run($(1..5), func(index,item){ (index > 3) ? {abort()} :: {status = item} })` + +[green]`4` + +`>>>` [blue]`run($(1..5), func(index,item){ (index > 2) ? {abort("aborted")} :: {status = item} })` + +[green]`aborted` + ==== Module "math.arith" Module activation: +