gsheets

README

Google Sheets Parser

Google Sheets Parser is a library for dynamically parsing Google Sheets into Golang structs.

Installation

go get github.com/esome/google-sheets-parser

Requirements

This library requires Go >= 1.23 as range over function mechanics are used.

Usage

The Image shows the sheet called "Users" which is contained in the example spreadsheet.

To Parse it, we would utilize following code:

package main

import (
	"fmt"
	"log"
	"time"
	
	"github.com/esome/google-sheets-parser"
	"google.golang.org/api/sheets/v4"
)

// User is a struct that represents a row in the Users Sheet
type User struct {
	ID        uint // <- By default, columns will be parsed into the equally named struct fields.
	Username  string
	Name      string
	Password  *string
	Weight    *uint
	CreatedAt *time.Time `gsheets:"Created At"` // <- Custom Column Name, optional, will be prioritized over the Struct Field Name
}

func main() {
	var svc *sheets.Service // <- You need to create a Google Sheets Service first, see below
	
	users, err := gsheets.ParseSheetIntoStructSlice[User](
		// minimal Config only containing the Google Sheets service (*sheets.Service)
		// Have a look in the example to learn how to create a reusable configuration 
		gsheets.Config{Service: svc},
		// Mandatory! you must define the SpreadsheetID, or an error will be returned
		gsheets.WithSpreadsheetID("15PTbwnLdGJXb4kgLVVBtZ7HbK3QEj-olOxsY7XTzvCc"),
		// Optional: you can pass an arbitrary amount of ConfigOptions for further customization for this call
		gsheets.WithDatetimeFormats( // <- in this case we provide further Datetime Formats to be recognized 
			"2.1.2006",
			"02.01.2006",
			"02.01.2006 15:04:05",
		),
	)
	if err != nil {
		log.Fatalf("Unable to parse page: %v", err)
	}

	// Do anything you want with the result
	fmt.Println(users)
}

Authenticating a Google Sheets Service

There are different ways to authenticate a Google Sheets Service.

Please refer to the Google Sheets Go Quickstart for more information.

Example

To try out the example yourself, check out the example/-Directory.
In there you will find an example that demonstrates how to create a common config for multiple parse calls.

Intention

This library is intended to be used as a library for parsing Google Sheets into Golang structs. It is not intended to be used as a library for generating Google Sheets from Golang structs.

At esome we use Google Sheets in some cases to communicate data with external partners. The data of these sheets sometimes needs to be imported into our data-warehouse. This library helps us to parse the data from the Google Sheets into Golang structs, which then can be written to the databases.

Origin

This library was originally a fork of the awesome work from Tobias Wimmer. All credits go to him for the initial implementation. Please consider checking out his repository as well, and support him.

Since the way the library is configured has changed significantly, we decided to create a complete separate/independent repository for it. This also allows us to maintain the library in a way that fits our needs better, and accept/make contributions that may have been rejected in the original project.

Contributing

Contributions are welcome! Please open an issue or pull request if you have any suggestions or want to contribute.

Documentation

Index

• Variables
• func ParseSheetIntoStructSlice[T any](cfg Config, opts ...ConfigOption) ([]T, error)
• func ParseSheetIntoStructs[T any](cfg Config, opts ...ConfigOption) (iter.Seq2[int, Result[T]], error)
• type Config
  • func MakeConfig(svc *sheets.Service, spreadsheetID string, opts ...ConfigOption) Config
  • func (c *Config) Context() context.Context
• type ConfigOption
  • func WithAllowSkipColumns(allow bool) ConfigOption
  • func WithAllowSkipFields(allow bool) ConfigOption
  • func WithContext(ctx context.Context) ConfigOption
  • func WithDatetimeFormats(formats ...string) ConfigOption
  • func WithSheetName(name string) ConfigOption
  • func WithSpreadsheetID(id string) ConfigOption
  • func WithTagName(name string) ConfigOption
• type ConvertError
  • func (e *ConvertError) Error() string
  • func (e *ConvertError) Unwrap() error
• type InvalidDateTimeFormatError
  • func (e *InvalidDateTimeFormatError) Error() string
• type MappingError
  • func (e *MappingError) Error() string
  • func (e *MappingError) Unwrap() error
• type Result

Variables

