Renovate library interface

[jsoizo]

Issue

#164

Summary

This PR implements the v2 public API redesign on top of the version_2_0_0 branch.

The change is intentionally breaking within the v2 line: it removes the legacy client / dsl.context API shape and replaces it with a smaller, immutable, lazy Sequence-based API under com.jsoizo.kotlincsv.

Design goals:

• separate CSV format definition from reader/writer behavior
• make public configuration immutable
• keep the core parser/writer pure and reusable
• separate core CSV conversion from file / stream I/O
• avoid carrying legacy compatibility layers into v2

Public API Shape

Entry points

API	Purpose
csvReader { ... }	DSL construction of CsvReader
csvReader(config: CsvReaderConfig)	construction from immutable config
csvWriter { ... }	DSL construction of CsvWriter
csvWriter(config: CsvWriterConfig)	construction from immutable config

Shared format model

data class CsvDialect(
    val delimiter: Char = ',',
    val quoteChar: Char = '"',
    val escapeChar: Char = '"',
    val lineTerminator: String = "\r\n",
)

CsvDialect represents CSV format itself and is shared by reader and writer. Reader/writer-specific behavior lives in their own config types.

Reader model

class CsvReader(val config: CsvReaderConfig = CsvReaderConfig()) {
    fun read(chars: Sequence<Char>): Sequence<List<String>>
    fun readAll(text: String): List<List<String>>
}

data class CsvReaderConfig(
    val dialect: CsvDialect = CsvDialect.RFC4180,
    val skipEmptyLine: Boolean = false,
    val insufficientFieldsRowBehaviour: InsufficientFieldsRowBehaviour =
        InsufficientFieldsRowBehaviour.ERROR,
    val excessFieldsRowBehaviour: ExcessFieldsRowBehaviour =
        ExcessFieldsRowBehaviour.ERROR,
)

Reader core has two entry points with the same parsing behavior:

• read(...): lazy API returning Sequence<List<String>>
• readAll(...): eager API materializing all rows into List<List<String>>

Exceptions are raised during terminal operations such as toList() or forEach() when using the lazy API.

Writer model

class CsvWriter(val config: CsvWriterConfig = CsvWriterConfig()) {
    fun write(rows: Sequence<List<String>>): Sequence<Char>
    fun writeAll(rows: List<List<String>>): String
}

data class CsvWriterConfig(
    val dialect: CsvDialect = CsvDialect.RFC4180,
    val outputLastLineTerminator: Boolean = true,
    val quoteMode: WriteQuoteMode = WriteQuoteMode.CANONICAL,
)

Writer core has the same lazy/eager split:

• write(...): lazy API returning Sequence<Char>
• writeAll(...): eager API materializing the encoded CSV as String

I/O API Shape

Core APIs do not own files or streams. I/O is provided as a thin outer layer.

For I/O-owned resources, read(path) { rows -> ... } keeps lazy sequence consumption inside the resource lifetime:

reader.read(path) { rows: Sequence<List<String>> ->
    rows.take(10).toList()
}

Eager helpers are also provided:

reader.readAll(path)
writer.write(rows, path)

The difference between read and readAll is lazy vs eager evaluation, not a different parsing model.

JVM-specific overloads provide File, InputStream, and OutputStream support. Common / JS APIs use kotlinx-io Path, Source, and Sink.

Breaking Changes Compared With origin/version_2_0_0

Removed

• legacy client package API
  • CsvFileReader
  • legacy CsvReader
  • legacy CsvWriter
  • BufferedLineReader
  • Reader
  • ICsvFileWriter
• legacy DSL package API
  • dsl.CsvReaderDsl
  • dsl.CsvWriterDsl
  • dsl.context.CsvReaderContext
  • dsl.context.CsvWriterContext
  • dsl.context.CsvWriteQuoteContext
• legacy parser facade
  • CsvParser
• legacy util surface
  • CSVException
  • Const
  • CsvDslMarker
  • Logger
  • LoggerNop

Added

• CsvDialect
• root DSL entry points:
  • csvReader { ... }
  • csvReader(config: CsvReaderConfig)
  • csvWriter { ... }
  • csvWriter(config: CsvWriterConfig)
