retable

type AnyValuesView ¶

type AnyValuesView struct {
	// Tit is the title of this view, returned by the Title() method.
	Tit string

	// Cols contains the column names defining both the column headers
	// and the number of columns in this view.
	Cols []string

	// Rows contains the data rows, where each row is a slice of any-typed values.
	// Each cell can hold a value of any type.
	Rows [][]any
}

AnyValuesView is a View implementation that stores cells as values of any type.

Unlike StringsView which is restricted to string values, AnyValuesView can hold heterogeneous data types within the same table. Each cell can contain values of different types (int, string, bool, struct, etc.), making it ideal for mixed-type data or when converting from other view types.

The underlying data structure uses [][]any, where each row is a slice of interface{} (any) values. This provides maximum flexibility at the cost of type safety and some performance overhead due to interface boxing.

Performance characteristics:

• Direct memory access: O(1) for cell retrieval
• Interface boxing overhead for value storage and retrieval
• Higher memory usage than StringsView due to interface overhead
• Type assertions required when accessing specific types

When to use AnyValuesView:

• Working with mixed-type tabular data (numbers, strings, booleans, etc.)
• Caching data from another View with NewAnyValuesViewFrom
• Need to store arbitrary Go values in table cells
• Converting between different view types
• Building dynamic tables where cell types aren't known at compile time

Example usage:

view := &retable.AnyValuesView{
    Tit:  "Mixed Data",
    Cols: []string{"ID", "Name", "Active", "Score"},
    Rows: [][]any{
        {1, "Alice", true, 95.5},
        {2, "Bob", false, 87.3},
    },
}
// Type assertion needed for specific types
if score, ok := view.Cell(0, 3).(float64); ok {
    fmt.Printf("Score: %.1f\n", score)
}

Thread safety: Not thread-safe. External synchronization required for concurrent access.

func NewAnyValuesViewFrom(source View) *AnyValuesView

// Cache an expensive computed view
expensiveView := retable.NewComputedView(...)
cached := retable.NewAnyValuesViewFrom(expensiveView)
// Now cached can be accessed multiple times without recomputation

func (view *AnyValuesView) Cell(row, col int) any

value := view.Cell(0, 2)
switch v := value.(type) {
case int:
    fmt.Printf("Integer: %d\n", v)
case string:
    fmt.Printf("String: %s\n", v)
case bool:
    fmt.Printf("Boolean: %t\n", v)
}

func (view *AnyValuesView) Columns() []string

func (view *AnyValuesView) NumRows() int

func (view *AnyValuesView) Title() string

type CellFormatter ¶

type CellFormatter interface {
	// FormatCell formats the view cell at a row/col position as string.
	//
	// Returns errors.ErrUnsupported if this formatter doesn't support the cell's type,
	// signaling that alternative formatters should be tried. Other errors indicate
	// actual formatting failures.
	//
	// The raw result indicates whether the returned string is in the raw format of
	// the target table format and can be used as-is (true), or if it needs to be
	// sanitized according to the output format (false).
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control
	//   - view: The table view containing the cell to format
	//   - row: Zero-based row index
	//   - col: Zero-based column index
	//
	// Returns:
	//   - str: The formatted string representation
	//   - raw: Whether the string is format-specific raw output
	//   - err: Error if formatting failed, or errors.ErrUnsupported if unsupported
	FormatCell(ctx context.Context, view View, row, col int) (str string, raw bool, err error)
}

CellFormatter is the primary interface for formatting table cell values as strings. This is the higher-level interface compared to Formatter, as it operates on cells within a table View context and supports format-specific "raw" output.

The CellFormatter design supports a sophisticated formatting pipeline where multiple formatters can be tried in sequence until one successfully formats a value. Formatters signal their inability to handle a value by returning errors.ErrUnsupported, which allows the caller to try alternative formatters.

The "raw" result concept is crucial for output format optimization: when raw is true, the string can be used directly in the output format without escaping or sanitization (e.g., HTML tags in HTML output, CSV-formatted values in CSV output). When raw is false, the string should be sanitized according to the output format (e.g., HTML-escaped).

Design pattern:

// Try formatters in priority order
str, raw, err := formatter1.FormatCell(ctx, view, row, col)
if errors.Is(err, errors.ErrUnsupported) {
    str, raw, err = formatter2.FormatCell(ctx, view, row, col)
}
if err != nil {
    // handle error or use fallback
}

Example usage:

formatter := PrintfCellFormatter("%.2f")
str, raw, err := formatter.FormatCell(ctx, view, 0, 0)
if err != nil {
    // handle error
}
if !raw {
    str = html.EscapeString(str) // sanitize for HTML output
}

func CellFormatterFromFormatter(f Formatter, rawResult bool) CellFormatter

formatter := SprintFormatter{}
cellFormatter := CellFormatterFromFormatter(formatter, false)
// cellFormatter can now be used in table rendering

func SprintCellFormatter(rawResult bool) CellFormatter

// Non-raw formatter (strings need sanitization)
formatter := SprintCellFormatter(false)
str, raw, _ := formatter.FormatCell(ctx, view, 0, 0)
// str contains fmt.Sprint output, raw == false

// Raw formatter (strings are pre-formatted)
rawFormatter := SprintCellFormatter(true)
str, raw, _ := rawFormatter.FormatCell(ctx, view, 0, 0)
// str contains fmt.Sprint output, raw == true

func TryFormattersOrSprint(formatters ...CellFormatter) CellFormatter

formatter := TryFormattersOrSprint(
    PrintfCellFormatter("%.2f"),      // Try formatting as float with 2 decimals
    LayoutFormatter("2006-01-02"),    // Try formatting as date
    // Falls back to fmt.Sprint for other types
)
str, raw, err := formatter.FormatCell(ctx, view, 0, 0)
// Uses first matching formatter, or fmt.Sprint if none match

type CellFormatterFunc ¶

type CellFormatterFunc func(ctx context.Context, view View, row, col int) (str string, raw bool, err error)

CellFormatterFunc is a function type that implements the CellFormatter interface, allowing plain functions to be used as CellFormatters.

This adapter type follows the common Go pattern of defining a function type that implements an interface (similar to http.HandlerFunc), making it easy to create inline formatters without defining separate types.

Example:

formatter := CellFormatterFunc(func(ctx context.Context, view View, row, col int) (string, bool, error) {
    val := view.Cell(row, col)
    if num, ok := val.(int); ok {
        return fmt.Sprintf("#%05d", num), false, nil
    }
    return "", false, errors.ErrUnsupported
})

func ReflectCellFormatterFunc(function any, rawResult bool) (formatter CellFormatterFunc, valType reflect.Type, err error)

// Simple type-safe formatter
formatter, typ, err := ReflectCellFormatterFunc(
    func(t time.Time) string {
        return t.Format("2006-01-02")
    },
    false,
)
// typ == reflect.TypeOf(time.Time{})
// formatter is a CellFormatterFunc that only works with time.Time

// With context and error handling
formatter, typ, err := ReflectCellFormatterFunc(
    func(ctx context.Context, val CustomType) (string, error) {
        if err := ctx.Err(); err != nil {
            return "", err
        }
        return val.Format(), nil
    },
    false,
)

// No arguments (formats any value the same way)
formatter, _, err := ReflectCellFormatterFunc(
    func() string { return "constant" },
    true,
)

func (f CellFormatterFunc) FormatCell(ctx context.Context, view View, row, col int) (str string, raw bool, err error)

type ExtraColsView ¶

type ExtraColsView []View

ExtraColsView is a zero-copy decorator that horizontally concatenates multiple Views, combining their columns into a single unified View. This is the columnar equivalent of a SQL JOIN operation, allowing you to merge data from different sources side-by-side.

Key Features ¶

• Horizontal concatenation: Columns from all views appear sequentially
• Zero-copy: No data duplication, references original Views
• Automatic row padding: Shorter views treated as having nil cells for extra rows
• Preserves types: Each cell maintains its original type from source View

Use Cases ¶

• Joining related data: Combine user profiles with their statistics
• Adding computed columns: Append calculated values to existing data
• Merging partial data: Combine views from different data sources
• Building composite reports: Unite data from multiple queries

Row Count Behavior ¶

The resulting view has as many rows as the longest input View. Shorter views are implicitly padded with nil values:

View1: 10 rows, 2 columns
View2: 5 rows, 3 columns
ExtraColsView: 10 rows, 5 columns (View2 rows 5-9 are all nil)

Column Order ¶

Columns appear in the order of views in the slice:

ExtraColsView{view1, view2, view3}
Columns: [view1.col0, view1.col1, view2.col0, view2.col1, view3.col0]

Performance Characteristics ¶

• No data copying: Only stores View references
• Linear column lookup: O(n) where n is number of views
• Constant row lookup: O(1) after finding the right view
• Memory efficient: Only overhead is the slice of View references

Example: Basic Column Concatenation ¶

// View1: Name and Age
people := NewStringsView("People", [][]string{
    {"Alice", "30"},
    {"Bob", "25"},
}, []string{"Name", "Age"})

// View2: City and Country
locations := NewStringsView("", [][]string{
    {"NYC", "USA"},
    {"London", "UK"},
}, []string{"City", "Country"})

// Combine them
combined := ExtraColsView{people, locations}
// Columns: ["Name", "Age", "City", "Country"]
// Row 0: ["Alice", "30", "NYC", "USA"]
// Row 1: ["Bob", "25", "London", "UK"]

Example: Unequal Row Counts ¶

view1 := NewStringsView("", [][]string{
    {"A1"}, {"A2"}, {"A3"},
}, []string{"Col1"})

view2 := NewStringsView("", [][]string{
    {"B1"},
}, []string{"Col2"})

combined := ExtraColsView{view1, view2}
// 3 rows total (max of 3 and 1)
combined.Cell(0, 0) -> "A1"
combined.Cell(0, 1) -> "B1"
combined.Cell(1, 0) -> "A2"
combined.Cell(1, 1) -> nil  // view2 has no row 1
combined.Cell(2, 0) -> "A3"
combined.Cell(2, 1) -> nil  // view2 has no row 2

Example: Adding Computed Columns ¶

// Original data
baseView := NewStructRowsView("Sales", salesData, nil, nil)

// Add computed columns via a custom view
computedView := ExtraColsAnyValueFuncView(nil, []string{"Total", "Tax"},
    func(row, col int) any {
        // Calculate based on baseView data
        if col == 0 { return calculateTotal(row) }
        return calculateTax(row)
    })

// Combine
enriched := ExtraColsView{baseView, computedView}
// Now has original columns plus Total and Tax

Example: Multi-Source Join ¶

users := loadUsersView()      // id, name, email
profiles := loadProfilesView() // bio, avatar
stats := loadStatsView()       // post_count, follower_count

