Welcome to kotlin-csv 👋
Pure Kotlin CSV Reader/Writer
easy to setup
use DSL so easy to read
on Java, we always need to close file. but it's boilerplate code and not friendly for non-JVM user.
provide interfaces which automatically close file without being aware.
kotlin multiplatform project
gradle DSL:
//gradle kotlin DSLimplementation("com.github.doyaaaaaken:kotlin-csv-jvm:0.15.0")//gradle groovy DSLimplementation 'com.github.doyaaaaaken:kotlin-csv-jvm:0.15.0'
maven:
<dependency><groupId>com.github.doyaaaaaken</groupId><artifactId>kotlin-csv-jvm</artifactId><version>0.15.0</version></dependency>
kscript
@file:DependsOn("com.github.doyaaaaaken:kotlin-csv-jvm:0.15.0")
Simple case
You can read csv file from String
, java.io.File
or java.io.InputStream
object.
// read from `String`val csvData: String = "a,b,c\nd,e,f"val rows: List<List<String>> = csvReader().readAll(csvData)// read from `java.io.File`val file: File = File("test.csv")val rows: List<List<String>> = csvReader().readAll(file)
Read with header
val csvData: String = "a,b,c\nd,e,f"val rows: List<Map<String, String>> = csvReader().readAllWithHeader(csvData)println(rows) //[{a=d, b=e, c=f}]
Read as Sequence
Sequence
type allows to execute lazily.
It starts to process each rows before reading all row data.
See detail about Sequence
type on Kotlin official document.
csvReader().open("test1.csv") {readAllAsSequence().forEach { row: List<String> ->//Do somethingprintln(row) //[a, b, c]}}csvReader().open("test2.csv") {readAllWithHeaderAsSequence().forEach { row: Map<String, String> ->//Do somethingprintln(row) //{id=1, name=doyaaaaaken}}}
NOTE:readAllAsSequence
and readAllWithHeaderAsSequence
methods can be only called inside open
method lambda block. Because, input stream is closed outside open
method lambda block.
Read line by line
If you want to handle line-by-line, you can do it by using open
method.
Use open
method and then use readNext
method inside nested block to read row.
csvReader().open("test.csv") {readNext()}
Write in a Suspending Function
val rows = listOf(listOf("a", "b", "c"), listOf("d", "e", "f")).asSequence()csvWriter().openAsync(testFileName) {delay(100) //other suspending taskrows.asFlow().collect {delay(100) // other suspending taskwriteRow(it)}}
Read in a Suspending Function
csvReader().openAsync("test.csv") {val container = mutalbeListOf<List<String>>()delay(100) //other suspending taskreadAllAsSequence().asFlow().collect { row ->delay(100) // other suspending taskcontainer.add(row)}}
Note: openAsync
can be and only be accessed through a coroutine
or another suspending
function
Customize
When you create CsvReader, you can choose read options.
// this is tsv reader's optionval tsvReader = csvReader {charset = "ISO_8859_1"quoteChar = '"'delimiter = '\t'escapeChar = '\\'}
Opton | default value | description |
charset |
| Charset encoding. The value must be supported by java.nio.charset.Charset. |
quoteChar |
| Character used as quote between each fields. |
delimiter |
| Character used as delimiter between each fields.
Use |
escapeChar |
| Character to escape quote inside field string.
Normally, you don't have to change this option.
See detail comment on |
skipEmptyLine |
| If empty line is found, skip it or not (=throw an exception). |
skipMissMatchedRow |
| If a invalid row which has different number of fields from other rows is found, skip it or not (=throw an exception). |
Simple case
You can write csv simply, only one line. No need to call other methods.
Also, You don't have to call use
, close
and flush
method.
val rows = listOf(listOf("a", "b", "c"), listOf("d", "e", "f"))csvWriter().writeAll(rows, "test.csv")// if you'd append data on the tail of the file, assign `append = true`.csvWriter().writeAll(rows, "test.csv", append = true)
You can also write csv file per each line.
Also, You don't have to call use
, close
and flush
method.
val row1 = listOf("a", "b", "c")val row2 = listOf("d", "e", "f")csvWriter().open("test.csv") {writeRow(row1)writeRow(row2)writeRow("g", "h", "i")writeRows(listOf(row1, row2))}
long-running write (manual control for file close)
If you want to close file writer manually for performance reason (i.e. streaming scenario), you can use openAndGetRawWriter
and get raw CsvFileWriter
.
DO NOT forget to call close
method manually.
val row1 = listOf("a", "b", "c")@OptIn(KotlinCsvExperimental::class)val writer = csvWriter().openAndGetRawWriter("test.csv")writer.writeRow(row1)writer.close()
Customize
When you create CsvWriter, you can choose write options.
val writer = csvWriter {charset = "ISO_8859_1"delimiter = '\t'nullCode = "NULL"lineTerminator = "\n"outputLastLineTerminator = truequote {mode = WriteQuoteMode.ALLchar = '\''}}
Option | default value | description |
charset |
| Charset encoding. The value must be supported by java.nio.charset.Charset. |
delimiter |
| Character used as delimiter between each fields.
Use |
nullCode |
| Character used when a written field is null value. |
lineTerminator |
| Character used as line terminator. |
outputLastLineTerminator |
| Output line break at the end of file or not. |
quote.char |
| Character to quote each fields. |
quote.mode |
| Quote mode.
- |
Documents
Libraries which use kotlin-csv
kotlin-grass: Csv File to Kotlin Data Class Parser.
Contributions, issues and feature requests are welcome!
Feel free to check issues page.
If you have question, feel free to ask in Kotlin slack's kotlin-csv
room.
$ git clone [email protected]:doyaaaaaken/kotlin-csv.git$ cd kotlin-csv$ ./gradlew check
Give a ⭐️ if this project helped you!
Copyright © 2019 doyaaaaaken. This project is Apache License 2.0 licensed.
This project is inspired ❤️ by scala-csv
This README was generated with ❤️ by readme-md-generator