From 56dcb1988068b9d4ae178f737532e33473e29594 Mon Sep 17 00:00:00 2001
From: NightEule5 <24661563+NightEule5@users.noreply.github.com>
Date: Thu, 5 May 2022 00:10:47 -0600
Subject: [PATCH] Add serialization annotations

---
 .../ktoml/annotations/TomlComments.kt         | 46 ++++++++++++++
 .../ktoml/annotations/TomlInlineTable.kt      | 51 +++++++++++++++
 .../ktoml/annotations/TomlInteger.kt          | 42 +++++++++++++
 .../ktoml/annotations/TomlLiteral.kt          | 35 +++++++++++
 .../ktoml/annotations/TomlMultiline.kt        | 62 +++++++++++++++++++
 5 files changed, 236 insertions(+)
 create mode 100644 ktoml-core/src/commonMain/kotlin/com/akuleshov7/ktoml/annotations/TomlComments.kt
 create mode 100644 ktoml-core/src/commonMain/kotlin/com/akuleshov7/ktoml/annotations/TomlInlineTable.kt
 create mode 100644 ktoml-core/src/commonMain/kotlin/com/akuleshov7/ktoml/annotations/TomlInteger.kt
 create mode 100644 ktoml-core/src/commonMain/kotlin/com/akuleshov7/ktoml/annotations/TomlLiteral.kt
 create mode 100644 ktoml-core/src/commonMain/kotlin/com/akuleshov7/ktoml/annotations/TomlMultiline.kt