fullProfile := ExtraColsView{users, profiles, stats}
// Columns: id, name, email, bio, avatar, post_count, follower_count

Edge Cases ¶

• Empty ExtraColsView{} results in 0 rows, 0 columns, empty title
• Single view ExtraColsView{view} behaves identically to view
• Views with 0 rows contribute 0 to final row count
• Negative row/col indices return nil
• Column index beyond total column count returns nil

Composition ¶

ExtraColsView can be nested and combined with other decorators:

base := NewStringsView(...)
extra1 := ExtraColsView{base, computedView1}
extra2 := ExtraColsView{extra1, computedView2}
filtered := &FilteredView{Source: extra2, RowLimit: 10}
// First 10 rows with all computed columns

Title Behavior ¶

The title is taken from the first view in the slice. If you need a custom title, wrap the result with ViewWithTitle.

func (e ExtraColsView) Cell(row, col int) any

view1 has columns ["A", "B"] (indices 0-1)
view2 has columns ["C", "D", "E"] (indices 2-4 in combined view)

combined := ExtraColsView{view1, view2}

combined.Cell(0, 0) -> view1.Cell(0, 0)  // Column "A"
combined.Cell(0, 1) -> view1.Cell(0, 1)  // Column "B"
combined.Cell(0, 2) -> view2.Cell(0, 0)  // Column "C"
combined.Cell(0, 3) -> view2.Cell(0, 1)  // Column "D"
combined.Cell(0, 4) -> view2.Cell(0, 2)  // Column "E"
combined.Cell(0, 5) -> nil               // Out of bounds

func (e ExtraColsView) Columns() []string

[view0.col0, view0.col1, ..., view1.col0, view1.col1, ..., viewN.colM]

view1.Columns() -> ["A", "B"]
view2.Columns() -> ["C", "D", "E"]
ExtraColsView{view1, view2}.Columns() -> ["A", "B", "C", "D", "E"]

func (e ExtraColsView) NumRows() int

view1.NumRows() -> 10
view2.NumRows() -> 5
view3.NumRows() -> 15
ExtraColsView{view1, view2, view3}.NumRows() -> 15

func (e ExtraColsView) Title() string

type ExtraRowView ¶

type ExtraRowView []View

ExtraRowView is a zero-copy decorator that vertically concatenates multiple Views, stacking their rows into a single unified View. This is the row equivalent of a SQL UNION operation, allowing you to combine data from different sources with the same column structure.

Key Features ¶

• Vertical concatenation: Rows from all views appear sequentially
• Zero-copy: No data duplication, references original Views
• Column alignment: All views must have compatible column structures
• Preserves types: Each cell maintains its original type from source View

Use Cases ¶

• Combining result sets: Merge data from multiple queries
• Appending batches: Stack incrementally loaded data
• Unifying data sources: Combine test + prod data for reports
• Building composite datasets: Unite similar data from different time periods

Column Structure Requirements ¶

ExtraRowView uses the column structure from the first view in the slice. All subsequent views should have the same column count and compatible types. The implementation does NOT validate column compatibility - it's the caller's responsibility to ensure views have matching structures.

Column names are taken only from the first view:

View1: ["Name", "Age"]  <- columns used
View2: ["Name", "Age"]
ExtraRowView columns: ["Name", "Age"]

If views have different columns, cells are accessed by position only:

View1: ["A", "B"]
View2: ["X", "Y"]
ExtraRowView: columns ["A", "B"], but view2.Cell(0, 0) returns "X" data

Row Count Behavior ¶

The resulting view has the sum of all input Views' row counts:

View1: 10 rows
View2: 5 rows
View3: 15 rows
ExtraRowView: 30 rows total

Performance Characteristics ¶

• No data copying: Only stores View references
• Linear row lookup: O(n) where n is number of views
• Constant column lookup: O(1)
• Memory efficient: Only overhead is the slice of View references

Example: Basic Row Concatenation ¶

// Historical data
past := NewStringsView("", [][]string{
    {"Alice", "30"},
    {"Bob", "25"},
}, []string{"Name", "Age"})

// Recent data
recent := NewStringsView("", [][]string{
    {"Charlie", "35"},
    {"Diana", "28"},
}, []string{"Name", "Age"})

// Combine them
all := ExtraRowView{past, recent}
// 4 rows total:
// Row 0: ["Alice", "30"]   (from past)
// Row 1: ["Bob", "25"]     (from past)
// Row 2: ["Charlie", "35"] (from recent)
// Row 3: ["Diana", "28"]   (from recent)

Example: Combining Multiple Data Sources ¶

usData := loadUSCustomers()      // 100 rows
euData := loadEUCustomers()      // 75 rows
asiaData := loadAsiaCustomers()  // 50 rows

allCustomers := ExtraRowView{usData, euData, asiaData}
// 225 rows total, all with same columns

Example: Appending Summary Rows ¶

dataRows := loadDataView()

// Create a summary row view
summaryData := [][]any{
    {"TOTAL", sumValues(), avgValues()},
}
summary := NewAnyValuesView("", summaryData, dataRows.Columns())

// Append summary at the bottom
withSummary := ExtraRowView{dataRows, summary}
// Last row contains the totals

Example: Combining Filtered Subsets ¶

allData := loadDataView()

// Split into categories
categoryA := &FilteredView{
    Source: allData,
    RowOffset: 0,
    RowLimit: 10,
}
categoryB := &FilteredView{
    Source: allData,
    RowOffset: 50,
    RowLimit: 10,
}

// Recombine selected rows
selected := ExtraRowView{categoryA, categoryB}
// 20 rows: first 10 from categoryA, then 10 from categoryB

Example: Multi-Batch Loading ¶

var batches []View
for batch := range loadIncrementally() {
    batches = append(batches, batch)
}
allData := ExtraRowView(batches)
// All batches combined into single view

Row Index Translation ¶

Cell access translates row indices to the appropriate source view:

view1 has 10 rows (indices 0-9)
view2 has 5 rows (indices 10-14 in combined view)
view3 has 8 rows (indices 15-22 in combined view)

combined := ExtraRowView{view1, view2, view3}

combined.Cell(5, 0)  -> view1.Cell(5, 0)   // Within view1
combined.Cell(12, 0) -> view2.Cell(2, 0)   // Within view2 (12-10=2)
combined.Cell(20, 0) -> view3.Cell(5, 0)   // Within view3 (20-15=5)

Edge Cases ¶

• Empty ExtraRowView{} results in 0 rows, 0 columns, empty title
• Single view ExtraRowView{view} behaves identically to view
• Views with 0 rows contribute nothing to final result
• Negative row/col indices return nil
• Column index beyond first view's column count returns nil
• Row index beyond total row count returns nil

Column Mismatch Behavior ¶

If views have different column counts, no error occurs:

• Columns() returns the first view's columns only

• Accessing a column index >= a view's column count returns nil for that view's rows

  view1 := NewStringsView("", [][]string{{"A", "B"}}, []string{"Col1", "Col2"}) view2 := NewStringsView("", [][]string{{"X"}}, []string{"Col1"})

  combined := ExtraRowView{view1, view2} combined.Columns() -> ["Col1", "Col2"] combined.Cell(0, 0) -> "A" combined.Cell(0, 1) -> "B" combined.Cell(1, 0) -> "X" combined.Cell(1, 1) -> nil // view2 has no column 1

Composition ¶

ExtraRowView can be nested and combined with other decorators:

batch1 := loadBatch1()
batch2 := loadBatch2()
combined := ExtraRowView{batch1, batch2}

// Filter the combined result
filtered := &FilteredView{
    Source: combined,
    RowLimit: 100,
}

// Add computed columns to the combination
enriched := ExtraColsAnyValueFuncView(filtered, []string{"Score"}, scoreFunc)

Title Behavior ¶

The title is taken from the first view in the slice. If you need a custom title, wrap the result with ViewWithTitle.

func (e ExtraRowView) Cell(row, col int) any

view1 has 2 rows (indices 0-1 in combined view)
view2 has 3 rows (indices 2-4 in combined view)

combined := ExtraRowView{view1, view2}

combined.Cell(0, 0) -> view1.Cell(0, 0)  // First row of view1
combined.Cell(1, 0) -> view1.Cell(1, 0)  // Second row of view1
combined.Cell(2, 0) -> view2.Cell(0, 0)  // First row of view2
combined.Cell(3, 0) -> view2.Cell(1, 0)  // Second row of view2
combined.Cell(4, 0) -> view2.Cell(2, 0)  // Third row of view2
combined.Cell(5, 0) -> nil               // Out of bounds

func (e ExtraRowView) Columns() []string

view1.Columns() -> ["A", "B", "C"]
view2.Columns() -> ["A", "B", "C"]
ExtraRowView{view1, view2}.Columns() -> ["A", "B", "C"]

func (e ExtraRowView) NumRows() int

view1.NumRows() -> 10
view2.NumRows() -> 5
view3.NumRows() -> 15
ExtraRowView{view1, view2, view3}.NumRows() -> 30

func (e ExtraRowView) Title() string

type FilteredView ¶

type FilteredView struct {
	// Source is the underlying View to filter and transform.
	// All Cell() calls are delegated to this View after applying
	// row offset and column mapping transformations.
	Source View

	// RowOffset is the index of the first row from Source to include.
	// Rows 0 to RowOffset-1 are skipped.
	// Negative values are treated as 0.
	// If RowOffset >= Source.NumRows(), the view will have 0 rows.
	//
	// Example:
	//   RowOffset: 0  -> starts at first row (no offset)
	//   RowOffset: 10 -> skips first 10 rows, starts at row 10
	RowOffset int

	// RowLimit caps the maximum number of rows in this view.
	// If RowLimit is 0 or negative, no limit is applied (all rows shown).
	// If RowLimit > 0, at most RowLimit rows are shown.
	// The actual row count may be less if Source has fewer rows available.
	//
	// Example:
	//   RowLimit: 0  -> no limit, show all rows after RowOffset
	//   RowLimit: 10 -> show at most 10 rows
	RowLimit int

	// ColumnMapping controls which columns are visible and in what order.
	//
	// If nil:
	//   - All columns from Source are included
	//   - Columns appear in their original order
	//   - NumCols() returns len(Source.Columns())
	//
	// If not nil:
	//   - Only mapped columns are included
	//   - len(ColumnMapping) determines NumCols()
	//   - Each element is an index into Source's columns
	//   - Columns can be reordered or duplicated
	//
	// Example:
	//   ColumnMapping: nil        -> [0, 1, 2, 3] (all columns)
	//   ColumnMapping: []int{0}   -> [0] (only first column)
	//   ColumnMapping: []int{2,0} -> [2, 0] (columns 2 and 0, reordered)
	//   ColumnMapping: []int{1,1} -> [1, 1] (column 1 duplicated)
	//
	// WARNING: Invalid indices (negative or >= Source.NumCols()) will cause
	// panics when accessing cells or column names.
	ColumnMapping []int
}

