README
¶
xls
Pure Golang library for reading Microsoft Excel 97-2004 .xls files (BIFF8 binary format).
Based on libxls and the original extrame/xls.
Install
go get github.com/meisbokai/xls
Usage
Open a file
package main
import (
"fmt"
"github.com/meisbokai/xls"
)
func main() {
wb, err := xls.Open("spreadsheet.xls", "utf-8")
if err != nil {
panic(err)
}
sheet := wb.GetSheet(0) // first sheet
if sheet == nil {
return
}
for i := 0; i <= int(sheet.MaxRow); i++ {
row := sheet.Row(i)
if row == nil {
continue
}
fmt.Println(row.Col(0)) // first column as formatted string
}
}
Open with closer
wb, closer, err := xls.OpenWithCloser("spreadsheet.xls", "utf-8")
if err != nil {
panic(err)
}
defer closer.Close()
Open from reader
file, err := os.Open("spreadsheet.xls")
if err != nil {
panic(err)
}
defer file.Close()
wb, err := xls.OpenReader(file, "utf-8")
if err != nil {
panic(err)
}
API
| Function | Description |
|---|---|
Open(file, charset) |
Open .xls file by path |
OpenWithCloser(file, charset) |
Open .xls, returns closer for deferred close |
OpenReader(reader, charset) |
Open .xls from io.ReadSeeker |
WorkBook fields
| Field | Type | Description |
|---|---|---|
Author |
string |
Document author |
Is5ver |
bool |
BIFF5 format flag |
Codepage |
uint16 |
Code page for text decoding |
Xfs |
[]st_xf_data |
Extended format table |
Fonts |
[]Font |
Font table |
Formats |
map[uint16]*Format |
Number format table |
WorkBook methods
| Method | Description |
|---|---|
GetSheet(num) |
Get sheet by index (0-based) |
NumSheets() |
Number of sheets |
ReadAllCells(max) |
Read all cells, max rows per sheet |
WorkSheet fields
| Field | Type | Description |
|---|---|---|
Name |
string |
Sheet name |
MaxRow |
uint16 |
Highest row number with data |
Selected |
bool |
Whether sheet is selected |
Visibility |
TWorkSheetVisibility |
Sheet visibility state |
Row methods
| Method | Description |
|---|---|
Col(i) |
Formatted cell value as string |
ColExact(i) |
Raw cell value (no format) |
FirstCol() |
First column index with data |
LastCol() |
Last column index with data |
Supported Data
- String cells (ASCII and Unicode)
- Numeric cells (integer and float, including RK-encoded)
- Date/time cells
- Formula cells (cached results)
- Blank cells with formatting
- Merged cell ranges
- Hyperlinks
Charset Support
The charset parameter controls text decoding. Pass "utf-8" for most files, or a specific charset name (e.g. "windows-1251") for legacy encodings.
Contributing
See docs/CONTRIBUTING.md for full development setup, testing, and PR guidelines.
License
Apache License 2.0
Documentation
¶
Overview ¶
Package xls provides a pure Go reader for Microsoft Excel 97-2004 binary (.xls) files (BIFF8 format). It does not support the newer .xlsx format.
Opening a file ¶
Use Open, OpenWithCloser, or OpenReader to obtain a WorkBook:
wb, err := xls.Open("spreadsheet.xls", "utf-8")
if err != nil {
log.Fatal(err)
}
The charset parameter controls text decoding. Pass "utf-8" for most files.
Reading data ¶
Access sheets by index with WorkBook.GetSheet, then iterate rows and columns:
sheet := wb.GetSheet(0)
for i := 0; i <= int(sheet.MaxRow); i++ {
row := sheet.Row(i)
if row == nil {
continue
}
fmt.Println(row.Col(0))
}
Key types ¶
- WorkBook: top-level container holding sheets, fonts, and formats
- WorkSheet: a single sheet with rows indexed by number
- Row: a row of cells; use Col(i) to search spanned columns for merged cells, or ColExact(i) for explicit cell values only
Supported features ¶
String cells (ASCII and Unicode), numeric cells (integer, float, RK-encoded), date/time cells, formula cells (cached results), blank cells, merged cell ranges, and hyperlinks.
Index ¶
- Constants
- Variables
- type BlankCol
- type CellRange
- type Col
- type Coler
- type Font
- type FontInfo
- type Format
- type FormulaCol
- type FormulaStringCol
- type HyperLink
- type LabelsstCol
- type MulBlankCol
- type MulrkCol
- type NumberCol
- type RK
- type Ranger
- type RkCol
- type Row
- type SstInfo
- type TWorkSheetVisibility
- type WorkBook
- type WorkSheet
- type Xf5
- type Xf8
- type XfRk
Examples ¶
Constants ¶
const MJD_0 float64 = 2400000.5
const MJD_JD2000 float64 = 51544.5
Variables ¶
var ErrIsInt = fmt.Errorf("is int")
Functions ¶
This section is empty.
Types ¶
type FormulaCol ¶
type FormulaCol struct {
Header struct {
Col
IndexXf uint16
Result [8]byte
Flags uint16
// contains filtered or unexported fields
}
Bts []byte
}
func (*FormulaCol) String ¶
func (c *FormulaCol) String(wb *WorkBook) []string
type FormulaStringCol ¶
func (*FormulaStringCol) String ¶
func (c *FormulaStringCol) String(wb *WorkBook) []string
type HyperLink ¶
type HyperLink struct {
CellRange
Description string
TextMark string
TargetFrame string
Url string
ShortedFilePath string
ExtendedFilePath string
IsUrl bool
}
hyperlink type's content
type LabelsstCol ¶
func (*LabelsstCol) String ¶
func (c *LabelsstCol) String(wb *WorkBook) []string
type MulBlankCol ¶
func (*MulBlankCol) LastCol ¶
func (c *MulBlankCol) LastCol() uint16
func (*MulBlankCol) String ¶
func (c *MulBlankCol) String(wb *WorkBook) []string
type Row ¶
type Row struct {
// contains filtered or unexported fields
}
Row the data of one row
func (*Row) Col ¶
Col Get the Nth Col from the Row, if has not, return nil. Suggest use Has function to test it.
Example ¶
Demonstrates Col() which searches spanned columns for merged cells, and ColExact() which returns a value only if the cell is explicitly present.
xlFile, err := Open("Table.xls", "utf-8")
if err != nil {
log.Fatal(err)
}
sheet := xlFile.GetSheet(0)
if sheet == nil {
return
}
row := sheet.Row(0)
if row == nil {
return
}
// Col returns the formatted value, searching across spanned columns for merged cells.
fmt.Println(row.Col(0))
// ColExact returns a value only if the cell is explicitly present at this index.
fmt.Println(row.ColExact(0))
func (*Row) ColExact ¶
ColExact Get the Nth Col from the Row, if has not, return nil. For merged cells value is returned for first cell only
type TWorkSheetVisibility ¶
type TWorkSheetVisibility byte
const ( WorkSheetVisible TWorkSheetVisibility = 0 WorkSheetHidden TWorkSheetVisibility = 1 WorkSheetVeryHidden TWorkSheetVisibility = 2 )
type WorkBook ¶
type WorkBook struct {
Is5ver bool
Type uint16
Codepage uint16
Xfs []st_xf_data
Fonts []Font
Formats map[uint16]*Format
Author string
// contains filtered or unexported fields
}
xls workbook type
func Open ¶
Open one xls file
Example ¶
if xlFile, err := Open("Table.xls", "utf-8"); err == nil {
fmt.Println(xlFile.Author)
}
Example (ErrorHandling) ¶
Demonstrates handling errors when opening a file.
_, err := Open("nonexistent.xls", "utf-8")
if err != nil {
log.Print("failed to open file: ", err)
return
}
func OpenReader ¶
func OpenReader(reader io.ReadSeeker, charset string) (wb *WorkBook, err error)
Open xls file from reader
func OpenWithCloser ¶
Open one xls file and return the closer
func (*WorkBook) GetSheet ¶
Get one sheet by its number
Example ¶
Output: read the content of first two cols in each row
if xlFile, err := Open("Table.xls", "utf-8"); err == nil {
if sheet1 := xlFile.GetSheet(0); sheet1 != nil {
fmt.Print("Total Lines ", sheet1.MaxRow, sheet1.Name)
col1 := sheet1.Row(0).Col(0)
col2 := sheet1.Row(0).Col(0)
for i := 0; i <= (int(sheet1.MaxRow)); i++ {
row1 := sheet1.Row(i)
col1 = row1.Col(0)
col2 = row1.Col(1)
fmt.Print("\n", col1, ",", col2)
}
}
}
func (*WorkBook) NumSheets ¶
Get the number of all sheets, look into example
Example ¶
if xlFile, err := Open("Table.xls", "utf-8"); err == nil {
for i := 0; i < xlFile.NumSheets(); i++ {
sheet := xlFile.GetSheet(i)
fmt.Println(sheet.Name)
}
}
func (*WorkBook) Parse ¶
func (w *WorkBook) Parse(buf io.ReadSeeker)
func (*WorkBook) ReadAllCells ¶
helper function to read all cells from file Notice: the max value is the limit of the max capacity of lines. Warning: the helper function will need big memeory if file is large.
Example ¶
Demonstrates reading all cells from all sheets using the ReadAllCells helper.
xlFile, err := Open("Table.xls", "utf-8")
if err != nil {
log.Fatal(err)
}
cells := xlFile.ReadAllCells(100)
for i, row := range cells {
fmt.Printf("Row %d: %v\n", i, row)
}
type WorkSheet ¶
type WorkSheet struct {
Name string
Selected bool
Visibility TWorkSheetVisibility
//NOTICE: this is the max row number of the sheet, so it should be count -1
MaxRow uint16
// contains filtered or unexported fields
}
WorkSheet in one WorkBook
Source Files