Merge pull request #13 from brudaswen/featue/use-CsvBuilder

Csv configuration via builder pattern

Author: brudaswen

CHANGELOG.md

@@ -6,6 +6,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.0] - 2020-11-08
+### Added
+- `Csv {}` builder function to configure Csv instance.
+
+### Changed
+- Use Unix newline (`\n`) as default `recordSeparator` (use `Csv { recordSeparator = "\r\n" }` or
+  `Csv.Rfc4180` for old behavior).
+- Using `QuoteMode.NONE` requires `escapeChar` to be set manually (use
+  `Csv { quoteMode = QuoteMode.NONE ; escapeChar = '\\' }` for old behavior).
+- Last line in CSV is *always* ignored when empty.
+- Throws `SerializationException` instead of `IllegalStateException` in case of error.
+
+### Removed
+- Removed `CsvConfiguration` (use `Csv {}` builder function instead).
+- Removed `Csv.default` (use `Csv { recordSeparator = "\r\n" }` instead).
+- Removed `Csv.rfc4180` (use `Csv.Rfc4180` instead).
+- Removed `Csv.excel` (use `Csv.Rfc4180` instead).
+
 ## [1.1.0] - 2020-11-08
 ### Added
 - Support `ignoreUnknownColumns`.

README.md

@@ -32,7 +32,6 @@ import kotlinx.serialization.ExperimentalSerializationApi
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.builtins.ListSerializer
 import kotlinx.serialization.csv.Csv
-import kotlinx.serialization.csv.CsvConfiguration
 
 @Serializable
 data class Person(val nickname: String, val name: String?, val appearance: Appearance)
