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


Pure go library for creating and processing Office Word (.docx), Excel (.xlsx) and Powerpoint (.pptx) documents

**unioffice** is a library for creation of Office Open XML documents (.docx, .xlsx
and .pptx).  Its goal is to be the most compatible and highest performance Go
library for creation and editing of docx/xlsx/pptx files.

[![Build Status](https://travis-ci.org/unidoc/unioffice.svg?branch=master)](https://travis-ci.org/unidoc/unioffice)
[![GitHub (pre-)release](https://img.shields.io/github/release/unidoc/unioffice/all.svg)](https://github.com/unidoc/unioffice/releases)
[![License: UniDoc EULA](https://img.shields.io/badge/license-UniDoc%20EULA-blue)](https://unidoc.io/eula/)
[![ApiDocs](https://img.shields.io/badge/godoc-reference-blue.svg)](https://apidocs.unidoc.io/unioffice/latest/)


![https://github.com/unidoc/unioffice/](./.github/preview.png "unioffice")

## Status ##

- Documents (docx) [Word]
	- Read/Write/Edit
	- Formatting
	- Images
	- Tables
	- Word to PDF (docx to pdf)
- Spreadsheets (xlsx) [Excel]
 	- Read/Write/Edit
 	- Cell formatting including conditional formatting
	- Cell validation (drop down combobox, rules, etc.)
    - Retrieve cell values as formatted by Excel (e.g. retrieve a date or number as displayed in Excel)
 	- Formula Evaluation (100+ functions supported currently, more will be added as required)
 	- Embedded Images
 	- All chart types
- PowerPoint (pptx) [PowerPoint]
	- Creation from templates
	- Textboxes/shapes


## Performance ##

There has been a great deal of interest in performance numbers for spreadsheet
creation/reading lately, so here are unioffice numbers for this
[benchmark](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/lots-of-rows)
which creates a sheet with 30k rows, each with 100 columns.

    creating 30000 rows * 100 cells took 3.92506863s
    saving took 89ns
    reading took 9.522383048s

Creation is fairly fast, saving is very quick due to no reflection usage, and
reading is a bit slower. The downside is that the binary is large (33MB) as it
contains generated structs, serialization and deserialization code for all of
DOCX/XLSX/PPTX.

## Installation ##
    
    go get github.com/unidoc/unioffice/v2

## License key
This software package (unioffice) is a commercial product and requires a license code to operate.

To Get a Metered License API Key in the Free Tier, sign up on https://cloud.unidoc.io

## Document Examples ##

- [Simple Text Formatting](https://github.com/unidoc/unioffice-examples/tree/master/document/simple) Text font colors, sizes, highlighting, etc.
- [Auto Generated Table of Contents](https://github.com/unidoc/unioffice-examples/tree/master/document/toc) Creating document headings with an auto generated TOC based off of the headingds
- [Floating Image](https://github.com/unidoc/unioffice-examples/tree/master/document/image) Placing an image somewhere on a page, absolutely positioned with different text wrapping.
- [Header & Footer](https://github.com/unidoc/unioffice-examples/tree/master/document/header-footer) Creating headers and footers including page numbering.
- [Multiple Headers & Footers](https://github.com/unidoc/unioffice-examples/tree/master/document/header-footer-multiple) Using different headers and footers depending on document section.
- [Inline Tables](https://github.com/unidoc/unioffice-examples/tree/master/document/tables) Adding an table with and without borders.
- [Using Existing Word Document as a Template](https://github.com/unidoc/unioffice-examples/tree/master/document/use-template) Opening a document as a template to re-use the styles created in the document.
- [Filling out Form Fields](https://github.com/unidoc/unioffice-examples/tree/master/document/fill-out-form) Opening a document with embedded form fields, filling out the fields and saving the result as  a new filled form.
- [Editing an existing document](https://github.com/unidoc/unioffice-examples/tree/master/document/edit-document) Open an existing document and replace/remove text without modifying formatting.

## Spreadsheet Examples ##
- [Simple](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/simple) A simple sheet with a few cells
- [Named Cells](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/named-cells) Different ways of referencing rows and cells
- [Cell Number/Date/Time Formats](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/number-date-time-formats) Creating cells with various number/date/time formats
- [Line Chart](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/line-chart)/[Line Chart 3D](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/line-chart-3d) Line Charts
- [Bar Chart](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/bar-chart) Bar Charts
- [Mutiple Charts](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/multiple-charts) Multiple charts on a single sheet
- [Named Cell Ranges](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/named-ranges) Naming cell ranges
- [Merged Cells](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/merged) Merge and unmerge cells
- [Conditional Formatting](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/conditional-formatting) Conditionally formatting cells, styling, gradients, icons, data bar
- [Complex](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/complex) Multiple charts, auto filtering and conditional formatting
- [Borders](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/borders) Individual cell borders and rectangular borders around a range of cells.
- [Validation](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/validation) Data validation including combo box dropdowns.
- [Frozen Rows/Cols](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/freeze-rows-cols) A sheet with a frozen header column and row

## Presentation Examples ##

- [Simple Text Boxes](https://github.com/unidoc/unioffice-examples/tree/master/presentation/simple) Simple text boxes and shapes
- [Images](https://github.com/unidoc/unioffice-examples/tree/master/presentation/image) Simple image insertion
- [Template](https://github.com/unidoc/unioffice-examples/tree/master/presentation/use-template/simple) Creating a presentation from a template

## Raw Types ##

The OOXML specification is large and creating a friendly API to cover the entire
specification is a very time consuming endeavor.  This library attempts to
provide an easy to use API for common use cases in creating OOXML documents
while allowing users to fall back to raw document manipulation should the
library's API not cover a specific use case.

The raw XML based types reside in the ```schema/``` directory. These types are
accessible from the wrapper types via a ```X()``` method that returns the raw
type. 

For example, the library currently doesn't have an API for setting a document
background color. However it's easy to do manually via editing the
```CT_Background``` element of the document.

    doc := document.New()
    doc.X().Background = wordprocessingml.NewCT_Background()
	doc.X().Background.ColorAttr = &wordprocessingml.ST_HexColor{}
	doc.X().Background.ColorAttr.ST_HexColorRGB = color.RGB(50, 50, 50).AsRGBString()

## Contribution guidelines ###

If you are interested in contributing, please contact us.

## Development Notes

The bash script file `run_test.sh` could be used to run test and update the test result (if required). This script could receive the following parameter:
- `-s`: Save a baseline, updates all the test result.
- `-v`: Run the test in verbose mode.
- `t` or `--testname` [test name]: Run a specific test name. For example `-t AddImage` would be running a `TestAddImage` test.

To run the script in dockerized environment, use the provided `Makefile` such as:

```bash
make docker-test
```
or

```bash
make docker-update-testdata
```

## Go Version Compatibility

Officially we support three latest Go versions.

## Support and consulting ##

Please email us at support@unidoc.io for any queries.

If you have any specific tasks that need to be done, we offer consulting in certain cases.
Please contact us with a brief summary of what you need and we will get back to you with a quote, if appropriate.

## License agreement ##

The use of this software package is governed by the end-user license agreement 
(EULA) available at: https://unidoc.io/eula/



unioffice

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)

Library for reading and writing Microsoft Word (Docx) files

# Godocx

[![Go CI](https://github.com/gomutex/godocx/actions/workflows/go.yml/badge.svg)](https://github.com/gomutex/godocx/actions/workflows/go.yml) ![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/gomutex/godocx) [![Go Reference](https://pkg.go.dev/badge/github.com/gomutex/godocx.svg)](https://pkg.go.dev/github.com/gomutex/godocx)
 [![Go Report Card](https://goreportcard.com/badge/github.com/gomutex/godocx)](https://goreportcard.com/report/github.com/gomutex/godocx) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)


<img width="650" src="./godocx.png" alt="Godocx logo">


Godocx is a library written in pure Go providing a set of functions that allow you to write to and read from Docx file. 

This library needs Go version 1.18 or later. The usage documentation for the godocx can be accessed via the [Godocx Documentation Page](https://gomutex.github.io/godocx). 

In depth, go docs can be seen using go's built-in documentation tool, or online at [go.dev](https://pkg.go.dev/github.com/gomutex/godocx). Please refer the [subpackage docx](https://pkg.go.dev/github.com/gomutex/godocx/docx) for the list of functions that can be used.


## Usage
Here's a simple example of how you can use Godocx to create and modify DOCX documents:

## Installation
Use the godocx in your project
```bash
go get github.com/gomutex/godocx
```


### Examples
Explore additional examples and use cases over at GitHub repository dedicated to showcasing the capabilities of Golang Docx:
https://github.com/gomutex/godocx-examples


```go
// More examples in separate repository
// https://github.com/gomutex/godocx-examples

package main

import (
	"log"

	"github.com/gomutex/godocx"
)

func main() {
		// Open an existing DOCX document
	// document, err := godocx.OpenDocument("./testdata/test.docx")

	// Create New Document
	document, err := godocx.NewDocument()
	if err != nil {
		log.Fatal(err)
	}

	document.AddHeading("Document Title", 0)

	// Add a new paragraph to the document
	p := document.AddParagraph("A plain paragraph having some ")
	p.AddText("bold").Bold(true)
	p.AddText(" and some ")
	p.AddText("italic.").Italic(true)

	document.AddHeading("Heading, level 1", 1)
	document.AddParagraph("Intense quote").Style("Intense Quote")
	document.AddParagraph("first item in unordered list").Style("List Bullet")
	document.AddParagraph("first item in ordered list").Style("List Number")

	records := []struct{ Qty, ID, Desc string }{{"5", "A001", "Laptop"}, {"10", "B202", "Smartphone"}, {"2", "E505", "Smartwatch"}}

	table := document.AddTable()
	table.Style("LightList-Accent4")
	hdrRow := table.AddRow()
	hdrRow.AddCell().AddParagraph("Qty")
	hdrRow.AddCell().AddParagraph("ID")
	hdrRow.AddCell().AddParagraph("Description")

	for _, record := range records {
		row := table.AddRow()
		row.AddCell().AddParagraph(record.Qty)
		row.AddCell().AddParagraph(record.ID)
		row.AddCell().AddParagraph(record.Desc)
	}

	// Save the modified document to a new file
	err = document.SaveTo("demo.docx")
	if err != nil {
		log.Fatal(err)
	}
}
```

## Demo Output

This is screenshot of demo document generated from the godocx library. 

![Screenshot of the demo output](https://github.com/gomutex/godocx-examples/raw/main/demo.png)


## Feature addtion request

If you need a feature that's missing in godocx, feel free to raise an issue describing what you want to achieve, along with a sample DOCX. While I can't promise immediate implementation, I'll review your request and work on it if it's valid.


## Inspiration
The Godocx library is inspired from the python-docx

## Licenses

The Godocx library is licensed under the [MIT License](https://opensource.org/licenses/MIT).

godocx

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 (8)

exl

unioffice

excelize

go-excel

xlsx

xlsx

godocx

cellwalker