bdatamatrix

README

BDataMatrix - Structured Tabular Data Management in Go

BDataMatrix is a lightweight Go library for managing structured tabular data efficiently. It provides functions to add, update, delete, sort, and query data, along with various export options such as CSV, TSV, JSON, and YAML.

Installation

To install BDataMatrix, run:

go get github.com/bearaujus/bdatamatrix

Import

import "github.com/bearaujus/bdatamatrix"

Features

• Create structured tabular data with defined headers.
• Add, update, delete, and search rows efficiently.
• Export data to CSV, TSV, JSON, YAML, or custom formats.
• Track header indices for optimized querying.
• Support for case-insensitive searching.

Usage

1. Creating a Matrix

Create a new matrix with headers:

matrix, err := bdatamatrix.New("ID", "Name", "Age")
if err != nil {
    log.Fatal(err)
}

Create a matrix with predefined data:

rows := [][]string{
    {"1", "Alice", "30"},
    {"2", "Bob", "25"},
}
matrix, err := bdatamatrix.NewWithData(rows, "ID", "Name", "Age")
if err != nil {
    log.Fatal(err)
}

2. Adding and Querying Rows

_ = matrix.AddRow("3", "Charlie", "35")

query := bdatamatrix.FindRowsQuery{
    Column:          "Name",
    Operator:        bdatamatrix.OperatorEquals,
    CaseInsensitive: true,
    Values:          []string{"Alice"},
}

result, err := matrix.FindRows(query)
if err != nil {
    log.Fatal(err)
}
fmt.Println("Matched rows:", result)

3. Exporting Data

Export as CSV:

csvOutput := matrix.ToCSV(true)
_ = csvOutput.Write("output.csv", 0644)

Export as JSON:

jsonOutput := matrix.ToJSON(true, false)
_ = jsonOutput.Write("output.json", 0644)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Index

• Variables
• type BDataMatrix
  • func New(keys ...string) (BDataMatrix, error)
  • func NewWithData(rows [][]string, keys ...string) (BDataMatrix, error)
• type FindRowsQuery
• type Operator
• type Output

Variables

var (
	// ErrEmptyHeader is returned when no header is provided.
	ErrEmptyHeader = errors.New("empty header")

	// ErrDuplicateHeader is returned when a duplicate header is encountered.
	ErrDuplicateHeader = errors.New("duplicate header")

	// ErrRowIndexOutOfRange is returned when the specified row index is invalid.
	ErrRowIndexOutOfRange = errors.New("row index out of range")

	// ErrColumnNotFound is returned when a specified column does not exist.
	ErrColumnNotFound = errors.New("column not found")

	// ErrNoRowsFound is returned when no rows match the query criteria.
	ErrNoRowsFound = errors.New("no rows found matching criteria")
)

Types

type BDataMatrix

