decxls

README

Decode XLS to Go struct

decxls is a module designed to assist in the decoding of xls based spreadsheets into go slice * structs. Based upon the initial work w/ CSV parsing from [https://github.com/gocarina/gocsv] wrapping the excel reader from [https://github.com/360EntSecGroup-Skylar/excelize].

Finding that too frequently, we are pulling everything from dictionaries to data, we used basic encoding styled libraries with struct tags "xls:" to map header rows to structs.

This module supports embedded structs and pointers as well as typical "unmarshalling" methodes TypeXLSUnmarshall to allow non-native type treatment for underlying data.

Installation

shift to directory...

Basic Spreadsheets

in the test directory, there is an Excel spreadsheet used by the go test functions. The spreadsheet has two sheets and a small number of rows and columns. By and large, Sheet1 and 2 are the same, but using out of order headers on the second sheet to test tag<->field mapping.

Unmarshalling with GoLang

There is an example of Unmarshalling in the xls_test.go file to show the basics.

import (
	"fmt"
	"github/dhushon/decxls"
)

type Test1 struct {
	Header1 string `xls:"Header 1"`
	Header2 int `xls:"Header 2"`
	Header3 CustomFloatUnmarshal `xls:"Header 3"`
}

type CustomFloatUnmarshal struct {
	Value string
	Percent float64
}

func (c *CustomFloatUnmarshal)UnmarshalXLS(value string) error {
	c.Value = value
	f , err := toFloat(value)
	if err != nil {
		return err
	}
	c.Percent = f
	return nil
}

const simplefile = "./test/Test1.xlsx"
const sheet = "Sheet 2"

type test1 []*Test1

func (tests test1) String() string {
    s := "["
    for i, test := range tests {
        if i > 0 {
            s += ", "
        }
        s += fmt.Sprintf("%v", test)
    }
    return s + "]"
}

func main {
	ts := test1{}
	err := UnmarshalFile(simplefile,sheet,&ts))
	fmt.Printf("Filename based, sheet selection %s test: %v\n",sheet,ts)
}

Documentation

Index

• Variables
• func SetHeaderNormalizer(f Normalizer)
• func SetXLSReader(xlsReader func(io.Reader) XLSReader)
• func UnmarshalExcelize(f *excelize.File, sheet string, out interface{}) error
• func UnmarshalFile(filename string, sheetName string, out interface{}) error
• type Decoder
• type ErrorHandler
• type NoUnmarshalFuncError
  • func (e NoUnmarshalFuncError) Error() string
• type Normalizer
  • func DefaultNameNormalizer() Normalizer
• type ParseError
  • func (e *ParseError) Error() string
  • func (e *ParseError) Unwrap() error
• type SimpleDecoder
• type TypeUnmarshalXLSWithFields
• type TypeUnmarshaller
• type XLSReader
  • func DefaultXLSReader(in io.Reader) XLSReader

Variables

var (
	//ErrEmptyFile is an error type
	ErrEmptyFile = errors.New("empty xls file given")
	//ErrNoStructTags error type if no tags are found
	ErrNoStructTags = errors.New("no xls struct tags found")
)

var (
	ErrQuote      = errors.New("extraneous or missing \" in quoted-field")
	ErrFieldCount = errors.New("wrong number of fields")
)

These are the errors that can be returned in ParseError.Err.

var FailIfDoubleHeaderNames = false

FailIfDoubleHeaderNames indicates whether it is considered an error when a header name is repeated in the xls header.

var FailIfUnmatchedStructTags = false

FailIfUnmatchedStructTags indicates whether it is considered an error when there is an unmatched struct tag.

var ShouldAlignDuplicateHeadersWithStructFieldOrder = false

ShouldAlignDuplicateHeadersWithStructFieldOrder indicates whether we should align duplicate XLS headers per their alignment in the struct definition.

var TagName = "xls"

TagName defines key in the struct field's tag to scan

var TagSeparator = ","

TagSeparator defines seperator string for multiple xls tags in struct fields

var UseColumnHeader = true

UseColumnHeader suggests that we try and pull the column name (row 0 in excelize) vs. row 1 in excellize = first visible row

Functions

func SetHeaderNormalizer

func SetHeaderNormalizer(f Normalizer)

SetHeaderNormalizer sets the normalizer used to normalize struct and header field names.

func SetXLSReader

func SetXLSReader(xlsReader func(io.Reader) XLSReader)

SetXLSReader sets the XLS reader used to parse XLS.

func UnmarshalExcelize

func UnmarshalExcelize(f *excelize.File, sheet string, out interface{}) error

UnmarshalExcelize will take an excelize opened XML file and marshal to an interface

func UnmarshalFile

func UnmarshalFile(filename string, sheetName string, out interface{}) error

UnmarshalFile parses the XLS from the file in the interface.

Types

type Decoder

type Decoder interface {
	// contains filtered or unexported methods
}

Decoder interface

type ErrorHandler

type ErrorHandler func(*ParseError) bool

ErrorHandler -

type NoUnmarshalFuncError

type NoUnmarshalFuncError struct {
	// contains filtered or unexported fields
}

NoUnmarshalFuncError is the custom error type to be raised in case there is no unmarshal function defined on type

func (NoUnmarshalFuncError) Error

func (e NoUnmarshalFuncError) Error() string

type Normalizer

type Normalizer func(string) string

Normalizer is a function that takes and returns a string. It is applied to struct and header field values before they are compared. It can be used to alter names for comparison. For instance, you could allow case insensitive matching or convert '-' to '_'.

func DefaultNameNormalizer

func DefaultNameNormalizer() Normalizer

DefaultNameNormalizer is a nop Normalizer.

type ParseError

type ParseError struct {
	StartLine int   // Line where the record starts
	Line      int   // Line where the error occurred
	Column    int   // Column (rune index) where the error occurred
	Err       error // The actual error
}

A ParseError is returned for parsing errors. Line numbers are 1-indexed and columns are 0-indexed.

func (*ParseError) Error

func (e *ParseError) Error() string

func (*ParseError) Unwrap

func (e *ParseError) Unwrap() error

type SimpleDecoder

type SimpleDecoder interface {
	// contains filtered or unexported methods
}

SimpleDecoder interface

type TypeUnmarshalXLSWithFields

type TypeUnmarshalXLSWithFields interface {
	UnmarshalXLSWithFields(key, value string) error
}

TypeUnmarshalXLSWithFields can be implemented on whole structs to allow for whole structures to customized internal vs one off fields

type TypeUnmarshaller

type TypeUnmarshaller interface {
	UnmarshalXLS(string) error
}

TypeUnmarshaller is implemented by any value that has an UnmarshalXLS method This converter is used to convert a string to your value representation of that string

type XLSReader

type XLSReader interface {
	Read() ([]string, error)
	ReadAll() ([][]string, error)
}

XLSReader interface

func DefaultXLSReader

func DefaultXLSReader(in io.Reader) XLSReader

DefaultXLSReader is the default XLS reader used to parse XLS (cf. xls.NewReader)