kaml

YAML support for kotlinx.serialization

Programming language: Kotlin

License: Apache License 2.0

Tags: Misc    

Latest version: v0.26.0

README

kaml

What is this?

This library adds YAML support to kotlinx.serialization.

Currently, only Kotlin/JVM is supported. (Follow this issue for a discussion of adding support for other targets.)

YAML version 1.2 is supported.

Usage samples

Parsing from YAML to a Kotlin object

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

Serializing from a Kotlin object to 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)

Parsing into YamlNode

It is possible to parse a string or an InputStream directly into a YamlNode, for example the following code prints 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
)

Referencing kaml

Add the following to your Gradle build script:

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:<version number here>" // Get the latest version number from 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:<version number here>") // Get the latest version number from https://github.com/charleskorn/kaml/releases/latest
}

Check the releases page for the latest release information, and the Maven Central page for examples of how to reference the library in other build systems.

Features

• Supports most major YAML features:

  • Scalars, including strings, booleans, integers and floats
  • Sequences (lists)
  • Maps
  • Nulls
  • Aliases and anchors, including merging aliases to form one map

• Supports parsing YAML to Kotlin objects (deserializing) and writing Kotlin objects as YAML (serializing)

• Supports kotlinx.serialization's polymorphism for sealed and unsealed types

Two styles are available (set YamlConfiguration.polymorphismStyle when creating an instance of Yaml):

• using YAML tags to specify the type:

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

• using a type property to specify the type:

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

The fragments above could be generated with:

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

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

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

• Supports Docker Compose-style extension fields

  x-common-labels: &common-labels
    labels:
      owned-by: [email protected]
      cost-centre: myteam

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

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

    # server-b and server-c are equivalent
    server-c:
      labels:
        owned-by: [email protected]
        cost-centre: myteam
      kind: backend

Specify the extension prefix by setting YamlConfiguration.extensionDefinitionPrefix when creating an instance of Yaml (eg. "x-" for the example above).

Extensions can only be defined at the top level of a document, and only if the top level element is a map or object. Any key starting with the extension prefix must have an anchor defined (&...) and will not be included in the deserialised value.

Contributing to kaml

Pull requests and bug reports are always welcome!

kaml uses Batect to simplify development environment setup:

• To build the library: ./batect build
• To run the tests and static analysis tools: ./batect check
• To run the tests and static analysis tools continuously: ./batect continuousCheck

Other commands are available by running ./batect --list-tasks

Reference links

• YAML 1.2 Specification
• snakeyaml-engine, the YAML parser this library is based on