csv

README

CSV

A Go CSV implementation inspired by Python's CSV module. It supports various CSV dialects (see below) and is fully backward compatible with the encoding/csv package in the Go standard library.

Examples

Here's a basic writing example:

f, err := os.Create("output.csv")
checkError(err)
defer func() {
  err := f.Close()
  checkError(err)
}
w := NewWriter(f)
w.Write([]string{
  "a",
  "b",
  "c",
})
w.Flush()
// output.csv will now contains the line "a b c" with a trailing newline.

Here's a basic reading example:

f, err := os.Open('myfile.csv')
checkError(err)
defer func() {
  err := f.Close()
  checkError(err)
}

r := NewReader(f)
for {
  fields, err := r.Read()
  if err == io.EOF {
    break
  }
  checkOtherErrors(err)
  handleFields(fields)
}

CSV dialects

To modify CSV dialect, have a look at csv.Dialect, csv.NewDialectWriter(...) and csv.NewDialectReader(...). It supports changing:

• separator/delimiter.
• quoting modes:
  • Always quote.
  • Never quote.
  • Quote when needed (minimal quoting).
  • Quote all non-numerical fields.
  • Quote all non-empty, non-numerical fields.
• line terminator.
• how quote character escaping should be done - using double escape, or using a custom escape character.

Have a look at the documentation in csv_test.go for example on how to use these. All values above have sane defaults (that makes the module behave the same as the csv module in the Go standard library).

Documentation

Package documentation can be found here.

Why was this developed?

I needed it for mysqlcsvdump to support variations of CSV output. The csv module in the Go (1.2) standard library was inadequate as it it does not support any CSV dialect modifications except changing separator and partially line termination.

Who developed this?

I'm Jens Rantil. Have a look at my blog for more info on what I'm working on.

Documentation

Overview

A CSV implementation inspired by Python's CSV module. Supports custom CSV formats.

Example (ReadingWriting)

buf := bytes.Buffer{}

writer := csv.NewWriter(&buf)
writer.Write([]string{"Hello", "World", "!"})
writer.Flush()

reader := csv.NewReader(&buf)
columns, err := reader.Read()
if err != nil {
	panic(err)
}

for _, s := range columns {
	fmt.Println(s)
}

Output:

Hello
World
!

Index

• Constants
• type Dialect
• type DoubleQuoteMode
• type QuoteMode
• type Reader
  • func NewDialectReader(r io.Reader, opts Dialect) *Reader
  • func NewReader(r io.Reader) *Reader
  • func (r *Reader) Read() ([]string, error)
  • func (r *Reader) ReadAll() ([][]string, error)
• type Writer
  • func NewDialectWriter(w io.Writer, opts Dialect) Writer
  • func NewWriter(w io.Writer) Writer
  • func (w Writer) Error() error
  • func (w Writer) Flush()
  • func (w Writer) Write(record []string) (err error)
  • func (w Writer) WriteAll(records [][]string) (err error)

Examples

• Package (ReadingWriting)

Constants

const (
	QuoteDefault            QuoteMode = iota // See DefaultQuoting.
	QuoteAll                          = iota // Quotes around every field.
	QuoteMinimal                      = iota // Quotes when needed.
	QuoteNonNumeric                   = iota // Quotes around non-numeric fields.
	QuoteNonNumericNonEmpty           = iota // Quotes around non-numeric or empty fields.

	// Never quote. Use with care. Could make things unparsable.
	QuoteNone = iota
)

Values QuoteMode can take.

const (
	DoubleQuoteDefault DoubleQuoteMode = iota // See DefaultDoubleQuote.
	DoDoubleQuote                      = iota // Escape using double escape characters.
	NoDoubleQuote                      = iota // Escape using escape character.
)

Values DoubleQuoteMode can take.

const (
	DefaultDelimiter      = ','
	DefaultQuoting        = QuoteMinimal
	DefaultDoubleQuote    = DoDoubleQuote
	DefaultEscapeChar     = '\\'
	DefaultQuoteChar      = '"'
	DefaultLineTerminator = "\n"
	DefaultComment        = '#'
)

Default dialect.

Types

type Dialect

type Dialect struct {
	// The delimiter that separates each field from another. Defaults to
	// DefaultDelimiter.
	Delimiter rune
	// What quoting mode to use. Defaults to DefaultQuoting.
	Quoting QuoteMode
	// How to escape quotes. Defaults to DefaultDoubleQuote.
	DoubleQuote DoubleQuoteMode
	// Character to use for escaping. Only used if DoubleQuote==NoDoubleQuote.
	// Defaults to DefaultEscapeChar.
	EscapeChar rune
	// Character to use as quotation mark around quoted fields. Defaults to
	// DefaultQuoteChar.
	QuoteChar rune
	// String that separates each record in a CSV file. Defaults to
	// DefaultLineTerminator.
	LineTerminator string

	// Comment, if not 0, is the comment character. Lines beginning with the
	// Comment character without preceding whitespace are ignored.
	// With leading whitespace the Comment character becomes part of the
	// field, even if TrimLeadingSpace is true.
	// Comment must be a valid rune and must not be \r, \n,
	// or the Unicode replacement character (0xFFFD).
	// It must also not be equal to Comma.
	Comment rune
}

A Dialect specifies the format of a CSV file. This structure is used by a Reader or Writer to know how to operate on the file they are reading/writing.

type DoubleQuoteMode

type DoubleQuoteMode int

DoubleQuoteMode defined how quote excaping should be done.

type QuoteMode

type QuoteMode int

QuoteMode defines how quotes should be handled.

type Reader

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

A Reader reads records from a CSV-encoded file.

Can be created by calling either NewReader or using NewDialectReader.

func NewDialectReader

func NewDialectReader(r io.Reader, opts Dialect) *Reader

Create a custom CSV reader.

func NewReader

func NewReader(r io.Reader) *Reader

Creates a reader that conforms to RFC 4180 and behaves identical as a encoding/csv.Reader.

See `Default*` constants for default dialect used.

func (*Reader) Read

func (r *Reader) Read() ([]string, error)

Read reads one record from r. The record is a slice of strings with each string representing one field.

func (*Reader) ReadAll

func (r *Reader) ReadAll() ([][]string, error)

ReadAll reads all the remaining records from r. Each record is a slice of fields. A successful call returns err == nil, not err == EOF. Because ReadAll is defined to read until EOF, it does not treat end of file as an error to be reported.

type Writer

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

A Writer writes records to a CSV encoded file.

Can be created by calling either NewWriter or using NewDialectWriter.

func NewDialectWriter

func NewDialectWriter(w io.Writer, opts Dialect) Writer

Create a custom CSV writer.

func NewWriter

func NewWriter(w io.Writer) Writer

Create a writer that conforms to RFC 4180 and behaves identical as a encoding/csv.Reader.

See `Default*` constants for default dialect used.

func (Writer) Error

func (w Writer) Error() error

Error reports any error that has occurred during a previous Write or Flush.

func (Writer) Flush

func (w Writer) Flush()

Flush writes any buffered data to the underlying io.Writer. To check if an error occurred during the Flush, call Error.

func (Writer) Write

func (w Writer) Write(record []string) (err error)

Writer writes a single CSV record to w along with any necessary quoting. A record is a slice of strings with each string being one field.

func (Writer) WriteAll

func (w Writer) WriteAll(records [][]string) (err error)

WriteAll writes multiple CSV records to w using Write and then calls Flush.