
CSV Reader/Writer library with an easy-to-use DSL interface, automating I/O handling. Supports reading from various sources, sequence processing, suspending functions, and customizable options for both reading and writing operations.
Pure Kotlin Multiplatform CSV reader and writer.
implementation("com.jsoizo:kotlin-csv:2.1.0")The multiplatform artifact resolves JVM, JS, Kotlin/Wasm, and supported
Kotlin/Native variants from Kotlin Multiplatform projects. Published
Native targets are macosArm64, iosArm64, iosSimulatorArm64,
linuxX64, linuxArm64, and mingwX64. Published Wasm targets are
wasmJs and wasmWasi.
Single-platform Gradle projects can also depend on the platform artifact
directly, for example kotlin-csv-jvm, kotlin-csv-js,
kotlin-csv-wasm-js, kotlin-csv-macosarm64, or kotlin-csv-linuxx64.
implementation 'com.jsoizo:kotlin-csv:2.1.0'<dependency>
<groupId>com.jsoizo</groupId>
<artifactId>kotlin-csv-jvm</artifactId>
<version>2.1.0</version>
</dependency>
<dependency>
<groupId>com.jsoizo</groupId>
<artifactId>kotlin-csv-js</artifactId>
<version>2.1.0</version>
</dependency>Snapshots of the next development version are published to Sonatype Central Portal Snapshots from the active development branch. SNAPSHOTs are unstable and may change at any time, but they let you try in-progress changes early.
Add the snapshots repository to your build, then declare the dependency with the corresponding -SNAPSHOT version
(see the active development branch's build.gradle.kts for the current value, for example 2.0.0-SNAPSHOT).
// settings.gradle.kts
dependencyResolutionManagement {
repositories {
mavenCentral()
maven("https://central.sonatype.com/repository/maven-snapshots/") {
mavenContent { snapshotsOnly() }
}
}
}// build.gradle.kts
implementation("com.jsoizo:kotlin-csv:<VERSION>-SNAPSHOT")The DSL builders return reusable, stateless instances; create them once and share them across calls.
import com.jsoizo.kotlincsv.csvReader
import com.jsoizo.kotlincsv.csvWriter
import com.jsoizo.kotlincsv.reader.CsvNullFieldIndicator
import com.jsoizo.kotlincsv.reader.readFromFile
import com.jsoizo.kotlincsv.reader.withHeader
import com.jsoizo.kotlincsv.writer.WriteQuoteMode
import com.jsoizo.kotlincsv.writer.writeToFile
val reader = csvReader()
val writer = csvWriter()// From a String — eager
val rows: List<List<String>> = reader.readAll("a,b,c\nd,e,f")
// From a File — lambda owns the open resource and closes it on exit
reader.readFromFile(File("data.csv")) { rows ->
rows.forEach { println(it) }
}
// With a header row (returns LinkedHashMap to preserve column order)
reader.readFromFile(File("data.csv")) { rows ->
val records = rows.withHeader().toList()
println(records.first()["id"])
}
// Nullable reads can distinguish "" from an unquoted empty field.
val nullableRows = csvReader {
nullFieldIndicator = CsvNullFieldIndicator.EMPTY_SEPARATORS
}.readAllNullable("\"empty\",\"null\"\n\"\",")reader.readFromFile(...) accepts String paths, kotlinx.io.files.Path,
and (on JVM) java.io.File. The block receives a cold
Sequence<List<String>>; take(n) and friends short-circuit cleanly
without parsing the rest of the file. For in-memory streams use
reader.read(source) (commonMain kotlinx.io.Source) or
reader.read(stream) (JVM java.io.InputStream).
val rows = listOf(
listOf("a", "b", "c"),
listOf("d", "e", "f"),
)
// To a String — eager
val csv: String = writer.writeAll(rows)
// One CSV record, with the same quoting and terminator options
val record: String = writer.writeRow(listOf("a", "b,c"))
val nullableRecord: String = writer.writeNullableRow(listOf(null, "", "value"))
// To a File
writer.writeToFile(rows, File("out.csv"))
// Nullable writes emit null as an unquoted empty field.
val nullableCsv = csvWriter {
quoteMode = WriteQuoteMode.ALL
}.writeAllNullable(listOf(listOf(null, "", "value")))For rows received one at a time, for example from an existing channel, append each record directly to your existing writer:
for (row in channel) {
bufferedWriter.append(writer.writeNullableRow(row))
}writeRow and writeNullableRow return strings and do not manage the channel
or output resource. With the default outputLastLineTerminator = true, each
record already ends in the configured terminator; do not append an extra newline.
With that option disabled, callers are responsible for separating records.
A quoted field may itself contain line breaks.
writer.writeToFile(...) accepts String paths, kotlinx.io.files.Path,
and (on JVM) java.io.File. For in-memory streams use
writer.write(rows, sink) (commonMain kotlinx.io.Sink) or
writer.write(rows, stream) (JVM java.io.OutputStream). Both
Sequence<List<String>> and List<List<String>> are accepted as the row
source.
Reader and writer share a CsvDialect value object that holds the four
characters defining the CSV format itself: delimiter, quoteChar,
escapeChar, lineTerminator. Format-independent policies stay on the
respective Config.
val tsvReader = csvReader {
dialect = CsvDialect.TSV
skipEmptyLine = true
}
val customWriter = csvWriter {
dialect = CsvDialect(delimiter = ';', escapeChar = '\\')
quoteMode = WriteQuoteMode.ALL
}| Reader option | Default | Description |
|---|---|---|
dialect |
CsvDialect.RFC4180 |
Shared CSV format (delimiter / quote / escape / line terminator). |
skipEmptyLine |
false |
Drop rows that are entirely empty before the field-count check. |
ignoreLeadingWhitespace |
false |
Ignore ASCII spaces/tabs before an opening quote at field start; preserve unquoted contents and whitespace inside quotes. |
excessFieldsRowBehaviour |
ERROR |
What to do when a row has more fields than the first row: ERROR / IGNORE / TRIM. |
insufficientFieldsRowBehaviour |
ERROR |
What to do when a row has fewer fields: ERROR / IGNORE / EMPTY_STRING. |
nullFieldIndicator |
NEITHER |
Which empty fields nullable reader APIs expose as null: NEITHER / EMPTY_SEPARATORS / EMPTY_QUOTES / BOTH. |
Quoted fields preceded by spaces or tabs can be read explicitly:
val rows = csvReader { ignoreLeadingWhitespace = true }
.readAll("a, \"b\"") // [[a, b]]For an immutable configuration, use config.withIgnoreLeadingWhitespace(true).
The original constructor and copy keep their five arguments; copying a
configuration preserves its whitespace option.
The default remains strict. This option does not trim unquoted fields, accept spaces after a closing quote, or consume a configured delimiter/quote/escape as whitespace. Other whitespace characters are not ignored.
CsvFieldNumDifferentException.rowNum counts CSV rows after reader filters
such as skipEmptyLine; it is not a physical source line number.
Nullable reader APIs (readNullable, readAllNullable, and nullable I/O
overloads) return String? values. withNullableHeader() keeps header keys
as non-null String; a null-looking empty header is treated as the empty
header name "", while data values remain nullable.
| Writer option | Default | Description |
|---|---|---|
dialect |
CsvDialect.RFC4180 |
Shared CSV format (delimiter / quote / escape / line terminator). |
outputLastLineTerminator |
true |
Emit a trailing line terminator after the final row. |
quoteMode |
CANONICAL |
When to wrap fields in quoteChar: CANONICAL (only when needed), ALL, or NON_NUMERIC. |
Charset is JVM-only and is passed as an argument on the I/O call:
reader.readFromFile(File("data.csv"), charset = "windows-31j") { it.toList() }
writer.writeToFile(rows, File("out.csv"), charset = "UTF-16LE")commonMain and JS overloads are UTF-8 only.
kotlin-csv's JVM I/O does not throw when the charset cannot map a
character. "windows-31j" and "Shift_JIS" write ? in its place. On
read, bytes the charset cannot decode become U+FFFD.
For Japanese text, use "windows-31j" (alias "MS932") rather than Java's
"Shift_JIS" (alias "SJIS"):
"windows-31j" decodes every byte
sequence that "Shift_JIS" decodes, plus Windows characters such as ①,
髙, and №.〜 (U+301C), − (U+2212), — (U+2014), and
‖ (U+2016) with ~ (U+FF5E), - (U+FF0D), ― (U+2015), and ∥
(U+2225). "windows-31j" writes the original four as ?. The
replacements produce the bytes that "Shift_JIS" writes for the
originals. Text typed on macOS or read with "Shift_JIS" can contain the
originals.BOM stripping on read defaults to ON (matches Excel-produced files):
reader.readFromFile(File("data.csv"), options = CsvReadIoOptions(stripBom = false))
writer.writeToFile(rows, File("out.csv"), options = CsvWriteIoOptions(prependBom = true))Keep the default dialect, CsvDialect.RFC4180. If the recipient's Excel
uses ; as the list separator, use CsvDialect(delimiter = ';'). The main
choice is the encoding. Pick it by what the recipient can read:
// UTF-8 with a BOM keeps every character.
writer.writeToFile(rows, "out.csv", options = CsvWriteIoOptions(prependBom = true))
// Windows-31J (JVM only) is for recipients that read only the Japanese Windows code page.
writer.writeToFile(rows, File("out.csv"), charset = "windows-31j")Windows-31J writes characters such as 𠮷 and emoji as ? without an
error. Replace 〜 (U+301C) and three similar characters first, as
described in Configuration. Do not combine
charset = "windows-31j" with prependBom = true. Windows-31J cannot
encode the BOM, so the file starts with ?.
To read a CSV file saved by Excel, keep the default UTF-8 for a UTF-8 file
and pass charset = "windows-31j" for a Windows-31J file. The reader drops a
leading BOM by default.
With FORMAT csv and the default NULL option, PostgreSQL writes NULL as
an unquoted empty field and an empty string as "". To keep that
difference, set nullFieldIndicator = EMPTY_SEPARATORS and read with a
nullable API such as readAllNullable. Write nullable rows with
WriteQuoteMode.ALL. The default CANONICAL mode writes both null and
"" as an unquoted empty field, so COPY FROM loads the empty strings as
NULL.
val pgReader = csvReader {
nullFieldIndicator = CsvNullFieldIndicator.EMPTY_SEPARATORS
}
val pgWriter = csvWriter {
dialect = CsvDialect(lineTerminator = "\n") // LF, as COPY TO STDOUT writes
quoteMode = WriteQuoteMode.ALL
}
val csv = pgWriter.writeAllNullable(listOf(listOf("1", null, "")))
// "1",,""
pgReader.readAllNullable(csv) // [[1, null, ]]./gradlew dokkaGeneratePublicationHtml — outputs
HTML to build/dokka/html/.Contributions, issues and feature requests are welcome!
If you have questions, ask away in Kotlin Slack's kotlin-csv room.
git clone git@github.com:jsoizo/kotlin-csv.git
cd kotlin-csv
./gradlew checkCopyright © 2024 jsoizo. This project is licensed under Apache 2.0.
This project was originally created by @doyaaaaaken. The initial work and contributions are greatly appreciated.
Pure Kotlin Multiplatform CSV reader and writer.
implementation("com.jsoizo:kotlin-csv:2.1.0")The multiplatform artifact resolves JVM, JS, Kotlin/Wasm, and supported
Kotlin/Native variants from Kotlin Multiplatform projects. Published
Native targets are macosArm64, iosArm64, iosSimulatorArm64,
linuxX64, linuxArm64, and mingwX64. Published Wasm targets are
wasmJs and wasmWasi.
Single-platform Gradle projects can also depend on the platform artifact
directly, for example kotlin-csv-jvm, kotlin-csv-js,
kotlin-csv-wasm-js, kotlin-csv-macosarm64, or kotlin-csv-linuxx64.
implementation 'com.jsoizo:kotlin-csv:2.1.0'<dependency>
<groupId>com.jsoizo</groupId>
<artifactId>kotlin-csv-jvm</artifactId>
<version>2.1.0</version>
</dependency>
<dependency>
<groupId>com.jsoizo</groupId>
<artifactId>kotlin-csv-js</artifactId>
<version>2.1.0</version>
</dependency>Snapshots of the next development version are published to Sonatype Central Portal Snapshots from the active development branch. SNAPSHOTs are unstable and may change at any time, but they let you try in-progress changes early.
Add the snapshots repository to your build, then declare the dependency with the corresponding -SNAPSHOT version
(see the active development branch's build.gradle.kts for the current value, for example 2.0.0-SNAPSHOT).
// settings.gradle.kts
dependencyResolutionManagement {
repositories {
mavenCentral()
maven("https://central.sonatype.com/repository/maven-snapshots/") {
mavenContent { snapshotsOnly() }
}
}
}// build.gradle.kts
implementation("com.jsoizo:kotlin-csv:<VERSION>-SNAPSHOT")The DSL builders return reusable, stateless instances; create them once and share them across calls.
import com.jsoizo.kotlincsv.csvReader
import com.jsoizo.kotlincsv.csvWriter
import com.jsoizo.kotlincsv.reader.CsvNullFieldIndicator
import com.jsoizo.kotlincsv.reader.readFromFile
import com.jsoizo.kotlincsv.reader.withHeader
import com.jsoizo.kotlincsv.writer.WriteQuoteMode
import com.jsoizo.kotlincsv.writer.writeToFile
val reader = csvReader()
val writer = csvWriter()// From a String — eager
val rows: List<List<String>> = reader.readAll("a,b,c\nd,e,f")
// From a File — lambda owns the open resource and closes it on exit
reader.readFromFile(File("data.csv")) { rows ->
rows.forEach { println(it) }
}
// With a header row (returns LinkedHashMap to preserve column order)
reader.readFromFile(File("data.csv")) { rows ->
val records = rows.withHeader().toList()
println(records.first()["id"])
}
// Nullable reads can distinguish "" from an unquoted empty field.
val nullableRows = csvReader {
nullFieldIndicator = CsvNullFieldIndicator.EMPTY_SEPARATORS
}.readAllNullable("\"empty\",\"null\"\n\"\",")reader.readFromFile(...) accepts String paths, kotlinx.io.files.Path,
and (on JVM) java.io.File. The block receives a cold
Sequence<List<String>>; take(n) and friends short-circuit cleanly
without parsing the rest of the file. For in-memory streams use
reader.read(source) (commonMain kotlinx.io.Source) or
reader.read(stream) (JVM java.io.InputStream).
val rows = listOf(
listOf("a", "b", "c"),
listOf("d", "e", "f"),
)
// To a String — eager
val csv: String = writer.writeAll(rows)
// One CSV record, with the same quoting and terminator options
val record: String = writer.writeRow(listOf("a", "b,c"))
val nullableRecord: String = writer.writeNullableRow(listOf(null, "", "value"))
// To a File
writer.writeToFile(rows, File("out.csv"))
// Nullable writes emit null as an unquoted empty field.
val nullableCsv = csvWriter {
quoteMode = WriteQuoteMode.ALL
}.writeAllNullable(listOf(listOf(null, "", "value")))For rows received one at a time, for example from an existing channel, append each record directly to your existing writer:
for (row in channel) {
bufferedWriter.append(writer.writeNullableRow(row))
}writeRow and writeNullableRow return strings and do not manage the channel
or output resource. With the default outputLastLineTerminator = true, each
record already ends in the configured terminator; do not append an extra newline.
With that option disabled, callers are responsible for separating records.
A quoted field may itself contain line breaks.
writer.writeToFile(...) accepts String paths, kotlinx.io.files.Path,
and (on JVM) java.io.File. For in-memory streams use
writer.write(rows, sink) (commonMain kotlinx.io.Sink) or
writer.write(rows, stream) (JVM java.io.OutputStream). Both
Sequence<List<String>> and List<List<String>> are accepted as the row
source.
Reader and writer share a CsvDialect value object that holds the four
characters defining the CSV format itself: delimiter, quoteChar,
escapeChar, lineTerminator. Format-independent policies stay on the
respective Config.
val tsvReader = csvReader {
dialect = CsvDialect.TSV
skipEmptyLine = true
}
val customWriter = csvWriter {
dialect = CsvDialect(delimiter = ';', escapeChar = '\\')
quoteMode = WriteQuoteMode.ALL
}| Reader option | Default | Description |
|---|---|---|
dialect |
CsvDialect.RFC4180 |
Shared CSV format (delimiter / quote / escape / line terminator). |
skipEmptyLine |
false |
Drop rows that are entirely empty before the field-count check. |
ignoreLeadingWhitespace |
false |
Ignore ASCII spaces/tabs before an opening quote at field start; preserve unquoted contents and whitespace inside quotes. |
excessFieldsRowBehaviour |
ERROR |
What to do when a row has more fields than the first row: ERROR / IGNORE / TRIM. |
insufficientFieldsRowBehaviour |
ERROR |
What to do when a row has fewer fields: ERROR / IGNORE / EMPTY_STRING. |
nullFieldIndicator |
NEITHER |
Which empty fields nullable reader APIs expose as null: NEITHER / EMPTY_SEPARATORS / EMPTY_QUOTES / BOTH. |
Quoted fields preceded by spaces or tabs can be read explicitly:
val rows = csvReader { ignoreLeadingWhitespace = true }
.readAll("a, \"b\"") // [[a, b]]For an immutable configuration, use config.withIgnoreLeadingWhitespace(true).
The original constructor and copy keep their five arguments; copying a
configuration preserves its whitespace option.
The default remains strict. This option does not trim unquoted fields, accept spaces after a closing quote, or consume a configured delimiter/quote/escape as whitespace. Other whitespace characters are not ignored.
CsvFieldNumDifferentException.rowNum counts CSV rows after reader filters
such as skipEmptyLine; it is not a physical source line number.
Nullable reader APIs (readNullable, readAllNullable, and nullable I/O
overloads) return String? values. withNullableHeader() keeps header keys
as non-null String; a null-looking empty header is treated as the empty
header name "", while data values remain nullable.
| Writer option | Default | Description |
|---|---|---|
dialect |
CsvDialect.RFC4180 |
Shared CSV format (delimiter / quote / escape / line terminator). |
outputLastLineTerminator |
true |
Emit a trailing line terminator after the final row. |
quoteMode |
CANONICAL |
When to wrap fields in quoteChar: CANONICAL (only when needed), ALL, or NON_NUMERIC. |
Charset is JVM-only and is passed as an argument on the I/O call:
reader.readFromFile(File("data.csv"), charset = "windows-31j") { it.toList() }
writer.writeToFile(rows, File("out.csv"), charset = "UTF-16LE")commonMain and JS overloads are UTF-8 only.
kotlin-csv's JVM I/O does not throw when the charset cannot map a
character. "windows-31j" and "Shift_JIS" write ? in its place. On
read, bytes the charset cannot decode become U+FFFD.
For Japanese text, use "windows-31j" (alias "MS932") rather than Java's
"Shift_JIS" (alias "SJIS"):
"windows-31j" decodes every byte
sequence that "Shift_JIS" decodes, plus Windows characters such as ①,
髙, and №.〜 (U+301C), − (U+2212), — (U+2014), and
‖ (U+2016) with ~ (U+FF5E), - (U+FF0D), ― (U+2015), and ∥
(U+2225). "windows-31j" writes the original four as ?. The
replacements produce the bytes that "Shift_JIS" writes for the
originals. Text typed on macOS or read with "Shift_JIS" can contain the
originals.BOM stripping on read defaults to ON (matches Excel-produced files):
reader.readFromFile(File("data.csv"), options = CsvReadIoOptions(stripBom = false))
writer.writeToFile(rows, File("out.csv"), options = CsvWriteIoOptions(prependBom = true))Keep the default dialect, CsvDialect.RFC4180. If the recipient's Excel
uses ; as the list separator, use CsvDialect(delimiter = ';'). The main
choice is the encoding. Pick it by what the recipient can read:
// UTF-8 with a BOM keeps every character.
writer.writeToFile(rows, "out.csv", options = CsvWriteIoOptions(prependBom = true))
// Windows-31J (JVM only) is for recipients that read only the Japanese Windows code page.
writer.writeToFile(rows, File("out.csv"), charset = "windows-31j")Windows-31J writes characters such as 𠮷 and emoji as ? without an
error. Replace 〜 (U+301C) and three similar characters first, as
described in Configuration. Do not combine
charset = "windows-31j" with prependBom = true. Windows-31J cannot
encode the BOM, so the file starts with ?.
To read a CSV file saved by Excel, keep the default UTF-8 for a UTF-8 file
and pass charset = "windows-31j" for a Windows-31J file. The reader drops a
leading BOM by default.
With FORMAT csv and the default NULL option, PostgreSQL writes NULL as
an unquoted empty field and an empty string as "". To keep that
difference, set nullFieldIndicator = EMPTY_SEPARATORS and read with a
nullable API such as readAllNullable. Write nullable rows with
WriteQuoteMode.ALL. The default CANONICAL mode writes both null and
"" as an unquoted empty field, so COPY FROM loads the empty strings as
NULL.
val pgReader = csvReader {
nullFieldIndicator = CsvNullFieldIndicator.EMPTY_SEPARATORS
}
val pgWriter = csvWriter {
dialect = CsvDialect(lineTerminator = "\n") // LF, as COPY TO STDOUT writes
quoteMode = WriteQuoteMode.ALL
}
val csv = pgWriter.writeAllNullable(listOf(listOf("1", null, "")))
// "1",,""
pgReader.readAllNullable(csv) // [[1, null, ]]./gradlew dokkaGeneratePublicationHtml — outputs
HTML to build/dokka/html/.Contributions, issues and feature requests are welcome!
If you have questions, ask away in Kotlin Slack's kotlin-csv room.
git clone git@github.com:jsoizo/kotlin-csv.git
cd kotlin-csv
./gradlew checkCopyright © 2024 jsoizo. This project is licensed under Apache 2.0.
This project was originally created by @doyaaaaaken. The initial work and contributions are greatly appreciated.