excelstruct

README

Excel Go binding struct

excelstruct is a comprehensive Go package that simplifies working with Excel files by allowing you to easily encode and decode structs example. Built on top of the powerful excelize library, it offers a solution for dealing with excel data in a structured and type-safe manner.

Features

• Type Safety: Work directly with Go structs, leveraging Go's type system
• Custom Type Support: Easily handle custom types with marshaler and unmarshaler interfaces
• Slice and Array Support: Encode and decode slices and arrays seamlessly
• Flexible Type Conversion: Built-in type conversion options eliminate the need for custom types in many cases
• Style Support: Apply Excel styles
• Data validation: Add data validation and column oriented helping for sqref

Installation

Go version 1.22+

go get github.com/itcomusic/excelstruct

License

MIT License

Documentation

Overview

Package excelstruct provides a reading and writing XLSX files using structs.

Index

• Constants
• Variables
• type ConvertValueError
  • func (e *ConvertValueError) Error() string
• type DataValidation
• type Decoder
  • func NewDecoder[T any](r *Read, opts DecoderOptions) (*Decoder[T], error)
  • func (c *Decoder[T]) All(res *[]T) error
  • func (c *Decoder[T]) Close()
  • func (c *Decoder[T]) Count() int
  • func (c *Decoder[T]) Decode(res *T) error
  • func (c *Decoder[T]) Next() bool
• type DecoderOptions
• type Encoder
  • func NewEncoder[T any](w *Write, opts EncoderOptions) (*Encoder[T], error)
  • func (e *Encoder[T]) All(v []T) error
  • func (e *Encoder[T]) Close() (err error)
  • func (e *Encoder[T]) Encode(v *T) error
  • func (e *Encoder[T]) SqrefRow(title string) (string, error)
• type EncoderOptions
• type InvalidUnmarshalError
  • func (e *InvalidUnmarshalError) Error() string
• type MarshalerError
  • func (e *MarshalerError) Error() string
  • func (e *MarshalerError) Unwrap() error
• type NameStyle
• type OpenFileOptions
• type Orientation
• type Read
  • func OpenFile(o OpenFileOptions) (*Read, error)
  • func (r *Read) Close()
• type ReadBoolConv
• type ReadStringConv
• type ReadTimeConv
• type ScaleAutoWidth
• type TitleConv
• type TitleMaxWidth
• type UnmarshalError
  • func (e *UnmarshalError) AsConvertValueError() []ConvertValueError
  • func (e *UnmarshalError) AsTypeError() []UnmarshalTypeError
  • func (e *UnmarshalError) Error() string
• type UnmarshalTypeError
  • func (e *UnmarshalTypeError) Error() string
• type UnsupportedTypeError
  • func (e *UnsupportedTypeError) Error() string
• type ValueMarshaler
• type ValueUnmarshaler
• type Write
  • func WriteFile(opts WriteFileOptions) (*Write, error)
  • func (w *Write) Close() error
• type WriteBoolConv
• type WriteFileOptions
• type WriteStringConv

Constants

const DefaultSheetName = "Sheet1"

Variables

var DefaultScaleAutoWidth = ScaleAutoWidth(func(len int) float64 {
	return float64(len) + 2.0
})

DefaultScaleAutoWidth is the scale function for default font size.

PR: https://github.com/qax-os/excelize/pull/1386

Types

type ConvertValueError

type ConvertValueError struct {
	Value string
	Field string
	Err   error
}

An ConvertValueError describes a value that was cannot convert to a specific user value.

func (*ConvertValueError) Error

func (e *ConvertValueError) Error() string

type DataValidation

type DataValidation func(title string) (*excelize.DataValidation, error)

DataValidation is the function to set in cell data validation.

type Decoder

type Decoder[T any] struct {
	*excelize.File
	// contains filtered or unexported fields
}

Decoder is a workspace for reading data from a file.

func NewDecoder

func NewDecoder[T any](r *Read, opts DecoderOptions) (*Decoder[T], error)

NewDecoder creates a decoder with the specified titles and struct.

func (*Decoder[T]) All

func (c *Decoder[T]) All(res *[]T) error

All decodes all rows to the struct.

func (*Decoder[T]) Close

func (c *Decoder[T]) Close()

Close closes the cursor.

func (*Decoder[T]) Count

func (c *Decoder[T]) Count() int

Count returns the number of rows.

func (*Decoder[T]) Decode

func (c *Decoder[T]) Decode(res *T) error

Decode decodes the row to the struct.

func (*Decoder[T]) Next

func (c *Decoder[T]) Next() bool

Next moves the cursor to the next row.

type DecoderOptions

type DecoderOptions struct {
	SheetName     string
	TitleRowIndex int
	TitleConv     TitleConv
	StringConv    ReadStringConv
	BoolConv      ReadBoolConv
	TimeConv      ReadTimeConv
	StructTag     string
}

DecoderOptions is the options for read workspace.

type Encoder

type Encoder[T any] struct {
	*excelize.File
	// contains filtered or unexported fields
}

Encoder is a writing data to a file.

func NewEncoder

func NewEncoder[T any](w *Write, opts EncoderOptions) (*Encoder[T], error)

NewEncoder creates encoder the specified titles and struct.

func (*Encoder[T]) All

func (e *Encoder[T]) All(v []T) error

All writes all values to file.

func (*Encoder[T]) Close

func (e *Encoder[T]) Close() (err error)

Close applies the style and data validation.

func (*Encoder[T]) Encode

func (e *Encoder[T]) Encode(v *T) error

Encode writes v to file.

