Pure Kotlin CSV Reader/Writer.

Design goals

1. Simple interface

• easy to setup
• use DSL so easy to read

2. Automatic handling of I/O

• in 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.

3. Multiplatform

• Kotlin Multiplatform projects support.

Usage

Download

Gradle

for Kotlin DSL

implementation("com.jsoizo:kotlin-csv-jvm:1.10.0") // for JVM platform
implementation("com.jsoizo:kotlin-csv-js:1.10.0") // for Kotlin JS platform

for Gradle DSL

implementation 'com.jsoizo:kotlin-csv-jvm:1.10.0' // for JVM platform
implementation 'com.jsoizo:kotlin-csv-js:1.10.0' // for Kotlin JS platform

Maven

<dependency>
  <groupId>com.jsoizo</groupId>
  <artifactId>kotlin-csv-jvm</artifactId>
  <version>1.10.0</version>
</dependency>
<dependency>
  <groupId>com.jsoizo</groupId>
  <artifactId>kotlin-csv-js</artifactId>
  <version>1.10.0</version>
</dependency>

kscript

@file:DependsOn("com.jsoizo:kotlin-csv-jvm:1.10.0") // for JVM platform
@file:DependsOn("com.jsoizo:kotlin-csv-js:1.10.0") // for Kotlin JS platform

Examples

CSV Read examples

Simple case

You can read csv file from String, java.io.File or java.io.InputStream object.
No need to do any I/O handling. (No need to call use, close and flush method.)

// 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.

Learn more about the Sequence type on Kotlin's official documentation.

csvReader().open("test1.csv") {
    readAllAsSequence().forEach { row: List<String> ->
        //Do something
        println(row) //[a, b, c]
    }
}

csvReader().open("test2.csv") {
    readAllWithHeaderAsSequence().forEach { row: Map<String, String> ->
        //Do something
        println(row) //{id=1, name=jsoizo}
    }
}

NOTE: readAllAsSequence and readAllWithHeaderAsSequence methods can only be called within the open lambda block. The input stream is closed after the open 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()
}

Read in a Suspending Function

csvReader().openAsync("test.csv") {
    val container = mutalbeListOf<List<String>>()
    delay(100) //other suspending task
    readAllAsSequence().asFlow().collect { row ->
        delay(100) // other suspending task
        container.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 option
val tsvReader = csvReader {
    charset = "ISO_8859_1"
    quoteChar = '"'
    delimiter = '\t'
    escapeChar = '\\'
}

CSV Write examples

Simple case

You can start writing csv in one line, no need to do any I/O handling (No need 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 into OutpusStream.
csvWriter().writeAll(rows, File("test.csv").outputStream())

You can also write a csv file line by line by open 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))
}

Write in a Suspending Function

val rows = listOf(listOf("a", "b", "c"), listOf("d", "e", "f")).asSequence()
csvWriter().openAsync(testFileName) {
    delay(100) //other suspending task
    rows.asFlow().collect {
        delay(100) // other suspending task
        writeRow(it)
    }
}

Write as String

val rows = listOf(listOf("a", "b", "c"), listOf("d", "e", "f"))
val csvString: String = csvWriter().writeAllAsString(rows) //a,b,c\r\nd,e,f\r\n

long-running write (manual control for file close)

If you want to close a file writer manually for performance reasons (e.g. streaming scenario), you can use openAndGetRawWriter and get a raw CsvFileWriter.
DO NOT forget to close the writer!

val row1 = listOf("a", "b", "c")

@OptIn(KotlinCsvExperimental::class)
val writer = csvWriter().openAndGetRawWriter("test.csv")
writer.writeRow(row1)
writer.close()

Customize

When you create a CsvWriter, you can choose write options.

val writer = csvWriter {
    charset = "ISO_8859_1"
    delimiter = '\t'
    nullCode = "NULL"
    lineTerminator = "\n"
    outputLastLineTerminator = true
    quote {
        mode = WriteQuoteMode.ALL
        char = '\''
    }
}

Links

Documents

• Change Logs

Libraries which use kotlin-csv

• kotlin-grass: Csv File to Kotlin Data Class Parser.

Miscellaneous

🤝 Contributing

Contributions, issues and feature requests are welcome! If you have questions, ask away in Kotlin Slack's kotlin-csv room.

💻 Development

git clone [email protected]:jsoizo/kotlin-csv.git
cd kotlin-csv
./gradlew check

Show your support

Give a ⭐️ if this project helped you!

📝 License

Copyright © 2024 jsoizo. This project is licensed under Apache 2.0.

This project is inspired ❤️ by scala-csv

This README was generated with ❤️ by readme-md-generator

Acknowledgments

This project was originally created by @doyaaaaaken. The initial work and contributions are greatly appreciated.