spreadsheet

README

spreadsheet

The spreadsheet package provides a lightweight writer for CSV and XLSX exports. It is intended for reporting and data-export workflows where applications need mixed-type row input, optional multi-sheet XLSX generation, configurable header styling, and context-aware file generation without dealing directly with spreadsheet encoding details.

Import

import "github.com/raykavin/gobox/spreadsheet"

What it provides

• Writer for generating spreadsheet files as raw bytes
• support for xlsx and csv output through FormatXLSX and FormatCSV
• Sheet definitions with tab name, headers, and rows
• Row as a convenient []any alias for mixed value types
• configurable XLSX header styling through Options.HeaderStyle
• configurable fallback sheet names through Options.DefaultSheetName
• context-aware generation with cancellation checks during encoding

Main types

• Format: supported output format (FormatXLSX or FormatCSV)
• Row: a single data row represented as []any
• Sheet: worksheet definition with Name, Headers, and Rows
• Options: writer configuration including default sheet name and optional *excelize.Style
• Writer: generates CSV or XLSX output and returns the encoded bytes

XLSX example

Use FormatXLSX when you want one or more worksheet tabs in the same workbook.

package main

import (
	"context"
	"log"
	"os"

	"github.com/raykavin/gobox/spreadsheet"
)

func main() {
	writer := spreadsheet.New(spreadsheet.Options{
		DefaultSheetName: "Report",
	})

	data, err := writer.Write(context.Background(), spreadsheet.FormatXLSX,
		spreadsheet.Sheet{
			Name:    "Users",
			Headers: []string{"ID", "Name", "Active"},
			Rows: []spreadsheet.Row{
				{1, "Alice", true},
				{2, "Bob", false},
			},
		},
		spreadsheet.Sheet{
			Name:    "Orders",
			Headers: []string{"OrderID", "Total"},
			Rows: []spreadsheet.Row{
				{1001, 199.90},
			},
		},
	)
	if err != nil {
		log.Fatal(err)
	}

	if err := os.WriteFile("report.xlsx", data, 0o644); err != nil {
		log.Fatal(err)
	}
}

CSV example

Use FormatCSV when you want a single flat export. Only the first Sheet is written in CSV mode.

package main

import (
	"context"
	"log"
	"os"

	"github.com/raykavin/gobox/spreadsheet"
)

func main() {
	writer := spreadsheet.New(spreadsheet.Options{})

	data, err := writer.Write(context.Background(), spreadsheet.FormatCSV,
		spreadsheet.Sheet{
			Headers: []string{"Name", "Age", "City"},
			Rows: []spreadsheet.Row{
				{"Alice", 30, "New York"},
				{"Bob", 25, "London"},
			},
		},
	)
	if err != nil {
		log.Fatal(err)
	}

	if err := os.WriteFile("users.csv", data, 0o644); err != nil {
		log.Fatal(err)
	}
}

Notes

• Write() requires at least one Sheet, and every sheet must define headers
• FormatCSV ignores any additional sheets after the first one
• empty or whitespace-only sheet names fall back to Options.DefaultSheetName
• the default XLSX header style uses bold text with a yellow background
• Options.HeaderStyle lets callers replace the default XLSX header styling
• XLSX cell values are written through excelize, while CSV values are converted with fmt.Sprint()
• Write() returns raw bytes so callers can save, stream, or attach the generated file as needed

Documentation

Overview

Package spreadsheet provides a lightweight writer for generating CSV and XLSX files as raw bytes.

Basic usage

writer := spreadsheet.New(spreadsheet.Options{})

data, err := writer.Write(ctx, spreadsheet.FormatXLSX,
    spreadsheet.Sheet{
        Name:    "Users",
        Headers: []string{"ID", "Name", "Active"},
        Rows: []spreadsheet.Row{
            {1, "Alice", true},
            {2, "Bob", false},
        },
    },
)
if err != nil {
    log.Fatal(err)
}
os.WriteFile("users.xlsx", data, 0o644)

CSV output

Pass FormatCSV to write a single flat sheet. Only the first Sheet is used.

data, err := writer.Write(ctx, spreadsheet.FormatCSV, sheet)

Custom header style

The default XLSX header style uses bold text with a yellow background. Pass an Options.HeaderStyle to replace it.

writer := spreadsheet.New(spreadsheet.Options{
    DefaultSheetName: "Report",
    HeaderStyle: &excelize.Style{
        Font: &excelize.Font{Bold: true, Color: "#FFFFFF"},
        Fill: excelize.Fill{Type: "pattern", Pattern: 1, Color: []string{"#0070C0"}},
    },
})

Index

• type Format
• type Options
• type Row
• type Sheet
• type Writer
  • func New(opts Options) *Writer
  • func (w *Writer) Write(ctx context.Context, format Format, sheets ...Sheet) ([]byte, error)

Types

type Format

type Format string

Format represents a supported spreadsheet format.

const (
	FormatXLSX Format = "xlsx"
	FormatCSV  Format = "csv"
)

type Options

type Options struct {
	// DefaultSheetName is used when Sheet.Name is empty.
	// Default: "Sheet1"
	DefaultSheetName string

	// HeaderStyle overrides the default XLSX header cell style.
	// Default: bold font + yellow background fill.
	HeaderStyle *excelize.Style
}

Options configures the Writer behaviour.

type Row

type Row []any

Row is a generic alias for a single row of data.

type Sheet

type Sheet struct {
	// Name is the tab name. Falls back to Options.DefaultSheetName when empty.
	Name    string
	Headers []string
	Rows    []Row
}

Sheet holds the data for a single worksheet tab (XLSX only).

type Writer

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

Writer generates spreadsheet files in CSV or XLSX format.

func New

func New(opts Options) *Writer

New creates a new Writer with the given options.

func (*Writer) Write

func (w *Writer) Write(ctx context.Context, format Format, sheets ...Sheet) ([]byte, error)

Write generates a spreadsheet and returns its raw bytes.

For CSV only the first Sheet is used.