FilteredView is a decorator that provides zero-copy filtering, slicing, and column remapping of an underlying View. It implements pagination, column selection, and column reordering without duplicating the underlying data.

Key Features ¶

• Row slicing: Skip rows (RowOffset) and limit results (RowLimit)
• Column filtering: Select specific columns via ColumnMapping
• Column reordering: Rearrange columns by mapping indices
• Zero-copy: No data duplication, just index manipulation

Use Cases ¶

• Pagination: Implement offset/limit patterns for large datasets
• Column selection: Export only specific columns (e.g., for CSV or API responses)
• Column reordering: Change column display order without modifying source data
• Data projection: Create different views of the same underlying data

Performance Characteristics ¶

FilteredView is extremely lightweight:

• No data copying: Source data is never duplicated
• Constant overhead: Cell access adds only index arithmetic
• Memory efficient: Only stores integers for offset, limit, and mapping

Example: Pagination ¶

// Original view with 1000 rows
source := NewStringsView("Products", productData, columns)

// Get page 3 (rows 20-29, assuming page size of 10)
page3 := &FilteredView{
    Source:    source,
    RowOffset: 20,
    RowLimit:  10,
}
fmt.Println(page3.NumRows()) // 10

Example: Column Selection ¶

// Select only columns 0, 2, and 4 from source
filtered := &FilteredView{
    Source:        source,
    ColumnMapping: []int{0, 2, 4},
}
// Accessing column 0 of filtered reads column 0 of source
// Accessing column 1 of filtered reads column 2 of source
// Accessing column 2 of filtered reads column 4 of source

Example: Column Reordering ¶

// Reverse column order (assuming 3 columns)
reversed := &FilteredView{
    Source:        source,
    ColumnMapping: []int{2, 1, 0},
}

Example: Combined Operations ¶

// Select specific columns AND paginate
view := &FilteredView{
    Source:        source,
    RowOffset:     100,
    RowLimit:      25,
    ColumnMapping: []int{0, 3, 5}, // Only columns 0, 3, 5
}

Field Details ¶

• Source: The underlying View to filter/transform (required)
• RowOffset: Number of rows to skip from the beginning (0 = no offset)
• RowLimit: Maximum number of rows to include (0 = no limit, show all remaining)
• ColumnMapping: nil = all columns; []int = column indices to include/reorder

Edge Cases ¶

• Negative RowOffset is treated as 0
• RowOffset beyond source length results in 0 rows
• Out-of-bounds cell access returns nil
• Invalid column mapping indices will panic on Cell() access

Composition ¶

FilteredView can wrap other FilteredViews for complex transformations:

base := NewStringsView(...)
step1 := &FilteredView{Source: base, ColumnMapping: []int{0, 2, 4, 6}}
step2 := &FilteredView{Source: step1, RowOffset: 10, RowLimit: 5}
// step2 shows rows 10-14 of base, with columns 0, 2, 4, 6

func (view *FilteredView) Cell(row, col int) any

source := NewStringsView("Data", [][]string{
    {"A0", "B0", "C0"},  // row 0
    {"A1", "B1", "C1"},  // row 1
    {"A2", "B2", "C2"},  // row 2
    {"A3", "B3", "C3"},  // row 3
}, []string{"A", "B", "C"})

filtered := &FilteredView{
    Source:        source,
    RowOffset:     1,           // skip first row
    RowLimit:      2,           // show 2 rows
    ColumnMapping: []int{2, 0}, // columns C, A
}

filtered.Cell(0, 0) -> "C1"  (row 1, col 2 in source)
filtered.Cell(0, 1) -> "A1"  (row 1, col 0 in source)
filtered.Cell(1, 0) -> "C2"  (row 2, col 2 in source)
filtered.Cell(2, 0) -> nil   (row 2 is out of bounds in filtered view)

func (view *FilteredView) Columns() []string

source.Columns() -> ["A", "B", "C", "D"]
view := &FilteredView{Source: source, ColumnMapping: []int{3, 1}}
view.Columns() -> ["D", "B"]

func (view *FilteredView) NumCols() int

func (view *FilteredView) NumRows() int

Source has 100 rows:
  RowOffset: 0,  RowLimit: 0   -> 100 rows
  RowOffset: 10, RowLimit: 0   -> 90 rows
  RowOffset: 10, RowLimit: 20  -> 20 rows
  RowOffset: 95, RowLimit: 20  -> 5 rows (limited by available data)
  RowOffset: 200, RowLimit: 0  -> 0 rows (offset beyond data)

func (view *FilteredView) Title() string

type Formatter ¶

type Formatter interface {
	// Format converts a reflect.Value to its string representation.
	// Returns errors.ErrUnsupported if the formatter doesn't support the value's type.
	Format(reflect.Value) (string, error)
}

Formatter is a reflection-based value formatter that converts a reflect.Value to a string. This is the simpler, lower-level interface compared to CellFormatter, as it operates directly on reflect.Value without requiring a View context or cell coordinates.

Formatter is useful when you need to format individual values that aren't necessarily part of a table structure, or when building custom CellFormatter implementations.

Example usage:

formatter := FormatterFunc(func(v reflect.Value) (string, error) {
    if v.Kind() == reflect.Int {
        return fmt.Sprintf("#%d", v.Int()), nil
    }
    return "", errors.ErrUnsupported
})
str, err := formatter.Format(reflect.ValueOf(42))
// str == "#42"

func FormatterFromCellFormatter(f CellFormatter) Formatter

cellFormatter := PrintfCellFormatter("%d%%")
formatter := FormatterFromCellFormatter(cellFormatter)
str, _ := formatter.Format(reflect.ValueOf(95))
// str == "95%"

type FormatterFunc ¶

type FormatterFunc func(reflect.Value) (string, error)

FormatterFunc is a function type that implements the Formatter interface, allowing plain functions to be used as Formatters.

This adapter type follows the common Go pattern of defining a function type that implements an interface (similar to http.HandlerFunc).

Example:

var formatter Formatter = FormatterFunc(func(v reflect.Value) (string, error) {
    return fmt.Sprintf("value: %v", v.Interface()), nil
})

func (f FormatterFunc) Format(v reflect.Value) (string, error)

type HeaderView ¶

type HeaderView struct {
	// Tit is the title of this view.
	Tit string

	// Cols contains the column names, which are also used as the data row.
	Cols []string
}

HeaderView is a specialized View that contains only a header row.

This view type displays column names as both the column headers and the single data row, making it useful for showing just table structure or for combining multiple views where you need header information displayed.

The view always has exactly one row (NumRows() returns 1), and that row contains the column names as values.

When to use HeaderView:

• Displaying table structure/schema information
• Creating view combinations where headers need to be visible
• Testing or debugging column configurations
• Generating table metadata displays

Example:

view := &retable.HeaderView{
    Tit:  "User Schema",
    Cols: []string{"ID", "Name", "Email", "Active"},
}
// Row 0 will contain: "ID", "Name", "Email", "Active"

func NewHeaderView(cols ...string) *HeaderView

view := retable.NewHeaderView("ID", "Name", "Email")
fmt.Println(view.NumRows())    // Output: 1
fmt.Println(view.Cell(0, 1))   // Output: Name

func NewHeaderViewFrom(source View) *HeaderView

original := retable.NewStringsView("Products", data, "ID", "Name", "Price")
headerOnly := retable.NewHeaderViewFrom(original)
// headerOnly contains just one row with "ID", "Name", "Price" as values

func (view *HeaderView) Cell(row, col int) any

func (view *HeaderView) Columns() []string

func (view *HeaderView) NumRows() int

func (view *HeaderView) Title() string

type LayoutFormatter ¶

type LayoutFormatter string

LayoutFormatter formats values that implement the Format(string) string method, such as time.Time, by calling their Format method with the layout string.

This formatter is specifically designed for types like time.Time that use layout strings for formatting. The string value of this type becomes the layout parameter passed to the value's Format method.

If the cell value doesn't implement the required interface, an error is returned (not errors.ErrUnsupported, but a descriptive error about the type mismatch).

Example usage:

// Format time.Time values as ISO dates
formatter := LayoutFormatter("2006-01-02")
str, raw, err := formatter.FormatCell(ctx, view, 0, 0)
// For time.Time value of "2024-03-15 14:30:00"
// str == "2024-03-15", raw == false

// Format as 12-hour time
timeFormatter := LayoutFormatter("3:04 PM")
// For time.Time value of "2024-03-15 14:30:00"
// str == "2:30 PM"

func (f LayoutFormatter) FormatCell(ctx context.Context, view View, row, col int) (str string, raw bool, err error)

type Option ¶

type Option int

Option represents formatting options that can be applied when rendering tables. Options are implemented as bit flags and can be combined using bitwise OR.

const (
	// OptionAddHeaderRow adds a header row containing column titles
	// as the first row in the formatted output.
	//
	// When this option is set, the View's Columns() method is called to get column titles,
	// and these are rendered as the first row before any data rows.
	//
	// Example:
	//
	//	rows, err := FormatViewAsStrings(ctx, view, nil, OptionAddHeaderRow)
	//	// First row will contain: ["Column1", "Column2", "Column3"]
	//	// Subsequent rows contain data
	OptionAddHeaderRow Option = 1 << iota
)

func (o Option) Has(option Option) bool

opts := OptionAddHeaderRow
if opts.Has(OptionAddHeaderRow) {
    // Header row option is enabled
}

func (o Option) String() string

opt := OptionAddHeaderRow
fmt.Println(opt.String()) // Output: "AddHeaderRow"

opt = 0
fmt.Println(opt.String()) // Output: "no Option"

type Parser ¶

type Parser interface {
	// ParseInt parses a string into a 64-bit signed integer.
	// Returns an error if the string is not a valid integer.
	ParseInt(string) (int64, error)

	// ParseUint parses a string into a 64-bit unsigned integer.
	// Returns an error if the string is not a valid unsigned integer.
	ParseUint(string) (uint64, error)

	// ParseFloat parses a string into a 64-bit floating point number.
	// May handle locale-specific formatting (e.g., comma vs. period decimals).
	// Returns an error if the string is not a valid float.
	ParseFloat(string) (float64, error)

	// ParseBool parses a string into a boolean value.
	// The strings recognized as true/false are implementation-specific.
	// Returns an error if the string is not recognized as a boolean.
	ParseBool(string) (bool, error)

	// ParseTime parses a string into a time.Time value.
	// May try multiple time formats in sequence.
	// Returns an error if the string doesn't match any recognized format.
	ParseTime(string) (time.Time, error)

	// ParseDuration parses a string into a time.Duration value.
	// Uses Go's standard duration format (e.g., "1h30m", "5s").
	// Returns an error if the string is not a valid duration.
	ParseDuration(string) (time.Duration, error)
}