diff --git a/ktoml-core/src/commonMain/kotlin/com/akuleshov7/ktoml/annotations/TomlComments.kt b/ktoml-core/src/commonMain/kotlin/com/akuleshov7/ktoml/annotations/TomlComments.kt
new file mode 100644
index 00000000..f3e7e1db
--- /dev/null
+++ b/ktoml-core/src/commonMain/kotlin/com/akuleshov7/ktoml/annotations/TomlComments.kt
@@ -0,0 +1,46 @@
+package com.akuleshov7.ktoml.annotations
+
+import kotlin.annotation.AnnotationTarget.PROPERTY
+import kotlinx.serialization.ExperimentalSerializationApi
+import kotlinx.serialization.SerialInfo
+
+/**
+ * Specifies comments to be applied the TOML element produced by a property during
+ * serialization. Has no effect on deserialization.
+ *
+ * ```kotlin
+ * @Serializable
+ * data class Data(
+ *     @TomlComments(inline = "Inline")
+ *     val x: Int,
+ *     @TomlComments(
+ *         "Descriptive comment 1",
+ *         "Descriptive comment 2"
+ *     )
+ *     val y: Int
+ * )
+ *
+ * val data = Data(x = 3, y = 7)
+ * ```
+ *
+ * would produce:
+ *
+ * ```toml
+ * x = 3 # Inline
+ *
+ * # Descriptive comment 1
+ * # Descriptive comment 2
+ * y = 7
+ * ```
+ *
+ * @property lines Comment lines to be placed before the TOML element.
+ * @property inline A comment placed *inline* with the TOML element, at the end
+ * of the line. If empty (the default), no comment will be written.
+ */
+@OptIn(ExperimentalSerializationApi::class)
+@SerialInfo
+@Target(PROPERTY)
+public annotation class TomlComments(
+    vararg val lines: String,
+    val inline: String = ""
+)
diff --git a/ktoml-core/src/commonMain/kotlin/com/akuleshov7/ktoml/annotations/TomlInlineTable.kt b/ktoml-core/src/commonMain/kotlin/com/akuleshov7/ktoml/annotations/TomlInlineTable.kt
new file mode 100644
index 00000000..894ce757
--- /dev/null
+++ b/ktoml-core/src/commonMain/kotlin/com/akuleshov7/ktoml/annotations/TomlInlineTable.kt
@@ -0,0 +1,51 @@
+package com.akuleshov7.ktoml.annotations
+
+import kotlin.annotation.AnnotationTarget.*
+import kotlinx.serialization.ExperimentalSerializationApi
+import kotlinx.serialization.SerialInfo
+
+/**
+ * Marks a TOML element as an inline table. Has no effect on deserialization.
+ *
+ * ```kotlin
+ * @Serializable
+ * data class Data(
+ *     @TomlInlineTable
+ *     val inlineTable: Table,
+ *     val tableArray: List<@TomlInlineTable Table>,
+ *     val inlineTable2: Table2
+ * )
+ *
+ * @Serializable
+ * data class Table(val int: Int)
+ *
+ * @Serializable
+ * @TomlInlineTable
+ * data class Table2(val string: String)
+ *
+ * val data = Data(
+ *     inlineTable = Table(int = -1),
+ *     tableArray = listOf(
+ *         Table(int = 3),
+ *         Table(int = 10)
+ *     ),
+ *     inlineTable2 = Table2(string = "text")
+ * )
+ * ```
+ *
+ * would produce:
+ *
+ * ```toml
+ * inlineTable = { int = -1 }
+ * tableArray = [ { int = 3 }, { int = 10 } ]
+ * inlineTable2 = { string = "text" }
+ * ```
+ */
+@OptIn(ExperimentalSerializationApi::class)
+@SerialInfo
+@Target(
+    PROPERTY,
+    TYPE_PARAMETER,
+    CLASS
+)
+public annotation class TomlInlineTable
diff --git a/ktoml-core/src/commonMain/kotlin/com/akuleshov7/ktoml/annotations/TomlInteger.kt b/ktoml-core/src/commonMain/kotlin/com/akuleshov7/ktoml/annotations/TomlInteger.kt
new file mode 100644
index 00000000..380891c6
--- /dev/null
+++ b/ktoml-core/src/commonMain/kotlin/com/akuleshov7/ktoml/annotations/TomlInteger.kt
@@ -0,0 +1,42 @@
+package com.akuleshov7.ktoml.annotations
+
+import com.akuleshov7.ktoml.writers.IntegerRepresentation
+import com.akuleshov7.ktoml.writers.IntegerRepresentation.DECIMAL
+import kotlin.annotation.AnnotationTarget.PROPERTY
+import kotlin.annotation.AnnotationTarget.TYPE_PARAMETER
+import kotlinx.serialization.ExperimentalSerializationApi
+import kotlinx.serialization.SerialInfo
+
+/**
+ * Specifies how a TOML integer element is encoded. Has no effect on deserialization.
+ *
+ * ```kotlin
+ * @Serializable
+ * data class Data(
+ *     @TomlInteger(HEX)
+ *     val mask: Int,
+ *     val perms: List<@TomlInteger(OCTAL) Int>
+ * )
+ *
+ * val data = Data(
+ *     mask = 0x00FF,
+ *     perms = listOf(0x1FF, 0x1ED, 0x1A4)
+ * )
+ * ```
+ *
+ * would produce:
+ *
+ * ```toml
+ * mask = 0x00FF
+ * perms = [ 0o777, 0o755, 0o644 ]
+ * ```
+ *
+ * @property representation How the integer is represented in TOML. The default
+ * behavior is [DECIMAL].
+ */
+@OptIn(ExperimentalSerializationApi::class)
+@SerialInfo
+@Target(PROPERTY, TYPE_PARAMETER)
+public annotation class TomlInteger(
+    val representation: IntegerRepresentation = DECIMAL
+)
diff --git a/ktoml-core/src/commonMain/kotlin/com/akuleshov7/ktoml/annotations/TomlLiteral.kt b/ktoml-core/src/commonMain/kotlin/com/akuleshov7/ktoml/annotations/TomlLiteral.kt
new file mode 100644
index 00000000..5c9554a3
--- /dev/null
+++ b/ktoml-core/src/commonMain/kotlin/com/akuleshov7/ktoml/annotations/TomlLiteral.kt
@@ -0,0 +1,35 @@
+package com.akuleshov7.ktoml.annotations
+
+import kotlin.annotation.AnnotationTarget.PROPERTY
+import kotlin.annotation.AnnotationTarget.TYPE_PARAMETER
+import kotlinx.serialization.ExperimentalSerializationApi
+import kotlinx.serialization.SerialInfo
+
+/**
+ * Marks a TOML string element as literal. Has no effect on deserialization.
+ *
+ * ```kotlin
+ * @Serializable
+ * data class Data(
+ *     @TomlLiteral
+ *     val text: String,
+ *     val list: List<@TomlLiteral String>
+ * )
+ *
+ * val data = Data(
+ *     text = "\"literal\"",
+ *     list = listOf("\\[a-z]*\\")
+ * )
+ * ```
+ *
+ * would produce:
+ *
+ * ```toml
+ * text = '"literal"'
+ * list = [ '\[a-z]*\' ]
+ * ```
+ */
+@OptIn(ExperimentalSerializationApi::class)
+@SerialInfo
+@Target(PROPERTY, TYPE_PARAMETER)
+public annotation class TomlLiteral
diff --git a/ktoml-core/src/commonMain/kotlin/com/akuleshov7/ktoml/annotations/TomlMultiline.kt b/ktoml-core/src/commonMain/kotlin/com/akuleshov7/ktoml/annotations/TomlMultiline.kt
new file mode 100644
index 00000000..bf6834c2
--- /dev/null
+++ b/ktoml-core/src/commonMain/kotlin/com/akuleshov7/ktoml/annotations/TomlMultiline.kt
@@ -0,0 +1,62 @@
+package com.akuleshov7.ktoml.annotations
+
+import kotlin.annotation.AnnotationTarget.PROPERTY
+import kotlin.annotation.AnnotationTarget.TYPE_PARAMETER
+import kotlinx.serialization.ExperimentalSerializationApi
+import kotlinx.serialization.SerialInfo
+
+/**
+ * Marks a TOML element and its children as multiline. Can be used on strings and
+ * arrays. Has no effect on deserialization.
+ *
+ * ```kotlin
+ * @Serializable
+ * data class Data(
+ *     @TomlMultiline
+ *     val multilineString: String,
+ *     @TomlMultiline
+ *     val multilineArray: List<Int>,
+ *     val multilineStringArray: List<@TomlMultiline String>,
+ *     @TomlMultiline
+ *     val multilineStringArray2: List<String>
+ * )
+ *
+ * val data = Data(text = "Some\nText", list = listOf(3, 5, 7, 11))
+ * ```
+ *
+ * would produce:
+ *
+ * ```toml
+ * multilineString = """
+ * Some
+ * Text
+ * """
+ *
+ * multilineArray = [
+ *     3,
+ *     5,
+ *     7,
+ *     11
+ * ]
+ *
+ * multilineStringArray = [ """
+ * string 1
+ * """,
+ * """
+ * string 2
+ * """ ]
+ *
+ * multilineStringArray2 = [
+ *     """
+ *     string 1
+ *     """,
+ *     """
+ *     string 2
+ *     """
+ * ]
+ * ```
+ */
+@OptIn(ExperimentalSerializationApi::class)
+@SerialInfo
+@Target(PROPERTY, TYPE_PARAMETER)
+public annotation class TomlMultiline