vcsv

README

VCSV - Vertigo CSV Reader for Go

vcsv is a Go package providing a flexible and powerful way to read and unmarshal CSV data into Go structs. It supports custom CSV headers, various data types, and user-defined parsing rules through struct tags.

Features

• Read CSV data and unmarshal into Go structs.
• Support for custom CSV headers.
• Handle various primitive types and custom types implementing encoding.TextUnmarshaler.
• Options such as format to specify the date format for time.Time fields.
• Flexible configuration options for CSV parsing.
• No external dependencies. Only uses the standard library.

Installation

To install VCSV, use the following command:

go get -u github.com/fond-of-vertigo/vcsv

Usage

Below are some examples of how to use the VCSV package.

Basic Usage

First, define a struct that maps to your CSV format:

import "time"

type Person struct {
    Name          string    `csv:"name"`
    Age           int       `csv:"age"`
    Birthdate     time.Time `csv:"birthdate,format:2006-01-02"`
    IsBirthday    bool      `csv:"is_birthday"`
}

When a CSV file contains no header, you can use the index tag to specify the column index instead of the column name:

type Person struct {
    Name          string    `csv:"index:0"`
    Age           int       `csv:"index:1"`
    Birthdate     time.Time `csv:"index:2,format:2006-01-02"`
    IsBirthday    bool      `csv:"index:3"`
}

Then, use VCSV to read and unmarshal data:

package main

import (
	"fmt"
	"github.com/fond-of-vertigo/vcsv"
	"os"
)

func main() {
	file, err := os.Open("data.csv")
	if err != nil {
		panic(err)
	}
	defer file.Close()

	reader, err := vcsv.New(file, vcsv.WithSeparationChar(','))
	if err != nil {
		panic(err)
	}

	var p Person
	for reader.Next(&err) {
        // Unmarshal the current line into the Person struct.
		if err := reader.UnmarshalLine(&p); err != nil { 
			panic(err)
		}
        
		fmt.Printf("%+v\n", p)
	}
}

Configuration Options

VCSV provides several options to configure the CSV reader:

• WithHeader([]string): Sets the CSV header columns manually.
• WithSeparationChar(rune): Sets a custom column separation character.
• WithReadHeader(int): Specifies which line of the CSV file contains the header.

Example:

reader, err := vcsv.New(file, vcsv.WithSeparationChar(';'), vcsv.WithHeader([]string{"Name", "Age", "Birthdate", "IsBirthday"}))

Documentation

Index

• type CSVReader
  • func New(r io.Reader, options ...Option) (*CSVReader, error)
  • func (r *CSVReader) CurrentLineIndex() int
  • func (r *CSVReader) Get(columnName string) (string, error)
  • func (r *CSVReader) GetByColumnIndex(columnIndex int) (string, error)
  • func (r *CSVReader) Header() []string
  • func (r *CSVReader) Next(err *error) bool
  • func (r *CSVReader) ReadHeader()
  • func (r *CSVReader) SetHeader(columns []string)
  • func (r *CSVReader) UnmarshalLine(v interface{}) error
• type Option
  • func WithHeader(columns []string) Option
  • func WithReadHeader(line int) Option
  • func WithSeparationChar(separationChar rune) Option

Types

type CSVReader

type CSVReader struct {
	// contains filtered or unexported fields
}

CSVReader is a CSV reader that supports iterating and reading CSV lines into structs. The csv reader is read by default in the first line. If the header is not in the first line, you can use the WithReadHeader option to set the line where the header is located.

func New

func New(r io.Reader, options ...Option) (*CSVReader, error)

New creates a new CSVReader.

func (*CSVReader) CurrentLineIndex

func (r *CSVReader) CurrentLineIndex() int

CurrentLineIndex returns the current CSV line index.

func (*CSVReader) Get

func (r *CSVReader) Get(columnName string) (string, error)

Get returns the value of the given column name.

func (*CSVReader) GetByColumnIndex

func (r *CSVReader) GetByColumnIndex(columnIndex int) (string, error)

GetByColumnIndex returns the value by the given column index.

func (*CSVReader) Header

func (r *CSVReader) Header() []string

Header returns the CSV header columns.

func (*CSVReader) Next

func (r *CSVReader) Next(err *error) bool

Next reads the next CSV line.

func (*CSVReader) ReadHeader

func (r *CSVReader) ReadHeader()

ReadHeader reads the current line, that was already read by Next as the CSV header. This method is called automatically when the CSVReader is created, use it only if you want to read the header again.

func (*CSVReader) SetHeader

func (r *CSVReader) SetHeader(columns []string)

SetHeader sets the CSV header columns.

func (*CSVReader) UnmarshalLine

func (r *CSVReader) UnmarshalLine(v interface{}) error

type Option

type Option func(*CSVReader)

func WithHeader

func WithHeader(columns []string) Option

WithHeader sets the CSV header columns.

func WithReadHeader

func WithReadHeader(line int) Option

WithReadHeader sets the line where the CSV header is located. If the value is negative, the header is not read. If the value is 0, the header is read from the first line. If the value is 1, the header is read from the second line, and so on.

The default value is 0.

func WithSeparationChar

func WithSeparationChar(separationChar rune) Option

WithSeparationChar sets the CSV separation character.