Merge pull request #85 from InsanusMokrassar/0.27.1

0.27.1
2025-10-25 09:10:07 +00:00 · 2020-04-25 10:12:53 +06:00
parent fad27ede78 b336b17eef
commit 668a201789
11 changed files with 109 additions and 42 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -49,6 +49,23 @@
        * `closePollExactAfter`
        * `closePollAfter`

+### 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
+    * `explanationLimit` range was added as future replacement of `quizPollExplanationLimit`
+        * `quizPollExplanationLimit` now is deprecated
+    * Extensions `toMarkdownExplanations`, `toMarkdownV2Explanations` and `toHtmlExplanations` was added
+    * Typealias `FullTextSourcesList` was added
+        * All extensions `fullEntitiesList` now return `FullTextSourcesList`
+        * All extensions of `List<TextSource>` now are extensions for `FullTextSourcesList`
+* `TelegramBotAPI-extensions-api`:
+    * `sendQuizPoll` now is using `explanation` parameter instead of `caption`
+
 ## 0.26.0

 * `Common`:
--- a/TelegramBotAPI-extensions-api/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/extensions/api/send/polls/SendPoll.kt
+++ b/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
 )
--- a/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/CommonAbstracts/Captioned.kt
+++ b/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/CommonAbstracts/Captioned.kt
@@ -15,4 +15,4 @@ interface CaptionedInput : Captioned {
    val captionEntities: List<TextPart>
 }

-fun CaptionedInput.fullEntitiesList() = caption ?.fullListOfSubSource(captionEntities) ?.map { it.source } ?: emptyList()
+fun CaptionedInput.fullEntitiesList(): FullTextSourcesList = caption ?.fullListOfSubSource(captionEntities) ?.map { it.source } ?: emptyList()
--- a/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/CommonAbstracts/Explained.kt
+++ b/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(): FullTextSourcesList = explanation ?.fullListOfSubSource(explanationEntities) ?.map { it.source } ?: emptyList()
--- a/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/CommonAbstracts/TextSource.kt
+++ b/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/CommonAbstracts/TextSource.kt
@@ -1,5 +1,8 @@
 package com.github.insanusmokrassar.TelegramBotAPI.CommonAbstracts

+typealias FullTextSourcesList = List<TextSource>
+typealias FullTextPartsList = List<TextPart>
+
 interface TextSource {
    val asMarkdownSource: String
    val asMarkdownV2Source: String
--- a/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/requests/send/polls/SendPoll.kt
+++ b/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.justTextSources
+import com.github.insanusmokrassar.TelegramBotAPI.CommonAbstracts.*
 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) {
-            error("Quiz poll explanation size must be in range $quizPollExplanationLimit," +
-                "but actual explanation contains ${caption.length} symbols")
+        if (explanation != null && explanation.length !in explanationLimit) {
+            error("Quiz poll explanation size must be in range $explanationLimit," +
+                "but actual explanation contains ${explanation.length} symbols")
        }
    }
 }
--- a/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/types/Common.kt
+++ b/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/types/Common.kt
@@ -55,7 +55,9 @@ val botCommandLimit = botCommandLengthLimit
 val botCommandDescriptionLimit = 3 .. 256
 val botCommandsLimit = 0 .. 100

-val quizPollExplanationLimit = 0 .. 200
+val explanationLimit = 0 .. 200
+@Deprecated("Will be removed in near updates", ReplaceWith("explanationLimit"))
+val quizPollExplanationLimit = explanationLimit

 val openPeriodPollSecondsLimit = 5 .. 600

--- a/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/types/message/content/TextContent.kt
+++ b/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/types/message/content/TextContent.kt
@@ -1,5 +1,6 @@
 package com.github.insanusmokrassar.TelegramBotAPI.types.message.content

+import com.github.insanusmokrassar.TelegramBotAPI.CommonAbstracts.FullTextSourcesList
 import com.github.insanusmokrassar.TelegramBotAPI.CommonAbstracts.TextPart
 import com.github.insanusmokrassar.TelegramBotAPI.requests.abstracts.Request
 import com.github.insanusmokrassar.TelegramBotAPI.requests.send.SendTextMessage
@@ -66,4 +67,4 @@ data class TextContent(
    }
 }

-fun TextContent.fullEntitiesList() = text.fullListOfSubSource(entities).map { it.source }
+fun TextContent.fullEntitiesList(): FullTextSourcesList = text.fullListOfSubSource(entities).map { it.source }
--- a/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/types/polls/Poll.kt
+++ b/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.TextPart
+import com.github.insanusmokrassar.TelegramBotAPI.CommonAbstracts.*
 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 captionEntities: List<TextPart> = emptyList(),
+    override val explanation: String? = null,
+    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.caption?.let { rawPoll.captionEntities.asTextParts(it) } ?: emptyList(),
+                rawPoll.explanation,
+                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,
-                captionEntities = value.captionEntities.asRawMessageEntities(),
+                explanation = value.caption,
+                explanationEntities = value.captionEntities.asRawMessageEntities(),
                openPeriod = (closeInfo as? ApproximateScheduledCloseInfo) ?.openDuration ?.seconds ?.toLong(),
                closeDate = (closeInfo as? ExactScheduledCloseInfo) ?.closeDateTime ?.unixMillisLong ?.div(1000L)
            )
