Expr.doc: add section about intervals

builtin-iterator.go

@@ -92,13 +92,23 @@ func runFunc(ctx kern.ExprContext, name string, args map[string]any) (result any
 			// params = map[string]any{kern.ParamIndex: it.Index(), kern.ParamItem: item}
 			params[kern.ParamIndex] = it.Index()
 			params[kern.ParamItem] = item
+
+			localCtx.UnsafeSetVar("_", item)
+			localCtx.UnsafeSetVar("__", it.Index())
+
+			abort := false
 			if _, err = op.InvokeNamed(localCtx, iterParamOperator, params); err != nil {
-				break
+				abort = true
 			} else if abortAny, exists := localCtx.GetVar(iterVarAbort); exists {
 				if abort, ok := boolean.ToBool(abortAny); ok && abort {
-					break
+					abort = true
 				}
 			}
+			localCtx.DeleteVar("__")
+			localCtx.DeleteVar("_")
+			if abort {
+				break
+			}
 		}
 	}
 

doc/Expr.adoc

@@ -506,6 +506,50 @@ Currently, boolean operations are evaluated using _short cut evaluation_. This m
 TIP: `ecli` provides the _ctrl()_ function that allows to change this behaviour.
 ====
 
+=== Intervals
+_Expr_ supports intervals, which are a special kind of data type. An interval is a range *_open on the right_* of integer values between a lower and an upper bound. The lower and upper bounds can be specified in any order, i.e. the lower bound can be greater than the upper bound. In this case, the interval is considered _descending_. 
+
+Unlike arrays, intervals are not collections of values, but rather a compact representation of a range of values. And unlike other programming languages that separate lower and upper bounds by a colonn, _Expr_ separates them by a double dot symbol `..`.
+
+NOTE: Intervals are _open on the right_, which means that the upper bound is not included in the interval. For example, the interval `1..5` contains the values 1, 2, 3, and 4, but not 5.
+
+_Expr_'s intervals also support step values, which are optionally specified by a third integer value after the upper bound, separated by another doble dot symbol `..`. In this case, the interval represents a range of values starting from the lower bound, up to the upper bound, with a step increment equal to the specified step value. If the step value is not specified, it defaults to 1.
+
+IMPORTANT: The step value must be a positive integer, despite the fact that the lower bound is greater than the upper bound. If it is negative or zero, an error is returned.
+
+.Interval literal syntax
+====
+*_interval_* = [_lower-bound_] "**..**" _upper-bound_ ["**..**" _step_]
+
+_lower-bound_ = _integer-expr_ +
+_upper-bound_ = _integer-expr_ +
+_step_ = _positive-integer-expr_
+====
+
+.Examples
+`>>>` [blue]`3..5` +
+[green]`3..5..1`
+
+`>>>` [blue]`5..3` +
+[green]`5..3..1`
+
+`>>>` [blue]`..4` +
+[green]`0..4..1`
+
+`>>>` [blue]`4..` +
+[green]`4..4..1`
+
+`>>>` [blue]`-1..-4` +
+[green]`-1..-4..1`
+
+`>>>` [blue]`-1..-4..-1` +
+[red]`Eval Error: [1:8] invalid interval specification: step must be positive`
+
+`>>>` [blue]`r = -1..-4` [gray]_// assign interval to variable r_ +
+[green]`-1..-4..1`
+
+Main usages of intervals are to generate slices of arrays and to check if a value is in an interval.
+
 === Arrays
 _Expr_ supports arrays of mixed-type values, also specified by normal expressions. Internally, _Expr_'s arrays are Go slices.
 
@@ -513,7 +557,7 @@ _Expr_ supports arrays of mixed-type values, also specified by normal expression
 ====
 *_array_* = _empty-array_ | _non-empty-array_ +
 _empty-array_ = "**[]**" +
-_non-empty-array_ = "**[**" _any-value_ {"**,**" _any-value_} "**]**" +
+_non-empty-array_ = "**[**" _any-value_ {"**,**" _any-value_} "**]**"
 ====
 
 .Examples
@@ -559,7 +603,7 @@ Array's items can be accessed using the index `[]` operator.
 
 .Sub-array (or slice of array) syntax
 ====
-*_slice_* = _array-expr_ "**[**" _integer-expr_ "**:**" _integer-expr_ "**]**"
+*_slice_* = _array-expr_ "**[**" _interval-expr_ "**]**"
 ====
 
 .Examples: Getting items from arrays
@@ -569,7 +613,7 @@ Array's items can be accessed using the index `[]` operator.
 `>>>` [blue]`index=2; ["a", "b", "c", "d"][index]` +
 [green]`c`
 
-`>>>` [blue]`["a", "b", "c", "d"][2:]` +
+`>>>` [blue]`["a", "b", "c", "d"][2..4]` +
 [green]`["c", "d"]`
 
 `>>>` [blue]`array=[1,2,3]; array[1]` +