Parser is the interface for parsing string representations into primitive Go types. This is the counterpart to formatting - it handles the conversion from strings back to typed values.

Parser provides a centralized place to configure parsing behavior, including:

• Which strings represent boolean true/false values
• Which strings represent nil/null values
• Which time formats to try when parsing time values
• Locale-specific number formatting (e.g., comma vs. period decimal separators)

The Parser interface is used by Scanners to perform the actual string-to-value conversions. By abstracting parsing into an interface, different parsing strategies can be used (strict vs. lenient, different locale conventions, etc.).

Example usage:

parser := NewStringParser()
// Configure custom boolean strings
parser.TrueStrings = []string{"true", "yes", "1", "on"}
parser.FalseStrings = []string{"false", "no", "0", "off"}

// Parse various types
i, _ := parser.ParseInt("42")          // 42
f, _ := parser.ParseFloat("3,14")      // 3.14 (handles comma decimal)
b, _ := parser.ParseBool("yes")        // true
t, _ := parser.ParseTime("2024-03-15") // time.Time value

type PrintfCellFormatter ¶

type PrintfCellFormatter string

PrintfCellFormatter implements CellFormatter by applying a Printf-style format string to cell values. The string value of this type is used as the format string for fmt.Sprintf.

This formatter never returns errors.ErrUnsupported - it will format any value type that fmt.Sprintf can handle, which includes all basic Go types. The formatted result is marked as non-raw (raw=false), meaning it should be sanitized for the output format.

Example usage:

// Format numbers with 2 decimal places
formatter := PrintfCellFormatter("%.2f")
str, raw, _ := formatter.FormatCell(ctx, view, 0, 0)
// For value 3.14159, str == "3.14", raw == false

// Format as percentage
percentFormatter := PrintfCellFormatter("%.0f%%")
str, _, _ := percentFormatter.FormatCell(ctx, view, 0, 0)
// For value 95, str == "95%"

func (format PrintfCellFormatter) FormatCell(ctx context.Context, view View, row, col int) (str string, raw bool, err error)

type PrintfRawCellFormatter ¶

type PrintfRawCellFormatter string

PrintfRawCellFormatter implements CellFormatter by applying a Printf-style format string to cell values, similar to PrintfCellFormatter, but marks the result as raw output.

The key difference from PrintfCellFormatter is that this formatter marks its output as "raw" (raw=true), indicating the formatted string is already in the correct format for the target output and doesn't need sanitization. This is useful when the format string produces output that's already escaped or contains format-specific markup.

Example usage:

// Format as HTML with embedded tags (already properly escaped)
formatter := PrintfRawCellFormatter("<b>%s</b>")
str, raw, _ := formatter.FormatCell(ctx, view, 0, 0)
// For value "Title", str == "<b>Title</b>", raw == true
// The raw=true signals that no further HTML escaping is needed

func (format PrintfRawCellFormatter) FormatCell(ctx context.Context, view View, row, col int) (str string, raw bool, err error)

type RawCellString ¶

type RawCellString string

RawCellString is a constant string CellFormatter that ignores the cell value entirely and always returns its own string value, marked as raw output.

This formatter is useful for injecting fixed content (like HTML snippets, icons, or format-specific markup) into table cells regardless of the actual cell value. Since the output is marked as raw, it won't be sanitized by the output format.

Example usage:

// Always show an HTML checkbox, regardless of cell value
checkboxFormatter := RawCellString(`<input type="checkbox" checked>`)
str, raw, _ := checkboxFormatter.FormatCell(ctx, view, 0, 0)
// str == `<input type="checkbox" checked>`, raw == true

// Use as a constant marker
marker := RawCellString("✓")

func (rawStr RawCellString) FormatCell(ctx context.Context, view View, row, col int) (str string, raw bool, err error)

type RawStringIfTrue ¶

type RawStringIfTrue string

RawStringIfTrue formats boolean cells by returning a specified string for true values and an empty string for false values, with the output marked as raw.

This is similar to StringIfTrue, but marks the output as raw, indicating it doesn't need sanitization. This is useful when the string contains format-specific markup like HTML tags or pre-escaped content. It panics if the cell value is not a bool.

Example usage:

// Show HTML icon for true, nothing for false
formatter := RawStringIfTrue(`<span class="icon-check"></span>`)
str, raw, _ := formatter.FormatCell(ctx, view, 0, 0)
// If cell value is true: str == `<span class="icon-check"></span>`, raw == true
// If cell value is false: str == "", raw == true

func (f RawStringIfTrue) FormatCell(ctx context.Context, view View, row, col int) (str string, raw bool, err error)

type ReflectCellView ¶

type ReflectCellView interface {
	View

	// ReflectCell returns the reflect.Value of the cell at the specified position.
	// This provides direct access to the underlying value's reflection metadata.
	//
	// The returned reflect.Value can be:
	//   - A valid value with the cell's actual type and value
	//   - A zero Value (from reflect.Value{}) if row/col are out of bounds
	//   - A reflect.Value containing nil if the cell is nil
	//
	// To check if a returned Value is valid, use:
	//   val := view.ReflectCell(row, col)
	//   if val.IsValid() { /* use val */ }
	//
	// Row and column indices are zero-based, same as Cell().
	ReflectCell(row, col int) reflect.Value
}

ReflectCellView extends the View interface with reflection-based cell access. This interface is useful when working with generic code that needs to inspect or manipulate cell values using Go's reflect package.

Use Cases ¶

• Type-safe data conversion via SmartAssign
• Generic formatters that inspect value types
• Building dynamic struct scanners
• Implementing custom CellFormatter instances

Automatic Wrapping ¶

Not all Views natively implement ReflectCellView. Use AsReflectCellView() to get a ReflectCellView from any View - it will either return the View directly (if it implements the interface) or wrap it automatically.

Performance Consideration ¶

Views that natively implement ReflectCellView (like ReflectValuesView) are more efficient than wrapped views, as they avoid repeated reflection operations via reflect.ValueOf().

Example Usage ¶

view := NewStringsView("Data", [][]string{{"123", "true"}}, []string{"Number", "Flag"})
reflectView := AsReflectCellView(view)

val := reflectView.ReflectCell(0, 0)  // reflect.Value containing "123"
if val.Kind() == reflect.String {
    fmt.Println(val.String())          // "123"
}

func AsReflectCellView(view View) ReflectCellView

var view View = NewStringsView(...)
reflectView := AsReflectCellView(view)
// reflectView.ReflectCell() is now available

func DerefView(source View) ReflectCellView

type Person struct {
    Name string
    Age  int
}

// Source with pointer values
people := []*Person{
    {Name: "Alice", Age: 30},
    {Name: "Bob", Age: 25},
}
source := NewStructRowsView("People", people, nil, nil)
// source.Cell(0, 0) returns &Person{Name: "Alice", Age: 30}

// Deref view automatically unwraps pointers
deref := DerefView(source)
// deref.Cell(0, 0) returns Person{Name: "Alice", Age: 30}

// View with cells wrapped in interface{}
source := NewAnyValuesView("Data", [][]any{
    {any(&Person{Name: "Alice"})},
})

deref := DerefView(source)
// Dereferences the pointer inside the interface
deref.Cell(0, 0) // Returns Person{Name: "Alice"}

// Combine dereferencing with filtering
source := NewStructRowsView("People", peoplePointers, nil, nil)
deref := DerefView(source)
filtered := &FilteredView{
    Source:    deref,
    RowLimit:  10,
}
// filtered provides first 10 dereferenced values

val := source.Cell(row, col)
if val != nil {
    derefVal := deref.Cell(row, col)
    // Use derefVal
}

rv := deref.(ReflectCellView).ReflectCell(row, col)
if rv.IsValid() && !rv.IsNil() {
    // Safe to use rv.Interface()
}

func ExtraColsAnyValueFuncView(left View, columns []string, anyValue func(row, col int) any) ReflectCellView

left has 3 columns: ["A", "B", "C"]
Adding 2 columns: ["D", "E"]

Combined view columns: ["A", "B", "C", "D", "E"]
Cell(0, 3) -> anyValue(0, 0)  // col 3 is "D", passed as 0 to anyValue
Cell(0, 4) -> anyValue(0, 1)  // col 4 is "E", passed as 1 to anyValue

// Base data: product prices
products := NewStringsView("Products", [][]string{
    {"Widget", "100"},
    {"Gadget", "200"},
}, []string{"Name", "Price"})

// Add computed tax and total columns
withTax := ExtraColsAnyValueFuncView(products, []string{"Tax", "Total"},
    func(row, col int) any {
        priceStr := products.Cell(row, 1).(string)
        price, _ := strconv.ParseFloat(priceStr, 64)
        if col == 0 { // Tax column
            return price * 0.1
        }
        // Total column
        return price * 1.1
    })

// Result columns: ["Name", "Price", "Tax", "Total"]
// Row 0: ["Widget", "100", 10.0, 110.0]
// Row 1: ["Gadget", "200", 20.0, 220.0]

// Generate a multiplication table without any base data
table := ExtraColsAnyValueFuncView(nil, []string{"A", "B", "Product"},
    func(row, col int) any {
        if col == 0 {
            return row + 1
        }
        if col == 1 {
            return row + 2
        }
        return (row + 1) * (row + 2)
    })

// When NumRows() is called, returns 0 because left is nil
// Typically you'd wrap this in a FilteredView to set row count

userData := loadUserView() // id, name

withStatus := ExtraColsAnyValueFuncView(userData, []string{"Status", "LastSeen"},
    func(row, col int) any {
        userID := userData.Cell(row, 0).(int)
        if col == 0 {
            return statusCache.Get(userID)
        }
        return lastSeenCache.Get(userID)
    })

scores := loadScoresView() // name, score

withGrade := ExtraColsAnyValueFuncView(scores, []string{"Grade"},
    func(row, col int) any {
        score := scores.Cell(row, 1).(int)
        if score >= 90 { return "A" }
        if score >= 80 { return "B" }
        if score >= 70 { return "C" }
        return "F"
    })

base := loadDataView()
step1 := ExtraColsAnyValueFuncView(base, []string{"A"}, funcA)
step2 := ExtraColsAnyValueFuncView(step1, []string{"B", "C"}, funcBC)
// step2 has base columns plus A, B, C

func ExtraColsReflectValueFuncView(left View, columns []string, reflectValue func(row, col int) reflect.Value) ReflectCellView

type Product struct {
    Name  string
    Price float64
}

products := NewStructRowsView("Products", productSlice, nil, nil)

