Excel binding to struct written in Go.(Only supports Go1.18+)

# exl
Excel binding to struct written in Go.(Only supports Go1.18+)

[![CircleCI](https://circleci.com/gh/go-the-way/exl/tree/main.svg?style=shield)](https://circleci.com/gh/go-the-way/exl/tree/main)
![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/go-the-way/exl)
[![codecov](https://codecov.io/gh/go-the-way/exl/branch/main/graph/badge.svg?token=8MAR3J959H)](https://codecov.io/gh/go-the-way/exl)
[![Go Report Card](https://goreportcard.com/badge/github.com/go-the-way/exl)](https://goreportcard.com/report/github.com/go-the-way/exl)
[![GoDoc](https://pkg.go.dev/badge/github.com/go-the-way/exl?status.svg)](https://pkg.go.dev/github.com/go-the-way/exl?tab=doc)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go#microsoft-excel)

## usage

### Read Excel

```go
package main

import (
	"fmt"
	
	"github.com/go-the-way/exl"
)

type ReadExcel struct {
	ID   int    `excel:"ID"`
	Name string `excel:"Name"`
}

func (*ReadExcel) ReadConfigure(rc *exl.ReadConfig) {}

func main() {
	if models, err := exl.ReadFile[*ReadExcel]("/to/path.xlsx"); err != nil {
		fmt.Println("read excel err:" + err.Error())
	} else {
		fmt.Printf("read excel num: %d\n", len(models))
	}
}
```

### Write Excel

```go
package main

import (
	"fmt"
	
	"github.com/go-the-way/exl"
)

type WriteExcel struct {
	ID   int    `excel:"ID"`
	Name string `excel:"Name"`
}

func (m *WriteExcel) WriteConfigure(wc *exl.WriteConfig) {}

func main() {
	if err := exl.Write("/to/path.xlsx", []*WriteExcel{{100, "apple"}, {200, "pear"}}); err != nil {
		fmt.Println("write excel err:" + err.Error())
	} else {
		fmt.Println("write excel done")
	}
}
```

## Writer

```go
package main

import (
	"fmt"

	"github.com/go-the-way/exl"
)

func main() {
	w := exl.NewWriter()
	if err := w.Write("int", []int{1, 2}); err != nil {
		fmt.Println(err)
		return
	}
	if err := w.Write("float", []float64{1.1, 2.2}); err != nil {
		fmt.Println(err)
		return
	}
	if err := w.Write("string", []string{"hello", "world"}); err != nil {
		fmt.Println(err)
		return
	}
	if err := w.Write("map", []map[string]string{{"id":"1000","name":"hello"},{"id":"2000","name":"world"}}); err != nil {
		fmt.Println(err)
		return
	}
	if err := w.Write("structWithField", []struct{ID int}{{1000},{2000}}); err != nil {
		fmt.Println(err)
		return
	}
	if err := w.Write("structWithTag", []struct{ID int `excel:"编号"`}{{1000},{2000}}); err != nil {
		fmt.Println(err)
		return
	}
	if err := w.Write("structWithTagAndIgnore", []struct{
		ID int `excel:"编号"`
		Extra int `excel:"-"`
		Name string `excel:"名称"`
	}{{1000,0,"Coco"},{2000,0,"Apple"}}); err != nil {
		fmt.Println(err)
		return
	} 
	if err := w.SaveTo("dist.xlsx"); err != nil {
		fmt.Println(err)
		return
	}
}
```


Golang library for reading and writing Microsoft Excel&trade; (XLSX) files

<img width="650" src="./excelize.svg" alt="Excelize logo">


 <a href="https://github.com/xuri/excelize/actions/workflows/go.yml"><img src="https://github.com/xuri/excelize/actions/workflows/go.yml/badge.svg" alt="Build Status"></a>
 <a href="https://codecov.io/gh/qax-os/excelize"><img src="https://codecov.io/gh/qax-os/excelize/branch/master/graph/badge.svg" alt="Code Coverage"></a>
 <a href="https://goreportcard.com/report/github.com/xuri/excelize/v2"><img src="https://goreportcard.com/badge/github.com/xuri/excelize/v2" alt="Go Report Card"></a>
 <a href="https://pkg.go.dev/github.com/xuri/excelize/v2"><img src="https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white" alt="go.dev"></a>
 <a href="https://opensource.org/licenses/BSD-3-Clause"><img src="https://img.shields.io/badge/license-bsd-orange.svg" alt="Licenses"></a>
 <a href="https://www.paypal.com/paypalme/xuri"><img src="https://img.shields.io/badge/Donate-PayPal-green.svg" alt="Donate"></a>


# Excelize

## Introduction

Excelize is a library written in pure Go providing a set of functions that allow you to write to and read from XLAM / XLSM / XLSX / XLTM / XLTX files. Supports reading and writing spreadsheet documents generated by Microsoft Excel&trade; 2007 and later. Supports complex components by high compatibility, and provided streaming API for generating or reading data from a worksheet with huge amounts of data. This library needs Go version 1.25.0 or later. The full docs can be seen using go's built-in documentation tool, or online at [go.dev](https://pkg.go.dev/github.com/xuri/excelize/v2) and [docs reference](https://xuri.me/excelize/).

## Basic Usage

### Installation

```bash
go get github.com/xuri/excelize
```

- If your packages are managed using [Go Modules](https://go.dev/blog/using-go-modules), please install with following command.

```bash
go get github.com/xuri/excelize/v2
```

### Create spreadsheet

Here is a minimal example usage that will create spreadsheet file.

```go
package main

import (
 "fmt"

 "github.com/xuri/excelize/v2"
)

func main() {
 f := excelize.NewFile()
 defer func() {
 if err := f.Close(); err != nil {
 fmt.Println(err)
 }
 }()
 // Create a new sheet.
 index, err := f.NewSheet("Sheet2")
 if err != nil {
 fmt.Println(err)
 return
 }
 // Set value of a cell.
 f.SetCellValue("Sheet2", "A2", "Hello world.")
 f.SetCellValue("Sheet1", "B2", 100)
 // Set active sheet of the workbook.
 f.SetActiveSheet(index)
 // Save spreadsheet by the given path.
 if err := f.SaveAs("Book1.xlsx"); err != nil {
 fmt.Println(err)
 }
}
```

### Reading spreadsheet

The following constitutes the bare to read a spreadsheet document.

```go
package main

import (
 "fmt"

 "github.com/xuri/excelize/v2"
)

func main() {
 f, err := excelize.OpenFile("Book1.xlsx")
 if err != nil {
 fmt.Println(err)
 return
 }
 defer func() {
 // Close the spreadsheet.
 if err := f.Close(); err != nil {
 fmt.Println(err)
 }
 }()
 // Get value from cell by given worksheet name and cell reference.
 cell, err := f.GetCellValue("Sheet1", "B2")
 if err != nil {
 fmt.Println(err)
 return
 }
 fmt.Println(cell)
 // Get all the rows in the Sheet1.
 rows, err := f.GetRows("Sheet1")
 if err != nil {
 fmt.Println(err)
 return
 }
 for _, row := range rows {
 for _, colCell := range row {
 fmt.Print(colCell, "\t")
 }
 fmt.Println()
 }
}
```

### Add chart to spreadsheet file

With Excelize chart generation and management is as easy as a few lines of code. You can build charts based on data in your worksheet or generate charts without any data in your worksheet at all.

<img width="650" src="./test/images/chart.png" alt="Excelize">

```go
package main

import (
 "fmt"

 "github.com/xuri/excelize/v2"
)

func main() {
 f := excelize.NewFile()
 defer func() {
 if err := f.Close(); err != nil {
 fmt.Println(err)
 }
 }()
 for idx, row := range [][]interface{}{
 {nil, "Apple", "Orange", "Pear"}, {"Small", 2, 3, 3},
 {"Normal", 5, 2, 4}, {"Large", 6, 7, 8},
 } {
 cell, err := excelize.CoordinatesToCellName(1, idx+1)
 if err != nil {
 fmt.Println(err)
 return
 }
 f.SetSheetRow("Sheet1", cell, &row)
 }
 if err := f.AddChart("Sheet1", "E1", &excelize.Chart{
 Type: excelize.Col3DClustered,
 Series: []excelize.ChartSeries{
 {
 Name: "Sheet1!$A$2",
 Categories: "Sheet1!$B$1:$D$1",
 Values: "Sheet1!$B$2:$D$2",
 },
 {
 Name: "Sheet1!$A$3",
 Categories: "Sheet1!$B$1:$D$1",
 Values: "Sheet1!$B$3:$D$3",
 },
 {
 Name: "Sheet1!$A$4",
 Categories: "Sheet1!$B$1:$D$1",
 Values: "Sheet1!$B$4:$D$4",
 }},
 Title: excelize.ChartTitle{
 Paragraph: []excelize.RichTextRun{
 {
 Text: "Fruit 3D Clustered Column Chart",
 },
 },
 },
 }); err != nil {
 fmt.Println(err)
 return
 }
 // Save spreadsheet by the given path.
 if err := f.SaveAs("Book1.xlsx"); err != nil {
 fmt.Println(err)
 }
}
```

### Add picture to spreadsheet file

```go
package main

import (
 "fmt"
 _ "image/gif"
 _ "image/jpeg"
 _ "image/png"

 "github.com/xuri/excelize/v2"
)

func main() {
 f, err := excelize.OpenFile("Book1.xlsx")
 if err != nil {
 fmt.Println(err)
 return
 }
 defer func() {
 // Close the spreadsheet.
 if err := f.Close(); err != nil {
 fmt.Println(err)
 }
 }()
 // Insert a picture.
 if err := f.AddPicture("Sheet1", "A2", "image.png", nil); err != nil {
 fmt.Println(err)
 }
 // Insert a picture to worksheet with scaling.
 if err := f.AddPicture("Sheet1", "D2", "image.jpg",
 &excelize.GraphicOptions{ScaleX: 0.5, ScaleY: 0.5}); err != nil {
 fmt.Println(err)
 }
 // Insert a picture offset in the cell with printing support.
 enable, disable := true, false
 if err := f.AddPicture("Sheet1", "H2", "image.gif",
 &excelize.GraphicOptions{
 PrintObject: &enable,
 LockAspectRatio: false,
 OffsetX: 15,
 OffsetY: 10,
 Locked: &disable,
 }); err != nil {
 fmt.Println(err)
 }
 // Save the spreadsheet with the origin path.
 if err = f.Save(); err != nil {
 fmt.Println(err)
 }
}
```

## Contributing

Contributions are welcome! Open a pull request to fix a bug, or open an issue to discuss a new feature or change. XML is compliant with [part 1 of the 5th edition of the ECMA-376 Standard for Office Open XML](https://www.ecma-international.org/publications-and-standards/standards/ecma-376/).

## Licenses

This program is under the terms of the BSD 3-Clause License. See [https://opensource.org/licenses/BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause).

The Excel logo is a trademark of [Microsoft Corporation](https://aka.ms/trademarks-usage). This artwork is an adaptation.

The Go gopher was created by [Renee French](https://go.dev/doc/gopher/README). Licensed under the [Creative Commons 4.0 Attributions license](http://creativecommons.org/licenses/by/4.0/).

## Gold Sponsors

<a href="https://www.gravityclimate.com" alt="Gravity"><img width="120" src="https://xuri.me/excelize/images/vendor/gravityclimate.com.svg" alt="Gravity"></a>

excelize

A simple and light reader to read a relate-db-like excel as a table

# Intro | 简介

[![Go Report Card](https://goreportcard.com/badge/github.com/szyhf/go-excel)](https://goreportcard.com/report/github.com/szyhf/go-excel)
![cover.run go](https://cover.run/go/github.com/szyhf/go-excel.svg?tag=golang-1.10)
[![GoDoc](https://godoc.org/github.com/szyhf/go-excel?status.png)](https://godoc.org/github.com/szyhf/go-excel)

Expect to create a reader library to read relate-db-like excel easily.
Just like read a config.

> This library can read all xlsx file correctly from our project now.

```shell
go get github.com/szyhf/go-excel
```

## Example | 用例

Here is a simple example.

Assume you have a xlsx file like below:

| ID  | NameOf | Age | Slice      | UnmarshalString |
| --- | ------ | --- | ---------- | --------------- |
| 1   | Andy   | 1   | 1\|2       | {"Foo":"Andy"}  |
| 2   | Leo    | 2   | 2\|3\|4    | {"Foo":"Leo"}   |
| 3   | Ben    | 3   | 3\|4\|5\|6 | {"Foo":"Ben"}   |
| 4   | Ming   | 4   | 1          | {"Foo":"Ming"}  |

+ the first row is the title row.
+ other row is the data row.

> All examples list in [https://godoc.org/github.com/szyhf/go-excel#pkg-examples](https://godoc.org/github.com/szyhf/go-excel#pkg-examples).

```go
// defined a struct
type Standard struct {
	// use field name as default column name
	ID      int
	// column means to map the column name
	Name    string `xlsx:"column(NameOf)"`
	// you can map a column into more than one field
	NamePtr *string `xlsx:"column(NameOf)"`
	// omit `column` if only want to map to column name, it's equal to `column(AgeOf)`
	Age     int     `xlsx:"AgeOf"`
	// split means to split the string into slice by the `|`
	Slice   []int `xlsx:"split(|)"`
	// *Temp implement the `encoding.BinaryUnmarshaler`
	Temp    *Temp `xlsx:"column(UnmarshalString)"`
	// support default encoding of json
	TempEncoding *TempEncoding `xlsx:"column(UnmarshalString);encoding(json)"`
	// use '-' to ignore.
	Ignored string `xlsx:"-"`
}

// func (this Standard) GetXLSXSheetName() string {
// 	return "Some other sheet name if need"
// }

type Temp struct {
	Foo string
}

// self define a unmarshal interface to unmarshal string.
func (this *Temp) UnmarshalBinary(d []byte) error {
	return json.Unmarshal(d, this)
}

func simpleUsage() {
	// will assume the sheet name as "Standard" from the struct name.
	var stdList []Standard
	err := excel.UnmarshalXLSX("./testdata/simple.xlsx", &stdList)
	if err != nil {
		panic(err)
	}
}

func defaultUsage(){
	conn := excel.NewConnecter()
	err := conn.Open("./testdata/simple.xlsx")
	if err != nil {
		panic(err)
	}
	defer conn.Close()

	// Generate an new reader of a sheet
	// sheetNamer: if sheetNamer is string, will use sheet as sheet name.
	//             if sheetNamer is int, will i'th sheet in the workbook, be careful the hidden sheet is counted. i ∈ [1,+inf]
	//             if sheetNamer is a object implements `GetXLSXSheetName()string`, the return value will be used.
	//             otherwise, will use sheetNamer as struct and reflect for it's name.
	// 			   if sheetNamer is a slice, the type of element will be used to infer like before.
	rd, err := conn.NewReader(stdSheetName)
	if err != nil {
		panic(err)
	}
	defer rd.Close()

	for rd.Next() {
		var s Standard
		// Read a row into a struct.
		err:=rd.Read(&s)
		if err!=nil{
			panic(err)
		}
		fmt.Printf("%+v",s)
	}

	// Read all is also supported.
	// var stdList []Standard
	// err = rd.ReadAll(&stdList)
	// if err != nil {
	//   panic(err)
	//	 return
	// }
	// fmt.Printf("%+v",stdList)

	// map with string key is support, too.
	// if value is not string
	// will try to unmarshal to target type
	// but will skip if unmarshal failed.

	// var stdSliceList [][]string
	// err = rd.ReadAll(&stdSliceList)
	// if err != nil {
	//   panic(err)
	//	 return
	// }
	// fmt.Printf("%+v",stdSliceList)

	// var stdMapList []map[string]string
	// err = rd.ReadAll(&stdMapList)
	// if err != nil {
	//   panic(err)
	//	 return
	// }
	// fmt.Printf("%+v",stdMapList)

	// Using binary instead of file.
	// xlsxData, err := ioutil.ReadFile(filePath)
	// if err != nil {
	// 	log.Println(err)
	// 	return
	// }

	// conn := excel.NewConnecter()
	// err = conn.OpenBinary(xlsxData)
}
```

> See the `simple.xlsx`.`Standard` in `testdata` and code in `./standard_test.go` and `./standard_example_test.go` for details.

> While read into a `[]string`, row of title can have duplicated titles, otherwise `ErrDuplicatedTitles` will be return.

## Advance | 进阶用法

The advance usage can make more options.

### Config | 配置

Using a config as "excel.Config":

```go
type Config struct {
	// sheet: if sheet is string, will use sheet as sheet name.
	//        if sheet is a object implements `GetXLSXSheetName()string`, the return value will be used.
	//        otherwise, will use sheet as struct and reflect for it's name.
	// 		  if sheet is a slice, the type of element will be used to infer like before.
	Sheet interface{}
	// Use the index row as title, every row before title-row will be ignore, default is 0.
	TitleRowIndex int
	// Skip n row after title, default is 0 (not skip), empty row is not counted.
	Skip int
	// Auto prefix to sheet name.
	Prefix string
	// Auto suffix to sheet name.
	Suffix string
}
```

Tips:

+ Empty row will be skipped.
+ Column larger than len(TitleRow) will be skipped.
+ Only empty cell can fill with default value, if a cell can not parse into a field it will return an error.
+ Default value can be unmarshal by `encoding.BinaryUnmarshaler`, too.
+ If no title row privoded, the default column name in exce like `'A', 'B', 'C', 'D' ......, 'XFC', 'XFD'` can be used as column name by 26-number-system.

For more details can see the code in `./test/advance_test.go` and file in `simple.xlsx`.`Advance.suffx` sheet.

## XLSX Tag | 标签使用

### column

Map to field name in title row, by default will use the field name.

### default

Set default value when no value is filled in excel cell, by default is 0 or "".

### split

Split a string and convert them to a slice, it won't work if not set.

### nil

Will not skip scan value in the cell equals to this 'nil value'

### req

Will return error if clomun title not exist in excel.

### encoding

Will decode the string value into the field can be unmarshal by the encoding type, currently, only `json` is supported, will use `encoding/json` package.

## XLSX Field Config | 字段的解析配置

Sometimes it’s a bit cumbersome to deal with escape characters (exp. #6), so implement the interface of `GetXLSXFieldConfigs() map[string]FieldConfig` will take a high priority than `tag` to provide the field config, more info to see the test file.

## RoadMap | 开发计划

+ Read xlsx file and got the expect xml. √
+ Prepare the shared string xml. √
+ Get the correct sheetX.xml. √
+ Read a row of a sheet. √
+ Read a cell of a row, fix the empty cell. √
+ Fill string cell with value of shared string xml. √
+ Can set the column name row, default is the first row. √
+ Read a row into a slice. √
+ Read a row to a struct by column name. √
+ Read a row into a map with string key. √
+ Read a row into a map by primary key.

## Thinking | 随想

在复杂的系统中（例如游戏）

有时候为了便于非专业人员设置一些配置

会使用Excel作为一种轻量级的关系数据库或者配置文件

毕竟对于很多非开发人员来说

配个Excel要比写json或者yaml什么简单得多

这种场景下

读取特定格式（符合关系数据库特点的表格）的数据会比各种花式写入Excel的功能更重要

毕竟从编辑上来说微软提供的Excel本身功能就非常强大了

而现在我找到的Excel库的功能都过于强大了

用起来有点浪费

于是写了这个简化库

这个库的工作参考了[tealeg/xlsx](https://github.com/tealeg/xlsx)的部分实现和读取逻辑。

感谢[tealeg](https://github.com/tealeg)


go-excel

Library to simplify reading the XML format used by recent version of Microsoft Excel in Go programs

xlsx

Fast and safe way to read/update your existing Microsoft Excel files in Go programs

# Xlsx2Go
[![Build Status](https://travis-ci.org/plandem/xlsx.svg?branch=master)](https://travis-ci.org/plandem/xlsx)
[![Code Coverage](https://codecov.io/gh/plandem/xlsx/branch/master/graph/badge.svg)](https://codecov.io/gh/plandem/xlsx) 
[![Go Report Card](https://goreportcard.com/badge/github.com/plandem/xlsx)](https://goreportcard.com/report/github.com/plandem/xlsx)
[![GoDoc](https://godoc.org/github.com/plandem/xlsx?status.svg)](https://godoc.org/github.com/plandem/xlsx)
[![License](http://img.shields.io/badge/license-MIT-red.svg?style=flat)](https://raw.githubusercontent.com/plandem/xlsx/master/LICENSE) 
[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fplandem%2Fxlsx.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fplandem%2Fxlsx?ref=badge_shield)
[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.me/gayvoronsky)

```go
package main

import (
	"github.com/plandem/xlsx"
	"github.com/plandem/xlsx/format/conditional"
	"github.com/plandem/xlsx/format/conditional/rule"
	"github.com/plandem/xlsx/format/styles"
)

func main() {
	xl := xlsx.New()
	defer xl.Close()

	//create a new sheet
	sheet := xl.AddSheet("The first sheet")

	//access by ref
	cell := sheet.CellByRef("A2")

	//set value
	cell.SetValue("Easy Peasy")

	//set cool styles
	cell.SetStyles(styles.New(
		styles.Font.Bold,
		styles.Font.Color("#ff0000"),
		styles.Fill.Type(styles.PatternTypeSolid),
		styles.Fill.Color("#ffff00"),
		styles.Border.Color("#009000"),
		styles.Border.Type(styles.BorderStyleMedium),
	))

	//add comment
	cell.SetComment("No Comment!")

	//add hyperlink
	sheet.CellByRef("A4").SetValueWithHyperlink("wikipedia", "http://google.com")

	//merge cells
	sheet.RangeByRef("A6:A7").Merge()
	sheet.CellByRef("A6").SetValue("merged cell")

	//iterating
	for iRow := 1; iRow < 7; iRow++ {
		//access by indexes
		cell := sheet.Cell(1, iRow)
		cell.SetValue(iRow)
	}

	//add conditional formatting
	sheet.AddConditional(conditional.New(
		conditional.AddRule(
			rule.Value.Between(1, 3, styles.New(
				styles.Font.Bold,
				styles.Font.Color("#ff0000"),
			)),
		),
		conditional.AddRule(
			rule.IconSet.Type(rule.IconSetType3Arrows),
		),
	), "B2:B7")

	xl.SaveAs("./foo.xlsx")
}
```

## Documentation
* [Guide](https://plandem.github.io/xlsx/)
* [API Documentation](https://godoc.org/github.com/plandem/xlsx)
* [Benchmarks](https://github.com/plandem/xlsx-benchmarks)

# Roadmap
- [ ] sheet: copy
- [ ] sheet: custom filters
- [x] sheet: streaming
- [x] merged cells: merge/split for ranges, cols, rows
- [x] hyperlinks: for cells, ranges, cols, rows
- [x] range: copy
- [x] row: copy
- [x] col: copy
- [x] cell: comments
- [ ] cell: formulas
- [x] cell: typed getter/setter for values
- [x] other: conditional formatting
- [x] other: rich texts
- [ ] other: drawing
- [ ] other: more optimization
- [ ] other: more tests

# Contribution 
- To prevent mess, sources have strict separation of markup and functionality. Document that describes OOXML is quite huge (about 6K pages), but the same time - functionality is not.
- All markup resides inside of 'ml' folders, only marshal/unmarshal is allowed here, no any functionality.
- Not every 'ml object' has related 'functional object' and vice versa.
- If you want some functionality, then wrap 'ml object' and do what you want.

### OOXML edition
XML is compliant with part 1 of the [5th edition](http://www.ecma-international.org/publications/standards/Ecma-376.htm) of the ECMA-376 Standard for Office Open XML

## License
[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fplandem%2Fxlsx.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fplandem%2Fxlsx?ref=badge_large)

Virtually traverse Excel cell by cell's name

# Cell Walker

[![codecov](https://codecov.io/github/chonla/cellwalker/graph/badge.svg?token=N2WFUOD9OB)](https://codecov.io/github/chonla/cellwalker) [![Go Report Card](https://goreportcard.com/badge/github.com/chonla/cellwalker)](https://goreportcard.com/report/github.com/chonla/cellwalker) [![Go Reference](https://pkg.go.dev/badge/github.com/chonla/cellwalker.svg)](https://pkg.go.dev/github.com/chonla/cellwalker)

Cell Walker is a go package for virtually traversing Excel cell by cell's name. The package does not actually traverse into a real Excel file.

## Example

```go
package main

import (
	"fmt"

	"github.com/chonla/cellwalker"
)

func main() {
	// Walk from a cell to other cell
	fmt.Println(cellwalker.At("B3").Right().Below().String()) // C4

	// Jump from a cell to other cell
	fmt.Println(cellwalker.At("C2").ColumnOffset(5).RowOffset(10).String()) // H12

	// Too far jump from a cell to other cell will hit the limit of boundary
	fmt.Println(cellwalker.At("ZZZ2").ColumnOffset(5).RowOffset(10).String()) // XFD12

	// Range walking apply other boundary to walker
	fmt.Println(cellwalker.Within("C2:H3").At("C3").Right().Below().String()) // D3

	// Too far jump in a new boundary
	fmt.Println(cellwalker.Within("C2:H3").At("ZZZ2").ColumnOffset(5).RowOffset(10).String()) // XFD12

	// Range traversal
	result1 := cellwalker.Within("B3:E5").At("C4") // Define range and initial cell position
	fmt.Println(result1.String()) // C4
	result2 := result1.Tour()
	fmt.Println(result2.String()) // D4
	result3 := result2.Tour()
	fmt.Println(result3.String()) // E4
	result4 := result3.Tour()
	fmt.Println(result4.String()) // B5
	result5 := result4.Tour()
	fmt.Println(result5.String()) // C5
	result6 := result5.Tour()
	fmt.Println(result6.String()) // D5
	result7 := result6.Tour()
	fmt.Println(result7.String()) // E5
	result8 := result7.Tour()
	fmt.Println(result8 == nil) // true
}
```

## License

[MIT](LICENSE)

The Best Go Libraries For Microsoft Office - Microsoft Excel (6)

exl

excelize

go-excel

xlsx

xlsx

cellwalker