goflat

README

goflat

Generic-friendly flat file marshaller and unmarshaller using the flat field tag in structs.

Overview

type Record struct {
    FirstName string `flat:"first_name"`
    LastName string  `flat:"last_name"`
    Age int          `flat:"age"`
    Height float32   `flat:"-"` // ignored
}

...

goflat.MarshalSliceToWriter[Record](ctx,inputCh,csvWriter,options)

...

goflat.UnmarshalToChan[Record](ctx,csvReader,options,outputCh)

Will result in:

first_name,last_name,age
John,Doe,30
Jane,Doe,20

Options

Both marshal and unmarshal operations support goflat.Options, which allow to introduce automatic safety checks, such as duplicated headers, flat tag coverage and more.

Custom marshal / unmarshal

Both operations can be customised for each field in a struct by having that value implementing goflat.Marshal and/or goflat.Unmarshal.

type Record struct {
    Field MyType `flat:"field"`
}

type MyType struct {
    Value int
}

func (m *MyType) Marshal() (string,error) {
    if m.Value %2 == 0 {
        return "odd", nil
    }

    return "even", nil
}

Documentation

Overview

Package goflat contains all the code to marshal and unmarshal tabular files.

Index

• Constants
• Variables
• func DetectReader(reader io.Reader) (*csv.Reader, error)
• func MarshalChannelToWriter[T any](ctx context.Context, inputCh <-chan T, writer *csv.Writer, opts Options) error
• func MarshalSliceToWriter[T any](ctx context.Context, values []T, writer *csv.Writer, opts Options) error
• func UnmarshalToCallback[T any](ctx context.Context, reader *csv.Reader, opts Options, callback func(T) error) error
• func UnmarshalToChannel[T any](ctx context.Context, reader *csv.Reader, opts Options, outputCh chan<- T) error
• func UnmarshalToSlice[T any](ctx context.Context, reader *csv.Reader, opts Options) ([]T, error)
• type Marshaller
• type Options
• type Unmarshaller

Constants

const FieldTag = "flat"

FieldTag is the tag that must be used in the struct fields so that goflat can work with them.

Variables

var (
	// ErrNotAStruct is returned when the value to be worked with is not a struct.
	ErrNotAStruct = errors.New("not a struct")
	// ErrTaglessField is returned when goflat works in strict mode and a field
	// of the input struct has no "flat" tag.
	ErrTaglessField = errors.New("tagless field")
	// ErrDuplicatedHeader is returned when there is more than one header with
	// the same value. Only returned if [Option.ErrorIfDuplicateHeaders] is set
	// to true.
	ErrDuplicatedHeader = errors.New("duplicated header")
	// ErrMissingHeader is returned when a header referenced in a "flat" tag
	// does not appear in the input file. Only returned if
	// [Option.ErrorIfMissingHeaders] is set to true.
	ErrMissingHeader = errors.New("missing header")
	// ErrUnsupportedType is returned when the unmarshaller encounters an
	// unsupported type.
	ErrUnsupportedType = errors.New("unsupported type")
)

Functions

func DetectReader

func DetectReader(reader io.Reader) (*csv.Reader, error)

DetectReader returns a CSV reader with a separator based on a best guess about the first line.

func MarshalChannelToWriter

func MarshalChannelToWriter[T any](ctx context.Context, inputCh <-chan T, writer *csv.Writer, opts Options) error

MarshalChannelToWriter marshals a channel of structs to a CSV file.

func MarshalSliceToWriter

func MarshalSliceToWriter[T any](ctx context.Context, values []T, writer *csv.Writer, opts Options) error

MarshalSliceToWriter marshals a slice of structs to a CSV file.

func UnmarshalToCallback

func UnmarshalToCallback[T any](ctx context.Context, reader *csv.Reader, opts Options, callback func(T) error) error

UnmarshalToCallback unamrshals a CSV file invoking a callback function on each row.

func UnmarshalToChannel

func UnmarshalToChannel[T any](ctx context.Context, reader *csv.Reader, opts Options, outputCh chan<- T) error

UnmarshalToChannel unmarshals a CSV file to a channel of structs. It automatically closes the channel at the end.

func UnmarshalToSlice

func UnmarshalToSlice[T any](ctx context.Context, reader *csv.Reader, opts Options) ([]T, error)

UnmarshalToSlice unmarshals a CSV file to a slice of structs.

Types

type Marshaller

type Marshaller interface {
	Marshal() (string, error)
}

Marshaller can be used to tell goflat to use custom logic to convert a field into a string.

type Options

type Options struct {

	// ErrorIfTaglessField causes goflat to error out if any struct field is
	// missing the `flat` tag.
	ErrorIfTaglessField bool
	// ErrorIfDuplicateHeaders causes goflat to error out if two struct fields
	// share the same `flat` tag value.
	ErrorIfDuplicateHeaders bool
	// ErrorIfMissingHeaders causes goflat to error out at unmarshalling time if
	// a header has no struct field with a corresponding `flat` tag.
	ErrorIfMissingHeaders bool
	// UnmarshalIgnoreEmpty causes the unmarshaller to skip any column which is
	// an empty string. This is useful for instance if you have integer values
	// and you are okay with empty string mapping to the zero value (0). For the
	// same reason this will cause booleans to be false if the column is empty.
	UnmarshalIgnoreEmpty bool
	// contains filtered or unexported fields
}

Options is used to configure the marshalling and unmarshalling processes.

type Unmarshaller

type Unmarshaller interface {
	Unmarshal(value string) (Unmarshaller, error)
}

Unmarshaller can be used to tell goflat to use custom logic to convert the input string into the type itself.