kotlin-csv

Kotlin CSV Reader/Writer

License

License

Categories

Categories

Kotlin Languages Data CSV Data Formats
GroupId

GroupId

com.github.doyaaaaaken
ArtifactId

ArtifactId

kotlin-csv-metadata
Last Version

Last Version

0.15.2
Release Date

Release Date

Type

Type

module
Description

Description

kotlin-csv
Kotlin CSV Reader/Writer
Project URL

Project URL

https://github.com/doyaaaaaken/kotlin-csv
Project Organization

Project Organization

com.github.doyaaaaaken
Source Code Management

Source Code Management

https://github.com/doyaaaaaken/kotlin-csv

Download kotlin-csv-metadata

Dependencies

There are no dependencies for this project. It is a standalone project that does not depend on any other jars.

Project Modules

There are no modules declared in this project.

Welcome to kotlin-csv 👋

Version License: Apache License 2.0 CircleCI codecov CodeFactor

Pure Kotlin CSV Reader/Writer

Principals

1. Simple interface

  • easy to setup
  • use DSL so easy to read

2. No need to be aware of file close

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

3. Multiplatform (Planned in #15)

  • kotlin multiplatform project

Usage

Download

gradle DSL:

//gradle kotlin DSL
implementation("com.github.doyaaaaaken:kotlin-csv-jvm:0.15.2")

//gradle groovy DSL
implementation 'com.github.doyaaaaaken:kotlin-csv-jvm:0.15.2'

maven:

<dependency>
  <groupId>com.github.doyaaaaaken</groupId>
  <artifactId>kotlin-csv-jvm</artifactId>
  <version>0.15.2</version>
</dependency>

kscript

@file:DependsOn("com.github.doyaaaaaken:kotlin-csv-jvm:0.15.2")

Examples

CSV Read examples

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 something
        println(row) //[a, b, c]
    }
}

csvReader().open("test2.csv") {
    readAllWithHeaderAsSequence().forEach { row: Map<String, String> ->
        //Do something
        println(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 task
    rows.asFlow().collect {
       delay(100) // other suspending task
        writeRow(it)
    }
}

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 = '\\'
}
Opton default value description
charset UTF-8 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 "\t" if reading TSV file.
escapeChar " Character to escape quote inside field string.
Normally, you don't have to change this option.
See detail comment on ICsvReaderContext.
skipEmptyLine false If empty line is found, skip it or not (=throw an exception).
skipMissMatchedRow false If a invalid row which has different number of fields from other rows is found, skip it or not (=throw an exception).

CSV Write examples

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 = true
    quote {
        mode = WriteQuoteMode.ALL
        char = '\''
    }
}
Option default value description
charset UTF-8 Charset encoding. The value must be supported by java.nio.charset.Charset.
delimiter , Character used as delimiter between each fields.
Use "\t" if reading TSV file.
nullCode (empty string) Character used when a written field is null value.
lineTerminator \r\n Character used as line terminator.
outputLastLineTerminator true Output line break at the end of file or not.
quote.char " Character to quote each fields.
quote.mode CANONICAL Quote mode.
- CANONICAL: Not quote normally, but quote special characters (quoteChar, delimiter, line feed). This is the specification of CSV.
- ALL: Quote all fields.
- NON_NUMERIC: Quote non-numeric fields. (ex. 1,"a",2.3)

Links

Documents

Libraries which use kotlin-csv

Miscellaneous

🤝 Contributing

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.

💻 Development

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

Show your support

Give a ⭐️ if this project helped you!

📝 License

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

Versions

Version
0.15.2
0.15.1
0.15.0
0.14.0
0.13.0
0.12.0
0.11.1
0.11.0
0.10.4
0.10.1
0.10.0
0.9.0
0.8.0
0.7.3
0.7.2
0.7.1
0.7.0