Basic Concepts

Core Types

werkbook is built around five core types that map directly to Excel concepts:

File

A File represents an entire Excel workbook (.xlsx). It holds one or more sheets and manages the formula dependency graph.

wb := werkbook.New()                                 // new workbook with "Sheet1"
wb := werkbook.New(werkbook.FirstSheet("Data"))       // custom first sheet name
wb, err := werkbook.Open("report.xlsx")               // open existing file

Sheet

A Sheet is a single worksheet within a workbook. All cell operations happen on a sheet.

sheet := wb.Sheet("Sheet1")       // get by name (nil if not found)
names := wb.SheetNames()          // list all sheet names
sheet, err := wb.NewSheet("Data") // add a new sheet
err := wb.DeleteSheet("Old")      // remove a sheet

Cell

A Cell represents a single cell at a column/row intersection. Cells store a value, an optional formula, and an optional style.

cell.Col()     // 1-based column number
cell.Value()   // the cell's Value
cell.Formula() // formula text, or ""
cell.Style()   // *Style, or nil

Row

A Row groups the cells in a single spreadsheet row.

row.Num()    // 1-based row number
row.Height() // custom height, or 0
row.Cells()  // all cells, sorted by column

Value

A Value is a tagged union that represents any cell value. There are five types:

v, _ := sheet.GetValue("A1")
v.IsEmpty()  // true if TypeEmpty
v.Raw()      // underlying Go value (float64, string, bool, or nil)

Coordinates

werkbook uses 1-based coordinates and standard A1 notation:

// Convert between formats
col, row, _ := werkbook.CellNameToCoordinates("B3")  // col=2, row=3
name, _ := werkbook.CoordinatesToCellName(2, 3)       // "B3"

// Column helpers
num, _ := werkbook.ColumnNameToNumber("AA") // 27
letter := werkbook.ColumnNumberToName(27)   // "AA"

// Range parsing
c1, r1, c2, r2, _ := werkbook.RangeToCoordinates("A1:C5")

Limits: 1,048,576 rows and 16,384 columns (A through XFD), matching Excel’s maximums.

Sparse Storage

werkbook uses sparse storage internally — only cells that contain data are stored in memory. This makes it efficient for large spreadsheets where most cells are empty.

Zero Dependencies

werkbook has no external dependencies. It uses only the Go standard library for ZIP handling, XML parsing, and everything else. This means minimal binary size, no dependency conflicts, and straightforward auditing.