tabular

type CellValidator func(column *Column, value any) error

type Column struct {
	// Key is the logical identifier of the column. For struct schemas it is the
	// field name; for dynamic schemas it is the map key that addresses the cell.
	Key string
	// Name is the header text that appears in the exported file and is matched
	// against the header row during import. Defaults to Key when empty.
	Name string
	// Type is the target Go type used when parsing cell values. For struct
	// schemas it is derived from the struct field type; for dynamic schemas it
	// must be provided via ColumnSpec.
	Type reflect.Type
	// Order controls the column order. Columns are sorted stably by Order.
	Order int
	// Width hints the column width for formats that support it (Excel).
	Width float64
	// Default is the value used during import when the source cell is empty.
	Default string
	// Format is the format template consumed by the default Formatter/Parser,
	// e.g. "2006-01-02" for dates or "%.2f" for floats.
	Format string
	// Formatter is the name of a custom Formatter registered on the exporter.
	Formatter string
	// Parser is the name of a custom ValueParser registered on the importer.
	Parser string
	// FormatterFn is a Formatter instance bound directly on the column, taking
	// precedence over the named Formatter registry.
	FormatterFn Formatter
	// ParserFn is a ValueParser instance bound directly on the column, taking
	// precedence over the named ValueParser registry.
	ParserFn ValueParser
	// Required marks the column as mandatory; empty cells trigger a validation
	// error during import. Applies to dynamic schemas.
	Required bool
	// Validators is an ordered list of custom cell validators. Applies to
	// dynamic schemas.
	Validators []CellValidator
	// Index is the struct field index path used by StructAdapter. nil for
	// dynamic columns.
	Index []int
}

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

type ColumnSpec struct {
	// Key is the logical identifier and the map key used to read/write cell
	// values. Required and must be unique within the schema.
	Key string
	// Name is the header text. Defaults to Key when empty.
	Name string
	// Type is the Go target type used for parsing. Required.
	Type reflect.Type
	// Order controls the column order; columns are sorted stably.
	Order int
	// Width hints the column width for Excel export.
	Width float64
	// Default is used during import when the cell is empty.
	Default string
	// Format template consumed by the default Formatter/Parser.
	Format string
	// Formatter / Parser names resolved against the exporter / importer
	// registries.
	Formatter string
	Parser    string
	// FormatterFn / ParserFn bind implementations directly; they take
	// precedence over the named lookups.
	FormatterFn Formatter
	ParserFn    ValueParser
	// Required marks the column as mandatory during import.
	Required bool
	// Validators runs additional cell validation after parsing.
	Validators []CellValidator
}

type ExportError struct {
	Row    int
	Column string
	Field  string
	Err    error
}

type Exporter interface {
	// RegisterFormatter registers a custom formatter referenced by Column.Formatter.
	RegisterFormatter(name string, formatter Formatter)
	// ExportToFile exports data to a tabular file on disk.
	ExportToFile(data any, filename string) error
	// Export exports data to a bytes.Buffer carrying tabular content.
	Export(data any) (*bytes.Buffer, error)
}

type Formatter interface {
	// Format converts a Go value to a cell string
	Format(value any) (string, error)
}

type FormatterFunc func(value any) (string, error)

type ImportError struct {
	Row    int
	Column string
	Field  string
	Err    error
}

type Importer interface {
	// RegisterParser registers a custom parser referenced by Column.Parser.
	RegisterParser(name string, parser ValueParser)
	// ImportFromFile imports data from a tabular file on disk.
	ImportFromFile(filename string) (any, []ImportError, error)
	// Import imports data from an io.Reader carrying tabular content.
	Import(reader io.Reader) (any, []ImportError, error)
}

type MapOption func(*mapAdapter)

type MappingOptions struct {
	// TrimSpace trims leading/trailing whitespace from each header cell.
	TrimSpace bool
}

type ParseRowOptions struct {
	// TrimSpace strips leading/trailing whitespace from each source cell
	// before applying defaults.
	TrimSpace bool
}

type ParserFunc func(cellValue string, targetType reflect.Type) (any, error)

type RowAdapter interface {
	// Schema returns the column definitions this adapter is built for.
	Schema() *Schema
	// Reader wraps the caller-provided data (e.g. []Struct, []map[string]any)
	// into an iterable sequence of read-only row views for export.
	Reader(data any) (RowReader, error)
	// Writer creates a result accumulator used by importers. The capacity hint
	// is advisory; adapters may ignore it.
	Writer(capacity int) RowWriter
}

type RowBuilder interface {
	// Set writes a parsed value for the given column.
	Set(column *Column, value any) error
	// Validate runs adapter-specific validation hooks (e.g. struct validator
	// or per-column cell validators plus row validators for maps).
	Validate() error
	// Value returns the underlying row representation (struct or map) in its
	// current state.
	Value() any
}

type RowReader interface {
	// All yields 0-based row index and a RowView for each row.
	All() iter.Seq2[int, RowView]
}

type RowValidator func(row map[string]any) error

type RowView interface {
	// Get returns the raw Go value held for the column. It may be nil for
	// missing map keys or zero struct fields.
	Get(column *Column) (any, error)
}

type RowWriter interface {
	// NewRow creates a fresh, writable row builder.
	NewRow() RowBuilder
	// Commit validates and appends the given row to the result set.
	Commit(row RowBuilder) error
	// Build returns the final aggregated result (e.g. []T or []map[string]any).
	Build() any
}

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

type TypedExporter[T any] struct {
	// contains filtered or unexported fields
}

type TypedImporter[T any] struct {
	// contains filtered or unexported fields
}

type ValueParser interface {
	// Parse converts a cell string to a Go value
	Parse(cellValue string, targetType reflect.Type) (any, error)
}