add Explained interface and use it in polls

CHANGELOG.md

@@ -51,6 +51,15 @@
 
 ### 0.27.1
 
+* `TelegramBotAPI`:
+    * Interface `Explained` and subsinterfaces `ExplainedInput` and `ExplainedOutput` was added
+        * Class `QuizPoll` now implement `ExplainedInput`
+        * In `QuizPoll#caption` and `QuizPoll#captionEntities` are deprecated now
+        * Class `SendQuizPoll` now implement `ExplainedOutput`
+        * In `SendQuizPoll#caption` is deprecated now
+* `TelegramBotAPI-extensions-api`:
+    * `sendQuizPoll` now is using `explanation` parameter instead of `caption`
+
 ## 0.26.0
 
 * `Common`:

TelegramBotAPI-extensions-api/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/extensions/api/send/polls/SendPoll.kt

@@ -83,7 +83,7 @@ suspend fun RequestsExecutor.sendQuizPoll(
     correctOptionId: Int,
     isAnonymous: Boolean = true,
     isClosed: Boolean = false,
-    caption: String? = null,
+    explanation: String? = null,
     parseMode: ParseMode? = null,
     closeInfo: ScheduledCloseInfo? = null,
     disableNotification: Boolean = false,
@@ -91,7 +91,7 @@ suspend fun RequestsExecutor.sendQuizPoll(
     replyMarkup: KeyboardMarkup? = null
 ) = execute(
     SendQuizPoll(
-        chatId, question, options, correctOptionId, isAnonymous, isClosed, caption, parseMode, closeInfo, disableNotification, replyToMessageId, replyMarkup
+        chatId, question, options, correctOptionId, isAnonymous, isClosed, explanation, parseMode, closeInfo, disableNotification, replyToMessageId, replyMarkup
     )
 )
 
@@ -102,14 +102,14 @@ suspend fun RequestsExecutor.sendQuizPoll(
     correctOptionId: Int,
     isAnonymous: Boolean = true,
     isClosed: Boolean = false,
-    caption: String? = null,
+    explanation: String? = null,
     parseMode: ParseMode? = null,
     closeInfo: ScheduledCloseInfo? = null,
     disableNotification: Boolean = false,
     replyToMessageId: MessageIdentifier? = null,
     replyMarkup: KeyboardMarkup? = null
 ) = sendQuizPoll(
-    chat.id, question, options, correctOptionId, isAnonymous, isClosed, caption, parseMode, closeInfo, disableNotification, replyToMessageId, replyMarkup
+    chat.id, question, options, correctOptionId, isAnonymous, isClosed, explanation, parseMode, closeInfo, disableNotification, replyToMessageId, replyMarkup
 )
 
 suspend fun RequestsExecutor.sendQuizPoll(
@@ -120,7 +120,7 @@ suspend fun RequestsExecutor.sendQuizPoll(
     options: List<String> = quizPoll.options.map { it.text },
     correctOptionId: Int = quizPoll.correctOptionId ?: error("Correct option ID must be provided by income QuizPoll or by developer"),
     isAnonymous: Boolean = quizPoll.isAnonymous,
-    caption: String? = null,
+    explanation: String? = null,
     parseMode: ParseMode? = null,
     closeInfo: ScheduledCloseInfo? = null,
     disableNotification: Boolean = false,
@@ -128,7 +128,7 @@ suspend fun RequestsExecutor.sendQuizPoll(
     replyMarkup: KeyboardMarkup? = null
 ) = execute(
     SendQuizPoll(
-        chatId, question, options, correctOptionId, isAnonymous, isClosed, caption, parseMode, closeInfo, disableNotification, replyToMessageId, replyMarkup
+        chatId, question, options, correctOptionId, isAnonymous, isClosed, explanation, parseMode, closeInfo, disableNotification, replyToMessageId, replyMarkup
     )
 )
 
@@ -140,12 +140,12 @@ suspend fun RequestsExecutor.sendQuizPoll(
     options: List<String> = quizPoll.options.map { it.text },
     correctOptionId: Int = quizPoll.correctOptionId ?: error("Correct option ID must be provided by income QuizPoll or by developer"),
     isAnonymous: Boolean = quizPoll.isAnonymous,
-    caption: String? = null,
+    explanation: String? = null,
     parseMode: ParseMode? = null,
     closeInfo: ScheduledCloseInfo? = null,
     disableNotification: Boolean = false,
     replyToMessageId: MessageIdentifier? = null,
     replyMarkup: KeyboardMarkup? = null
 ) = sendQuizPoll(
-    chat.id, question, options, correctOptionId, isAnonymous, isClosed, caption, parseMode, closeInfo, disableNotification, replyToMessageId, replyMarkup
+    chat.id, question, options, correctOptionId, isAnonymous, isClosed, explanation, parseMode, closeInfo, disableNotification, replyToMessageId, replyMarkup
 )

TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/CommonAbstracts/Explained.kt

@@ -0,0 +1,18 @@
+package com.github.insanusmokrassar.TelegramBotAPI.CommonAbstracts
+
+import com.github.insanusmokrassar.TelegramBotAPI.types.ParseMode.ParseMode
+import com.github.insanusmokrassar.TelegramBotAPI.utils.fullListOfSubSource
+
+interface Explained {
+    val explanation: String?
+}
+
+interface ExplainedOutput : Explained {
+    val parseMode: ParseMode?
+}
+
+interface ExplainedInput : Explained {
+    val explanationEntities: List<TextPart>
+}
+
+fun ExplainedInput.fullEntitiesList() = explanation ?.fullListOfSubSource(explanationEntities) ?.map { it.source } ?: emptyList()

TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/requests/send/polls/SendPoll.kt

@@ -1,7 +1,6 @@
 package com.github.insanusmokrassar.TelegramBotAPI.requests.send.polls
 
-import com.github.insanusmokrassar.TelegramBotAPI.CommonAbstracts.CaptionedOutput
+import com.github.insanusmokrassar.TelegramBotAPI.CommonAbstracts.*
-import com.github.insanusmokrassar.TelegramBotAPI.CommonAbstracts.justTextSources
 import com.github.insanusmokrassar.TelegramBotAPI.requests.send.abstracts.ReplyingMarkupSendMessageRequest
 import com.github.insanusmokrassar.TelegramBotAPI.requests.send.abstracts.SendMessageRequest
 import com.github.insanusmokrassar.TelegramBotAPI.types.*
@@ -202,7 +201,7 @@ data class SendQuizPoll(
     @SerialName(isClosedField)
     override val isClosed: Boolean = false,
     @SerialName(explanationField)
-    override val caption: String? = null,
+    override val explanation: String? = null,
     @SerialName(explanationParseModeField)
     override val parseMode: ParseMode? = null,
     @Transient
@@ -213,11 +212,15 @@ data class SendQuizPoll(
     override val replyToMessageId: MessageIdentifier? = null,
     @SerialName(replyMarkupField)
     override val replyMarkup: KeyboardMarkup? = null
-) : SendPoll(), CaptionedOutput {
+) : SendPoll(), CaptionedOutput, ExplainedOutput {
     override val type: String = quizPollType
     override val requestSerializer: SerializationStrategy<*>
         get() = serializer()
 
+    @Deprecated("Will be removed in near updates", ReplaceWith("explanation"))
+    override val caption: String?
+        get() = explanation
+
     @SerialName(openPeriodField)
     override val openPeriod: LongSeconds?
         = (closeInfo as? ApproximateScheduledCloseInfo) ?.openDuration ?.millisecondsLong ?.div(1000)
@@ -234,9 +237,9 @@ data class SendQuizPoll(
             throw IllegalArgumentException("Correct option id must be in range of $correctOptionIdRange, but actual " +
                 "value is $correctOptionId")
         }
-        if (caption != null && caption.length !in quizPollExplanationLimit) {
+        if (explanation != null && explanation.length !in quizPollExplanationLimit) {
             error("Quiz poll explanation size must be in range $quizPollExplanationLimit," +
-                "but actual explanation contains ${caption.length} symbols")
+                "but actual explanation contains ${explanation.length} symbols")
         }
     }
 }

TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/types/polls/Poll.kt

@@ -1,7 +1,6 @@
 package com.github.insanusmokrassar.TelegramBotAPI.types.polls
 
-import com.github.insanusmokrassar.TelegramBotAPI.CommonAbstracts.CaptionedInput
+import com.github.insanusmokrassar.TelegramBotAPI.CommonAbstracts.*
-import com.github.insanusmokrassar.TelegramBotAPI.CommonAbstracts.TextPart
 import com.github.insanusmokrassar.TelegramBotAPI.types.*
 import com.github.insanusmokrassar.TelegramBotAPI.types.MessageEntity.*
 import com.github.insanusmokrassar.TelegramBotAPI.utils.nonstrictJsonFormat
@@ -71,9 +70,9 @@ private class RawPoll(
     @SerialName(correctOptionIdField)
     val correctOptionId: Int? = null,
     @SerialName(explanationField)
-    val caption: String? = null,
+    val explanation: String? = null,
     @SerialName(explanationEntitiesField)
-    val captionEntities: List<RawMessageEntity> = emptyList(),
+    val explanationEntities: List<RawMessageEntity> = emptyList(),
     @SerialName(openPeriodField)
     val openPeriod: LongSeconds? = null,
     @SerialName(closeDateField)
@@ -131,12 +130,19 @@ data class QuizPoll(
      * Nullable due to documentation (https://core.telegram.org/bots/api#poll)
      */
     val correctOptionId: Int? = null,
-    override val caption: String? = null,
+    override val explanation: String? = null,
-    override val captionEntities: List<TextPart> = emptyList(),
+    override val explanationEntities: List<TextPart> = emptyList(),
     override val isClosed: Boolean = false,
     override val isAnonymous: Boolean = false,
     override val scheduledCloseInfo: ScheduledCloseInfo? = null
-) : Poll(), CaptionedInput
+) : Poll(), CaptionedInput, ExplainedInput {
+    @Deprecated("Will be removed in near updates", ReplaceWith("explanation"))
+    override val caption: String?
+        get() = explanation
+    @Deprecated("Will be removed in near updates", ReplaceWith("explanationEntities"))
+    override val captionEntities: List<TextPart>
+        get() = explanationEntities
+}
 
 @Serializer(Poll::class)
 internal object PollSerializer : KSerializer<Poll> {
@@ -154,8 +160,8 @@ internal object PollSerializer : KSerializer<Poll> {
                 rawPoll.options,
                 rawPoll.votesCount,
                 rawPoll.correctOptionId,
-                rawPoll.caption,
+                rawPoll.explanation,
-                rawPoll.caption?.let { rawPoll.captionEntities.asTextParts(it) } ?: emptyList(),
+                rawPoll.explanation?.let { rawPoll.explanationEntities.asTextParts(it) } ?: emptyList(),
                 rawPoll.isClosed,
                 rawPoll.isAnonymous,
                 rawPoll.scheduledCloseInfo
@@ -206,8 +212,8 @@ internal object PollSerializer : KSerializer<Poll> {
                 value.isAnonymous,
                 regularPollType,
                 correctOptionId = value.correctOptionId,
-                caption = value.caption,
+                explanation = value.caption,
-                captionEntities = value.captionEntities.asRawMessageEntities(),
+                explanationEntities = value.captionEntities.asRawMessageEntities(),
                 openPeriod = (closeInfo as? ApproximateScheduledCloseInfo) ?.openDuration ?.seconds ?.toLong(),
                 closeDate = (closeInfo as? ExactScheduledCloseInfo) ?.closeDateTime ?.unixMillisLong ?.div(1000L)
             )