Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/him188/yamlkt
Multiplatform YAML parser & serializer for kotlinx.serialization written in pure Kotlin
https://github.com/him188/yamlkt
kotlin multiplatform serialization yaml
Last synced: 9 days ago
JSON representation
Multiplatform YAML parser & serializer for kotlinx.serialization written in pure Kotlin
- Host: GitHub
- URL: https://github.com/him188/yamlkt
- Owner: Him188
- License: apache-2.0
- Created: 2020-03-05T14:54:59.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-06-24T07:48:55.000Z (5 months ago)
- Last Synced: 2024-10-15T16:40:48.490Z (24 days ago)
- Topics: kotlin, multiplatform, serialization, yaml
- Language: Kotlin
- Homepage:
- Size: 589 KB
- Stars: 132
- Watchers: 7
- Forks: 14
- Open Issues: 30
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# YamlKt
[](https://bintray.com/mamoe/yamlkt/yamlkt/)
[kotlinx.serialization]: https://github.com/kotlin/kotlinx.serialization
Fast multi-platform YAML with comments support for [kotlinx.serialization]
This project is in alpha state.
## Setup
Third-party formats for [kotlinx.serialization] is strongly dependent on the versions of `kotlinx-serialization-core` and Kotlin compiler.
The table below shows recommended version parings.
Note that normally you may use higher versions within the minor version range, e.g. preferring `1.3.3` or `1.3.0` over `1.3.2`.
| yamlkt | Kotlin | kotlinx-serialization-core |
|:------:|:------:|:--------------------------:|
| 0.3.3 | 1.3.70 | 0.20.0 |
| 0.5.3 | 1.4.0 | 1.0.0-RC |
| 0.6.0 | 1.4.10 | 1.0.0-RC2 |
| 0.8.0 | 1.4.10 | 1.0.1 |
| 0.9.0 | 1.4.30 | 1.1.0-RC |
| 0.10.2 | 1.5.20 | 1.2.1 |
| 0.10.2 | 1.5.31 | 1.3.0 |
| 0.11.0 | 1.6.21 | 1.3.3 |
| 0.12.0 | 1.6.21 | 1.3.3 |
| 0.12.0 | 1.7.10 | 1.3.3 |
| 0.13.0 | 1.8.0 | 1.5.0 |
#### Gradle
```kotlin
repositories {
mavenCentral()
}
```
```kotlin
dependencies {
implementation("net.mamoe.yamlkt:yamlkt:0.13.0")
}
```
**If your project is multiplatform, you need only to add this dependency for commonMain:**
```kotlin
commonMain {
dependencies {
implementation("net.mamoe.yamlkt:yamlkt:0.13.0")
}
}
```
#### Maven
Only JVM target is available for Maven.
```xml
net.mamoe.yamlkt
yamlkt-jvm
0.13.0
```
## Overview
This library supports:
- fast deserializing YAML text to a structured object
- contextual and polymorphic serialization: `@Contextual`, `@Polymorphic`
- dynamic types: `YamlDynamicSerializer` which works on `Any`
- `YamlElement` wrapper classes, allowing `YamlMap.getInt`, `YamlMap.getLong`
- comments encoding (Using annotation `Comment`)
The features that aren't yet supported:
- Anchors (`*`, `&`)
- Explicit types (e.g. `!!map`)
- Multiline string (`|` and `>` are partially supported; `\` is not)
## Usage
### Serialize / deserialize with compiled serializers
This is the fastest and recommended way.
```kotlin
@Serializable
data class Test(
val test: String,
val optional: String = "optional", // Having default value means optional
val nest: Nested,
val list: List
) {
@Serializable
data class Nested(
val numberCast: Int
)
}
println(Yaml.parse(Test.serializer(), """
test: testString
nest:
numberCast: 0xFE
list: [str, "str2"]
"""))
```
### Contextual serializing / deserializing
YamlKt provides a contextual serializer `YamlDynamicSerializer` for `Any`
and `YamlNullDynamicSerializer` for `Any?`
By default, `YamlDynamicSerializer` is installed to `Any`.
You can start by using `@Contextual`:
```kotlin
@Serializable
data class Test(
val any: @Contextual Any
)
Yaml.parse(Test.serializer(), yamlText)
```
For input YAML text:
```yaml
test: { key1: v1, key2: [v2, v3, v4] }
```
Alternatively, you can deserialize without any class:
```kotlin
val map: Map = Yaml.parseMap("""test: { key1: v1, key2: [v2, v3, v4] }""")
```
### `YamlElement`
`YamlElement` is a type-safe way to deserialize without descriptors.
```kotlin
val map: YamlMap = Yaml.decodeYamlMapFromString("""test: { key1: v1, key2: [v2, v3, v4] }""")
```
### Comments
Annotate your comments to a field(property) using `@Comment`:
Example:
```kotlin
@Serializable
data class User(
@Comment("The name of the user")
val name: String = "value"
)
```
gives yaml text:
```yaml
# The name of the user
name: ""
```