withFormatted := ExtraColsReflectValueFuncView(products, []string{"FormattedPrice"},
    func(row, col int) reflect.Value {
        rv := products.(ReflectCellView).ReflectCell(row, 1) // Price field
        price := rv.Float()
        formatted := fmt.Sprintf("$%.2f", price)
        return reflect.ValueOf(formatted)
    })

withOptional := ExtraColsReflectValueFuncView(base, []string{"Optional"},
    func(row, col int) reflect.Value {
        if shouldBeNil(row) {
            return reflect.Value{} // Invalid value represents nil
        }
        return reflect.ValueOf(computeValue(row))
    })

withConverted := ExtraColsReflectValueFuncView(base, []string{"AsString"},
    func(row, col int) reflect.Value {
        val := base.(ReflectCellView).ReflectCell(row, 0)
        // Use reflection to convert to string
        str := fmt.Sprint(val.Interface())
        return reflect.ValueOf(str)
    })

// Less efficient: Using ExtraColsAnyValueFuncView
ExtraColsAnyValueFuncView(v, cols, func(r, c int) any {
    rv := v.(ReflectCellView).ReflectCell(r, c)
    // ... reflection operations ...
    return rv.Interface() // Extra boxing
})

// More efficient: Using ExtraColsReflectValueFuncView
ExtraColsReflectValueFuncView(v, cols, func(r, c int) reflect.Value {
    rv := v.(ReflectCellView).ReflectCell(r, c)
    // ... reflection operations ...
    return rv // No boxing
})

type ReflectTypeCellFormatter ¶

type ReflectTypeCellFormatter struct {
	// Types maps exact reflect.Type to their CellFormatters.
	// This has the highest priority in the matching hierarchy.
	// Example: reflect.TypeOf(time.Time{}) -> LayoutFormatter("2006-01-02")
	Types map[reflect.Type]CellFormatter

	// InterfaceTypes maps interface types to their CellFormatters.
	// Cell types are checked if they implement these interfaces.
	// Example: reflect.TypeOf((*fmt.Stringer)(nil)).Elem() -> custom formatter
	InterfaceTypes map[reflect.Type]CellFormatter

	// Kinds maps reflect.Kind to their CellFormatters.
	// This provides fallback formatting for broad categories of types.
	// Example: reflect.Int -> PrintfCellFormatter("%d")
	Kinds map[reflect.Kind]CellFormatter

	// Default is the fallback formatter used when no type, interface, or kind matches.
	// If nil and no match is found, errors.ErrUnsupported is returned.
	Default CellFormatter
}

ReflectTypeCellFormatter is a sophisticated type-based routing formatter that selects the appropriate CellFormatter based on the reflected type, interface, or kind of a cell value.

This formatter implements a hierarchical matching strategy:

1. Exact type match (Types map) - highest priority
2. Interface type match (InterfaceTypes map) - checks if type implements interface
3. Kind match (Kinds map) - matches reflect.Kind (int, string, struct, etc.)
4. Pointer dereferencing - if pointer type has no match, checks dereferenced type
5. Default formatter - fallback for unmatched types

The formatter returns errors.ErrUnsupported if no matching formatter is found and no Default is configured, allowing it to be used in formatter chains.

Design pattern: This type uses an immutable builder pattern where all With* methods return a new instance, allowing for safe concurrent usage and compositional configuration.

Example usage:

formatter := NewReflectTypeCellFormatter().
    WithTypeFormatter(reflect.TypeOf(time.Time{}), LayoutFormatter("2006-01-02")).
    WithKindFormatter(reflect.Int, PrintfCellFormatter("%d")).
    WithDefaultFormatter(SprintCellFormatter(false))

str, raw, err := formatter.FormatCell(ctx, view, 0, 0)
// Automatically routes to the correct formatter based on cell type

func NewReflectTypeCellFormatter() *ReflectTypeCellFormatter

formatter := NewReflectTypeCellFormatter().
    WithTypeFormatter(reflect.TypeOf(time.Time{}), LayoutFormatter("2006-01-02")).
    WithKindFormatter(reflect.Float64, PrintfCellFormatter("%.2f"))

func (f *ReflectTypeCellFormatter) FormatCell(ctx context.Context, view View, row, col int) (str string, raw bool, err error)

func (f *ReflectTypeCellFormatter) WithDefaultFormatter(fmt CellFormatter) *ReflectTypeCellFormatter

// Use fmt.Sprint as fallback for unmatched types
formatter := base.WithDefaultFormatter(SprintCellFormatter(false))

// Use a custom fallback that logs unmatched types
formatter = base.WithDefaultFormatter(
    CellFormatterFunc(func(ctx context.Context, view View, row, col int) (string, bool, error) {
        val := view.Cell(row, col)
        log.Printf("unmatched type: %T", val)
        return fmt.Sprint(val), false, nil
    }),
)

func (f *ReflectTypeCellFormatter) WithInterfaceTypeFormatter(typ reflect.Type, fmt CellFormatter) *ReflectTypeCellFormatter

// Format any type implementing fmt.Stringer with its String() method
stringerType := reflect.TypeOf((*fmt.Stringer)(nil)).Elem()
formatter := base.WithInterfaceTypeFormatter(
    stringerType,
    CellFormatterFunc(func(ctx context.Context, view View, row, col int) (string, bool, error) {
        return view.Cell(row, col).(fmt.Stringer).String(), false, nil
    }),
)

// Format any type implementing a custom interface
formatterInterface := reflect.TypeOf((*CustomFormatter)(nil)).Elem()
formatter = formatter.WithInterfaceTypeFormatter(formatterInterface, myFormatter)

func (f *ReflectTypeCellFormatter) WithKindFormatter(kind reflect.Kind, fmt CellFormatter) *ReflectTypeCellFormatter

// Format all integer types with zero-padding
formatter := base.WithKindFormatter(
    reflect.Int,
    PrintfCellFormatter("%05d"),
)

// Format all float types with 2 decimal places
formatter = formatter.WithKindFormatter(
    reflect.Float64,
    PrintfCellFormatter("%.2f"),
)

// Format all struct types with JSON
formatter = formatter.WithKindFormatter(
    reflect.Struct,
    customJSONFormatter,
)

func (f *ReflectTypeCellFormatter) WithTypeFormatter(typ reflect.Type, fmt CellFormatter) *ReflectTypeCellFormatter

// Format time.Time values with custom layout
formatter := base.WithTypeFormatter(
    reflect.TypeOf(time.Time{}),
    LayoutFormatter("2006-01-02"),
)

// Format custom type with specific formatter
formatter = formatter.WithTypeFormatter(
    reflect.TypeOf(MyCustomType{}),
    PrintfCellFormatter("custom: %v"),
)

type ReflectValuesView ¶

type ReflectValuesView struct {
	// Tit is the title of this view, returned by the Title() method.
	Tit string

	// Cols contains the column names defining both the column headers
	// and the number of columns in this view.
	Cols []string

	// Rows contains the data rows, where each row is a slice of reflect.Value.
	// Each cell is stored as a reflect.Value for introspection capabilities.
	Rows [][]reflect.Value
}

ReflectValuesView is a View implementation that stores cells as reflect.Value.

This view type is designed for advanced use cases requiring reflection-based operations on cell data. Each cell is stored as a reflect.Value, providing access to type information and reflection capabilities while maintaining the View interface.

The underlying data structure uses [][]reflect.Value, where each cell can be introspected, compared, and manipulated using Go's reflection package. This is particularly useful for generic operations, type discovery, and dynamic value manipulation.

ReflectValuesView implements both View and ReflectCellView interfaces, providing both standard Cell() and specialized ReflectCell() methods.

Performance characteristics:

• Direct memory access: O(1) for cell retrieval
• Reflection overhead for value operations
• Higher memory usage than AnyValuesView due to reflect.Value storage
• Efficient for reflection-heavy operations

When to use ReflectValuesView:

• Need type introspection on cell values
• Implementing generic algorithms that work with arbitrary types
• Converting between different representation forms
• Caching reflection results for performance
• Building dynamic view transformations
• Working with code generation or analysis tools

Example usage:

source := retable.NewStringsView("Data", data, "A", "B")
reflected, _ := retable.NewReflectValuesViewFrom(source)

// Access via standard interface
value := reflected.Cell(0, 0)

// Access via reflection interface
reflectVal := reflected.ReflectCell(0, 0)
fmt.Printf("Type: %s, Kind: %s\n", reflectVal.Type(), reflectVal.Kind())

Thread safety: Not thread-safe. External synchronization required for concurrent access.

func NewReflectValuesViewFrom(source View) (*ReflectValuesView, error)

original := retable.NewStringsView("Data", rows, "A", "B", "C")
reflected, err := retable.NewReflectValuesViewFrom(original)
if err != nil {
    log.Fatal(err)
}
// All cells are now stored as reflect.Value for introspection
for row := 0; row < reflected.NumRows(); row++ {
    for col := range reflected.Columns() {
        val := reflected.ReflectCell(row, col)
        fmt.Printf("Type: %s\n", val.Type())
    }
}

func (view *ReflectValuesView) Cell(row, col int) any

func (view *ReflectValuesView) Columns() []string

func (view *ReflectValuesView) NumRows() int

func (view *ReflectValuesView) ReflectCell(row, col int) reflect.Value

val := view.ReflectCell(0, 0)
if val.IsValid() {
    fmt.Printf("Type: %s, Kind: %s\n", val.Type(), val.Kind())
    if val.Kind() == reflect.Int {
        fmt.Printf("Int value: %d\n", val.Int())
    }
}

func (view *ReflectValuesView) Title() string

type Scanner ¶

type Scanner interface {
	// ScanString parses a string value into the destination reflect.Value.
	//
	// The dest parameter must be settable (obtained from a pointer's Elem()).
	// The scanner should check dest's type and use the appropriate parser method
	// to convert the string.
	//
	// Returns errors.ErrUnsupported if the scanner doesn't support the dest type,
	// allowing scanner chains. Other errors indicate actual parsing failures.
	//
	// Parameters:
	//   - dest: The settable reflect.Value to write the parsed value into
	//   - str: The string to parse
	//   - parser: The Parser to use for primitive type conversions
	//
	// Returns:
	//   - error: Parsing error, or errors.ErrUnsupported if type not supported
	ScanString(dest reflect.Value, str string, parser Parser) error
}

Scanner is the interface for parsing string values into Go values using reflection. This is the inverse operation of formatting - it converts string representations back into typed Go values.

Scanners work in conjunction with Parsers to handle the actual string-to-value conversion. The Scanner is responsible for orchestrating the conversion, while the Parser provides the primitive parsing operations (int, float, bool, time, etc.).

The Scanner interface operates at a lower level than the table system, working directly with reflect.Value. This makes it reusable across different contexts beyond just table cell parsing.

