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.
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 |
repositories {
mavenCentral()
}
dependencies {
implementation("net.mamoe.yamlkt:yamlkt:0.13.0")
}
If your project is multiplatform, you need only to add this dependency for commonMain:
commonMain {
dependencies {
implementation("net.mamoe.yamlkt:yamlkt:0.13.0")
}
}
Only JVM target is available for Maven.
<dependency>
<groupId>net.mamoe.yamlkt</groupId>
<artifactId>yamlkt-jvm</artifactId>
<version>0.13.0</version>
</dependency>
This library supports:
@Contextual
, @Polymorphic
YamlDynamicSerializer
which works on Any
YamlElement
wrapper classes, allowing YamlMap.getInt
, YamlMap.getLong
Comment
)The features that aren't yet supported:
*
, &
)!!map
)|
and >
are partially supported; \
is not)This is the fastest and recommended way.
@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
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: ""