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 over a channel 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 they are parsed, instead of buffering the whole sheet
• String, numeric, date, and boolean cell values, with spreadsheet-style column labels (A, B, ..., AA, ...)

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)
		}
	}
}

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

	Type CellType

	Value any
}

Cell is a single spreadsheet cell.

type CellType

type CellType int

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 int
	Cells []Cell
	Error error
}

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.