From 3a85241b0611bae4c76fd5749e0facc38b957497 Mon Sep 17 00:00:00 2001 From: Andrey Kuleshov Date: Sat, 19 Feb 2022 23:45:37 +0300 Subject: [PATCH] Updating readme and GitHub pages with new user scenarios (#111) --- README.md | 14 ++++---- index.md | 104 +++++++++++++++++++++++++++++++++++------------------- 2 files changed, 74 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 052cbd27..2a595912 100644 --- a/README.md +++ b/README.md @@ -81,12 +81,12 @@ To import `ktoml` library you need to add following dependencies to your code: com.akuleshov7 ktoml-core - 0.2.9 + 0.2.10 com.akuleshov7 ktoml-file - 0.2.9 + 0.2.10 ``` @@ -95,8 +95,8 @@ To import `ktoml` library you need to add following dependencies to your code: Gradle Groovy ```groovy -implementation 'com.akuleshov7:ktoml-core:0.2.9' -implementation 'com.akuleshov7:ktoml-file:0.2.9' +implementation 'com.akuleshov7:ktoml-core:0.2.10' +implementation 'com.akuleshov7:ktoml-file:0.2.10' ``` @@ -104,8 +104,8 @@ implementation 'com.akuleshov7:ktoml-file:0.2.9' Gradle Kotlin ```kotlin -implementation("com.akuleshov7:ktoml-core:0.2.9") -implementation("com.akuleshov7:ktoml-file:0.2.9") +implementation("com.akuleshov7:ktoml-core:0.2.10") +implementation("com.akuleshov7:ktoml-file:0.2.10") ``` @@ -319,4 +319,4 @@ Translation of the example above to json-terminology: ``` -:heavy_exclamation_mark: You can check how this example works in [ReadMeExampleTest](ktoml-core/src/commonTest/kotlin/decoder/ReadMeExampleTest.kt). +:heavy_exclamation_mark: You can check how this example works in [ReadMeExampleTest](https://github.com/akuleshov7/ktoml/blob/main/ktoml-core/src/commonTest/kotlin/com/akuleshov7/ktoml/decoders/ReadMeExampleTest.kt). diff --git a/index.md b/index.md index a64b2940..2753f14e 100644 --- a/index.md +++ b/index.md @@ -1,7 +1,9 @@ +## + Fully Native and Multiplatform Kotlin serialization library for serialization/deserialization of [toml](https://toml.io/en/) format. Uses native [kotlinx.serialization](https://github.com/Kotlin/kotlinx.serialization), provided by Kotlin. This library contains no Java code and no Java dependencies. -We believe that TOML is actually the most readable and user-friendly *configuration file* format. -So we decided to support this format for the kotlinx serialization library. +We believe that TOML is actually the most readable and user-friendly **configuration file** format. +So we decided to support this format for the `kotlinx` serialization library. ## How ktoml works: examples @@ -10,74 +12,102 @@ This tool natively deserializes toml expressions using native Kotlin compiler pl The following example: ```toml someBooleanProperty = true +# inline tables in gradle 'libs.versions.toml' notation +gradle-libs-like-property = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" } [table1] -property1 = 5 +# it can be null or nil, but don't forget to mark it with '?' in the codes +# keep in mind, that null is prohibited by TOML spec, but it is very important in Kotlin +property1 = null property2 = 6 +# check property3 in Table1 below. As it has the default value, it is not required and can be not provided [table2] someNumber = 5 [table2."akuleshov7.com"] - name = "my name" - configurationList = ["a", "b", "c"] + name = 'this is a "literal" string' + # empty lists are also supported + configurationList = ["a", "b", "c", null] # such redeclaration of table2 # is prohibited in toml specification; # but ktoml is allowing it in non-strict mode: [table2] otherNumber = 5.56 + ``` can be deserialized to `MyClass`: ```kotlin - @Serializable - data class MyClass( - val someBooleanProperty: Boolean, - val table1: Table1, - val table2: Table2 - ) - - @Serializable - data class Table1(val property1: Int, val property2: Int) - - @Serializable - data class Table2( - val someNumber: Int, - @SerialName("akuleshov7.com") - val inlineTable: InlineTable, - val otherNumber: Double - ) - - @Serializable - data class InlineTable( - val name: String, - @SerialName("configurationList") - val overriddenName: List - ) +@Serializable +data class MyClass( + val someBooleanProperty: Boolean, + val table1: Table1, + val table2: Table2, + @SerialName("gradle-libs-like-property") + val kotlinJvm: GradlePlugin +) + +@Serializable +data class Table1( + // nullable values, from toml you can pass null/nil/empty value to this kind of a field + val property1: Long?, + // please note, that according to the specification of toml integer values should be represented with Long + val property2: Long, + // no need to pass this value as it has the default value and is NOT REQUIRED + val property3: Long = 5 +) + +@Serializable +data class Table2( + val someNumber: Long, + @SerialName("akuleshov7.com") + val inlineTable: InlineTable, + val otherNumber: Double +) + +@Serializable +data class GradlePlugin(val id: String, val version: Version) + +@Serializable +data class Version(val ref: String) + ``` with the following code: ```kotlin -stringWhereTomlIsStored.deserialize() +Toml.decodeFromString(/* your toml string */) ``` Translation of the example above to json-terminology: + ```json { "someBooleanProperty": true, "table1": { "property1": 5, "property2": 5 - }, + }, "table2": { - "someNumber": 5, - "akuleshov7.com": { - "name": "my name", - "configurationList": ["a", "b", "c"], - "otherNumber": 5.56 + "someNumber": 5, + "akuleshov7.com": { + "name": "my name", + "configurationList": [ + "a", + "b", + "c" + ], + "otherNumber": 5.56 + } + }, + "gradle-libs-like-property": { + "id": "org.jetbrains.kotlin.jvm", + "version": { + "ref": "kotlin" } } } + ``` -You can check how this example works in [ReadMeExampleTest](ktoml-core/src/commonTest/kotlin/decoder/ReadMeExampleTest.kt). +:heavy_exclamation_mark: You can check how this example works in [ReadMeExampleTest](https://github.com/akuleshov7/ktoml/blob/main/ktoml-core/src/commonTest/kotlin/com/akuleshov7/ktoml/decoders/ReadMeExampleTest.kt).