Merge pull request #85 from InsanusMokrassar/0.27.1

0.27.1

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`:

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/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()

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()

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

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 explanationLimit) {
-            error("Quiz poll explanation size must be in range $quizPollExplanationLimit," +
+            error("Quiz poll explanation size must be in range $explanationLimit," +
-                "but actual explanation contains ${caption.length} symbols")
+                "but actual explanation contains ${explanation.length} symbols")
         }
     }
 }

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
 

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 }

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)
             )

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()
+
 

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