type BDataMatrix interface {
	// AddRow appends a single row to the matrix.
	//
	// Parameters:
	//   - values: A variadic list of strings representing a row.
	//
	// Returns:
	//   - An error if the number of values does not match the header length.
	AddRow(values ...string) error

	// AddRows appends multiple rows to the matrix.
	//
	// Parameters:
	//   - rows: A variadic list of rows, where each row is a slice of strings.
	//
	// Returns:
	//   - An error if any row's length does not match the header length.
	AddRows(rows ...[]string) error

	// GetRow retrieves the row at the specified index.
	//
	// Parameters:
	//   - index: The zero-based index of the row.
	//
	// Returns:
	//   - The row as a slice of strings.
	//   - An error if the index is out of range.
	GetRow(index int) ([]string, error)

	// GetRows retrieves multiple rows specified by their indexes.
	//
	// Parameters:
	//   - indexes: A variadic list of row indexes.
	//
	// Returns:
	//   - A new BDataMatrix containing only the specified rows.
	//   - An error if any index is out of range.
	GetRows(indexes ...int) (BDataMatrix, error)

	// GetColumn retrieves a column by header name.
	//
	// Parameters:
	//   - key: The header name of the column.
	//
	// Returns:
	//   - A slice of strings containing the values of the column.
	//   - An error if the column does not exist.
	GetColumn(key string) ([]string, error)

	// GetColumns returns a new BDataMatrix containing only the specified columns.
	//
	// Parameters:
	//   - keys: A variadic list of header names.
	//
	// Returns:
	//   - A new BDataMatrix whose rows contain only the values from the specified columns.
	//   - An error if any of the specified columns do not exist.
	GetColumns(keys ...string) (BDataMatrix, error)

	// UpdateRow updates the row at the specified index with new values.
	//
	// Parameters:
	//   - index: The zero-based index of the row to update.
	//   - values: A variadic list of new values for the row.
	//
	// Returns:
	//   - An error if the index is out of range or if the number of values does not match the header length.
	UpdateRow(index int, values ...string) error

	// DeleteRow removes the row at the specified index.
	//
	// Parameters:
	//   - index: The zero-based index of the row to delete.
	//
	// Returns:
	//   - An error if the index is out of range.
	DeleteRow(index int) error

	// FindRows returns a new BDataMatrix containing only the rows that match the given query.
	// It searches in the column specified by query.Column and compares each row's value using
	// query.Operator and query.CaseInsensitive. A row is included if any of the query.Values match.
	//
	// Parameters:
	//   - query: A FindRowsQuery struct with fields:
	//       - Column: Column to search in.
	//       - Operator: Comparison operator (e.g., OperatorEquals, OperatorContains).
	//       - CaseInsensitive: If true, comparison ignores letter case.
	//       - Values: Values to compare against.
	//
	// Returns:
	//   - A new BDataMatrix with matching rows.
	//   - An error if the specified column does not exist or no rows match.
	FindRows(query FindRowsQuery) (BDataMatrix, error)

	// SortBy sorts the rows based on the specified header keys.
	//
	// Parameters:
	//   - keys: A variadic list of header names to sort by.
	//     If no keys are provided, the matrix is sorted by all header columns in order.
	//
	// Returns:
	//   - An error if any of the specified columns do not exist.
	SortBy(keys ...string) error

	// Header returns the header row as a slice of strings.
	//
	// Returns:
	//   - A []string representing the header.
	Header() []string

	// Rows returns all rows (excluding the header) as a two-dimensional slice of strings.
	//
	// Returns:
	//   - A [][]string containing all rows.
	Rows() [][]string

	// Data returns the full dataset as a two-dimensional slice of strings.
	//
	// Parameters:
	//   - withHeader: If true, includes the header as the first row; otherwise, returns only the data rows.
	//
	// Returns:
	//   - A [][]string where the first element is the header if withHeader is true, followed by data rows.
	//   - If withHeader is false, only the data rows are returned.
	//
	// Example usage:
	//
	//	// Get the full dataset with the header included.
	//	dataWithHeader := matrix.Data(true)
	//
	//	// Get only the data rows, excluding the header.
	//	dataWithoutHeader := matrix.Data(false)
	Data(withHeader bool) [][]string

	// Clear removes all rows from the matrix while preserving the header.
	//
	// Example:
	//   matrix.Clear()
	Clear()

	// Preview prints the matrix as a formatted table.
	//
	// Example:
	//   matrix.Preview()
	//   Output:
	//     +----+-------+-----+
	//     | ID | Name  | Age |
	//     +----+-------+-----+
	//     | 1  | Alice | 30  |
	//     | 2  | Bob   | 25  |
	//     | 3  | alice | 28  |
	//     +----+-------+-----+
	Preview()

	// ToCSV exports the matrix in CSV format.
	//
	// Parameters:
	//   - withHeader: If true, includes the header row in the output.
	//
	// Returns:
	//   - An Output interface representing the CSV data.
	ToCSV(withHeader bool) Output

	// ToTSV exports the matrix in TSV (tab-separated) format.
	//
	// Parameters:
	//   - withHeader: If true, includes the header row in the output.
	//
	// Returns:
	//   - An Output interface representing the TSV data.
	ToTSV(withHeader bool) Output

	// ToYAML exports the matrix in YAML format.
	//
	// Parameters:
	//   - withHeader: If true, represents each row as an object with header keys.
	//
	// Returns:
	//   - An Output interface representing the YAML data.
	ToYAML(withHeader bool) Output

	// ToJSON exports the matrix in JSON format.
	//
	// Parameters:
	//   - withHeader: If true, each row is represented as an object with header keys.
	//   - compact: If false, the JSON output is pretty-printed; otherwise, it is compact.
	//
	// Returns:
	//   - An Output interface representing the JSON data.
	ToJSON(withHeader, compact bool) Output

	// ToCustom exports the matrix using a custom separator.
	//
	// Parameters:
	//   - withHeader: If true, includes the header row in the output.
	//   - separator: The string to use as a separator between columns.
	//
	// Returns:
	//   - An Output interface representing the custom-formatted data.
	ToCustom(withHeader bool, separator string) Output
}

