xls

README

go-xls

A small Go package for reading legacy Microsoft Excel .xls (BIFF8) workbooks. It lists worksheet names and streams each sheet's rows as an iterator without loading the whole sheet into memory.

Features

• Open workbooks from a file path or any io.ReaderAt
• List the names of a workbook's visible worksheets
• Stream rows of a sheet as an iter.Seq[Row] iterator as they are parsed, instead of buffering the whole sheet
• String, numeric, date, and boolean cell values, with spreadsheet-style column labels (A, B, ..., AA, ...)
• Each Row reports FirstCol/LastCol, the 0-based column range Excel recorded as having data, even if some of those columns are empty

Installation

go get github.com/b0r1ssh/go-xls

Usage

package main

import (
	"fmt"
	"log"

	"github.com/b0r1ssh/go-xls"
)

func main() {
	f, err := xls.OpenFile("report.xls")
	if err != nil {
		log.Fatal(err)
	}

	for _, name := range f.SheetNames() {
		fmt.Println("sheet:", name)
	}

	for row := range f.ReadRows(f.SheetNames()[0]) {
		if row.Error != nil {
			log.Fatal(row.Error)
		}

		for _, cell := range row.Cells {
			fmt.Printf("%s%d = %v\n", cell.Column, row.Index+1, cell.Value)
		}
	}
}

Row.Cells only contains cells that hold a value, so blank cells in the middle of a row are skipped. Use Row.FirstCol and Row.LastCol to know the full column range Excel recorded for the row instead of inferring it from Cells:

for row := range f.ReadRows("Sheet1") {
	fmt.Printf("row %d spans columns %d to %d\n", row.Index, row.FirstCol, row.LastCol)
}

Release workflow for contributors

Merging a pull request into main automatically creates a Git tag and a GitHub release. Before merging, use at most one of these labels to select the semantic version increment:

• patch: bug fixes and other backward-compatible changes (v1.2.3 to v1.2.4).
• minor: new backward-compatible functionality (v1.2.3 to v1.3.0).
• major: breaking API changes (v1.2.3 to v2.0.0).

When no release label is present, the workflow uses patch. Do not combine patch, minor, and major labels on one pull request; the release workflow will fail if more than one is present.

Use the skip-release label for documentation, CI, or other changes that do not need a new module version. When a pull request with this label is merged, the publish workflow skips the release entirely.

Documentation

Overview

Package xls reads legacy Microsoft Excel .xls (BIFF8) workbooks. It exposes the sheet names of a workbook and streams each sheet's rows without loading the whole sheet into memory.

Index

• type Cell
• type CellType
• type File
  • func OpenFile(path string) (*File, error)
  • func OpenReader(r io.ReaderAt) (*File, error)
  • func (f *File) ReadRows(sheetName string) iter.Seq[Row]
  • func (f *File) SheetNames() []string
• type Row
• type Sheet

Types

type Cell

type Cell struct {
	// Column is the spreadsheet-style column label, e.g. "A", "B", "AA".
	Column string

	// Value holds the actual value of the cell. Its type is indicated by Type.
	Value any

	// Index is the 0-based index of this cell within its row.
	Index int

	// Type indicates the type of value stored in this cell.
	Type CellType
}

Cell is a single spreadsheet cell.

type CellType

type CellType uint8

CellType identifies the Go type stored in a Cell's Value.

const (
	// TypeString means Value is a string.
	TypeString CellType = iota
	// TypeNumeric means Value is a float64.
	TypeNumeric
	// TypeBoolean means Value is a bool.
	TypeBoolean
	// TypeDate means Value is a time.Time.
	TypeDate
)

type File

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

File is an opened .xls workbook. Call Close when done with it.

func OpenFile

func OpenFile(path string) (*File, error)

OpenFile opens the .xls workbook at path. The returned File must be closed with Close.

func OpenReader

func OpenReader(r io.ReaderAt) (*File, error)

OpenReader opens a .xls workbook from r. Unlike OpenFile, the caller retains ownership of r and Close will not close it.

func (*File) ReadRows

func (f *File) ReadRows(sheetName string) iter.Seq[Row]

ReadRows streams the rows of the sheet named sheetName in order. Rows are produced synchronously as the returned sequence is iterated.

func (*File) SheetNames

func (f *File) SheetNames() []string

SheetNames returns the names of the workbook's visible worksheets, in the order they appear in Excel.

type Row

type Row struct {
	// Index is the 0-based index of this row within the sheet.
	Index int

	// Cells holds the individual cells in this row.
	Cells []Cell

	// Error holds any error encountered while reading this row.
	Error error

	// FirstCol and LastCol are the 0-based range of columns that carry
	// data in this row, as recorded by Excel's ROW record.
	FirstCol uint16
	LastCol  uint16
}

Row is one row of cells read from a sheet. If Error is non-nil, the other fields are not meaningful.

type Sheet

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

Sheet is a worksheet within a workbook.