godotils

README

godotils

Utilities for creating, iterating and decoding godog.Table into structs.

Installation

go get github.com/lukasngl/godotils

Features

• Get table header with godotils.Header and iterate over rows with godotils.Rows(table)
• Map columns to struct fields via table:"<column name>[,optional]" struct tag
• Optional columns with table:",optional" struct tag or WithAllowMissingColumns option
• Ignore extra columns with WithAllowExtraColumns option
• Custom unmarshalers for specific types

Usage

Basic unmarshaling

type Row struct {
    Name  string  `table:"name"`
    Age   int     `table:"age"`
    Score float64 `table:"score"`
}

table := godotils.Table([][]string{
    {"name", "age", "score"},
    {"Alice", "30", "95.5"},
    {"Bob", "25", "87.3"},
})

var rows []Row
err := godotils.UnmarshalTable(table, &rows)

Table iteration

// Get header
header := godotils.Header(table)

// Iterate all rows
for row := range godotils.Rows(table) {
    // row is []string
}

// Skip header row
for row := range godotils.Rows(table, true) {
    // row is []string
}

// Get a specific column by index
nameColumn := godotils.Column(table, 0)

// Iterate all columns
for column := range godotils.Columns(table) {
    // column is []string
}

Custom Unmarshalers

You can provide custom unmarshaling logic for specific types:

func UnmarshalYesNo(data []byte, v any) error {
    boolPtr, ok := (v).(*bool)
    if !ok {
        return fmt.Errorf("expected *bool, got %T", v)
    }

    switch data := string(data); data {
    case "yes":
        *boolPtr = true
        return nil
    case "no":
        *boolPtr = false
        return nil
    default:
        return fmt.Errorf("expected %q or %q, got %q", "yes", "no", data)
    }
}

type Row struct {
    YesNo bool `table:"yesno"`
}

table := godotils.Table([][]string{
    {"yesno"},
    {"yes"},
    {"no"},
})

var rows []Row
err := godotils.UnmarshalTable(
    table,
    &rows,
    godotils.WithUnmarshalFuncFor[bool](UnmarshalYesNo),
)

Documentation

Overview

Package godotils provides utility functions for working with godog tables, including table creation, iteration, and unmarshaling into Go structs.

Index

• func Column(table *godog.Table, index int) []string
• func Columns(table *godog.Table) iter.Seq[[]string]
• func Header(table *godog.Table) []string
• func Rows(table *godog.Table, skipHeader ...bool) iter.Seq[[]string]
• func Table(rows [][]string) *godog.Table
• func UnmarshalTable(table *godog.Table, dest any, options ...UnmarshalOption) error
• type UnmarshalFunc
  • func (f UnmarshalFunc) Unmarshal(data []byte, v any) error
• type UnmarshalOption
  • func WithAllowExtraColumns() UnmarshalOption
  • func WithAllowMissingColumns() UnmarshalOption
  • func WithDefaultUnmarshalFunc(fn UnmarshalFunc) UnmarshalOption
  • func WithDefaultUnmarshaler(unmarshaler Unmarshaler) UnmarshalOption
  • func WithUnmarshalFunc(t reflect.Type, fn UnmarshalFunc) UnmarshalOption
  • func WithUnmarshalFuncFor[T any](fn UnmarshalFunc) UnmarshalOption
  • func WithUnmarshaler(t reflect.Type, unmarshaler Unmarshaler) UnmarshalOption
  • func WithUnmarshalerFor[T any](unmarshaller Unmarshaler) UnmarshalOption
• type Unmarshaler

Functions

func Column

func Column(table *godog.Table, index int) []string

Column extracts a single column from the table by index and returns it as a string slice. Note: No bounds checking is performed. Panics if index is out of range.

func Columns

func Columns(table *godog.Table) iter.Seq[[]string]

Columns returns an iterator over all columns in the table as string slices. The iterator follows the iter.Seq pattern introduced in Go 1.23.

func Header

func Header(table *godog.Table) []string

