kaml

这是什么？

这个库为kotlinx.serialization添加了YAML支持。

目前，仅完全支持Kotlin/JVM。

Kotlin/JS和Kotlin/Wasm支持被视为高度实验性的。它目前尚未完全功能化，可能随时被移除或修改。

（关于添加对其他目标的支持的讨论，请关注这个issue。）

支持YAML 1.2版本。

使用示例

从YAML解析为Kotlin对象

@Serializable
data class Team(
    val leader: String,
    val members: List<String>
)

val input = """
        leader: Amy
        members:
          - Bob
          - Cindy
          - Dan
    """.trimIndent()

val result = Yaml.default.decodeFromString(Team.serializer(), input)

println(result)

从Kotlin对象序列化为YAML

@Serializable
data class Team(
    val leader: String,
    val members: List<String>
)

val input = Team("Amy", listOf("Bob", "Cindy", "Dan"))

val result = Yaml.default.encodeToString(Team.serializer(), input)

println(result)

解析为YamlNode

可以直接将字符串或InputStream解析为YamlNode，例如以下代码输出Cindy。

val input = """
        leader: Amy
        members:
          - Bob
          - Cindy
          - Dan
    """.trimIndent()

val result = Yaml.default.parseToYamlNode(input)

println(
    result
        .yamlMap.get<YamlList>("members")!![1]
        .yamlScalar
        .content
)

引用kaml

在Gradle构建脚本中添加以下内容：

Groovy DSL

plugins {
    id 'org.jetbrains.kotlin.jvm' version '1.4.20'
    id 'org.jetbrains.kotlin.plugin.serialization' version '1.4.20'
}

dependencies {
  implementation "com.charleskorn.kaml:kaml:<在此处填写版本号>" // 从https://github.com/charleskorn/kaml/releases/latest获取最新版本号
}

Kotlin DSL

plugins {
    kotlin("jvm") version "1.4.20"
    kotlin("plugin.serialization") version "1.4.20"
}

dependencies {
  implementation("com.charleskorn.kaml:kaml:<在此处填写版本号>") // 从https://github.com/charleskorn/kaml/releases/latest获取最新版本号
}

查看发布页面获取最新的发布信息，以及Maven Central页面获取在其他构建系统中引用该库的示例。

功能

支持大多数主要的YAML功能：
- 标量，包括字符串、布尔值、整数和浮点数
- 序列（列表）
- 映射
- 空值
- 别名和锚点，包括合并别名以形成一个映射
支持将YAML解析为Kotlin对象（反序列化）和将Kotlin对象写入为YAML（序列化）

支持kotlinx.serialization的多态性，适用于密封和非密封类型

有两种可用的样式（在创建Yaml实例时设置YamlConfiguration.polymorphismStyle）：

使用YAML标签指定类型：

servers:
  - !<frontend>
    hostname: a.mycompany.com
  - !<backend>
    database: db-1

使用type属性指定类型：

servers:
  - type: frontend
    hostname: a.mycompany.com
  - type: backend
    database: db-1

上述片段可以通过以下方式生成：

@Serializable
sealed class Server {
  @SerialName("frontend")
  @Serializable
  data class Frontend(val hostname: String) : Server()

  @SerialName("backend")
  @Serializable
  data class Backend(val database: String) : Server()
}

@Serializable
data class Config(val servers: List<Server>)

val config = Config(listOf(
  Frontend("a.mycompany.com"),
  Backend("db-1")
))

val result = Yaml.default.encodeToString(Config.serializer(), config)

println(result)

支持Docker Compose风格的扩展字段

x-common-labels: &common-labels
  labels:
    owned-by: myteam@mycompany.com
    cost-centre: myteam

servers:
  server-a:
    <<: *common-labels
    kind: frontend

  server-b:
    <<: *common-labels
    kind: backend

  # server-b 和 server-c 是等价的
  server-c:
    labels:
      owned-by: myteam@mycompany.com
      cost-centre: myteam
    kind: backend