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
  

  通过在创建Yaml实例时设置YamlConfiguration.extensionDefinitionPrefix来指定扩展前缀（例如，上面示例中的"x-"）。

  扩展只能在文档的顶层定义，并且只有当顶层元素是映射或对象时才可以定义。任何以扩展前缀开头的键必须定义一个锚点（&...），并且不会包含在反序列化的值中。

为kaml做贡献

随时欢迎提交拉取请求和错误报告！

kaml使用Gradle进行构建和测试：

• 构建库：./gradlew assemble
• 运行测试和静态分析工具：./gradlew check
• 持续运行测试和静态分析工具：./gradlew --continuous check

参考链接

• YAML 1.2规范
• snakeyaml-engine，这个库基于的YAML解析器