Skip to content

Commit

Permalink
Update CHANGELOG and README
Browse files Browse the repository at this point in the history
  • Loading branch information
Sven Obser committed Dec 13, 2024
1 parent 0d497cf commit 9bff21c
Show file tree
Hide file tree
Showing 2 changed files with 60 additions and 23 deletions.
33 changes: 32 additions & 1 deletion CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,32 @@
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [2.1.0] - 2024-14-13

### Changed

- Update to Kotlin 2.1.0.
- Update to Kotlinx-Serialization 1.7.3.
- Make `CsvConfig` public.

### Removed

- Removed `Csv(from: Csv, action: CsvBuilder.() -> Unit)` (use `from.configure {}` instead).

## [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
Expand All @@ -19,35 +35,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- 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`.

## [1.0.2] - 2020-10-11

### Changed

- Update to *Kotlin Serialization* `1.0.0`.

## [1.0.1] - 2020-09-30

### Added

- Source compatibility with Java 8.

### Changed

- Update to *Kotlin Serialization* `1.0.0-RC2`.

## [1.0.0] - 2020-09-24

### Changed

- Compatibility with *Kotlin Serialization* `1.0.0-RC`.

## [0.2.0] - 2020-05-24

### Changed

- Compatibility with *Kotlin Serialization* `0.20.0`.
- (De-)Serialization of sealed classes no longer reads/writes columns for objects.
- String for `kotlin.Unit` can no longer be provided and the `Unit` object is handled as any other object.
- String for `kotlin.Unit` can no longer be provided and the `Unit` object is handled as any other object.

## [0.1.0] - 2020-02-21

### Added

- Initial release for *Kotlin Serialization* `0.14.0`.
50 changes: 28 additions & 22 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,24 +9,27 @@
Library to easily use *Kotlin Serialization* to serialize/parse CSV.

All types of record classes are supported (primitives, classes, enums, nested classes, ...).
However, CSV serialization works best if the column number if fixed. So, collections (lists, sets, maps) and
However, CSV serialization works best if the column number if fixed. So, collections (lists, sets, maps) and
open classes should be avoided.

## Gradle Dependencies

```kotlin
// Kotlin Serialization CSV
implementation("de.brudaswen.kotlinx.serialization:kotlinx-serialization-csv:2.0.0")
implementation("de.brudaswen.kotlinx.serialization:kotlinx-serialization-csv:2.1.0")

// Kotlin Serialization is added automatically, but can be added to force a specific version
implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.0.0")
implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.7.3")
```

## Usage
First configure your project according to the

First configure your project according to the
[documentation](https://github.com/Kotlin/kotlinx.serialization#setup)
of the *Kotlin Serialization* library.

### CSV Example

```kotlin
import kotlinx.serialization.ExperimentalSerializationApi
import kotlinx.serialization.Serializable
Expand Down Expand Up @@ -69,37 +72,40 @@ fun main() {
// ]
}
```

### Pre-defined CSV formats

The library comes with multiple pre-defined Csv formats that can be used out of the box.

| Config | Description |
|--- |--- |
| `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). |
| Config | Description |
|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `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 configuring the `Csv` instance during
initialization via the `Csv { }` builder function.

| Option | Default Value | Description |
|--- |--- | --- |
| `delimiter` | `,` | The delimiter character between columns. |
| `recordSeparator` | `\n` | The record separator. |
| `quoteChar` | `"` | The quote character used to quote column values. |
| Option | Default Value | Description |
|------------------------|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `delimiter` | `,` | The delimiter character between columns. |
| `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` | 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. |
| `headerSeparator` | `.` | Character that is used to separate hierarchical header names. |
| `ignoreUnknownColumns` | `false` | Ignore unknown columns (only has effect when `hasHeaderRecord` is enabled). |
| `hasTrailingDelimiter` | `false` | If records end with a trailing `delimiter`. |
| `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. |
| `headerSeparator` | `.` | Character that is used to separate hierarchical header names. |
| `ignoreUnknownColumns` | `false` | Ignore unknown columns (only has effect when `hasHeaderRecord` is enabled). |
| `hasTrailingDelimiter` | `false` | If records end with a trailing `delimiter`. |

## Requirements

| Dependency | Versions |
|--- |--- |
| *Kotlin Serialization* | 1.0.0 |
|------------------------|----------|
| *Kotlin Serialization* | 2.1.0 |

## License

Expand Down

0 comments on commit 9bff21c

Please sign in to comment.