initial commit

.golangci.yaml

@@ -0,0 +1,111 @@
+linters-settings:
+  funlen:
+    lines: 110
+    statements: 70
+  gci:
+    sections:
+      - standard
+      - default
+      - localmodule
+    custom-order: true
+  goconst:
+    min-len: 2
+    min-occurrences: 2
+  gocritic:
+    enabled-tags:
+      - diagnostic
+      - experimental
+      - opinionated
+      - performance
+      - style
+  gocyclo:
+    min-complexity: 15
+  cyclop:
+    skip-tests: true
+    max-complexity: 15
+  godot:
+    capital: true
+  goimports:
+    local-prefixes: github.com/lzambarda/goflat
+  govet:
+    settings:
+      printf:
+        funcs:
+          - (github.com/golangci/golangci-lint/pkg/logutils.Log).Infof
+          - (github.com/golangci/golangci-lint/pkg/logutils.Log).Warnf
+          - (github.com/golangci/golangci-lint/pkg/logutils.Log).Errorf
+          - (github.com/golangci/golangci-lint/pkg/logutils.Log).Fatalf
+    disable:
+      - fieldalignment
+  lll:
+    line-length: 140
+  misspell:
+    locale: UK
+  tagliatelle:
+    case:
+      rules:
+        json: snake
+  unparam:
+    check-exported: true
+
+  wrapcheck:
+    ignoreSigs:
+      - .Errorf(
+      - errors.New(
+      - errors.Unwrap(
+      - errors.Join(
+      - .Wrap(
+      - .Wrapf(
+      - .WithMessage(
+      - .WithMessagef(
+      - .WithStack(
+      - status.Error(
+
+  wsl:
+    allow-cuddle-declarations: true
+
+issues:
+  # Excluding configuration per-path, per-linter, per-text and per-source
+  exclude-rules:
+    - path: _test\.go
+      linters:
+        - bodyclose
+        - dupl # we usually duplicate code in tests
+        - dupword
+        - errcheck
+        - errchkjson # we mostly dump file diffs, no biggie
+        - funlen
+        - gochecknoglobals
+        - goconst # sometimes it is easier this way
+        - gocritic
+        - gosec # security check is not important in tests
+        - govet
+        - maintidx
+        - revive
+        - unparam
+        - varnamelen
+        - wrapcheck
+    - path: testing
+      linters:
+        - errcheck
+  fix: true
+  exclude-use-default: false
+  exclude-dirs:
+    - model
+    - tmp
+    - bin
+    - scripts
+
+run:
+  allow-parallel-runners: true
+  tests: true
+  build-tags:
+    - integration
+
+linters:
+  enable-all: true
+  disable:
+    - exhaustruct # I want to use zero values... and sometime leave a field uninitialised, because it'll be later.
+    - depguard # because I don't want to write a dedicated config file.
+    - nonamedreturns # I don't fully agree with this
+    - paralleltest # I don't agree with this level of nitpicking

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Luca Zambarda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,54 @@
+# goflat
+
+Generic-friendly flat file marshaller and unmarshaller using the `flat` field tag in structs.
+
+## Overview
+
+```go
+type Record struct {
+    FirstName string `flat:"first_name"`
+    LastName string  `flat:"last_name"`
+    Age int          `flat:"age"`
+    Height float32   `flat:"-"` // ignored
+}
+
+ch := make(chan Record)
+
+...
+
+goflat.MarshalSliceToWriter[Record](ctx,ch,csvWriter,options)
+```
+
+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`.
+
+```go
+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
+}
+```

doc.go

@@ -0,0 +1,2 @@
+// Package goflat contains all the code to marshal and unmarshal tabular files.
+package goflat

errors.go

@@ -0,0 +1,25 @@
+package goflat
+
+import "errors"
+
+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")
+	// ErrMismatchedFields is returned when the input structs have inconsistent
+	// fields. In theory this will never be returned.
+	ErrMismatchedFields = errors.New("mismatched fields")
+	// ErrUnsupportedType is returned when the unmarshaller encounters an
+	// unsupported type.
+	ErrUnsupportedType = errors.New("unsupported type")
+)

go.mod

@@ -0,0 +1,8 @@
+module github.com/lzambarda/goflat
+
+go 1.23.2
+
+require (
+	github.com/google/go-cmp v0.6.0
+	golang.org/x/sync v0.9.0
+)

go.sum

@@ -0,0 +1,4 @@
+github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+golang.org/x/sync v0.9.0 h1:fEo0HyrW1GIgZdpbhCRO0PkJajUS5H9IFUztCgEo2jQ=
+golang.org/x/sync v0.9.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=

marshal.go

@@ -0,0 +1,84 @@
+package goflat
+
+import (
+	"context"
+	"encoding/csv"
+	"fmt"
+)
+
+// Marshaller can be used to tell goflat to use custom logic to convert a field
+// into a string.
+type Marshaller interface {
+	Marshal() (string, error)
+}
+
+// MarshalSliceToWriter marshals a slice of structs to a CSV file.
+func MarshalSliceToWriter[T any](ctx context.Context, values []T, writer *csv.Writer, opts Options) error {
+	ch := make(chan T) //nolint:varnamelen // Fine here.
+
+	go func() {
+		defer close(ch)
+
+		for _, value := range values {
+			select {
+			case <-ctx.Done():
+				return
+			case ch <- value:
+			}
+		}
+	}()
+
+	return MarshalChannelToWriter(ctx, ch, writer, opts)
+}
+
+// MarshalChannelToWriter marshals a channel of structs to a CSV file.
+func MarshalChannelToWriter[T any](ctx context.Context, inputCh <-chan T, writer *csv.Writer, opts Options) error {
+	opts.headersFromStruct = true
+
+	factory, err := newFactory[T](nil, opts)
+	if err != nil {
+		return fmt.Errorf("new factory: %w", err)
+	}
+
+	err = writer.Write(factory.marshalHeaders())
+	if err != nil {
+		return fmt.Errorf("write headers: %w", err)
+	}
+
+	var currentLine int
+	var value T
+
+	for {
+		var channelHasValue bool
+
+		select {
+		case <-ctx.Done():
+			return ctx.Err() //nolint:wrapcheck // No need here.
+		case value, channelHasValue = <-inputCh:
+		}
+
+		if !channelHasValue {
+			break
+		}
+
+		record, err := factory.marshal(value, string(writer.Comma))
+		if err != nil {
+			return fmt.Errorf("marshal %d: %w", currentLine, err)
+		}
+
+		err = writer.Write(record)
+		if err != nil {
+			return fmt.Errorf("write line %d: %w", currentLine, err)
+		}
+
+		currentLine++
+	}
+
+	writer.Flush()
+
+	if err = writer.Error(); err != nil {
+		return fmt.Errorf("flush: %w", err)
+	}
+
+	return nil
+}

marshal_test.go

@@ -0,0 +1,56 @@
+package goflat_test
+
+import (
+	"bytes"
+	"context"
+	"encoding/csv"
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+
+	"github.com/lzambarda/goflat"
+)
+
+func TestMarshal(t *testing.T) {
+	expected, err := testdata.ReadFile("testdata/marshal/success.csv")
+	if err != nil {
+		t.Fatalf("read test file: %v", err)
+	}
+
+	type record struct {
+		FirstName string  `flat:"first_name"`
+		LastName  string  `flat:"last_name"`
+		Ignore    uint8   `flat:"-"`
+		Age       int     `flat:"age"`
+		Height    float32 `flat:"height"`
+	}
+
+	input := []record{
+		{
+			FirstName: "John",
+			LastName:  "Doe",
+			Ignore:    123,
+			Age:       30,
+			Height:    1.75,
+		},
+		{
+			FirstName: "Jane",
+			LastName:  "Doe",
+			Ignore:    123,
+			Age:       25,
+			Height:    1.65,
+		},
+	}
+	var got bytes.Buffer
+
+	writer := csv.NewWriter(&got)
+
+	err = goflat.MarshalSliceToWriter(context.Background(), input, writer, goflat.Options{})
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+
+	if diff := cmp.Diff(string(expected), got.String()); diff != "" {
+		t.Errorf("(-expected, +got):\n%s", diff)
+	}
+}