func (*Encoder[T]) SqrefRow

func (e *Encoder[T]) SqrefRow(title string) (string, error)

SqrefRow returns the range of the row by title.

type EncoderOptions

type EncoderOptions struct {
	SheetName             string
	TitleRowIndex         int
	TitleName             []string
	DisallowUnknownFields bool
	TitleConv             TitleConv
	TitleMaxWidth         TitleMaxWidth
	TitleScaleAutoWidth   ScaleAutoWidth
	DataValidation        DataValidation
	ValidationOverRow     int
	StringConv            WriteStringConv
	BoolConv              WriteBoolConv
	Orientation           Orientation

	CellNumFmt  map[excelize.CellType]int
	TitleNumFmt map[string]int

	CellStyle  *excelize.Style
	Style      NameStyle
	TitleStyle map[string]string // map[title]style
}

EncoderOptions is the options for write workspace.

type InvalidUnmarshalError

type InvalidUnmarshalError struct {
	Type reflect.Type
}

An InvalidUnmarshalError describes an invalid argument passed to Unmarshal. (The argument to Unmarshal must be a non-nil pointer.)

func (*InvalidUnmarshalError) Error

func (e *InvalidUnmarshalError) Error() string

type MarshalerError

type MarshalerError struct {
	Type reflect.Type
	Err  error
	// contains filtered or unexported fields
}

A MarshalerError represents an error from calling a MarshalXLSXValue.

func (*MarshalerError) Error

func (e *MarshalerError) Error() string

func (*MarshalerError) Unwrap

func (e *MarshalerError) Unwrap() error

Unwrap returns the underlying error.

type NameStyle

type NameStyle map[string]excelize.Style

NameStyle is the naming style to quick search style.

type OpenFileOptions

type OpenFileOptions struct {
	FilePath string
	Style    NameStyle
	Excel    *excelize.Options
}

OpenFileOptions is the options for open file.

type Orientation

type Orientation string

const (
	OrientationRow    Orientation = "row"
	OrientationColumn Orientation = "col"
)

type Read

type Read struct {
	*excelize.File
}

func OpenFile

func OpenFile(o OpenFileOptions) (*Read, error)

OpenFile opens a xlsx file.

func (*Read) Close

func (r *Read) Close()

Close closes the file.

type ReadBoolConv

type ReadBoolConv func(title string, v string) (bool, error)

ReadBoolConv is the function to convert value to bool.

type ReadStringConv

type ReadStringConv func(title string, v string) (string, error)

ReadStringConv is the function to convert value to string.

type ReadTimeConv

type ReadTimeConv func(v string) (time.Time, error)

ReadTimeConv is the function to convert value to time.Time.

type ScaleAutoWidth

type ScaleAutoWidth func(len int) float64

ScaleAutoWidth is a scale function for auto width.

type TitleConv

type TitleConv func(title string) string

TitleConv is the function to convert title name.

type TitleMaxWidth

type TitleMaxWidth func(title string) float64

TitleMaxWidth is the function to set in cell max width. (0 - disable, -1 - no limit).

type UnmarshalError

type UnmarshalError struct {
	Row int
	Err []error
}

An UnmarshalError describes an error that was occurred during unmarshal.

func (*UnmarshalError) AsConvertValueError

func (e *UnmarshalError) AsConvertValueError() []ConvertValueError

AsConvertValueError returns the all ConvertValueError in UnmarshalError.

func (*UnmarshalError) AsTypeError

func (e *UnmarshalError) AsTypeError() []UnmarshalTypeError

AsTypeError returns the all UnmarshalTypeError in UnmarshalError.

func (*UnmarshalError) Error

func (e *UnmarshalError) Error() string

Error returns the all error in UnmarshalError.

type UnmarshalTypeError

type UnmarshalTypeError struct {
	Value string       // description of string value - "bool", "array", "number -5"
	Type  reflect.Type // type of Go value it could not be assigned to
	Field string       // the full path from root node to the field
	Err   error        // the error returns convert function string to type
}

An UnmarshalTypeError describes a EXCEL value that was not appropriate for a value of a specific Go type.

func (*UnmarshalTypeError) Error

func (e *UnmarshalTypeError) Error() string

type UnsupportedTypeError

type UnsupportedTypeError struct {
	Type reflect.Type
}

An UnsupportedTypeError is returned by Marshal when attempting to encode an unsupported value type.

func (*UnsupportedTypeError) Error

func (e *UnsupportedTypeError) Error() string

type ValueMarshaler

type ValueMarshaler interface {
	MarshalXLSXValue() ([]string, error)
}

ValueMarshaler is the interface implemented by an object that can marshal value itself into a string form.

type ValueUnmarshaler

type ValueUnmarshaler interface {
	UnmarshalXLSXValue(value []string) error
}

ValueUnmarshaler is the interface implemented by an object that can unmarshal value a string representation of itself.

type Write

type Write struct {
	*excelize.File
	// contains filtered or unexported fields
}

func WriteFile

func WriteFile(opts WriteFileOptions) (*Write, error)

WriteFile writes a xlsx file.

func (*Write) Close

func (w *Write) Close() error

Close closes the file.

type WriteBoolConv

type WriteBoolConv func(title string, v bool) (string, error)

WriteBoolConv is the function to convert bool to string.

type WriteFileOptions

type WriteFileOptions struct {
	FilePath  string
	StructTag string
	Excel     *excelize.Options
}

WriteFileOptions is the options for write file.

type WriteStringConv

type WriteStringConv func(title string, v string) (string, error)

WriteStringConv is the function to convert string value.