Add YamlNamingStrategy

[russellbanks]

Adds YamlNamingStrategy from #398 with pre-defined snake_case, kebab-case, PascalCase, and camelCase.

The SnakeCase implementation has been taken and modified from JsonNamingStrategy.kt in KotlinX Serialization.

Usage

YamlConfiguration(
    yamlNamingStrategy = YamlNamingStrategy.PascalCase  // CamelCase, SnakeCase, KebabCase
),

Example data class:

@Serializable
data class Data(
   val propertyName: String,
   val otherName: String
)

Example Yaml:

PropertyName: "value"
OtherName: "value"

This will successfully serialize and deserialize without the need for @SerialName on every value in the data class.

Custom naming strategy

Converts to lowercase and capitalises first letter:

YamlConfiguration(
    yamlNamingStrategy = { it.lowercase().replaceFirstChar(Char::titlecase) }
),

Converts to uppercase

YamlConfiguration(
    yamlNamingStrategy = String::uppercase
),

Note

As @SerialName is resolved at compile time rather than runtime, using a YamlNamingStrategy will ignore the casing of all @SerialName annotations.

Closes #398

[charleskorn]

Thank you for the PR @russellbanks!

[kenyee]

any idea when this will be merged?
Could use this on a project I'm working on :-)

[charleskorn]

any idea when this will be merged? Could use this on a project I'm working on :-)

This is currently an incomplete draft - it'll be merged when it's ready :)

If you'd like to see it merged sooner, I'm sure @russellbanks would love some help.

[russellbanks]

It's the linking up of the algorithms to the serial names that would be helpful to have some pointers for :)

[charleskorn]

It's the linking up of the algorithms to the serial names that would be helpful to have some pointers for :)

This is where property names are emitted - so that should be the place to perform the transformation.

[russellbanks]

@charleskorn This is ready for review I think!

One thing that I should note is that applying a naming strategy will ignore the casing of all @SerialName annotations as that is resolved at compile time rather than runtime, meaning there's no way to know if it was applied or not. Naming strategies should cover most naming cases in Yaml and in the rare case that there is inconsistent naming, @SerialName or a custom naming strategy can be used instead.

[charleskorn]

Thanks for putting this together @russellbanks! Overall it's looking good.

[russellbanks]

@charleskorn I've made the requested changes! Let me know if there's anything else.

[charleskorn]

This is looking great, thanks again for this @russellbanks.

I've just noticed one more case that is missing a test: could you please add a test for the case where an unknown property is included in the YAML document being read? I want to make sure the exception includes the transformed names (from the naming strategy) rather than the property in the descriptor.

[russellbanks]

This is looking great, thanks again for this @russellbanks.

I've just noticed one more case that is missing a test: could you please add a test for the case where an unknown property is included in the YAML document being read? I want to make sure the exception includes the transformed names (from the naming strategy) rather than the property in the descriptor.

Well thought @charleskorn! I've been able to map that but this test case fails and I'm not sure how to map the YamlMap's entries.

context("given some input representing an object with an unknown key, using a naming strategy") {
    val input = "oneTwoThree: something".trimIndent()

    context("parsing that input") {
        it("throws an exception with the naming strategy applied") {
            val exception = shouldThrow<UnknownPropertyException> {
                Yaml(
                    configuration = YamlConfiguration(yamlNamingStrategy = YamlNamingStrategy.SnakeCase)
                ).decodeFromString(ComplexStructure.serializer(), input)
            }

            exception.asClue {
                it.message shouldBe "Unknown property 'one_two_three'. Known properties are: boolean, byte, char, double, enum, float, int, long, nullable, short, string"
                it.line shouldBe 1
                it.column shouldBe 1
                it.propertyName shouldBe "one_two_three"
                it.validPropertyNames shouldBe setOf("boolean", "byte", "char", "double", "enum", "float", "int", "long", "nullable", "short", "string")
                it.path shouldBe YamlPath.root.withMapElementKey("one_two_three", Location(1, 1))
            }
        }
    }
}

This is the test case that fails

it.path shouldBe YamlPath.root.withMapElementKey("one_two_three", Location(1, 1))

Expected :YamlPath(segments=[com.charleskorn.kaml.YamlPathSegment$Root@1ebcc98f, MapElementKey(key=one_two_three, location=Location(line=1, column=1))])
Actual   :YamlPath(segments=[com.charleskorn.kaml.YamlPathSegment$Root@1ebcc98f, MapElementKey(key=oneTwoThree, location=Location(line=1, column=1))])

[charleskorn]

I think the test is not quite right - the exception should contain the properties as they appear / would appear in YAML.

So this:

it.path shouldBe YamlPath.root.withMapElementKey("one_two_three", Location(1, 1))

should be:

it.path shouldBe YamlPath.root.withMapElementKey("oneTwoThree", Location(1, 1))

And the exception message should be something like Unknown property 'oneTwoThree'. Known properties are: boolean, byte, ...

[russellbanks]

@charleskorn I've done that and I have also tested this PR by publishing to Maven Local and it works well in my project :)

[charleskorn]

Thanks again for the PR @russellbanks!