var (
	// ErrNoService is returned when no Google API service is registered to the Config.
	ErrNoService = errors.New("gsheets: no Google API service registered")
	// ErrNoSpreadSheetID is returned when no spreadsheet ID is provided to the parse call.
	ErrNoSpreadSheetID = errors.New("gsheets: no spreadsheet id provided")
	// ErrUnsupportedType is returned when the type of field is not supported.
	ErrUnsupportedType = errors.New("gsheets: unsupported type")
	// ErrNoMapping is returned when not a single field mapping is found.
	ErrNoMapping = errors.New("gsheets: no mapping found")
	// ErrFieldNotFoundInSheet is returned when a field is not found in the sheet.
	ErrFieldNotFoundInSheet = errors.New("gsheets: field not found in sheet")
	// ErrFieldNotFoundInStruct is returned when a field/column is not found in the struct.
	ErrFieldNotFoundInStruct = errors.New("gsheets: field not found in struct")
)

Functions

func ParseSheetIntoStructSlice

func ParseSheetIntoStructSlice[T any](cfg Config, opts ...ConfigOption) ([]T, error)

ParseSheetIntoStructSlice parses a sheet page and returns a slice of structs with the give type. If an error occurs, the function will immediately return it.

func ParseSheetIntoStructs

func ParseSheetIntoStructs[T any](cfg Config, opts ...ConfigOption) (iter.Seq2[int, Result[T]], error)

ParseSheetIntoStructs parses a sheet page and returns an iterator over the parsing Result. If an error occurs during validation or when fetching data, the function will return it. Parsing errors are returned as part of the Result, and can therefore be handled by the caller. The iterator will still proceed to the next row, if it isn't stopped.

Types

type Config

type Config struct {
	Service *sheets.Service
	// contains filtered or unexported fields
}

Config holds the configuration for the Google Sheets parser.

func MakeConfig

func MakeConfig(svc *sheets.Service, spreadsheetID string, opts ...ConfigOption) Config

MakeConfig creates a new Config with the given Google Sheets service and arbitrary options.

func (*Config) Context

func (c *Config) Context() context.Context

Context returns the configured context, or creates a new background context

type ConfigOption

type ConfigOption func(*config)

ConfigOption is a function allows to modify a Config.

func WithAllowSkipColumns

func WithAllowSkipColumns(allow bool) ConfigOption

WithAllowSkipColumns allows to skip columns that cannot be mapped to a struct field. If this is set to false, an error will be raised.

func WithAllowSkipFields

func WithAllowSkipFields(allow bool) ConfigOption

WithAllowSkipFields allows to skip fields that are not found in the sheet. If this is set to false, an error will be raised.

func WithContext

func WithContext(ctx context.Context) ConfigOption

WithContext sets the given context for the Config. This context will be used for all API calls, and cancellation will be respected during iteration.

func WithDatetimeFormats

func WithDatetimeFormats(formats ...string) ConfigOption

WithDatetimeFormats allows to define additional date-time formats to be recognized during the parsing.

func WithSheetName

func WithSheetName(name string) ConfigOption

WithSheetName sets the sheet-name for the Config.

func WithSpreadsheetID

func WithSpreadsheetID(id string) ConfigOption

WithSpreadsheetID sets the spreadsheet ID for the Config.

func WithTagName

func WithTagName(name string) ConfigOption

WithTagName sets the tag-name to be looked at in the structs. This might come in handy if you have multiple structs with different tags, or another library also uses `gsheets:` as tag identifier.

type ConvertError

type ConvertError struct {
	Typ reflect.Kind
	CV  string
	// contains filtered or unexported fields
}

ConvertError is returned when a conversion error occurs.

func (*ConvertError) Error

func (e *ConvertError) Error() string

func (*ConvertError) Unwrap

func (e *ConvertError) Unwrap() error

type InvalidDateTimeFormatError

type InvalidDateTimeFormatError struct {
	CV      string
	Formats []string
}

InvalidDateTimeFormatError is returned when an invalid datetime format is encountered.

func (*InvalidDateTimeFormatError) Error

func (e *InvalidDateTimeFormatError) Error() string

type MappingError

type MappingError struct {
	Sheet string
	Cell  string
	Field string
	// contains filtered or unexported fields
}

MappingError is returned when an error is encountered during the mapping.

func (*MappingError) Error

func (e *MappingError) Error() string

func (*MappingError) Unwrap

func (e *MappingError) Unwrap() error

type Result

type Result[T any] struct {
	Val T
	Err error
}

Result is a struct that holds the result of a parsing operation. It contains the parsed value or an error if any.