Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tealeg/xlsx

Go library for reading and writing XLSX files.
https://github.com/tealeg/xlsx

excel go spreadsheet xlsx

Last synced: 3 days ago
JSON representation

Go library for reading and writing XLSX files.

Awesome Lists containing this project

README 

        
* XLSX



[[https://github.com/tealeg/xlsx/actions/workflows/go.yml][https://github.com/tealeg/xlsx/actions/workflows/go.yml/badge.svg?branch=master]]

[[https://codecov.io/gh/tealeg/xlsx][https://codecov.io/gh/tealeg/xlsx/branch/master/graph/badge.svg]]

[[https://pkg.go.dev/github.com/tealeg/xlsx/v3][https://pkg.go.dev/badge/github.com/tealeg/xlsx/v3.svg]]

[[https://github.com/tealeg/xlsx#license][https://img.shields.io/badge/license-bsd-orange.svg]]



** Introduction

xlsx is a library to simplify reading and writing the XML format, used

by versions of Microsoft Excel since 2002, in Go programs.



* Current status

We're back! The will of the people has spoken.  [[https://github.com/tealeg][I]] tried to slowly let

this die, but the patches keep coming in, and people keep expressing

frustration at the alternatives.  So, the fate of this library

lies with you all. [[https://github.com/tealeg][I]] will review patches, make releases, etc.  [[https://github.com/tealeg][I]]

don't plan to take on any new development work here myself, but I will

attempt to support you if you do.



** Tutorial



If you'd like an introduction to this project try the [[https://github.com/tealeg/xlsx/blob/master/tutorial/tutorial.adoc][tutorial]].



** Different versions of this project



*** Prior to v1.0.0



You don't want these versions ;-)



It's hard to remember exactly, but work on this library started within

a month of the first public announcement of Go, now more than a decade

ago.  It was essentially a quick hack to get data out of XLSX files at

my workplace.  Nobody but me relied on it, so it was fine to use this

brand new language for this task. Somewhat later I decided to share

the code, and I know it was well established as an open-source project

by the time I left that job in late 2011.



Although I did do some "release" tags, versioning in Go in the early

days relied on tagging your code with the name of the Go release

(i.e. go1.2) and then `go get` would fetch that tag, if it existed,

and if not, it'd grab the master branch.



*** Version 1.x.x



Version 1.0.0 was tagged in 2017 to support vendoring tools.



As of October 8th, 2019, I've branched off v1.x.x maintenance work

from master.  The master branch now tracks v2.x.x.



If you have existing code, can live with the issues in the 1.x.x

codebase, and don't want to update your code to use a later version,

then you can stick to these releases.  I mostly won't be touching this

code, but if something really important comes up, let me know.



*** Version 2.x.x



Version 2.0.0 introduced breaking changes in the API.



The scope of these changes included the way `Col` elements and

`DataValidation` works, as these aspects have been built around

incorrect models of the underlying XLSX format.



See the [[milestone][https://github.com/tealeg/xlsx/milestone/5]] for details.



Version 2.0.1 was tagged purely because 2.0.0 wasn't handled correctly

with regards to how go modules work. It isn't possible to use 2.0.0

from a Go Modules based project.



*** Version 3.x.x 

Version 3.0.0 introduces some more breaking changes in the API.  All

methods that can return an `xlsx.File` struct now accept zero, one or

many `xlsx.FileOption` functions as their final arguments.  These can

be used to modify the behaviour of the resultant struct - in

particular they replace the `...WithRowLimit` variants of those

methods with the result of calling `xlsx.RowLimit` and they add the

ability to define a custom backing store for the spreadsheet data to

be held in whilst processing.



StreamFileBuilder has been dropped from this version of the library as it has become difficult to maintain. 



** Full API docs

The full API docs can be viewed using go's built in documentation

tool, or online at [[https://pkg.go.dev/github.com/tealeg/xlsx/v3][pkg.go.dev]].



** Contributing



 Please be patient, maintaining XLSX doesn't pay anyone's salary (to my knowledge).



If you'd like to propose a change please ensure the following:



- All existing tests are passing.

- There are tests in the test suite that cover the changes you're making.

- You have added documentation strings (in English) to (at least) the public functions you've added or modified.

- Your use of, or creation of, XML is compliant with [[http://www.ecma-international.org/publications/standards/Ecma-376.htm][part 1 of the 4th edition of the ECMA-376 Standard for Office Open XML]].



Eat a peach - Geoff