@@ -1583,7 +1627,33 @@ Module activation: +
 Syntax: +
 `{4sp}run(<iterator>, <operator>, <vars>) -> 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: +

int-iterator.go

@@ -17,6 +17,8 @@ import (
 type IntIterator struct {
 	count   int64
 	index   int64
+	next    int64
+	current any
 	start   int64
 	stop    int64
 	step    int64
@@ -110,26 +112,23 @@ func (it *IntIterator) CallOperation(name string, args map[string]any) (v any, e
 }
 
 func (it *IntIterator) Current() (item any, err error) {
-	if it.start <= it.stop {
-		if it.index >= it.start && it.index < it.stop {
-			item = it.index
-		} else {
-			err = io.EOF
-		}
-	} else {
-		if it.index > it.stop && it.index <= it.start {
-			item = it.index
-		} else {
-			err = io.EOF
-		}
-	}
-	return
+	return it.current, nil
 }
 
 func (it *IntIterator) Next() (item any, err error) {
-	it.index += it.step
-	if item, err = it.Current(); err != io.EOF {
+	item = it.next
+	if it.step > 0 {
+		if it.next+it.step > it.stop {
+			err = io.EOF
+		}
+	} else if it.next+it.step < it.stop {
+		err = io.EOF
+	}
+	if err == nil {
+		it.index++
 		it.count++
+		it.next += it.step
+		it.current = item
 	}
 	return
 }
@@ -143,7 +142,9 @@ func (it *IntIterator) Count() int64 {
 }
 
 func (it *IntIterator) Reset() error {
-	it.index = it.start - it.step
+	it.index = -1
+	it.next = it.start
+	it.current = nil
 	it.count = 0
 	return nil
 }

kern/common-params.go

@@ -26,7 +26,7 @@ const (
 	ParamIterator  = "iterator"
 )
 
-// to be moved in its own source file
+// to be moved into its own source file
 const (
 	ConstLastIndex = 0xFFFF_FFFF
 )

operator-in.go

@@ -10,6 +10,7 @@ import (
 	"git.portale-stac.it/go-pkg/expr/sym"
 	"git.portale-stac.it/go-pkg/expr/types/array"
 	"git.portale-stac.it/go-pkg/expr/types/dict"
+	"git.portale-stac.it/go-pkg/expr/types/interval"
 	"git.portale-stac.it/go-pkg/expr/types/list"
 )
 
@@ -46,6 +47,9 @@ func evalIn(ctx kern.ExprContext, opTerm *scan.Term) (v any, err error) {
 	} else if list.IsLinkedList(rightValue) {
 		ls, _ := rightValue.(*list.LinkedList)
 		v = ls.HasValue(leftValue)
+	} else if interval.IsInterval(rightValue) {
+		r, _ := rightValue.(*interval.IntervalType)
+		v = r.Contains(leftValue)
 	} else {
 		err = opTerm.ErrIncompatibleTypes(leftValue, rightValue)
 	}

scan/term.go

@@ -15,7 +15,6 @@ type TermPriority uint32
 
 const (
 	PriNone TermPriority = iota
-	PriInterval
 	PriBut
 	PriAssign
 	PriIterOp // map, filter, digest, etc
@@ -24,6 +23,7 @@ const (
 	PriAnd
 	PriNot
 	PriRelational
+	PriInterval
 	PriBitwiseOr
 	PriBitwiseAnd
 	PriBitwiseNot

t_index_test.go

@@ -45,10 +45,11 @@ func TestCollections(t *testing.T) {
 		/*  29 */ {`"abcdef"['x'..]`, nil, `[1:14] interval expression expected integer, got string (x)`},
 		/*  30 */ {`"abcdef"[1+..]`, nil, `[1:12] infix operator "+" requires two non-nil operands, got 1`},
 		/*  31 */ {`"abcdef"[1..4+]`, nil, `[1:15] infix operator "+" requires two non-nil operands, got 1`},
+		/*  32 */ {`r=-1..0..2; "abcdef"[r]`, "fdb", nil},
 	}
 
 	t.Setenv("EXPR_PATH", ".")
 
-	// RunTestSuiteSpec(t, section, inputs, 30)
+	// RunTestSuiteSpec(t, section, inputs, 32)
 	RunTestSuite(t, section, inputs)
 }

t_iterator_test.go

@@ -45,9 +45,10 @@ func TestIteratorParser(t *testing.T) {
 		/*  26 */ {`it=$(1..5..2); it++`, int64(1), nil},
 		/*  27 */ {`it=$(1.5..5..2); it++`, nil, `[1:13] interval expression expected integer, got float (1.5)`},
 		/*  28 */ {`it=$(.."z"); it++`, nil, `[1:7] interval expression expected integer, got string (z)`},
+		/*  29 */ {`it=$(3..1); it++; it.index`, int64(0), nil},
 	}
 
-	// RunTestSuiteSpec(t, section, inputs, 27)
+	// RunTestSuiteSpec(t, section, inputs, 25)
 	RunTestSuite(t, section, inputs)
 }
 

types/interval/interval.go

@@ -8,6 +8,7 @@ import (
 	"fmt"
 
 	"git.portale-stac.it/go-pkg/expr/kern"
+	"git.portale-stac.it/go-pkg/expr/types"
 )
 
 const TypeName = "interval"
@@ -60,6 +61,17 @@ func (p *IntervalType) ToIntTriple() (b, e, s int) {
 	return
 }
 
+func (p *IntervalType) Contains(value any) (ok bool) {
+	if v, err := types.ToGoInt64(value, TypeName); err == nil {
+		if p.begin <= p.end {
+			ok = (v >= p.begin && v < p.end && (v-p.begin)%p.step == 0)
+		} else {
+			ok = (v <= p.begin && v > p.end && (v-p.begin)%p.step == 0)
+		}
+	}
+	return
+}
+
 // func (b *bool) EqualTo(other kern.Equaler) (equal bool) {
 // 	if otherBool, ok := other.(*bool); ok {
 // 		equal = b == otherBool