README
¶
Go CSV
The GoCSV package aims to provide easy serialization and deserialization functions to use CSV in Golang
API and techniques inspired from https://godoc.org/gopkg.in/mgo.v2
Installation
go get -u github.com/gocarina/gocsv
Full example
Consider the following CSV file
client_id,client_name,client_age
1,Jose,42
2,Daniel,26
3,Vincent,32
Easy binding in Go!
package main
import (
"fmt"
"os"
"github.com/gocarina/gocsv"
)
type NotUsed struct {
Name string
}
type Client struct { // Our example struct, you can use "-" to ignore a field
Id string `csv:"client_id"`
Name string `csv:"client_name"`
Age string `csv:"client_age"`
NotUsedString string `csv:"-"`
NotUsedStruct NotUsed `csv:"-"`
}
func main() {
clientsFile, err := os.OpenFile("clients.csv", os.O_RDWR|os.O_CREATE, os.ModePerm)
if err != nil {
panic(err)
}
defer clientsFile.Close()
clients := []*Client{}
if err := gocsv.UnmarshalFile(clientsFile, &clients); err != nil { // Load clients from file
panic(err)
}
for _, client := range clients {
fmt.Println("Hello", client.Name)
}
if _, err := clientsFile.Seek(0, 0); err != nil { // Go to the start of the file
panic(err)
}
clients = append(clients, &Client{Id: "12", Name: "John", Age: "21"}) // Add clients
clients = append(clients, &Client{Id: "13", Name: "Fred"})
clients = append(clients, &Client{Id: "14", Name: "James", Age: "32"})
clients = append(clients, &Client{Id: "15", Name: "Danny"})
csvContent, err := gocsv.MarshalString(&clients) // Get all clients as CSV string
//err = gocsv.MarshalFile(&clients, clientsFile) // Use this to save the CSV back to the file
if err != nil {
panic(err)
}
fmt.Println(csvContent) // Display all clients as CSV string
}
Customizable Converters
type DateTime struct {
time.Time
}
// Convert the internal date as CSV string
func (date *DateTime) MarshalCSV() (string, error) {
return date.Time.Format("20060201"), nil
}
// You could also use the standard Stringer interface
func (date *DateTime) String() (string) {
return date.String() // Redundant, just for example
}
// Convert the CSV string as internal date
func (date *DateTime) UnmarshalCSV(csv string) (err error) {
date.Time, err = time.Parse("20060201", csv)
return err
}
type Client struct { // Our example struct with a custom type (DateTime)
Id string `csv:"id"`
Name string `csv:"name"`
Employed DateTime `csv:"employed"`
}
Customizable CSV Reader / Writer
func main() {
...
gocsv.SetCSVReader(func(in io.Reader) gocsv.CSVReader {
r := csv.NewReader(in)
r.Comma = '|'
return r // Allows use pipe as delimiter
})
...
gocsv.SetCSVReader(func(in io.Reader) gocsv.CSVReader {
r := csv.NewReader(in)
r.LazyQuotes = true
r.Comma = '.'
return r // Allows use dot as delimiter and use quotes in CSV
})
...
gocsv.SetCSVReader(func(in io.Reader) gocsv.CSVReader {
//return csv.NewReader(in)
return gocsv.LazyCSVReader(in) // Allows use of quotes in CSV
})
...
gocsv.UnmarshalFile(file, &clients)
...
gocsv.SetCSVWriter(func(out io.Writer) *gocsv.SafeCSVWriter {
writer := csv.NewWriter(out)
writer.Comma = '|'
return gocsv.NewSafeCSVWriter(writer)
})
...
gocsv.MarshalFile(&clients, file)
...
}
Documentation
¶
Index ¶
- Variables
- func CSVToChanMaps(reader io.Reader, c chan<- map[string]string) error
- func CSVToMap(in io.Reader) (map[string]string, error)
- func CSVToMaps(reader io.Reader) ([]map[string]string, error)
- func Marshal(in interface{}, out io.Writer) (err error)
- func MarshalBytes(in interface{}) (out []byte, err error)
- func MarshalCSV(in interface{}, out CSVWriter) (err error)
- func MarshalCSVWithoutHeaders(in interface{}, out CSVWriter) (err error)
- func MarshalChan(c <-chan interface{}, out CSVWriter) error
- func MarshalChanWithoutHeaders(c <-chan interface{}, out CSVWriter) error
- func MarshalFile(in interface{}, file *os.File) (err error)
- func MarshalString(in interface{}) (out string, err error)
- func MarshalStringWithoutHeaders(in interface{}) (out string, err error)
- func MarshalWithoutHeaders(in interface{}, out io.Writer) (err error)
- func SetCSVReader(csvReader func(io.Reader) CSVReader)
- func SetCSVWriter(csvWriter func(io.Writer) *SafeCSVWriter)
- func SetHeaderNormalizer(f Normalizer)
- func Unmarshal(in io.Reader, out interface{}) error
- func UnmarshalBytes(in []byte, out interface{}) error
- func UnmarshalBytesToCallback(in []byte, f interface{}) error
- func UnmarshalBytesToCallbackWithError(in []byte, f interface{}) error
- func UnmarshalBytesToChan(in []byte, c interface{}) error
- func UnmarshalCSV(in CSVReader, out interface{}) error
- func UnmarshalCSVToMap(in CSVReader, out interface{}) error
- func UnmarshalCSVWithoutHeaders(in CSVReader, out interface{}) error
- func UnmarshalDecoder(in Decoder, out interface{}) error
- func UnmarshalDecoderToCallback(in SimpleDecoder, f interface{}) error
- func UnmarshalDecoderToChan(in SimpleDecoder, c interface{}) error
- func UnmarshalFile(in *os.File, out interface{}) error
- func UnmarshalFileWithErrorHandler(in *os.File, errHandler ErrorHandler, out interface{}) error
- func UnmarshalMultipartFile(in *multipart.File, out interface{}) error
- func UnmarshalString(in string, out interface{}) error
- func UnmarshalStringToCallback(in string, c interface{}) (err error)
- func UnmarshalStringToCallbackWithError(in string, c interface{}) (err error)
- func UnmarshalStringToChan(in string, c interface{}) error
- func UnmarshalToCallback(in io.Reader, f interface{}) error
- func UnmarshalToCallbackWithError(in io.Reader, f interface{}) error
- func UnmarshalToChan(in io.Reader, c interface{}) error
- func UnmarshalToChanWithErrorHandler(in io.Reader, errorHandler ErrorHandler, c interface{}) error
- func UnmarshalToChanWithoutHeaders(in io.Reader, c interface{}) error
- func UnmarshalWithErrorHandler(in io.Reader, errHandle ErrorHandler, out interface{}) error
- func UnmarshalWithoutHeaders(in io.Reader, out interface{}) error
- type CSVReader
- type CSVWriter
- type Decoder
- type ErrorHandler
- type NoMarshalFuncError
- type NoUnmarshalFuncError
- type Normalizer
- type SafeCSVWriter
- type SimpleDecoder
- type TypeMarshaller
- type TypeUnmarshalCSVWithFields
- type TypeUnmarshaller
- type Unmarshaller
Constants ¶
This section is empty.
Variables ¶
var ( ErrUnmatchedStructTags = errors.New("unmatched struct tags") ErrDoubleHeaderNames = errors.New("double header names") )
var ( ErrEmptyCSVFile = errors.New("empty csv file given") ErrNoStructTags = errors.New("no csv struct tags found") )
var (
ErrChannelIsClosed = errors.New("channel is closed")
)
var FailIfDoubleHeaderNames = false
FailIfDoubleHeaderNames indicates whether it is considered an error when a header name is repeated in the csv header.
var FailIfUnmatchedStructTags = false
FailIfUnmatchedStructTags indicates whether it is considered an error when there is an unmatched struct tag.
var FieldsCombiner = "."
FieldSeperator defines how to combine parent struct with child struct
var ShouldAlignDuplicateHeadersWithStructFieldOrder = false
ShouldAlignDuplicateHeadersWithStructFieldOrder indicates whether we should align duplicate CSV headers per their alignment in the struct definition.
var TagName = "csv"
TagName defines key in the struct field's tag to scan
var TagSeparator = ","
TagSeparator defines seperator string for multiple csv tags in struct fields
Functions ¶
func CSVToChanMaps ¶
CSVToChanMaps parses the CSV from the reader and send a dictionary in the chan c, using the header row as the keys.
func CSVToMaps ¶
CSVToMaps takes a reader and returns an array of dictionaries, using the header row as the keys
func MarshalBytes ¶
MarshalBytes returns the CSV bytes from the interface.
func MarshalCSV ¶
MarshalCSV returns the CSV in writer from the interface.
func MarshalCSVWithoutHeaders ¶
MarshalCSVWithoutHeaders returns the CSV in writer from the interface.
func MarshalChan ¶
MarshalChan returns the CSV read from the channel.
func MarshalChanWithoutHeaders ¶
MarshalChanWithoutHeaders returns the CSV read from the channel.
func MarshalFile ¶
MarshalFile saves the interface as CSV in the file.
func MarshalString ¶
MarshalString returns the CSV string from the interface.
func MarshalStringWithoutHeaders ¶
MarshalStringWithoutHeaders returns the CSV string from the interface.
func MarshalWithoutHeaders ¶
MarshalWithoutHeaders returns the CSV in writer from the interface.
func SetCSVReader ¶
SetCSVReader sets the CSV reader used to parse CSV.
func SetCSVWriter ¶
func SetCSVWriter(csvWriter func(io.Writer) *SafeCSVWriter)
SetCSVWriter sets the SafeCSVWriter used to format CSV.
func SetHeaderNormalizer ¶
func SetHeaderNormalizer(f Normalizer)
SetHeaderNormalizer sets the normalizer used to normalize struct and header field names.
func UnmarshalBytes ¶
UnmarshalBytes parses the CSV from the bytes in the interface.
func UnmarshalBytesToCallback ¶
UnmarshalBytesToCallback parses the CSV from the bytes and send each value to the given func f. The func must look like func(Struct).
func UnmarshalBytesToCallbackWithError ¶
UnmarshalBytesToCallbackWithError parses the CSV from the bytes and send each value to the given func f.
If func returns error, it will stop processing, drain the parser and propagate the error to caller.
The func must look like func(Struct) error.
func UnmarshalBytesToChan ¶
UnmarshalBytesToChan parses the CSV from the bytes and send each value in the chan c. The channel must have a concrete type.
func UnmarshalCSV ¶
UnmarshalCSV parses the CSV from the reader in the interface.
func UnmarshalCSVToMap ¶
UnmarshalCSVToMap parses a CSV of 2 columns into a map.
func UnmarshalCSVWithoutHeaders ¶
UnmarshalCSVWithoutHeaders parses a headerless CSV with passed in CSV reader
func UnmarshalDecoder ¶
UnmarshalDecoder parses the CSV from the decoder in the interface
func UnmarshalDecoderToCallback ¶
func UnmarshalDecoderToCallback(in SimpleDecoder, f interface{}) error
UnmarshalDecoderToCallback parses the CSV from the decoder and send each value to the given func f. The func must look like func(Struct).
func UnmarshalDecoderToChan ¶
func UnmarshalDecoderToChan(in SimpleDecoder, c interface{}) error
UnmarshalDecoderToChan parses the CSV from the decoder and send each value in the chan c. The channel must have a concrete type.
func UnmarshalFile ¶
UnmarshalFile parses the CSV from the file in the interface.
func UnmarshalFileWithErrorHandler ¶
func UnmarshalFileWithErrorHandler(in *os.File, errHandler ErrorHandler, out interface{}) error
UnmarshalFileWithErrorHandler parses the CSV from the file in the interface.
func UnmarshalMultipartFile ¶
UnmarshalMultipartFile parses the CSV from the multipart file in the interface.
func UnmarshalString ¶
UnmarshalString parses the CSV from the string in the interface.
func UnmarshalStringToCallback ¶
UnmarshalStringToCallback parses the CSV from the string and send each value to the given func f. The func must look like func(Struct).
func UnmarshalStringToCallbackWithError ¶
UnmarshalStringToCallbackWithError parses the CSV from the string and send each value to the given func f.
If func returns error, it will stop processing, drain the parser and propagate the error to caller.
The func must look like func(Struct) error.
func UnmarshalStringToChan ¶
UnmarshalStringToChan parses the CSV from the string and send each value in the chan c. The channel must have a concrete type.
func UnmarshalToCallback ¶
UnmarshalToCallback parses the CSV from the reader and send each value to the given func f. The func must look like func(Struct).
func UnmarshalToCallbackWithError ¶
UnmarshalToCallbackWithError parses the CSV from the reader and send each value to the given func f.
If func returns error, it will stop processing, drain the parser and propagate the error to caller.
The func must look like func(Struct) error.
func UnmarshalToChan ¶
UnmarshalToChan parses the CSV from the reader and send each value in the chan c. The channel must have a concrete type.
func UnmarshalToChanWithErrorHandler ¶
func UnmarshalToChanWithErrorHandler(in io.Reader, errorHandler ErrorHandler, c interface{}) error
UnmarshalToChanWithErrorHandler parses the CSV from the reader in the interface.
func UnmarshalToChanWithoutHeaders ¶
UnmarshalToChanWithoutHeaders parses the CSV from the reader and send each value in the chan c. The channel must have a concrete type.
func UnmarshalWithErrorHandler ¶
func UnmarshalWithErrorHandler(in io.Reader, errHandle ErrorHandler, out interface{}) error
Unmarshal parses the CSV from the reader in the interface.
func UnmarshalWithoutHeaders ¶
UnmarshalWithoutHeaders parses the CSV from the reader in the interface.
Types ¶
type CSVReader ¶
func DefaultCSVReader ¶
DefaultCSVReader is the default CSV reader used to parse CSV (cf. csv.NewReader)
func LazyCSVReader ¶
LazyCSVReader returns a lazy CSV reader, with LazyQuotes and TrimLeadingSpace.
type ErrorHandler ¶
type ErrorHandler func(*csv.ParseError) bool
type NoMarshalFuncError ¶
type NoMarshalFuncError struct {
// contains filtered or unexported fields
}
NoMarshalFuncError is the custom error type to be raised in case there is no marshal function defined on type
func (NoMarshalFuncError) Error ¶
func (e NoMarshalFuncError) Error() string
type NoUnmarshalFuncError ¶
type NoUnmarshalFuncError struct {
// contains filtered or unexported fields
}
NoUnmarshalFuncError is the custom error type to be raised in case there is no unmarshal function defined on type
func (NoUnmarshalFuncError) Error ¶
func (e NoUnmarshalFuncError) Error() string
type Normalizer ¶
Normalizer is a function that takes and returns a string. It is applied to struct and header field values before they are compared. It can be used to alter names for comparison. For instance, you could allow case insensitive matching or convert '-' to '_'.
func DefaultNameNormalizer ¶
func DefaultNameNormalizer() Normalizer
DefaultNameNormalizer is a nop Normalizer.
type SafeCSVWriter ¶
func DefaultCSVWriter ¶
func DefaultCSVWriter(out io.Writer) *SafeCSVWriter
DefaultCSVWriter is the default SafeCSVWriter used to format CSV (cf. csv.NewWriter)
func NewSafeCSVWriter ¶
func NewSafeCSVWriter(original *csv.Writer) *SafeCSVWriter
type SimpleDecoder ¶
SimpleDecoder .
func NewSimpleDecoderFromCSVReader ¶
func NewSimpleDecoderFromCSVReader(r CSVReader) SimpleDecoder
NewSimpleDecoderFromCSVReader creates a SimpleDecoder, which may be passed to the UnmarshalDecoder* family of functions, from a CSV reader. Note that encoding/csv.Reader implements CSVReader, so you can pass one of those directly here.
type TypeMarshaller ¶
TypeMarshaller is implemented by any value that has a MarshalCSV method This converter is used to convert the value to it string representation
type TypeUnmarshalCSVWithFields ¶
TypeUnmarshalCSVWithFields can be implemented on whole structs to allow for whole structures to customized internal vs one off fields
type TypeUnmarshaller ¶
TypeUnmarshaller is implemented by any value that has an UnmarshalCSV method This converter is used to convert a string to your value representation of that string
type Unmarshaller ¶
type Unmarshaller struct {
Headers []string
MismatchedHeaders []string
MismatchedStructFields []string
// contains filtered or unexported fields
}
Unmarshaller is a CSV to struct unmarshaller.
func NewUnmarshaller ¶
func NewUnmarshaller(reader *csv.Reader, out interface{}) (*Unmarshaller, error)
NewUnmarshaller creates an unmarshaller from a csv.Reader and a struct.
func (*Unmarshaller) Read ¶
func (um *Unmarshaller) Read() (interface{}, error)
Read returns an interface{} whose runtime type is the same as the struct that was used to create the Unmarshaller.
func (*Unmarshaller) ReadUnmatched ¶
func (um *Unmarshaller) ReadUnmatched() (interface{}, map[string]string, error)
ReadUnmatched is same as Read(), but returns a map of the columns that didn't match a field in the struct
func (*Unmarshaller) RenormalizeHeaders ¶
func (um *Unmarshaller) RenormalizeHeaders(headerNormalizer func([]string) []string) error
RenormalizeHeaders will remap the header names based on the headerNormalizer. This can be used to map a CSV to a struct where the CSV header names do not match in the file but a mapping is known
Source Files
Directories