--- a/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/utils/CaptionAndTextSourcesToText.kt
+++ b/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/utils/CaptionAndTextSourcesToText.kt
@@ -1,14 +1,13 @@
 package com.github.insanusmokrassar.TelegramBotAPI.utils

 import com.github.insanusmokrassar.TelegramBotAPI.CommonAbstracts.*
+import com.github.insanusmokrassar.TelegramBotAPI.types.*
 import com.github.insanusmokrassar.TelegramBotAPI.types.ParseMode.*
-import com.github.insanusmokrassar.TelegramBotAPI.types.captionLength
 import com.github.insanusmokrassar.TelegramBotAPI.types.message.content.TextContent
 import com.github.insanusmokrassar.TelegramBotAPI.types.message.content.fullEntitiesList
-import com.github.insanusmokrassar.TelegramBotAPI.types.textLength

 fun createFormattedText(
-    entities: List<TextSource>,
+    entities: FullTextSourcesList,
    partLength: Int = 4096,
    mode: ParseMode = MarkdownParseMode
 ): List<String> {
@@ -49,56 +48,74 @@ fun createFormattedText(


 fun createMarkdownText(
-    entities: List<TextSource>,
+    entities: FullTextSourcesList,
    partLength: Int = 4096
 ): List<String> = createFormattedText(entities, partLength, MarkdownParseMode)

-fun List<TextSource>.toMarkdownCaptions(): List<String> = createMarkdownText(
+fun FullTextSourcesList.toMarkdownCaptions(): List<String> = createMarkdownText(
    this,
    captionLength.last + 1
 )
 fun CaptionedInput.toMarkdownCaptions(): List<String> = fullEntitiesList().toMarkdownCaptions()

-fun List<TextSource>.toMarkdownTexts(): List<String> = createMarkdownText(
+fun FullTextSourcesList.toMarkdownTexts(): List<String> = createMarkdownText(
    this,
    textLength.last + 1
 )
 fun TextContent.toMarkdownTexts(): List<String> = fullEntitiesList().toMarkdownTexts()

+fun FullTextSourcesList.toMarkdownExplanations(): List<String> = createMarkdownText(
+    this,
+    explanationLimit.last + 1
+)
+fun ExplainedInput.toMarkdownExplanations(): List<String> = fullEntitiesList().toMarkdownTexts()
+

 fun createMarkdownV2Text(
-    entities: List<TextSource>,
+    entities: FullTextSourcesList,
    partLength: Int = 4096
 ): List<String> = createFormattedText(entities, partLength, MarkdownV2ParseMode)

-fun List<TextSource>.toMarkdownV2Captions(): List<String> = createMarkdownV2Text(
+fun FullTextSourcesList.toMarkdownV2Captions(): List<String> = createMarkdownV2Text(
    this,
    captionLength.last + 1
 )
 fun CaptionedInput.toMarkdownV2Captions(): List<String> = fullEntitiesList().toMarkdownV2Captions()

-fun List<TextSource>.toMarkdownV2Texts(): List<String> = createMarkdownV2Text(
+fun FullTextSourcesList.toMarkdownV2Texts(): List<String> = createMarkdownV2Text(
    this,
    textLength.last + 1
 )
 fun TextContent.toMarkdownV2Texts(): List<String> = fullEntitiesList().toMarkdownV2Texts()

+fun FullTextSourcesList.toMarkdownV2Explanations(): List<String> = createMarkdownV2Text(
+    this,
+    explanationLimit.last + 1
+)
+fun ExplainedInput.toMarkdownV2Explanations(): List<String> = fullEntitiesList().toMarkdownV2Texts()
+

 fun createHtmlText(
-    entities: List<TextSource>,
+    entities: FullTextSourcesList,
    partLength: Int = 4096
 ): List<String> = createFormattedText(entities, partLength, HTMLParseMode)

-fun List<TextSource>.toHtmlCaptions(): List<String> = createHtmlText(
+fun FullTextSourcesList.toHtmlCaptions(): List<String> = createHtmlText(
    this,
    captionLength.last + 1
 )
 fun CaptionedInput.toHtmlCaptions(): List<String> = fullEntitiesList().toHtmlCaptions()

-fun List<TextSource>.toHtmlTexts(): List<String> = createHtmlText(
+fun FullTextSourcesList.toHtmlTexts(): List<String> = createHtmlText(
    this,
    textLength.last + 1
 )
 fun TextContent.toHtmlTexts(): List<String> = fullEntitiesList().toHtmlTexts()

+fun FullTextSourcesList.toHtmlExplanations(): List<String> = createHtmlText(
+    this,
+    explanationLimit.last + 1
+)
+fun ExplainedInput.toHtmlExplanations(): List<String> = fullEntitiesList().toHtmlTexts()
+

--- a/gradle.properties
+++ b/gradle.properties
@@ -7,6 +7,6 @@ uuid_version=0.1.0
 ktor_version=1.3.2

 library_group=com.github.insanusmokrassar
-library_version=0.27.0
+library_version=0.27.1

 gradle_bintray_plugin_version=1.8.4