net.mamoe.yamlkt:yamlkt-metadata

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.

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

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

Maven

Only JVM target is available for Maven.

<dependency>
    <groupId>net.mamoe.yamlkt</groupId>
    <artifactId>yamlkt-jvm</artifactId>
    <version>0.13.0</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)

Usage

Serialize / deserialize with compiled serializers

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

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