kantan.csv is a library for CSV parsing and serialization written in the Scala programming language.

Getting started

kantan.csv is currently available for Scala 2.12 and 2.13.

The current version is 0.7.0, which can be added to your project with one or more of the following line(s) in your SBT build file:

// Core library, included automatically if any other module is imported.
libraryDependencies += "com.nrinaudo" %% "kantan.csv" % "0.7.0"

// Java 8 date and time instances.
libraryDependencies += "com.nrinaudo" %% "kantan.csv-java8" % "0.7.0"

// Provides scalaz type class instances for kantan.csv, and vice versa.
libraryDependencies += "com.nrinaudo" %% "kantan.csv-scalaz" % "0.7.0"

// Provides cats type class instances for kantan.csv, and vice versa.
libraryDependencies += "com.nrinaudo" %% "kantan.csv-cats" % "0.7.0"

// Automatic type class instances derivation.
libraryDependencies += "com.nrinaudo" %% "kantan.csv-generic" % "0.7.0"

// Provides instances for refined types.
libraryDependencies += "com.nrinaudo" %% "kantan.csv-refined" % "0.7.0"

// Provides instances for enumeratum types.
libraryDependencies += "com.nrinaudo" %% "kantan.csv-enumeratum" % "0.7.0"

// Provides instances for libra types.
libraryDependencies += "com.nrinaudo" %% "kantan.csv-libra" % "0.7.0"

Additionally, while kantan.csv comes with a default parser / serializer (that has pretty good performances), some people might prefer to use older, more reputable implementations. The following engines are currently supported:

// commons-csv engine.
libraryDependencies += "com.nrinaudo" %% "kantan.csv-commons" % "0.7.0"

// jackson-csv engine.
libraryDependencies += "com.nrinaudo" %% "kantan.csv-jackson" % "0.7.0"

Motivation

CSV is an unreasonably popular data exchange format. It suffers from poor (or at the very least late) standardisation, and is often a nightmare to work with when it contains more complex data than just lists of numerical values.

I started writing kantan.csv when I realised I was spending more time dealing with the data container than the data itself. My goal is to abstract CSV away as much as possible and allow developers to describe their data and where it comes from, and then just work with it.

kantan.csv is meant to be RFC compliant, but flexible enough that it should parse any sane variation on the format. Should you find CSV files that don’t parse, please file an issue and I’ll look into it.

While I’m pretty happy with kantan.csv, or at least the direction it’s headed, I do not pretend that it will fit all use cases. It fits mine, but might not work for everyone. I’m happy to hear suggestions on how this can be addressed, though.

Tutorials

• Decoding rows as collections
• Decoding cells as arbitrary types
• Decoding rows as tuples
• Decoding rows as case classes
• Decoding rows as arbitrary types
• Decoding CSV data into a collection
• Decoding CSV data one row at a time
• What can be parsed as CSV data?
• Error handling
• Encoding collections as rows
• Encoding arbitrary types as cells
• Encoding tuples as rows
• Encoding case classes as rows
• Encoding arbitrary types as rows
• Encoding entire collections
• Encoding one row at a time
• What can CSV data be written to?
• Encoders, decoders and codecs
• Using header values instead of indexes
• Default instances
• External CSV libraries
• Cats module
• Scalaz module
• Generic module
• Java 8 dates and times
• Refined module
• Enumeratum module
• Libra module
• Working with BOMs (and MS Excel)