Design pattern: Scanners should check the dest type and call the appropriate Parser method to convert the string into the target type. For complex types, scanners may need to perform additional logic (e.g., splitting strings, handling null values, type conversions).

Example usage:

scanner := ScannerFunc(func(dest reflect.Value, str string, parser Parser) error {
    if dest.Kind() == reflect.Int {
        i, err := parser.ParseInt(str)
        if err != nil {
            return err
        }
        dest.SetInt(i)
        return nil
    }
    return errors.ErrUnsupported
})

var result int
destValue := reflect.ValueOf(&result).Elem()
err := scanner.ScanString(destValue, "42", parser)
// result == 42

type ScannerFunc ¶

type ScannerFunc func(dest reflect.Value, str string, parser Parser) error

ScannerFunc is a function type that implements the Scanner interface, allowing plain functions to be used as Scanners.

This adapter type follows the common Go pattern of defining a function type that implements an interface (similar to http.HandlerFunc), making it easy to create inline scanners without defining separate types.

Example:

var scanner Scanner = ScannerFunc(func(dest reflect.Value, str string, parser Parser) error {
    if dest.Type() == reflect.TypeOf(time.Time{}) {
        t, err := parser.ParseTime(str)
        if err != nil {
            return err
        }
        dest.Set(reflect.ValueOf(t))
        return nil
    }
    return errors.ErrUnsupported
})

func (f ScannerFunc) ScanString(dest reflect.Value, str string, parser Parser) error

type SingleReflectValueView ¶

type SingleReflectValueView struct {
	// Tit is the title of this view, usually inherited from the source.
	Tit string

	// Col is the name of the single column in this view.
	Col string

	// Val is the reflect.Value stored in the single cell.
	Val reflect.Value
}

SingleReflectValueView is a View implementation containing exactly one cell stored as a reflect.Value.

This specialized view type represents a 1x1 table (single row, single column) where the cell value is stored as a reflect.Value. It implements both View and ReflectCellView interfaces.

SingleReflectValueView is useful for:

• Extracting and wrapping a single cell from a larger view
• Representing scalar values as a minimal view
• Type introspection on individual values
• Building view hierarchies where leaf nodes are single values

Performance characteristics:

• Minimal memory footprint (one value + metadata)
• O(1) access time
• No allocations for repeated access

Example usage:

// Extract a single cell from another view
source := retable.NewStringsView("Data", rows, "A", "B", "C")
singleCell := retable.NewSingleReflectValueView(source, 0, 1)
fmt.Println(singleCell.Cell(0, 0)) // Value from source row 0, col 1

Thread safety: Immutable after creation, safe for concurrent reads.

func NewSingleReflectValueView(source View, row, col int) *SingleReflectValueView

source := retable.NewStringsView(
    "Products",
    [][]string{
        {"Widget", "9.99"},
        {"Gadget", "19.99"},
    },
    "Name", "Price",
)
priceView := retable.NewSingleReflectValueView(source, 1, 1)
fmt.Println(priceView.Cell(0, 0)) // Output: 19.99

func (view *SingleReflectValueView) Cell(row, col int) any

func (view *SingleReflectValueView) Columns() []string

func (view *SingleReflectValueView) NumRows() int

func (view *SingleReflectValueView) ReflectCell(row, col int) reflect.Value

func (view *SingleReflectValueView) Title() string

type SprintFormatter ¶

type SprintFormatter struct{}

SprintFormatter is a universal Formatter that uses fmt.Sprint to format any value. This formatter never returns an error and accepts all value types.

It extracts the actual Go value using reflect.Value.Interface() and formats it using fmt.Sprint, which uses the value's String() method if available, or falls back to the default Go formatting.

Example:

var f Formatter = SprintFormatter{}
str, _ := f.Format(reflect.ValueOf(time.Now()))
// str contains the time formatted by time.Time's String() method

func (SprintFormatter) Format(v reflect.Value) (string, error)

type StringIfTrue ¶

type StringIfTrue string

StringIfTrue formats boolean cells by returning a specified string for true values and an empty string for false values. The output is marked as non-raw.

This formatter is useful for creating checkmarks, labels, or indicators that only appear when a condition is true. It panics if the cell value is not a bool.

Example usage:

// Show checkmark for true, nothing for false
formatter := StringIfTrue("✓")
str, raw, _ := formatter.FormatCell(ctx, view, 0, 0)
// If cell value is true: str == "✓", raw == false
// If cell value is false: str == "", raw == false

// Show "Active" for true, nothing for false
statusFormatter := StringIfTrue("Active")

func (f StringIfTrue) FormatCell(ctx context.Context, view View, row, col int) (str string, raw bool, err error)

type StringParser ¶

type StringParser struct {
	// TrueStrings lists all strings that should be parsed as boolean true.
	// Default includes: "true", "True", "TRUE", "yes", "Yes", "YES", "1"
	TrueStrings []string `json:"trueStrings"`

	// FalseStrings lists all strings that should be parsed as boolean false.
	// Default includes: "false", "False", "FALSE", "no", "No", "NO", "0"
	FalseStrings []string `json:"falseStrings"`

	// NilStrings lists all strings that represent nil/null values.
	// Default includes: "", "nil", "<nil>", "null", "NULL"
	// This is used by higher-level scanning logic to detect null values.
	NilStrings []string `json:"nilStrings"`

	// TimeFormats lists time layout strings to try when parsing time values.
	// Formats are tried in order until one succeeds.
	// Default includes RFC3339, ISO dates, and several common formats.
	TimeFormats []string `json:"timeFormats"`
}

StringParser is a configurable implementation of the Parser interface that handles string-to-value conversions with support for multiple conventions and formats.

Key features:

• Configurable boolean string representations (e.g., "yes"/"no", "1"/"0")
• Configurable nil/null string representations
• Multiple time format attempts for flexible time parsing
• Locale-aware float parsing (e.g., handling comma decimal separators)

The StringParser uses standard Go parsing functions (strconv, time.Parse) internally, but adds flexibility through configuration and fallback strategies.

Example usage:

parser := NewStringParser()
// Parser comes pre-configured with sensible defaults

// Customize boolean parsing
parser.TrueStrings = append(parser.TrueStrings, "enabled", "on")
parser.FalseStrings = append(parser.FalseStrings, "disabled", "off")

// Add custom time formats
parser.TimeFormats = append([]string{"01/02/2006"}, parser.TimeFormats...)

// Parse with custom configuration
b, _ := parser.ParseBool("enabled") // true
t, _ := parser.ParseTime("03/15/2024") // uses custom format

func NewStringParser() *StringParser

parser := NewStringParser()
// Use with defaults
value, _ := parser.ParseBool("yes") // true

// Or customize
parser.TrueStrings = append(parser.TrueStrings, "ja", "oui", "si")

func (p *StringParser) ParseBool(str string) (bool, error)

parser := NewStringParser()
b, _ := parser.ParseBool("true")  // true, nil
b, _ := parser.ParseBool("yes")   // true, nil
b, _ := parser.ParseBool("1")     // true, nil
b, _ := parser.ParseBool("false") // false, nil
b, _ := parser.ParseBool("no")    // false, nil
b, err := parser.ParseBool("maybe") // false, error

func (p *StringParser) ParseDuration(str string) (time.Duration, error)

d, _ := parser.ParseDuration("1h30m")    // 1 hour 30 minutes
d, _ := parser.ParseDuration("5s")       // 5 seconds
d, _ := parser.ParseDuration("100ms")    // 100 milliseconds
d, _ := parser.ParseDuration("2h45m30s") // 2 hours 45 minutes 30 seconds
_, err := parser.ParseDuration("invalid") // error

func (p *StringParser) ParseFloat(str string) (float64, error)

f, _ := parser.ParseFloat("3.14")    // 3.14 (standard)
f, _ := parser.ParseFloat("3,14")    // 3.14 (comma decimal)
f, _ := parser.ParseFloat("-2.5e10") // -2.5e10 (scientific notation)

func (p *StringParser) ParseInt(str string) (int64, error)

i, err := parser.ParseInt("42")    // 42, nil
i, err := parser.ParseInt("-123")  // -123, nil
i, err := parser.ParseInt("abc")   // 0, error

func (p *StringParser) ParseTime(str string) (time.Time, error)

parser := NewStringParser()
t, _ := parser.ParseTime("2024-03-15T14:30:00Z")    // RFC3339
t, _ := parser.ParseTime("2024-03-15")              // ISO date
t, _ := parser.ParseTime("15.03.2024")              // German date format
t, _ := parser.ParseTime("2024-03-15 14:30:00")     // DateTime format
_, err := parser.ParseTime("not a date")            // error

func (p *StringParser) ParseUint(str string) (uint64, error)

u, err := parser.ParseUint("42")    // 42, nil
u, err := parser.ParseUint("0")     // 0, nil
u, err := parser.ParseUint("-1")    // 0, error (negative not allowed)

type StringsView ¶

type StringsView struct {
	// Tit is the title of this view, returned by the Title() method.
	Tit string

	// Cols contains the column names defining both the column headers
	// and the number of columns in this view.
	Cols []string

	// Rows contains the data rows, where each row is a slice of strings.
	// Rows can have fewer elements than len(Cols) for sparse data support.
	Rows [][]string
}

StringsView is a View implementation that uses strings as cell values. It is the most straightforward and commonly used view type for tabular string data.

The Cols field defines the column names and determines the number of columns. Each element in Rows represents a row of data, where each row is a slice of strings.

StringsView supports sparse data: a row within Rows can have fewer slice elements than Cols, in which case empty strings ("") are returned as values for missing cells. This allows for efficient storage of tables with many empty cells.

Performance characteristics:

• Direct memory access: O(1) for cell retrieval
• Memory efficient for string-only data
• No type conversion overhead

When to use StringsView:

• Working with CSV, TSV, or other text-based tabular data
• All cell values are strings or can be represented as strings
• Need simple, fast access to string data
• Memory efficiency is important for large string tables

Example usage:

view := retable.NewStringsView(
    "Products",
    [][]string{
        {"ID", "Name", "Price"},
        {"1", "Widget", "9.99"},
        {"2", "Gadget", "19.99"},
    },
)
fmt.Println(view.Cell(0, 1)) // Output: Widget

Sparse data example:

view := &retable.StringsView{
    Cols: []string{"A", "B", "C"},
    Rows: [][]string{
        {"1", "2", "3"},
        {"4"}, // Missing B and C - will return empty strings
    },
}
fmt.Println(view.Cell(1, 2)) // Output: "" (empty string)

func NewStringsView(title string, rows [][]string, cols ...string) *StringsView

view := retable.NewStringsView(
    "Users",
    [][]string{
        {"alice", "30"},
        {"bob", "25"},
    },
    "Name", "Age",
)

