table: support filtering

Support filtering of rows, useful with `StringWithTupleIndex` which
will get the original tuple index.

We also support relative-to-end indices in `HorizontalDividers`.

Author: RaduBerinde

internal/ascii/table/table.go

@@ -60,11 +60,20 @@ func Define[T any](fields ...Element) Layout[T] {
 // A Layout defines the layout of a table.
 type Layout[T any] struct {
 	fields []Element
+	// FilterFn can be set to filter out rows. This is useful when using the tuple
+	// index (e.g. StringWithTupleIndex), as the tuple index indicates the
+	// original (pre-filter) index.
+	FilterFn func(tupleIndex int, tuple T) (passed bool)
 }
 
 // HorizontalDividers is a set of row indices before which a horizontal divider
-// is placed. If nil, the defult is to place a divider before the first row
+// is placed. If nil, the default is to place a divider before the first row
 // (i.e. HorizontalDividers{0}).
+//
+// A negative index corresponds to the end of the table, with -1 being the last
+// row (meaning there will be a divider before the last row).
+//
+// The row indices apply after any filtering is performed (see Layout.FilterFn).
 type HorizontalDividers map[int]struct{}
 
 func MakeHorizontalDividers(rowIdx ...int) HorizontalDividers {
@@ -75,34 +84,45 @@ func MakeHorizontalDividers(rowIdx ...int) HorizontalDividers {
 	return hd
 }
 
-func (hd HorizontalDividers) Contains(rowIdx int) bool {
+func (hd HorizontalDividers) Contains(rowIdx int, numRows int) bool {
 	if hd == nil {
 		// Special case the nil value.
 		return rowIdx == 0
 	}
-	_, ok := hd[rowIdx]
-	return ok
+	if _, ok := hd[rowIdx]; ok {
+		return true
+	}
+	// Negative indices count from the end of the table (-1 is the last row).
+	if _, ok := hd[rowIdx-numRows]; ok {
+		return true
+	}
+	return false
 }
 
 // RenderOptions specifies the options for rendering a table.
 type RenderOptions struct {
 	HorizontalDividers HorizontalDividers
 }
 
-// Render renders the given iterator of rows of a table into the given cursor,
-// returning the modified cursor.
-func (d *Layout[T]) Render(start ascii.Cursor, opts RenderOptions, rows ...T) ascii.Cursor {
+// Render renders the given tuples into the given cursor, returning the modified
+// cursor.
+func (d *Layout[T]) Render(start ascii.Cursor, opts RenderOptions, tuples ...T) ascii.Cursor {
 	cur := start
 
-	tuples := rows
-	vals := make([]string, len(tuples))
+	rows := make([]int, 0, len(tuples))
+	for i := range tuples {
+		if d.FilterFn == nil || d.FilterFn(i, tuples[i]) {
+			rows = append(rows, i)
+		}
+	}
+	vals := make([]string, len(rows))
 	for fieldIdx, c := range d.fields {
 		if fieldIdx > 0 {
 			// Each column is separated by a space from the previous column or
 			// separator.
 			rowCur := cur
-			for rowIdx := range tuples {
-				if opts.HorizontalDividers.Contains(rowIdx) {
+			for rowIdx := range rows {
+				if opts.HorizontalDividers.Contains(rowIdx, len(rows)) {
 					rowCur = rowCur.Down(1)
 					rowCur.WriteString("-")
 				}
@@ -113,8 +133,8 @@ func (d *Layout[T]) Render(start ascii.Cursor, opts RenderOptions, rows ...T) as
 		if _, ok := c.(divider); ok {
 			rowCur := cur
 			rowCur.WriteString("|")
-			for rowIdx := range tuples {
-				if opts.HorizontalDividers.Contains(rowIdx) {
+			for rowIdx := range rows {
+				if opts.HorizontalDividers.Contains(rowIdx, len(rows)) {
 					rowCur = rowCur.Down(1)
 					rowCur.WriteString("+")
 				}
@@ -125,8 +145,8 @@ func (d *Layout[T]) Render(start ascii.Cursor, opts RenderOptions, rows ...T) as
 			continue
 		}
 		f := c.(Field[T])
-		for i, t := range tuples {
-			vals[i] = f.renderValue(i, t)
+		for rowIdx, tupleIdx := range rows {
+			vals[rowIdx] = f.renderValue(tupleIdx, tuples[tupleIdx])
 		}
 
 		width := c.width()
@@ -140,7 +160,7 @@ func (d *Layout[T]) Render(start ascii.Cursor, opts RenderOptions, rows ...T) as
 		pad(cur, width, align, header)
 		rowCur := cur
 		for rowIdx := range vals {
-			if opts.HorizontalDividers.Contains(rowIdx) {
+			if opts.HorizontalDividers.Contains(rowIdx, len(vals)) {
 				rowCur = rowCur.Down(1)
 				rowCur.RepeatByte(width, '-')
 			}
@@ -151,7 +171,7 @@ func (d *Layout[T]) Render(start ascii.Cursor, opts RenderOptions, rows ...T) as
 	}
 	rowCur := start.Down(len(vals) + 1)
 	for rowIdx := range vals {
-		if opts.HorizontalDividers.Contains(rowIdx) {
+		if opts.HorizontalDividers.Contains(rowIdx, len(vals)) {
 			rowCur = rowCur.Down(1)
 		}
 	}

internal/ascii/table/table_test.go

@@ -6,7 +6,6 @@ package table
 
 import (
 	"fmt"
-	"slices"
 	"strconv"
 	"testing"
 
@@ -20,16 +19,6 @@ func TestTable(t *testing.T) {
 		Age      int
 		Cuteness int
 	}
-	cats := []Cat{
-		{Name: "Chicken", Age: 5, Cuteness: 10},
-		{Name: "Heart", Age: 4, Cuteness: 10},
-		{Name: "Mai", Age: 2, Cuteness: 10},
-		{Name: "Poi", Age: 15, Cuteness: 10},
-		{Name: "Pigeon", Age: 2, Cuteness: 10},
-		{Name: "Sugar", Age: 8, Cuteness: 10},
-		{Name: "Yaya", Age: 5, Cuteness: 10},
-		{Name: "Yuumi", Age: 5, Cuteness: 10},
-	}
 
 	wb := ascii.Make(1, 10)
 	datadriven.RunTest(t, "testdata/table", func(t *testing.T, td *datadriven.TestData) string {
@@ -51,43 +40,55 @@ func TestTable(t *testing.T) {
 				opts.HorizontalDividers[i] = struct{}{}
 			}
 		}
+		var def Layout[Cat]
+		cats := []Cat{
+			{Name: "Chicken", Age: 5, Cuteness: 10},
+			{Name: "Heart", Age: 4, Cuteness: 10},
+			{Name: "Mai", Age: 2, Cuteness: 10},
+			{Name: "Poi", Age: 15, Cuteness: 10},
+			{Name: "Pigeon", Age: 2, Cuteness: 10},
+			{Name: "Sugar", Age: 8, Cuteness: 10},
+			{Name: "Yaya", Age: 5, Cuteness: 10},
+			{Name: "Yuumi", Age: 5, Cuteness: 10},
+		}
 		switch td.Cmd {
 		case "cats-tuple-index":
-			def := Define[Cat](
+			def = Define[Cat](
 				StringWithTupleIndex("idx", 3, AlignLeft, func(tupleIndex int, r Cat) string {
 					return fmt.Sprintf("%d", tupleIndex)
 				}),
 				Div(),
 				String("name", 7, align, func(c Cat) string { return c.Name }),
 			)
-			wb.Reset(1)
-			def.Render(wb.At(0, 0), opts, cats...)
-			return wb.String()
+
 		case "cats-nodiv":
-			def := Define[Cat](
+			def = Define[Cat](
 				String("name", 6, AlignLeft, func(c Cat) string { return c.Name }),
 				Int("age", 3, align, func(c Cat) int { return c.Age }),
 				Int("cuteness", 8, align, func(c Cat) int { return c.Cuteness }),
 			)
-			wb.Reset(1)
-			def.Render(wb.At(0, 0), opts, cats...)
-			return wb.String()
+
 		case "cats-column-too-wide":
-			c := slices.Clone(cats)
-			for i := range c {
-				c[i].Age *= 1_000_000
+			for i := range cats {
+				cats[i].Age *= 1_000_000
 			}
-			def := Define[Cat](
+			def = Define[Cat](
 				String("name", 6, AlignLeft, func(c Cat) string { return c.Name }),
 				Div(),
 				Int("age", 3, align, func(c Cat) int { return c.Age }),
 				Int("c", 1, align, func(c Cat) int { return c.Cuteness }),
 			)
-			wb.Reset(1)
-			def.Render(wb.At(0, 0), opts, c...)
-			return wb.String()
+
 		default:
 			return fmt.Sprintf("unknown command: %s", td.Cmd)
 		}
+		wb.Reset(1)
+		if td.HasArg("odd") {
+			def.FilterFn = func(tupleIndex int, c Cat) bool {
+				return c.Age%2 == 1
+			}
+		}
+		def.Render(wb.At(0, 0), opts, cats...)
+		return wb.String()
 	})
 }

internal/ascii/table/testdata/table

@@ -64,7 +64,7 @@ idx |    name
 6   |    Yaya
 7   |   Yuumi
 
-cats-tuple-index horizontal-dividers=(0,1,2,3,6,7)
+cats-tuple-index horizontal-dividers=(0,1,2,3,-2,-1)
 ----
 idx |    name
 ----+--------
@@ -82,6 +82,16 @@ idx |    name
 ----+--------
 7   |   Yuumi
 
+cats-tuple-index odd horizontal-dividers=(1,-1)
+----
+idx |    name
+0   | Chicken
+----+--------
+3   |     Poi
+6   |    Yaya
+----+--------
+7   |   Yuumi
+
 cats-column-too-wide
 ----
 name    |      age  c
@@ -95,7 +105,7 @@ Sugar   |  8000000 10
 Yaya    |  5000000 10
 Yuumi   |  5000000 10
 
-cats-column-too-wide horizontal-dividers=(0,3,5)
+cats-column-too-wide horizontal-dividers=(0,3,-3)
 ----
 name    |      age  c
 --------+------------