BDataMatrix defines the behavior for a data matrix.

func New

func New(keys ...string) (BDataMatrix, error)

New create a new BDataMatrix with the provided headers.

Example usage:

// Create a new matrix with headers "ID", "Name", "Age".
matrix, err := New("ID", "Name", "Age")
if err != nil {
    // handle error
}

// Add rows.
_ = matrix.AddRow("1", "Alice", "30")
_ = matrix.AddRow("2", "Bob", "25")

// Find rows where "Name" equals "Alice" (case-insensitive).
query := FindRowsQuery{
    Column:          "Name",
    Operator:        OperatorEquals,
    CaseInsensitive: true,
    Values:          []string{"Alice"},
}
result, err := matrix.FindRows(query)
if err != nil {
    // handle error
}

// Preview the matrix.
matrix.Preview()

// Export as CSV (with header) and write to file.
csvOut := matrix.ToCSV(true)
_ = csvOut.Write("output.csv", 0644)

func NewWithData

func NewWithData(rows [][]string, keys ...string) (BDataMatrix, error)

NewWithData creates a new BDataMatrix with the provided headers and initial data.

Example usage:

// Define initial data rows.
rows := [][]string{
    {"1", "Alice", "30"},
    {"2", "Bob", "25"},
}

// Create a new matrix with headers and data.
matrix, err := NewWithData(rows, "ID", "Name", "Age")
if err != nil {
    // handle error
}

// Preview the matrix.
matrix.Preview()

// Export as JSON (compact format).
jsonOut := matrix.ToJSON(true, true)
_ = jsonOut.Write("output.json", 0644)

type FindRowsQuery

type FindRowsQuery struct {
	// Column is the header name of the column to search.
	Column string
	// Operator is the comparison operator to apply.
	Operator Operator
	// CaseInsensitive indicates whether the comparison should ignore letter case.
	CaseInsensitive bool
	// Values is a slice of values to compare against.
	Values []string
}

FindRowsQuery specifies the criteria for searching rows.

type Operator

type Operator int

Operator defines the type of comparison for queries.

const (
	OperatorEquals Operator = iota
	OperatorNotEquals
	OperatorContains
	OperatorStartsWith
	OperatorEndsWith
)

type Output

type Output interface {
	// Write writes the output data to a file with the given name and file mode.
	//
	// Parameters:
	//   - name: The filename to write to.
	//   - mode: The file mode (permissions) to use when writing.
	//
	// Returns:
	//   - An error if writing fails.
	Write(name string, mode os.FileMode) error

	// Bytes returns the output data as a byte slice.
	//
	// Returns:
	//   - A []byte containing the output data.
	Bytes() []byte

	// String returns the output data as a string.
	//
	// Returns:
	//   - A string representation of the output data.
	String() string
}

Output defines methods for exporting matrix data.

Example usage:

// Get CSV output and write to file.
csvOut := matrix.ToCSV(true)
err := csvOut.Write("output.csv", 0644)
if err != nil {
    // handle error
}

// Retrieve JSON output as a string.
jsonOut := matrix.ToJSON(true, false)
fmt.Println(jsonOut.String())