view := retable.NewStringsView(
    "Users",
    [][]string{
        {"Name", "Age"}, // This becomes the header
        {"alice", "30"},
        {"bob", "25"},
    },
)

func (view *StringsView) Cell(row, col int) any

func (view *StringsView) Columns() []string

func (view *StringsView) NumRows() int

func (view *StringsView) Title() string

type StringsViewer ¶

type StringsViewer struct {
	// Cols specifies the column names to use when creating Views.
	// Can be empty or nil, in which case column names will be handled
	// by the underlying View implementation (NewStringsView).
	Cols []string
}

StringsViewer is a Viewer implementation that creates Views from two-dimensional string slices ([][]string).

This is one of the simplest Viewer implementations and is useful when working with raw string data, such as CSV files, database query results converted to strings, or any tabular data represented as strings.

Column Names:

The Cols field can be used to specify column names for the Views. If provided, these names will be used as the column headers in the resulting View. If Cols is empty or nil, NewStringsView will use default column names or the table may be treated as having no headers.

The behavior when Cols is provided:

• If Cols has fewer entries than columns in the data, remaining columns will use default names
• If Cols has more entries than columns in the data, extra names are ignored

Example:

// Create a StringsViewer with column names
viewer := StringsViewer{
    Cols: []string{"Name", "Age", "City"},
}

// Use it to create a View from string data
data := [][]string{
    {"Alice", "30", "NYC"},
    {"Bob", "25", "LA"},
}
view, err := viewer.NewView("People", data)

// Create a StringsViewer without predefined columns
viewer := StringsViewer{}
view, err := viewer.NewView("Data", data)

func (v StringsViewer) NewView(title string, table any) (View, error)

viewer := StringsViewer{Cols: []string{"Product", "Price", "Stock"}}

inventory := [][]string{
    {"Widget", "9.99", "100"},
    {"Gadget", "19.99", "50"},
    {"Doohickey", "29.99", "25"},
}

view, err := viewer.NewView("Inventory", inventory)
if err != nil {
    log.Fatal(err)
}

fmt.Println(view.Title())    // "Inventory"
fmt.Println(view.Columns())  // ["Product", "Price", "Stock"]
fmt.Println(view.NumRows())  // 3

// Access data through the View interface
cell := view.Cell(0, 0)  // "Widget"

type StructFieldNaming ¶

type StructFieldNaming struct {
	// Tag is the struct field tag to be used as column title.
	// When non-empty, struct fields are checked for this tag name,
	// and the tag value is used as the column title.
	//
	// Tag values support comma-separated options, where only the first
	// part before the comma is used as the column title:
	//   `json:"name,omitempty"` results in column title "name"
	//
	// If Tag is empty, then every struct field will be treated as untagged.
	Tag string

	// Ignore specifies a column title value that marks fields to be excluded.
	// Any field whose column title matches this value will be ignored and
	// not appear in the resulting table view.
	//
	// Common patterns:
	//   - Use "-" to match the convention `json:"-"` for ignored fields
	//   - Use "" (empty string) to ignore all unexported or empty-titled fields
	Ignore string

	// Untagged is called with the struct field name to generate a column title
	// when the field has no tag matching Tag (or Tag is empty).
	//
	// If Untagged is nil, the raw struct field name is used as the column title.
	//
	// Common functions to use:
	//   - SpacePascalCase: "FirstName" -> "First Name"
	//   - SpaceGoCase: "HTTPServer" -> "HTTP Server"
	//   - Custom function for domain-specific naming conventions
	Untagged func(fieldName string) (column string)
}

StructFieldNaming defines how struct fields are mapped to column titles as used by View. It provides flexible control over which struct fields become columns and what their column titles are through struct tags and custom naming functions.

The mapping process follows these rules:

• Only exported (public) struct fields are considered for column mapping
• Anonymous embedded struct fields are recursively processed, with their fields inlined
• If a Tag is specified, the struct tag value is used as the column title
• For fields without tags (or if Tag is empty), the Untagged function determines the column title
• Fields matching the Ignore value are excluded from the table

Example usage with struct tags:

type Person struct {
    FirstName string `csv:"first_name"`
    LastName  string `csv:"last_name"`
    Age       int    `csv:"age"`
    Internal  string `csv:"-"` // ignored when Ignore is set to "-"
}

naming := &StructFieldNaming{
    Tag:    "csv",
    Ignore: "-",
}
columns := naming.Columns(&Person{}) // ["first_name", "last_name", "age"]

Example with custom naming function:

naming := &StructFieldNaming{
    Untagged: SpacePascalCase, // "FirstName" becomes "First Name"
}

A nil *StructFieldNaming is a valid value and is equivalent to the zero value, which will use all exported struct fields with their field name as column title.

StructFieldNaming implements the Viewer interface, allowing it to create Views from slices or arrays of structs.

func (n *StructFieldNaming) ColumnStructFieldValue(structVal reflect.Value, column string) reflect.Value

type Person struct {
    Name string `csv:"full_name"`
    Age  int    `csv:"age"`
}
naming := &StructFieldNaming{Tag: "csv"}
person := Person{Name: "John", Age: 30}
val := naming.ColumnStructFieldValue(reflect.ValueOf(person), "full_name")
// val.String() == "John"

func (n *StructFieldNaming) Columns(strct any) []string

type User struct {
    ID       int    `db:"user_id"`
    Username string `db:"username"`
    Password string `db:"-"`
}
naming := &StructFieldNaming{Tag: "db", Ignore: "-"}
cols := naming.Columns(&User{}) // ["user_id", "username"]

func (n *StructFieldNaming) IsIgnored(column string) bool

func (n *StructFieldNaming) NewView(title string, table any) (View, error)

type Product struct {
    Name  string `json:"name"`
    Price float64 `json:"price"`
}
naming := &StructFieldNaming{Tag: "json"}
products := []Product{{"Widget", 9.99}, {"Gadget", 19.99}}
view, err := naming.NewView("Products", products)

func (n *StructFieldNaming) String() string

func (n *StructFieldNaming) StructFieldColumn(field reflect.StructField) string

func (n *StructFieldNaming) WithIgnore(ignore string) *StructFieldNaming

naming := (&StructFieldNaming{Tag: "csv"}).WithIgnore("-")

func (n *StructFieldNaming) WithTag(tag string) *StructFieldNaming

naming := (&StructFieldNaming{}).WithTag("json").WithIgnore("-")

type StructRowsView ¶

type StructRowsView struct {
	// contains filtered or unexported fields
}

StructRowsView is a View implementation that provides efficient access to tabular data stored in a slice or array of structs.

StructRowsView is created by StructRowsViewer.NewView and implements the View interface, allowing struct data to be formatted, exported, or displayed as tables.

The view uses reflection to extract field values on demand, with caching to optimize repeated access to the same row. This makes it efficient for scenarios where rows are accessed sequentially or where the same row is queried multiple times.

Field-to-column mapping:

• If indices is nil, struct fields map 1:1 to columns in declaration order
• If indices is non-nil, it specifies which struct field index maps to each column
• The indices slice has one entry per struct field, with values indicating column positions
• An index value of -1 means that field is excluded from the view

Performance characteristics:

• Row access is O(1) - direct slice indexing
• Cell access includes reflection overhead on first access per row
• Subsequent cell access for the same row uses cached values (O(1))
• Memory usage scales with the number of structs in the underlying slice

This type is thread-safe for concurrent read access.

func (view *StructRowsView) Cell(row, col int) any

func (view *StructRowsView) Columns() []string

func (view *StructRowsView) NumRows() int

func (view *StructRowsView) ReflectCell(row, col int) reflect.Value

val := view.ReflectCell(0, 0)
if val.IsValid() && val.CanInt() {
    fmt.Println("Integer value:", val.Int())
}

func (view *StructRowsView) Title() string

type StructRowsViewer ¶

type StructRowsViewer struct {
	StructFieldNaming

	// MapIndices maps struct field indices to column indices in the output view.
	//
	// The key is the index of a field as returned by StructFieldTypes (exported
	// fields in declaration order, with embedded struct fields inlined).
	// The value is the column index where that field's data should appear.
	//
	// If MapIndices is nil, fields map 1:1 to columns in their natural order.
	//
	// Mapping a field index to -1 excludes that field from the view entirely.
	//
	// All column indices from 0 to N-1 must be mapped exactly once (excluding -1),
	// where N is the number of columns in the output.
	//
	// Example:
	//   MapIndices: map[int]int{
	//       0: 1,  // field 0 -> column 1
	//       1: 0,  // field 1 -> column 0 (swap with field 0)
	//       2: -1, // field 2 -> excluded
	//       3: 2,  // field 3 -> column 2
	//   }
	MapIndices map[int]int
}

StructRowsViewer implements Viewer for tables represented by a slice or array of struct rows, with advanced control over column ordering and field inclusion.

StructRowsViewer extends StructFieldNaming with the ability to rearrange columns and selectively exclude specific struct fields by their index. This is useful when:

• You need to reorder columns without changing the struct definition
• You want to exclude specific fields beyond what struct tags provide
• You need programmatic control over which fields appear in the view

The viewer uses reflection to extract field values from each struct in the slice, mapping them to columns according to the StructFieldNaming rules and MapIndices configuration.

Column mapping process:

1. All exported struct fields are identified (including embedded struct fields)
2. StructFieldNaming rules determine the column title for each field
3. MapIndices (if set) remaps field indices to column positions
4. Fields mapped to -1 are excluded from the output
5. A StructRowsView is created to provide access to the data

Example with field reordering:

type Employee struct {
    ID        int
    FirstName string
    LastName  string
    Salary    float64
}

viewer := &StructRowsViewer{
    StructFieldNaming: StructFieldNaming{
        Untagged: SpacePascalCase,
    },
    MapIndices: map[int]int{
        0: 2,  // ID appears in 3rd column
        1: 0,  // FirstName appears in 1st column
        2: 1,  // LastName appears in 2nd column
        3: -1, // Salary is excluded
    },
}
// Columns will be: ["First Name", "Last Name", "ID"]

Example with field exclusion:

viewer := &StructRowsViewer{}
viewer = viewer.WithIgnoreFieldIndex(3) // Ignore field at index 3

StructRowsViewer implements the Viewer interface.

func DefaultStructRowsViewer() *StructRowsViewer

type Person struct {
    Name string `col:"Full Name"`
    Age  int
}
viewer := DefaultStructRowsViewer()
view, err := viewer.NewView("People", []Person{{Name: "John", Age: 30}})

func NoTagsStructRowsViewer() *StructRowsViewer

type Person struct {
    Name string
    Age  int
}
viewer := NoTagsStructRowsViewer()
view, err := viewer.NewView("People", []Person{{Name: "John", Age: 30}})
// Column titles will be: "Name", "Age"

func (v *StructRowsViewer) NewView(title string, table any) (View, error)

