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.

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:

• 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)

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 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: ""