Basic Concepts

werkbook is a sparse, in-memory .xlsx model with a built-in formula engine. The root package is designed around workbook concepts instead of raw OOXML parts.

Core Types

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

File

A File represents an entire workbook. It owns:

• the ordered sheet list
• the formula dependency graph
• workbook-scoped metadata such as date system, tables, defined names, and calculation properties

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()   // cached 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:

Type	Go Value	Example
TypeEmpty	nil	Empty cell
TypeNumber	float64	42, 3.14
TypeString	string	"Hello"
TypeBool	bool	true, false
TypeError	string	"#DIV/0!"

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

Workbook Metadata

The root package also exposes higher-level workbook features:

• DefinedName for workbook-scoped and sheet-scoped named ranges
• Table and TableStyle for worksheet tables and structured references
• CalcProperties for workbook calculation settings like manual mode and full-calc flags

These are all part of the public API, not hidden OOXML details.

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 the .xlsx worksheet maximums.

Formula Evaluation

Formula cells are compiled and tracked in a dependency graph.

• SetFormula("A1", "B1+C1") stores the formula text without a leading =
• GetValue("A1") evaluates the formula lazily
• Recalculate() forces evaluation of all dirty formula cells
• Precedents() and DirectDependents() expose direct formula edges for inspection tools

This means the library behaves like a workbook model, not just a file writer.

Date Systems

Excel supports two date systems:

• the default 1900 system
• the 1904 system used by some Mac-authored workbooks

werkbook preserves the date system when opening files and lets you opt into it for new workbooks with werkbook.WithDate1904(true).

Sparse Storage

werkbook stores only the rows and cells that actually exist. Empty cells do not consume memory. A row can still exist without cells if it carries row metadata such as a custom height.

Zero Dependencies

werkbook has no external dependencies. ZIP handling, XML parsing, and formula evaluation all live in the module itself or the Go standard library.