type Order struct {
    OrderID   int    `csv:"id"`
    Customer  string `csv:"customer"`
    Total     float64 `csv:"total"`
}
viewer := &StructRowsViewer{
    StructFieldNaming: StructFieldNaming{Tag: "csv"},
}
orders := []Order{{1, "Alice", 99.99}, {2, "Bob", 149.99}}
view, err := viewer.NewView("Orders", orders)

func (v *StructRowsViewer) String() string

func (v *StructRowsViewer) WithIgnore(ignore string) *StructRowsViewer

viewer := (&StructRowsViewer{Tag: "csv"}).WithIgnore("-")

func (v *StructRowsViewer) WithIgnoreField(structPtr, fieldPtr any) *StructRowsViewer

type Person struct {
    Name   string
    Age    int
    Secret string
}
var p Person
viewer := (&StructRowsViewer{}).WithIgnoreField(&p, &p.Secret)

func (v *StructRowsViewer) WithIgnoreFieldIndex(fieldIndex int) *StructRowsViewer

// Exclude the 3rd field (index 2)
viewer := (&StructRowsViewer{}).WithIgnoreFieldIndex(2)

func (v *StructRowsViewer) WithIgnoreFieldIndices(fieldIndices ...int) *StructRowsViewer

// Exclude fields at indices 2, 5, and 7
viewer := (&StructRowsViewer{}).WithIgnoreFieldIndices(2, 5, 7)

func (v *StructRowsViewer) WithMapIndex(fieldIndex, columnIndex int) *StructRowsViewer

viewer := (&StructRowsViewer{}).
    WithMapIndex(0, 2).  // field 0 -> column 2
    WithMapIndex(1, 0).  // field 1 -> column 0
    WithMapIndex(2, 1)   // field 2 -> column 1

func (v *StructRowsViewer) WithMapIndices(mapIndices map[int]int) *StructRowsViewer

viewer := (&StructRowsViewer{}).WithMapIndices(map[int]int{
    0: 2,  // field 0 -> column 2
    1: 0,  // field 1 -> column 0
    2: 1,  // field 2 -> column 1
    3: -1, // field 3 -> excluded
})

func (v *StructRowsViewer) WithTag(tag string) *StructRowsViewer

viewer := (&StructRowsViewer{}).WithTag("json").WithIgnore("-")

type UnsupportedCellFormatter ¶

type UnsupportedCellFormatter struct{}

UnsupportedCellFormatter is a CellFormatter that always returns errors.ErrUnsupported. This is useful as a placeholder or for explicitly marking certain cell types as unsupported in a formatting configuration.

In a formatter chain, this can be used to force trying the next formatter, or to document that a particular cell type intentionally has no formatter.

Example usage:

// Explicitly mark a type as unsupported
var formatter CellFormatter = UnsupportedCellFormatter{}
_, _, err := formatter.FormatCell(ctx, view, 0, 0)
// err == errors.ErrUnsupported

func (UnsupportedCellFormatter) FormatCell(ctx context.Context, view View, row, col int) (str string, raw bool, err error)

type UnsupportedFormatter ¶

type UnsupportedFormatter struct{}

UnsupportedFormatter is a Formatter that always returns errors.ErrUnsupported. This is useful as a placeholder or when you want to explicitly mark certain types as unsupported in a formatting chain.

Example:

// Mark a type as unsupported, forcing fallback to another formatter
var f Formatter = UnsupportedFormatter{}
_, err := f.Format(reflect.ValueOf("anything"))
// err == errors.ErrUnsupported

func (UnsupportedFormatter) Format(v reflect.Value) (string, error)

type View ¶

type View interface {
	// Title returns the name/title of this table.
	// The title is used for display purposes and when writing to formats
	// that support named tables (e.g., Excel sheet names, HTML table captions).
	// Returns an empty string if the table has no title.
	Title() string

	// Columns returns the names of all columns in this table.
	// The length of the returned slice defines the number of columns.
	// Individual column names may be empty strings if unnamed.
	// The returned slice should not be modified by callers.
	// Column names are used as headers when writing to CSV, HTML, etc.
	Columns() []string

	// NumRows returns the total number of data rows in this table.
	// This does not include any header row - it's purely the count of data rows.
	// Returns 0 for an empty table.
	NumRows() int

	// Cell returns the value at the specified row and column coordinates.
	// Row and column indices are zero-based.
	//
	// Returns nil in these cases:
	//   - row is negative or >= NumRows()
	//   - col is negative or >= len(Columns())
	//   - the cell actually contains a nil value
	//
	// The returned value type depends on the View implementation and
	// the underlying data source. Common types include:
	//   - string (for text-based sources like CSV)
	//   - numeric types (int, float64, etc.)
	//   - time.Time (for date/time values)
	//   - bool
	//   - custom types (for struct-based Views)
	//
	// Callers should use type assertions or reflection to work with
	// the returned value. For more type-safe access, consider using
	// ViewToStructSlice or SmartAssign functions.
	Cell(row, col int) any
}

View is the central interface in the retable package that represents read-only tabular data in a uniform, type-agnostic way. It provides access to table metadata (title, columns) and cell data through a simple coordinate-based API.

View is designed as an in-memory abstraction - implementations should load all data before wrapping it as a View. This design choice eliminates the need for context parameters and error handling in the core View methods, simplifying the API.

Design Philosophy ¶

The View interface follows these principles:

• Immutability: Views are read-only; modifications create new Views
• Simplicity: No error returns from data access methods (data already in memory)
• Uniformity: All tabular data sources expose the same interface
• Composability: Views can be wrapped and transformed via decorator types

Coordinate System ¶

Views use zero-based indexing:

• Columns are numbered 0 to len(Columns())-1
• Rows are numbered 0 to NumRows()-1

Cell Values ¶

Cell values are returned as any (empty interface) and can be:

• Go primitives (int, string, bool, float64, etc.)
• Complex types (time.Time, custom structs, etc.)
• nil (for missing/null values or out-of-bounds access)

Common Implementations ¶

The package provides several View implementations:

• StringsView: Backed by [][]string (from CSV, text)
• StructRowsView: Backed by []StructType (reflection-based)
• AnyValuesView: Backed by [][]any (from SQL, mixed types)
• ReflectValuesView: Backed by [][]reflect.Value (advanced)

View Wrappers ¶

Several wrapper types transform Views without copying data:

• FilteredView: Row/column filtering and remapping
• DerefView: Automatic pointer dereferencing
• ExtraColsView: Horizontal concatenation
• ExtraRowsView: Vertical concatenation
• ViewWithTitle: Custom title override

Example Usage ¶

// Create a view from structs
type Person struct {
    Name string
    Age  int
}
people := []Person{{"Alice", 30}, {"Bob", 25}}
view := NewStructRowsView("People", people, nil, nil)

// Access data
fmt.Println(view.Title())              // "People"
fmt.Println(view.Columns())            // ["Name", "Age"]
fmt.Println(view.NumRows())            // 2
fmt.Println(view.Cell(0, 0))           // "Alice"
fmt.Println(view.Cell(0, 1))           // 30
fmt.Println(view.Cell(2, 0))           // nil (out of bounds)

func NewStructRowsView(title string, columns []string, indices []int, rows reflect.Value) View

// For struct: {Field0, Field1, Field2, Field3}
// To create columns: [Field1, Field3, Field0] (Field2 excluded)
indices := []int{2, 0, -1, 1}
view := NewStructRowsView("Data", []string{"Col0", "Col1", "Col2"}, indices, rowsValue)

func SingleCellView[T any](title, column string, value T) View

// Create a single-cell view with an integer
view := retable.SingleCellView("Count", "Total", 42)
fmt.Println(view.Title())      // Output: Count
fmt.Println(view.NumRows())    // Output: 1
fmt.Println(view.Cell(0, 0))   // Output: 42

// Create a single-cell view with a string
view := retable.SingleCellView("Status", "Message", "Success")
fmt.Println(view.Cell(0, 0))   // Output: Success

func SingleColView[T any](column string, rows []T) View

// Create a single-column view of integers
numbers := []int{10, 20, 30, 40}
view := retable.SingleColView("Value", numbers)
fmt.Println(view.NumRows())    // Output: 4
fmt.Println(view.Cell(2, 0))   // Output: 30

// Create a single-column view of strings
names := []string{"Alice", "Bob", "Charlie"}
view := retable.SingleColView("Name", names)
fmt.Println(view.Cell(1, 0))   // Output: Bob

func ViewWithTitle(source View, title string) View

original := retable.NewStringsView("Original Title", data, "A", "B")
renamed := retable.ViewWithTitle(original, "New Title")
fmt.Println(renamed.Title())       // Output: New Title
fmt.Println(renamed.Cell(0, 0))    // Delegates to original
fmt.Println(original.Title())      // Output: Original Title (unchanged)

type Viewer ¶

type Viewer interface {
	// NewView creates a View with the specified title from the given table data.
	//
	// The table parameter should contain tabular data in a format that this
	// Viewer implementation recognizes. Different Viewer implementations accept
	// different types:
	//   - StringsViewer accepts [][]string
	//   - StructRowsViewer accepts []StructType or []*StructType
	//
	// Returns an error if:
	//   - table is not a supported type for this Viewer
	//   - table is nil or empty (implementation-dependent)
	//   - the data structure is invalid or malformed
	//
	// The title parameter becomes the result of the View's Title() method.
	// It can be an empty string if no title is needed.
	NewView(title string, table any) (View, error)
}

Viewer is a factory interface for creating Views from arbitrary table data. Viewers are responsible for recognizing specific data structures (like [][]string or []StructType) and wrapping them as View implementations.

Purpose ¶

The Viewer interface provides a uniform way to create Views from different data representations without needing to know the exact View type to construct. This is especially useful in generic code that works with multiple data formats.

Standard Implementations ¶

• StringsViewer: Creates views from [][]string (CSV, text data)
• StructRowsViewer: Creates views from struct slices via reflection

Example Usage ¶

// Using StringsViewer
viewer := StringsViewer{FirstRowIsHeader: true}
data := [][]string{
    {"Name", "Age"},
    {"Alice", "30"},
    {"Bob", "25"},
}
view, err := viewer.NewView("People", data)

// Using StructRowsViewer
type Person struct {
    Name string
    Age  int
}
people := []Person{{"Alice", 30}, {"Bob", 25}}
viewer := NewStructRowsViewer(nil)
view, err := viewer.NewView("People", people)

Custom Viewers ¶

Implement this interface to create Views from custom data structures:

type MyViewer struct{}

func (v MyViewer) NewView(title string, table any) (View, error) {
    myData, ok := table.(MyDataType)
    if !ok {
        return nil, fmt.Errorf("expected MyDataType, got %T", table)
    }
    return myViewFromData(title, myData), nil
}