@@ -45,7 +44,7 @@ enum class Gender { MALE, FEMALE }
 
 @OptIn(ExperimentalSerializationApi::class)
 fun main() {
-    val csv = Csv(CsvConfiguration(hasHeaderRecord = true))
+    val csv = Csv { hasHeaderRecord = true }
 
     val records = listOf(
         Person("Neo", "Thomas A. Anderson", Appearance(Gender.MALE, 37, 1.86)),
@@ -61,7 +60,7 @@ fun main() {
         nickname,appearance.gender,appearance.height,appearance.age,name
         Neo,MALE,1.86,37,Thomas A. Anderson
         Trinity,FEMALE,1.74,,
-    """.trimIndent().replace("\n", "\r\n")
+    """.trimIndent()
     val parsed = csv.decodeFromString(ListSerializer(Person.serializer()), input)
     println(parsed)
     // [
@@ -70,26 +69,25 @@ fun main() {
     // ]
 }
 ```
-
 ### Pre-defined CSV formats
-The library comes with multiple pre-defined formats that can be used out of the box.
+The library comes with multiple pre-defined Csv formats that can be used out of the box.
 
 | Config                 | Description |
 |---                     |---          |
-| `default`              | Standard Comma Separated Value format, as for `rfc4180` but allowing empty lines. *Format is unstable and may change in upcoming versions.* |
-| `rfc4180`              | Comma separated format as defined by [RFC 4180](http://tools.ietf.org/html/rfc4180). |
-| `excel`                | Excel file format (using a comma as the value delimiter). |
+| `Csv.Default`          | Standard Comma Separated Value format, as for `Rfc4180` but using Unix newline (`\n`) as record separator and ignoring empty lines. *Format is unstable and may change in upcoming versions.* |
+| `Csv.Rfc4180`          | Comma separated format as defined by [RFC 4180](http://tools.ietf.org/html/rfc4180). |
 
 ### Configuration
-CSV serialization and parsing options can be changed by providing a custom `CsvConfiguration`.
+CSV serialization and parsing options can be changed by configuring the `Csv` instance during
+initialization via the `Csv { }` builder function.
 
 | Option                 | Default Value  | Description |
 |---                     |---             | ---         |
 | `delimiter`            | `,`            | The delimiter character between columns. |
-| `recordSeparator`      | `\r\n`         | The record separator. |
+| `recordSeparator`      | `\n`           | The record separator. |
 | `quoteChar`            | `"`            | The quote character used to quote column values. |
 | `quoteMode`            | `MINIMAL`      | The quote mode used to decide if a column value should get quoted.<ul><li>`ALL`: Quotes *all* fields.</li><li>`ALL_NON_NULL`: Quotes all *non-null fields* and *fields which contain special characters*.</li><li>`ALL_NON_NUMERIC`: Quotes all *non-numeric fields* and *fields which contain special characters*.</li><li>`MINIMAL`: Quotes *fields which contain special characters*.</li><li>`NONE`: *Never* quotes fields (requires `CsvConfiguration.escapeChar` to be set).</li></ul> |
-| `escapeChar`           | `null` (`\\` for `QuoteMode.NONE`) | The escape character used to escape reserved characters in a column value. |
+| `escapeChar`           | `null`         | The escape character used to escape reserved characters in a column value. |
 | `nullString`           | *empty string* | The value to identify `null` values. |
 | `ignoreEmptyLines`     | `true`         | Ignore empty lines during parsing. |
 | `hasHeaderRecord`      | `false`        | First line is header record. |

application/src/main/kotlin/de/brudaswen/kotlinx/serialization/example/Example.kt

@@ -4,7 +4,6 @@ import kotlinx.serialization.ExperimentalSerializationApi
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.builtins.ListSerializer
 import kotlinx.serialization.csv.Csv
-import kotlinx.serialization.csv.CsvConfiguration
 
 @Serializable
 data class Person(val nickname: String, val name: String?, val appearance: Appearance)
@@ -17,7 +16,7 @@ enum class Gender { MALE, FEMALE }
 
 @OptIn(ExperimentalSerializationApi::class)
 fun main() {
-    val csv = Csv(CsvConfiguration(hasHeaderRecord = true))
+    val csv = Csv { hasHeaderRecord = true }
 
     val records = listOf(
         Person("Neo", "Thomas A. Anderson", Appearance(Gender.MALE, 37, 1.86)),
@@ -33,7 +32,7 @@ fun main() {
         nickname,appearance.gender,appearance.height,appearance.age,name
         Neo,MALE,1.86,37,Thomas A. Anderson
         Trinity,FEMALE,1.74,,
-    """.trimIndent().replace("\n", "\r\n")
+    """.trimIndent()
     val parsed = csv.decodeFromString(ListSerializer(Person.serializer()), input)
     println(parsed)
     // [

gradle.properties

@@ -1,4 +1,4 @@
-version=1.1.1-SNAPSHOT
+version=2.0.0-SNAPSHOT
 kotlin.code.style=official
 
 # Disable generation of metadata sha256/sha512 checksum

library/src/main/kotlin/kotlinx/serialization/csv/Csv.kt

@@ -1,31 +1,30 @@
 package kotlinx.serialization.csv
 
 import kotlinx.serialization.*
-import kotlinx.serialization.csv.CsvConfiguration.Companion.rfc4180
+import kotlinx.serialization.csv.config.CsvBuilder
+import kotlinx.serialization.csv.config.CsvConfig
 import kotlinx.serialization.csv.decode.CsvReader
 import kotlinx.serialization.csv.decode.RootCsvDecoder
 import kotlinx.serialization.csv.decode.StringSource
 import kotlinx.serialization.csv.encode.RootCsvEncoder
-import kotlinx.serialization.modules.EmptySerializersModule
 import kotlinx.serialization.modules.SerializersModule
 
 /**
  * The main entry point to work with CSV serialization.
  *
  * It is typically used by constructing an application-specific instance, with configured CSV-specific behaviour
- * ([configuration] parameter) and, if necessary, registered
- * custom serializers (in [SerializersModule] provided by [context] parameter).
+ * and, if necessary, registered in [SerializersModule] custom serializers.
+ * `Csv` instance can be configured in its `Csv {}` factory function using [CsvBuilder].
+ * For demonstration purposes or trivial usages, Csv [companion][Csv.Default] can be used instead.
  *
  * Then constructed instance can be used either as regular [SerialFormat] or [StringFormat].
- *
- * @param configuration CSV settings used during parsing/serialization.
- * @param serializersModule Serialization module settings (e.g. custom serializers).
  */
 @ExperimentalSerializationApi
-class Csv(
-    internal val configuration: CsvConfiguration,
-    override val serializersModule: SerializersModule = EmptySerializersModule
-) : SerialFormat, StringFormat {
+sealed class Csv(internal val config: CsvConfig) : SerialFormat, StringFormat {
+
+    override val serializersModule: SerializersModule
+        get() = config.serializersModule
+
     /**
      * Serialize [value] into CSV record(s).
      *
@@ -45,60 +44,51 @@ class Csv(
      * @param string The CSV string to parse.
      */
     override fun <T> decodeFromString(deserializer: DeserializationStrategy<T>, string: String): T {
-        val reader = CsvReader(StringSource(string), configuration)
+        val reader = CsvReader(StringSource(string), config)
         val input = RootCsvDecoder(this, reader)
         val result = input.decodeSerializableValue(deserializer)
 
         require(reader.isDone) { "Reader has not consumed the whole input: $reader" }
         return result
     }
 
-    companion object : StringFormat {
+    internal class Impl(config: CsvConfig) : Csv(config)
 
-        /**
-         * Standard Comma Separated Value format, as for [rfc4180] but allowing empty lines.
-         *
-         * Settings are:
-         * - [CsvConfiguration.delimiter] = `','`
-         * - [CsvConfiguration.quoteChar] = `'"'`
-         * - [CsvConfiguration.recordSeparator] = `"\r\n"`
-         * - [CsvConfiguration.ignoreEmptyLines] = `true`
-         */
-        val default = Csv(CsvConfiguration.default)
+    /**
+     * Standard *Comma Separated Value* format.
+     *
+     * Settings are:
+     * - [CsvConfig.delimiter] = `','`
+     * - [CsvConfig.quoteChar] = `'"'`
+     * - [CsvConfig.recordSeparator] = `"\n"`
+     * - [CsvConfig.ignoreEmptyLines] = `true`
+     */
+    companion object Default : Csv(CsvConfig.Default) {
 
         /**
-         * Comma separated format as defined by [RFC 4180](http://tools.ietf.org/html/rfc4180).
+         * [RFC 4180](http://tools.ietf.org/html/rfc4180) *Comma Separated Value* format.
          *
          * Settings are:
-         * - [CsvConfiguration.delimiter] = `','`
-         * - [CsvConfiguration.quoteChar] = `'"'`
-         * - [CsvConfiguration.recordSeparator] = `"\r\n"`
-         * - [CsvConfiguration.ignoreEmptyLines] = `false`
+         * - [CsvConfig.delimiter] = `','`
+         * - [CsvConfig.quoteChar] = `'"'`
+         * - [CsvConfig.recordSeparator] = `"\r\n"`
+         * - [CsvConfig.ignoreEmptyLines] = `false`
          */
-        val rfc4180 = Csv(CsvConfiguration.rfc4180)
-
-        override val serializersModule: SerializersModule
-            get() = default.serializersModule
-
-        /**
-         * Serialize [value] into CSV record(s) using [CsvConfiguration.default].
-         *
-         * @param serializer The serializer used to serialize the given object.
-         * @param value The [Serializable] object.
-         */
-        override fun <T> encodeToString(serializer: SerializationStrategy<T>, value: T): String =
-            default.encodeToString(serializer, value)
+        val Rfc4180: Csv
+            get() = Impl(CsvConfig.Rfc4180)
+    }
+}
 
-        /**
-         * Parse CSV [string] into [Serializable] object using [CsvConfiguration.default].
-         *
-         * @param deserializer The deserializer used to parse the given CSV string.
-         * @param string The CSV string to parse.
-         */
-        override fun <T> decodeFromString(
-            deserializer: DeserializationStrategy<T>,
-            string: String
-        ): T =
-            default.decodeFromString(deserializer, string)
+/**
+ * Creates an instance of [Csv] configured from the optionally given [Csv instance][from] and
+ * adjusted with [action].
+ */
+@ExperimentalSerializationApi
+@Suppress("FunctionName")
+fun Csv(from: Csv = Csv.Default, action: CsvBuilder.() -> Unit): Csv {
+    val conf = CsvBuilder(from.config).run {
+        action()
+        build()
     }
+    return Csv.Impl(conf)
 }