Added itrs:tap

_docs/mod/itrs.md

@@ -11,10 +11,19 @@ itrs:from LIST
 
 Returns an iterator which will step through the elements of LIST.
 
+### tap
+
+```
+itrs:tap ITR BLOCK
+```
+
+Returns an iterator which will execute BLOCK for each element consumed. The elements are consumed from the
+iterator ITR. BLOCK will only be executed when the element is consumed.
+
 ### to-list
 
 ```
-lists:to-list ITR
+itrs:to-list ITR
 ```
 
 Consume the elements of the iterator ITR and return the elements as a list.

ucl/builtins/itrs.go

@@ -10,6 +10,7 @@ func Itrs() ucl.Module {
 		Name: "itrs",
 		Builtins: map[string]ucl.BuiltinHandler{
 			"from":    iterFrom,
+			"tap":     iterTap,
 			"to-list": iterToList,
 		},
 	}
@@ -47,6 +48,45 @@ func (f *fromIterator) Next(ctx context.Context) (ucl.Object, error) {
 	return v, nil
 }
 
+func iterTap(ctx context.Context, args ucl.CallArgs) (any, error) {
+	var (
+		src ucl.Iterable
+		tap ucl.Invokable
+	)
+
+	if err := args.Bind(&src, &tap); err != nil {
+		return nil, err
+	}
+
+	return &tappedIterator{src, tap}, nil
+}
+
+type tappedIterator struct {
+	src ucl.Iterable
+	tap ucl.Invokable
+}
+
+func (f *tappedIterator) String() string {
+	return "tappedIterator{}"
+}
+
+func (f *tappedIterator) HasNext() bool {
+	return f.src.HasNext()
+}
+
+func (f *tappedIterator) Next(ctx context.Context) (ucl.Object, error) {
+	v, err := f.src.Next(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	if _, err := f.tap.Invoke(ctx, v); err != nil {
+		return nil, err
+	}
+
+	return v, nil
+}
+
 func iterToList(ctx context.Context, args ucl.CallArgs) (any, error) {
 	var itr ucl.Iterable
 	if err := args.Bind(&itr); err != nil {