Fast multi-platform YAML with comments support for kotlinx.serialization
This project is in alpha state.
Third-party formats for kotlinx.serialization is strongly dependent on the versions of kotlinx-serialization-core
and Kotlin compiler.
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 |
repositories {
mavenCentral()
}
dependencies {
implementation("net.mamoe.yamlkt:yamlkt:0.10.2")
}
If your project is multiplatform, you need only to add this dependency for commonMain:
commonMain {
dependencies {
implementation("net.mamoe.yamlkt:yamlkt:0.10.2")
}
}
Only JVM target is available for Maven.
<dependency>
<groupId>net.mamoe.yamlkt</groupId>
<artifactId>yamlkt-jvm</artifactId>
<version>0.10.2</version>
</dependency>
This library supports:
- fast deserializing YAML text to a structured object
- contextual and polymorphic serialization:
@Contextual
,@Polymorphic
- dynamic types:
YamlDynamicSerializer
which works onAny
YamlElement
wrapper classes, allowingYamlMap.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)
This approach is fastest and recommended way as the type is already provided.
@Serializable
data class Test(
val test: String,
val optional: String = "optional", // Having default value means optional
val nest: Nested,
val list: List<String>
) {
@Serializable
data class Nested(
val numberCast: Int
)
}
println(Yaml.parse(Test.serializer(), """
test: testString
nest:
numberCast: 0xFE
list: [str, "str2"]
"""))
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
:
@Serializable
data class Test(
val any: @Contextual Any
)
Yaml.parse(Test.serializer(), yamlText)
For input YAML text:
test: { key1: v1, key2: [v2, v3, v4] }
Alternatively, you can deserialize without any class:
val map: Map<String?, Any?> = Yaml.parseMap("""test: { key1: v1, key2: [v2, v3, v4] }""")
YamlElement
is a type-safe way to deserialize without descriptors.
val map: YamlMap = Yaml.decodeYamlMapFromString("""test: { key1: v1, key2: [v2, v3, v4] }""")
Annotate your comments to a field(property) using @Comment
:
Example:
@Serializable
data class User(
@Comment("The name of the user")
val name: String = "value"
)
gives yaml text:
# The name of the user
name: ""