Add comment support.

[Cybermaxke]

Adds support that descriptions of Items are added to saved configuration files. This is useful when auto-generating configuration files. Persisting custom comments between load and write isn't supported.

• Is disabled by default, to prevent breaking changes.
• Toml, Yaml and Hocon support.

TODO:

• Add spec level descriptions.
• Yaml
• Xml the current output structure isn't optimal for comments
• Other things?
• Still needs proper testing.

Given the following example:

fun main() {
    val config = Config {
        addSpec(DefSpec)
        enable(Feature.WRITE_DESCRIPTIONS_AS_COMMENTS)
    }

    Files.newBufferedWriter(Paths.get("test.toml")).use {
        config.toToml.toWriter(it)
        it.flush()
    }
}

object DefSpec : ConfigSpec() {
    val type by optional(default = "value1", description = "My awesome description")
    val other by optional(default = "value2", description = "My other description,\nwith multiple lines")

    object Nested : ConfigSpec("nested") {
        val values by optional(default = arrayOf("1", "two"), description = "This is an array")
        val map by optional(default = mapOf("key" to "value"), description = "A map")
        val intArray2d by optional(default = arrayListOf(intArrayOf(1, 2), intArrayOf(3, 4)), description = "2D int array")
    }
}

Outputs:

[def]

# My awesome description
type = "value1"

# My other description,
# with multiple lines
other = "value2"

[def.nested]

# This is an array
values = ["1", "two"]

# 2D int array
intArray2d = [[1, 2], [3, 4]]

# A map
[def.nested.map]
key = "value"

[codecov]

Codecov Report

Merging #48 into master will decrease coverage by 3.05%.
The diff coverage is 57.77%.

@@             Coverage Diff              @@
##             master      #48      +/-   ##
============================================
- Coverage     90.14%   87.08%   -3.06%     
- Complexity      406      408       +2     
============================================
  Files            66       66              
  Lines          2211     2384     +173     
  Branches        432      481      +49     
============================================
+ Hits           1993     2076      +83     
- Misses          125      183      +58     
- Partials         93      125      +32

Impacted Files	Coverage Δ	Complexity Δ
...f-core/src/main/kotlin/com/uchuhimo/konf/Config.kt	54.54% <0%> (-2.87%)	0 <0> (ø)
...main/kotlin/com/uchuhimo/konf/source/SourceNode.kt	100% <100%> (ø)	0 <0> (ø)	⬇️
...re/src/main/kotlin/com/uchuhimo/konf/ConfigSpec.kt	81.25% <100%> (+0.39%)	9 <1> (ø)	⬇️
.../kotlin/com/uchuhimo/konf/source/base/MapSource.kt	100% <100%> (ø)	3 <0> (ø)	⬇️
...-core/src/main/kotlin/com/uchuhimo/konf/Feature.kt	100% <100%> (ø)	2 <0> (ø)	⬇️
...kotlin/com/uchuhimo/konf/source/base/FlatSource.kt	90.24% <100%> (+0.37%)	5 <0> (ø)	⬇️
...tlin/com/uchuhimo/konf/source/hocon/HoconWriter.kt	52.38% <16.66%> (-47.62%)	3 <1> (ø)
...onf-core/src/main/kotlin/com/uchuhimo/konf/Spec.kt	72.5% <20%> (-3.82%)	0 <0> (ø)
.../main/kotlin/com/moandjiezana/toml/Toml4jWriter.kt	61.59% <28.3%> (-20.59%)	3 <0> (ø)
...kotlin/com/uchuhimo/konf/source/toml/TomlWriter.kt	80% <50%> (-20%)	3 <1> (ø)
... and 4 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 53d71bd...aa0b165. Read the comment docs.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed after 30 days if no further activity occurs, but feel free to re-open a closed issue if needed.

[Prof-Bloodstone]

@Cybermaxke Are you still interested in adding this feature? I'm on the hunt (again) for a configuration library and this is one of the things stopping me from using konf.
If you are not interested in picking it back-up, I might be able to take it over in a few months, If I won't find anything else that'd suit me better.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed after 30 days if no further activity occurs, but feel free to re-open a closed issue if needed.

[solonovamax]

@Cybermaxke I'm in the same position as @Prof-Bloodstone.
Do you plan on continuing work on this or are you open to contributions?

Konf so far is the only lib I can find that meets my requirements, and I'd really love for this feature to be added.

[Cybermaxke]

@solonovamax I'm not planning to work on this anytime soon, so feel free to continue working on it.

[solonovamax]

Alright, I'll take a look at it. 👍

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed after 30 days if no further activity occurs, but feel free to re-open a closed issue if needed.

[nhubbard]

I've integrated this PR into my fork of Konf.

nhubbard@b2f3c98