Skip to content

README.md

Latest commit

 

History

History
172 lines (123 loc) · 5 KB

README.md

File metadata and controls

172 lines (123 loc) · 5 KB

kaml

Build Status Coverage License Maven Central

What is this?

This library adds YAML support to kotlinx.serialization.

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)

Features

  • Supports most major YAML features:

  • 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: myteam@mycompany.com
    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: myteam@mycompany.com
      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.

Referencing kaml

Add the following to your Gradle build script:

implementation("com.charleskorn.kaml:kaml:<version number here>")

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.

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