csvutil

csvutil supports nested or embedded structs.

• Embedded structs: Fields are flattened into the CSV.
• Inline tags: Use the csv:",inline" tag to flatten a struct. You can also provide a prefix (e.g., csv:"prefix_,inline") to namespace the underlying fields in the CSV columns.

type Address struct {
	Street string `csv:"street"`
	City   string `csv:"city"`
}

type User struct {
	Name        string  `csv:"name"`
	Address     Address `csv:",inline"` // Flattened
	HomeAddress Address `csv:"home_,inline"` // Prefixed: home_street, home_city
	WorkAddress Address `csv:"work_,inline"` // Prefixed: work_street, work_city
	Age         int     `csv:"age,omitempty"`
}

You can override how specific types are handled using four methods, listed in order of precedence:

1. Registered functions: Use Encoder.WithMarshalers or Decoder.WithUnmarshalers to register custom functions for specific types.
2. Interface implementation (Registered): Register an interface (e.g., fmt.Stringer) and implement it on your types.
3. csvutil interfaces: Implement csvutil.Marshaler and csvutil.Unmarshaler on your types.
4. Standard library interfaces: Implement encoding.TextMarshaler and encoding.TextUnmarshaler on your types.

// Example: Implementing csvutil.Marshaler
type Foo int64

func (f Foo) MarshalCSV() ([]byte, error) {
	return strconv.AppendInt(nil, int64(f), 16), nil
}

func (f *Foo) UnmarshalCSV(data []byte) error {
	i, err := strconv.ParseInt(string(data), 16, 64)
	if err != nil {
		return err
	}
	*f = Foo(i)
	return nil
}

To decode a CSV file that lacks a header row, first generate a header slice using csvutil.Header based on your target struct. Then, pass this header slice to csvutil.NewDecoder as additional arguments.

type User struct {
	ID   int
	Name string
	Age  int `csv:",omitempty"`
	City string
}

csvReader := csv.NewReader(strings.NewReader(`
1,John,27,la
2,Bob,,ny`))

// Generate header from struct
userHeader, err := csvutil.Header(User{}, "csv")
if err != nil {
	log.Fatal(err)
}

// Pass header to NewDecoder
dec, err := csvutil.NewDecoder(csvReader, userHeader...)
if err != nil {
	log.Fatal(err)
}

var users []User
for {
	var u User
	if err := dec.Decode(&u); err == io.EOF {
		break
	} else if err != nil {
		log.Fatal(err)
	}
	users = append(users, u)
}

Install the csvutil package using go get.

go get github.com/jszwec/csvutil

To use a different delimiter like a tab (\t), configure the underlying csv.Reader or csv.Writer before passing them to csvutil.

// Decoder for TSV
csvReader := csv.NewReader(r)
csvReader.Comma = '\t'
dec, err := csvutil.NewDecoder(csvReader)

// Encoder for TSV
var buf bytes.Buffer
w := csv.NewWriter(&buf)
w.Comma = '\t'
enc := csvutil.NewEncoder(w)

Since the CSV specification does not define how to encode slices or maps, csvutil does not support them by default. To use them, create a type alias for the slice or map and implement the csvutil.Marshaler and csvutil.Unmarshaler interfaces.

type Strings []string

func (s Strings) MarshalCSV() ([]byte, error) {
	return []byte(strings.Join(s, ",")), nil
}

type StringMap map[string]string

func (sm StringMap) MarshalCSV() ([]byte, error) {
	return []byte(fmt.Sprint(sm)), nil
}

The Decoder uses a mapping system to connect CSV columns to struct fields. When Decode is called, it looks up the appropriate decoding function for each field.

Custom decoding logic is provided via Unmarshalers. When a field's type matches a registered concrete type, that function is used. If no concrete match is found, the Decoder checks if the field implements any of the registered interfaces in the order they were registered. This allows for flexible, polymorphic decoding of CSV data.

By default, csvutil looks for the csv tag. You can change this by setting the Tag field on the Encoder or Decoder.

type Foo struct {
	Bar int `custom:"bar"`
}

// Use 'custom' tag instead of 'csv'
dec, err := csvutil.NewDecoder(r)
dec.Tag = "custom"

enc := csvutil.NewEncoder(w)
enc.Tag = "custom"

The Decoder.Map function allows you to intercept and modify raw field values before they are decoded into Go types. This is useful for data normalization, such as converting custom strings (e.g., 'n/a') into standard formats (e.g., 'NaN') that strconv can handle.

dec, err := csvutil.NewDecoder(r)
if err != nil {
	log.Fatal(err)
}

// Normalize 'n/a' to 'NaN' for float64 fields
dec.Map = func(field, column string, v any) string {
	if _, ok := v.(float64); ok && field == "n/a" {
		return "NaN"
	}
	return field
}

Use csvutil.Unmarshal for simple, one-off decoding of CSV bytes into a slice of structs. It uses the standard Go csv.Reader with default options. For streaming or more advanced use cases, use csvutil.NewDecoder.

var csvInput = []byte(`
name,age,CreatedAt
jacek,26,2012-04-01T15:00:00Z
john,,0001-01-01T00:00:00Z`,
)

type User struct {
	Name      string `csv:"name"`
	Age       int    `csv:"age,omitempty"`
	CreatedAt time.Time
}

var users []User
if err := csvutil.Unmarshal(csvInput, &users); err != nil {
	fmt.Println("error:", err)
}

for _, u := range users {
	fmt.Printf("%+v\n", u)
}