Header extracts and returns the first row of the table as a string slice. If the table is empty, it returns nil.

func Rows

func Rows(table *godog.Table, skipHeader ...bool) iter.Seq[[]string]

Rows returns an iterator over all rows in the table as string slices. If skipHeader is true, the first row (header) is skipped. The iterator follows the iter.Seq pattern introduced in Go 1.23.

func Table

func Table(rows [][]string) *godog.Table

Table creates a godog.Table from a 2D slice of strings. Each inner slice represents a row in the table, with elements representing cell values.

func UnmarshalTable

func UnmarshalTable(table *godog.Table, dest any, options ...UnmarshalOption) error

UnmarshalTable unmarshals a godog.Table into a slice of structs. The dest parameter must be a pointer to a slice of structs. The table's header row is used to map columns to struct fields using the "table" tag, or the field name if no tag is present. Fields can be marked as optional with "table:\"name,optional\"".

By default, JSON unmarshaling is used for cell values. Custom unmarshalers can be configured using the With* option functions.

Types

type UnmarshalFunc

type UnmarshalFunc func(data []byte, v any) error

UnmarshalFunc is a function type that implements the Unmarshaler interface. This allows regular functions to be used as unmarshalers.

func (UnmarshalFunc) Unmarshal

func (f UnmarshalFunc) Unmarshal(data []byte, v any) error

Unmarshal implements the Unmarshaler interface by calling the function itself.

type UnmarshalOption

type UnmarshalOption = func(*unmarshalConfig)

UnmarshalOption is a function that configures unmarshal behavior.

func WithAllowExtraColumns

func WithAllowExtraColumns() UnmarshalOption

WithAllowExtraColumns returns an option that allows the table to have columns that don't map to any struct field. Without this option, extra columns cause an error.

func WithAllowMissingColumns

func WithAllowMissingColumns() UnmarshalOption

WithAllowMissingColumns returns an option that allows struct fields to have no corresponding table column, unless the field is marked as optional. Without this option, missing columns cause an error.

func WithDefaultUnmarshalFunc

func WithDefaultUnmarshalFunc(fn UnmarshalFunc) UnmarshalOption

WithDefaultUnmarshalFunc returns an option that sets the default unmarshaler to use for all types that don't have a specific unmarshaler configured. This is a convenience wrapper that accepts a function directly.

func WithDefaultUnmarshaler

func WithDefaultUnmarshaler(unmarshaler Unmarshaler) UnmarshalOption

WithDefaultUnmarshaler returns an option that sets the default unmarshaler to use for all types that don't have a specific unmarshaler configured. The default unmarshaler is json.Unmarshal.

func WithUnmarshalFunc

func WithUnmarshalFunc(t reflect.Type, fn UnmarshalFunc) UnmarshalOption

WithUnmarshalFunc returns an option that registers a custom unmarshaler for a specific type. This is a convenience wrapper that accepts a function directly.

func WithUnmarshalFuncFor

func WithUnmarshalFuncFor[T any](fn UnmarshalFunc) UnmarshalOption

WithUnmarshalFuncFor returns an option that registers a custom unmarshaler for a specific type T. This is a convenience wrapper that accepts a function directly.

func WithUnmarshaler

func WithUnmarshaler(t reflect.Type, unmarshaler Unmarshaler) UnmarshalOption

WithUnmarshaler returns an option that registers a custom unmarshaler for a specific type. The type-specific unmarshaler takes precedence over the default unmarshaler.

func WithUnmarshalerFor

func WithUnmarshalerFor[T any](unmarshaller Unmarshaler) UnmarshalOption

WithUnmarshalerFor returns an option that registers a custom unmarshaler for a specific type T. This is a type-safe convenience wrapper around WithUnmarshaler.

type Unmarshaler

type Unmarshaler interface {
	Unmarshal(byte []byte, v any) error
}

Unmarshaler is an interface for types that can unmarshal data into a value. It follows the same pattern as json.Unmarshaler but with a different method signature.