YamlKt

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.

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

Gradle

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")
    }
}

Maven

Only JVM target is available for Maven.

<dependency>
    <groupId>net.mamoe.yamlkt</groupId>
    <artifactId>yamlkt-jvm</artifactId>
    <version>0.10.2</version>
</dependency>

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)

Learn to use

Serialize / deserialize with compiled serializers

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"]
"""))

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:

@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] }""")

Comments

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

antohaby / yamlkt