• reader API:
  • CsvReader
  • CsvReaderConfig
  • CsvReaderConfigBuilder
  • InsufficientFieldsRowBehaviour
  • ExcessFieldsRowBehaviour
  • CsvHeader
  • common/JVM read I/O extensions
• writer API:
  • CsvWriter
  • CsvWriterConfig
  • CsvWriterConfigBuilder
  • WriteQuoteMode
  • common/JVM write I/O extensions
• new v2 documentation:
  • README.md rewrite
  • V2_MIGRATION_GUIDE.md
  • Module.md
• common / JVM / JS tests for the new API surface

Migration Sketch

Reader

Before:

val rows = csvReader {
    delimiter = '\t'
}.readAll(file)

After:

val reader = csvReader {
    dialect = CsvDialect.TSV
}

val rows = reader.readAll(path)

For lazy consumption:

reader.read(path) { rows ->
    rows.forEach { row ->
        // consume inside the block
    }
}

Writer

Before:

csvWriter {
    quote {
        mode = WriteQuoteMode.ALL
    }
}.writeAll(rows, file)

After:

val writer = csvWriter {
    dialect = CsvDialect.RFC4180
    quoteMode = WriteQuoteMode.ALL
}

writer.write(rows, path)

Public Functions

Top-level DSL entry points (commonMain)

Function	Signature
csvReader	csvReader(init: CsvReaderConfigBuilder.() -> Unit = {}): CsvReader
csvReader	csvReader(config: CsvReaderConfig): CsvReader
csvWriter	csvWriter(init: CsvWriterConfigBuilder.() -> Unit = {}): CsvWriter
csvWriter	csvWriter(config: CsvWriterConfig): CsvWriter

Core (commonMain)

Receiver	Function	Signature
CsvReader	read	read(chars: Sequence<Char>): Sequence<List<String>>
CsvReader	readAll	readAll(text: String): List<List<String>>
CsvWriter	write	write(rows: Sequence<List<String>>): Sequence<Char>
CsvWriter	writeAll	writeAll(rows: List<List<String>>): String
Sequence<List<String>>	withHeader	withHeader(...): Sequence<CsvHeader>

Reader I/O extensions (commonMain)

Function	Signature
CsvReader.read	read(source: Source, options, block): T
CsvReader.readAll	readAll(source: Source, options): List<List<String>>
CsvReader.readFromFile	readFromFile(path: Path, options, block): T
CsvReader.readFromFile	readFromFile(filePath: String, options, block): T
CsvReader.readAllFromFile	readAllFromFile(path: Path, options): List<List<String>>
CsvReader.readAllFromFile	readAllFromFile(filePath: String, options): List<List<String>>

Writer I/O extensions (commonMain)

Function	Signature
CsvWriter.write	write(rows: Sequence<List<String>>, sink: Sink, options)
CsvWriter.write	write(rows: List<List<String>>, sink: Sink, options)
CsvWriter.writeToFile	writeToFile(rows: Sequence<List<String>>, path: Path, options)
CsvWriter.writeToFile	writeToFile(rows: List<List<String>>, path: Path, options)
CsvWriter.writeToFile	writeToFile(rows: Sequence<List<String>>, filePath: String, options)
CsvWriter.writeToFile	writeToFile(rows: List<List<String>>, filePath: String, options)

JVM-only I/O extensions (jvmMain)

Function	Signature
CsvReader.readFromFile	readFromFile(file: File, charset, options, block): T
CsvReader.readAllFromFile	readAllFromFile(file: File, charset, options): List<List<String>>
CsvReader.read	read(stream: InputStream, charset, options, block): T
CsvReader.readAll	readAll(stream: InputStream, charset, options): List<List<String>>
CsvWriter.writeToFile	writeToFile(rows: Sequence<List<String>>, file: File, charset, options)
CsvWriter.writeToFile	writeToFile(rows: List<List<String>>, file: File, charset, options)
CsvWriter.write	write(rows: Sequence<List<String>>, stream: OutputStream, charset, options)
CsvWriter.write	write(rows: List<List<String>>, stream: OutputStream, charset, options)

Notes:

• options は Reader 側が CsvReadIoOptions、Writer 側が CsvWriteIoOptions。
• charset はすべて default "UTF-8"。
• block シグネチャは (Sequence<List<String>>) -> T。