From 9cee22165d021a8d5946e3be495a955ca38fe4ad Mon Sep 17 00:00:00 2001 From: InsanusMokrassar Date: Mon, 11 May 2020 20:32:14 +0600 Subject: [PATCH] start normal filling of docs --- .../CallbackQueryUpdatesConversations.kt | 9 ++++ .../utils/updates/CommandsFilters.kt | 41 +++++++++++++++++-- .../SentMessageUpdatesConversations.kt | 9 ++++ .../utils/updates/UpdatesChatFilters.kt | 12 ++++++ .../CommonAbstracts/Captioned.kt | 8 ++++ .../CommonAbstracts/Explained.kt | 8 ++++ .../types/message/content/TextContent.kt | 8 ++++ 7 files changed, 91 insertions(+), 4 deletions(-) diff --git a/TelegramBotAPI-extensions-utils/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/extensions/utils/updates/CallbackQueryUpdatesConversations.kt b/TelegramBotAPI-extensions-utils/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/extensions/utils/updates/CallbackQueryUpdatesConversations.kt index 4aff11eefa..7b1a1c5222 100644 --- a/TelegramBotAPI-extensions-utils/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/extensions/utils/updates/CallbackQueryUpdatesConversations.kt +++ b/TelegramBotAPI-extensions-utils/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/extensions/utils/updates/CallbackQueryUpdatesConversations.kt @@ -5,12 +5,21 @@ import com.github.insanusmokrassar.TelegramBotAPI.types.update.CallbackQueryUpda import kotlinx.coroutines.flow.Flow import kotlinx.coroutines.flow.mapNotNull +/** + * @return New [Flow] with [DataCallbackQuery] type, got from [CallbackQueryUpdate.data] field + */ fun Flow.asDataCallbackQueryFlow() = mapNotNull { it.data as? DataCallbackQuery } +/** + * @return New [Flow] with [GameShortNameCallbackQuery] type, got from [CallbackQueryUpdate.data] field + */ fun Flow.asGameShortNameCallbackQueryFlow() = mapNotNull { it.data as? GameShortNameCallbackQuery } +/** + * @return New [Flow] with [UnknownCallbackQueryType] type, got from [CallbackQueryUpdate.data] field + */ fun Flow.asUnknownCallbackQueryFlow() = mapNotNull { it.data as? UnknownCallbackQueryType } diff --git a/TelegramBotAPI-extensions-utils/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/extensions/utils/updates/CommandsFilters.kt b/TelegramBotAPI-extensions-utils/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/extensions/utils/updates/CommandsFilters.kt index 1d991b0c0d..1e3719e5af 100644 --- a/TelegramBotAPI-extensions-utils/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/extensions/utils/updates/CommandsFilters.kt +++ b/TelegramBotAPI-extensions-utils/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/extensions/utils/updates/CommandsFilters.kt @@ -8,12 +8,37 @@ import com.github.insanusmokrassar.TelegramBotAPI.types.message.content.fullEnti import com.github.insanusmokrassar.TelegramBotAPI.types.update.abstracts.BaseSentMessageUpdate import kotlinx.coroutines.flow.* +/** + * Convert incoming [com.github.insanusmokrassar.TelegramBotAPI.types.message.abstracts.ContentMessage.content] of + * messages with [fullEntitiesList] and check that incoming message contains ONLY ONE [TextSource] and that is + * [BotCommandTextSource]. Besides, it is checking that [BotCommandTextSource.command] [Regex.matches] with incoming + * [commandRegex] + * + * @return The same message in case if it contains only [BotCommandTextSource] with [Regex.matches] + * [BotCommandTextSource.command] + * + * @see fullEntitiesList + * @see asContentMessagesFlow + * @see onlyTextContentMessages + */ fun Flow.filterExactCommands( commandRegex: Regex ) = asContentMessagesFlow().onlyTextContentMessages().filter { contentMessage -> (contentMessage.content.fullEntitiesList().singleOrNull() as? BotCommandTextSource) ?.let { commandRegex.matches(it.command) } == true } +/** + * Convert incoming [com.github.insanusmokrassar.TelegramBotAPI.types.message.abstracts.ContentMessage.content] of + * messages with [fullEntitiesList] and check that incoming message contains [BotCommandTextSource]. Besides, it is + * checking that [BotCommandTextSource.command] [Regex.matches] with incoming [commandRegex] + * + * @return The same message in case if it contains somewhere in text [BotCommandTextSource] with [Regex.matches] + * [BotCommandTextSource.command] + * + * @see fullEntitiesList + * @see asContentMessagesFlow + * @see onlyTextContentMessages + */ fun Flow.filterCommandsInsideTextMessages( commandRegex: Regex ) = asContentMessagesFlow().onlyTextContentMessages().filter { contentMessage -> @@ -23,10 +48,18 @@ fun Flow.filterCommandsInsideTextMessages( } /** - * @return Result [Flow] will emit all [TextSource]s to the collector ONLY IN CASE if first [TextSource] is - * [BotCommandTextSource] and its [BotCommandTextSource.command] is [Regex.matches] to incoming [commandRegex]. Internal - * behaviour contains next rules: all incoming text sources will be passed as is, [RegularTextSource] will be divided - * by " " for several [RegularTextSource] which will contains not empty args without spaces + * Convert incoming [com.github.insanusmokrassar.TelegramBotAPI.types.message.abstracts.ContentMessage.content] of + * messages with [fullEntitiesList] and check that incoming message contains first [TextSource] as + * [BotCommandTextSource]. Besides, it is checking that [BotCommandTextSource.command] [Regex.matches] with incoming + * [commandRegex] and for other [TextSource] objects used next rules: all incoming text sources will be passed as is, + * [RegularTextSource] will be split by " " for several [RegularTextSource] which will contains not empty args without + * spaces. + * + * @return Converted list with first entity [BotCommandTextSource] and than all others according to rules in description + * + * @see fullEntitiesList + * @see asContentMessagesFlow + * @see onlyTextContentMessages */ fun Flow.filterCommandsWithArgs( commandRegex: Regex diff --git a/TelegramBotAPI-extensions-utils/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/extensions/utils/updates/SentMessageUpdatesConversations.kt b/TelegramBotAPI-extensions-utils/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/extensions/utils/updates/SentMessageUpdatesConversations.kt index 78d52d8274..15ebf19f76 100644 --- a/TelegramBotAPI-extensions-utils/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/extensions/utils/updates/SentMessageUpdatesConversations.kt +++ b/TelegramBotAPI-extensions-utils/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/extensions/utils/updates/SentMessageUpdatesConversations.kt @@ -5,14 +5,23 @@ import com.github.insanusmokrassar.TelegramBotAPI.types.update.abstracts.BaseSen import kotlinx.coroutines.flow.Flow import kotlinx.coroutines.flow.mapNotNull +/** + * Will map incoming [BaseSentMessageUpdate]s to [ContentMessage] from [BaseSentMessageUpdate.data] + */ fun Flow.asContentMessagesFlow() = mapNotNull { it.data as? ContentMessage<*> } +/** + * Will map incoming [BaseSentMessageUpdate]s to [ChatEventMessage] from [BaseSentMessageUpdate.data] + */ fun Flow.asChatEventsFlow() = mapNotNull { it.data as? ChatEventMessage } +/** + * Will map incoming [BaseSentMessageUpdate]s to [UnknownMessageType] from [BaseSentMessageUpdate.data] + */ fun Flow.asUnknownMessagesFlow() = mapNotNull { it.data as? UnknownMessageType } diff --git a/TelegramBotAPI-extensions-utils/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/extensions/utils/updates/UpdatesChatFilters.kt b/TelegramBotAPI-extensions-utils/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/extensions/utils/updates/UpdatesChatFilters.kt index ab619f683a..4ee90dd8f9 100644 --- a/TelegramBotAPI-extensions-utils/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/extensions/utils/updates/UpdatesChatFilters.kt +++ b/TelegramBotAPI-extensions-utils/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/extensions/utils/updates/UpdatesChatFilters.kt @@ -7,13 +7,25 @@ import com.github.insanusmokrassar.TelegramBotAPI.types.update.abstracts.BaseMes import kotlinx.coroutines.flow.Flow import kotlinx.coroutines.flow.filter +/** + * [Flow.filter] incoming [BaseMessageUpdate]s by their [ChatId] + */ fun Flow.filterBaseMessageUpdates(chatId: ChatId): Flow = filter { it.data.chat.id == chatId } +/** + * [Flow.filter] incoming [BaseMessageUpdate]s by their [ChatId] using [Chat.id] of [chat] + */ fun Flow.filterBaseMessageUpdates(chat: Chat): Flow = filterBaseMessageUpdates(chat.id) +/** + * [Flow.filter] incoming [SentMediaGroupUpdate]s by their [ChatId] + */ fun Flow.filterSentMediaGroupUpdates(chatId: ChatId): Flow = filter { it.data.first().chat.id == chatId } +/** + * [Flow.filter] incoming [SentMediaGroupUpdate]s by their [ChatId] using [Chat.id] of [chat] + */ fun Flow.filterSentMediaGroupUpdates(chat: Chat): Flow = filterSentMediaGroupUpdates(chat.id) diff --git a/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/CommonAbstracts/Captioned.kt b/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/CommonAbstracts/Captioned.kt index 8111d0e9d1..bca0bb2f49 100644 --- a/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/CommonAbstracts/Captioned.kt +++ b/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/CommonAbstracts/Captioned.kt @@ -12,7 +12,15 @@ interface CaptionedOutput : Captioned { } interface CaptionedInput : Captioned { + /** + * Not full list of entities. This list WILL NOT contain [TextPart]s with [com.github.insanusmokrassar.TelegramBotAPI.types.MessageEntity.textsources.RegularTextSource] + * @see [CaptionedInput.fullEntitiesList] + */ val captionEntities: List } +/** + * Convert its [CaptionedInput.captionEntities] to list of [com.github.insanusmokrassar.TelegramBotAPI.CommonAbstracts.TextSource] + * with [com.github.insanusmokrassar.TelegramBotAPI.types.MessageEntity.textsources.RegularTextSource] + */ fun CaptionedInput.fullEntitiesList(): FullTextSourcesList = caption ?.fullListOfSubSource(captionEntities) ?.map { it.source } ?: emptyList() diff --git a/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/CommonAbstracts/Explained.kt b/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/CommonAbstracts/Explained.kt index 941b21e1f0..4cebc2ed29 100644 --- a/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/CommonAbstracts/Explained.kt +++ b/TelegramBotAPI/src/commonMain/kotlin/com/github/insanusmokrassar/TelegramBotAPI/CommonAbstracts/Explained.kt @@ -12,7 +12,15 @@ interface ExplainedOutput : Explained { } interface ExplainedInput : Explained { + /** + * Not full list of entities. This list WILL NOT contain [TextPart]s with [com.github.insanusmokrassar.TelegramBotAPI.types.MessageEntity.textsources.RegularTextSource] + * @see [ExplainedInput.fullEntitiesList] + */ val explanationEntities: List } +/** + * Convert its [ExplainedInput.explanationEntities] to list of [com.github.insanusmokrassar.TelegramBotAPI.CommonAbstracts.TextSource] + * with [com.github.insanusmokrassar.TelegramBotAPI.types.MessageEntity.textsources.RegularTextSource] + */ fun ExplainedInput.fullEntitiesList(): FullTextSourcesList = explanation ?.fullListOfSubSource(explanationEntities) ?.map { it.source } ?: emptyList() diff --git 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 index 9ddd37b480..890f308f36 100644 --- 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 @@ -14,6 +14,10 @@ import com.github.insanusmokrassar.TelegramBotAPI.utils.* data class TextContent( val text: String, + /** + * Not full list of entities. This list WILL NOT contain [TextPart]s with [com.github.insanusmokrassar.TelegramBotAPI.types.MessageEntity.textsources.RegularTextSource] + * @see [TextContent.fullEntitiesList] + */ val entities: List = emptyList() ) : MessageContent { override fun createResend( @@ -67,4 +71,8 @@ data class TextContent( } } +/** + * Convert its [TextContent.entities] to list of [com.github.insanusmokrassar.TelegramBotAPI.CommonAbstracts.TextSource] + * with [com.github.insanusmokrassar.TelegramBotAPI.types.MessageEntity.textsources.RegularTextSource] + */ fun TextContent.fullEntitiesList(): FullTextSourcesList = text.fullListOfSubSource(entities).map { it.source }