Need help with kaml?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

charleskorn
224 Stars 18 Forks Apache License 2.0 479 Commits 4 Opened issues

Description

YAML support for kotlinx.serialization

Services available

!
?

Need anything else?

Contributors list

# 76,855
Kotlin
golang
cheat-s...
gitlab
302 commits
# 26
netlify
TypeScr...
GraphQL
javascr...
109 commits
# 645,165
TeX
circuit...
tikz
Shell
6 commits
# 522,203
Kotlin
Shell
Java
reactor
4 commits
# 268,737
Shell
cbor
seriali...
Kotlin
1 commit
# 303,114
C++
Shell
crypto
secret-...
1 commit
# 13,300
scalajs
Apache ...
elastic...
React
1 commit
# 569,598
Java
Kotlin
Shell
refacto...
1 commit
# 326,787
HTML
Shell
flashca...
Android
1 commit

kaml

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

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
)

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

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

println(result)

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

Two styles are available (set

YamlConfiguration.polymorphismStyle
when creating an instance of
Yaml
):
  • using YAML tags to specify the type:

    servers:
      - !
        hostname: a.mycompany.com
      - !
        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)

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

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

println(result)

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

servers: server-a: <<: kind: frontend server-b: backend server-b and server-c are equivalent server-c: labels: owned-by: myteam cost-centre:>

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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.