new dsls for keyboards #472

tgbotapi.core/src/commonMain/kotlin/dev/inmo/tgbotapi/types/CallbackQuery/DataCallbackQuery.kt

@@ -1,5 +1,10 @@
 package dev.inmo.tgbotapi.types.CallbackQuery
 
+/**
+ * [CallbackQuery] with [data] field
+ *
+ * @see dev.inmo.tgbotapi.types.buttons.InlineKeyboardButtons.CallbackDataInlineKeyboardButton
+ */
 sealed interface DataCallbackQuery : CallbackQuery {
     val data: String
 }

tgbotapi.core/src/commonMain/kotlin/dev/inmo/tgbotapi/types/buttons/InlineKeyboardButtons/InlineKeyboardButton.kt

@@ -2,10 +2,13 @@ package dev.inmo.tgbotapi.types.buttons.InlineKeyboardButtons
 
 import dev.inmo.tgbotapi.types.*
 import dev.inmo.tgbotapi.types.games.CallbackGame
-import kotlinx.serialization.SerialName
-import kotlinx.serialization.Serializable
+import kotlinx.serialization.*
 import kotlinx.serialization.json.JsonElement
 
+/**
+ * Some button of [dev.inmo.tgbotapi.types.buttons.InlineKeyboardMarkup]. See inheritors and visit
+ * https://core.telegram.org/bots/api#inlinekeyboardbutton for more info
+ */
 @Serializable(InlineKeyboardButtonSerializer::class)
 sealed interface InlineKeyboardButton {
     val text: String
@@ -17,30 +20,56 @@ data class UnknownInlineKeyboardButton internal constructor(
     val rawData: JsonElement
 ) : InlineKeyboardButton
 
+/**
+ * This type of button must always be the first button in the first row. Visit
+ * https://core.telegram.org/bots/api#payments for mor info
+ */
 @Serializable
 data class PayInlineKeyboardButton(
     override val text: String,
+    @Deprecated("Don't use this button due to removing of this in near release")
+    @Transient
+    val pay: Boolean = true
+) : InlineKeyboardButton {
+    @ExperimentalSerializationApi
+    @EncodeDefault
     @SerialName(payField)
-    val pay: Boolean
-) : InlineKeyboardButton
+    private val toPay = true
+}
 
+/**
+ * Simple button with [callbackData] which you are able to catch this type of updates and data using
+ * [dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onDataCallbackQuery] in
+ * case you are using Behaviour Builder OR [dev.inmo.tgbotapi.updateshandlers.FlowsUpdatesFilter.callbackQueriesFlow]
+ * with [kotlinx.coroutines.flow.filterIsInstance] and filtering by type [dev.inmo.tgbotapi.types.CallbackQuery.DataCallbackQuery]
+ */
 @Serializable
 data class CallbackDataInlineKeyboardButton(
     @SerialName(textField)
     override val text: String,
+    /**
+     * You will receive this data in [dev.inmo.tgbotapi.types.CallbackQuery.DataCallbackQuery.data] field
+     */
     @SerialName(callbackDataField)
     val callbackData: String
 ) : InlineKeyboardButton
 
+/**
+ * Button with [callbackGame]
+ */
 @Serializable
 data class CallbackGameInlineKeyboardButton(
     @SerialName(textField)
     override val text: String
 ) : InlineKeyboardButton {
     @SerialName(callbackGameField)
+    @EncodeDefault
     private val callbackGame = CallbackGame
 }
 
+/**
+ * You may use this button to automatically authorize your user on [loginUrl]
+ */
 @Serializable
 data class LoginURLInlineKeyboardButton(
     override val text: String,
@@ -48,6 +77,16 @@ data class LoginURLInlineKeyboardButton(
     val loginUrl: LoginURL
 ) : InlineKeyboardButton
 
+/**
+ * Complex button with [switchInlineQueryCurrentChat] which will be sent to you in an [dev.inmo.tgbotapi.types.InlineQueries.query.InlineQuery]
+ * which you may catch in [dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onBaseInlineQuery] and get
+ * from [dev.inmo.tgbotapi.types.InlineQueries.query.BaseInlineQuery.query] (or changed by user query in case he will be
+ * the fastest hand in the wild west). Can be forwarded in any chat with message in case if it is the only one button in
+ * message, but will be converted to a [SwitchInlineQueryInlineKeyboardButton].
+ * Remember that clicking on this button will automatically insert username of this bot in current chat, paste
+ * [switchInlineQueryCurrentChat] as a query and create and inline request to your bot
+ * Visit https://core.telegram.org/bots/api#inlinekeyboardbutton for more info
+ */
 @Serializable
 data class SwitchInlineQueryCurrentChatInlineKeyboardButton(
     override val text: String,
@@ -55,6 +94,15 @@ data class SwitchInlineQueryCurrentChatInlineKeyboardButton(
     val switchInlineQueryCurrentChat: String
 ) : InlineKeyboardButton
 
+/**
+ * Complex button with [switchInlineQuery] which will be sent to you in an [dev.inmo.tgbotapi.types.InlineQueries.query.InlineQuery]
+ * which you may catch in [dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onBaseInlineQuery] and get
+ * from [dev.inmo.tgbotapi.types.InlineQueries.query.BaseInlineQuery.query] (or changed by user query in case he will be
+ * the fastest hand in the wild west). Can be forwarded in any chat with message in case if it is the only one button in message.
+ * Remember that clicking on this button will automatically insert username of this bot in the chosen by user chat, paste
+ * [switchInlineQuery] as a query and create and inline request to your bot.
+ * Visit https://core.telegram.org/bots/api#inlinekeyboardbutton for more info
+ */
 @Serializable
 data class SwitchInlineQueryInlineKeyboardButton(
     override val text: String,
@@ -62,6 +110,9 @@ data class SwitchInlineQueryInlineKeyboardButton(
     val switchInlineQuery: String
 ) : InlineKeyboardButton
 
+/**
+ * Simple [url] button. Can be forwarded in any chat with message in case if it is the only one button in message
+ */
 @Serializable
 data class URLInlineKeyboardButton(
     override val text: String,

tgbotapi.core/src/commonMain/kotlin/dev/inmo/tgbotapi/types/buttons/KeyboardButton.kt

@@ -9,11 +9,21 @@ import kotlinx.serialization.encoding.Decoder
 import kotlinx.serialization.encoding.Encoder
 import kotlinx.serialization.json.*
 
+/**
+ * Representation union of https://core.telegram.org/bots/api#keyboardbutton . See inheritors for more info
+ */
 @Serializable(KeyboardButtonSerializer::class)
 sealed interface KeyboardButton {
     val text: String
 }
 
+/**
+ * Simple button. user will send text of this button. You will be able to catch this text in updates and data using
+ * [dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onText] in
+ * case you are using Behaviour Builder OR with [dev.inmo.tgbotapi.updateshandlers.FlowsUpdatesFilter.messagesFlow]
+ * and [kotlinx.coroutines.flow.filterIsInstance] and filtering by type
+ * [dev.inmo.tgbotapi.types.message.abstracts.CommonMessage] and [dev.inmo.tgbotapi.extensions.utils.onlyTextContentMessages]
+*/
 @Serializable
 data class SimpleKeyboardButton(
     override val text: String
@@ -25,22 +35,45 @@ data class UnknownKeyboardButton internal constructor(
     val raw: String
 ) : KeyboardButton
 
+/**
+ * Private chats only. When user will tap on this button, his contact (with his number and name) will be sent to the bot. You will be able
+ * to catch this contact in updates and data using [dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onContact] in
+ * case you are using Behaviour Builder OR with [dev.inmo.tgbotapi.updateshandlers.FlowsUpdatesFilter.messagesFlow]
+ * and [kotlinx.coroutines.flow.filterIsInstance] and filtering by type
+ * [dev.inmo.tgbotapi.types.message.abstracts.CommonMessage] and [dev.inmo.tgbotapi.extensions.utils.onlyContactContentMessages]
+*/
 @Serializable
 data class RequestContactKeyboardButton(
     override val text: String
 ) : KeyboardButton {
     @SerialName(requestContactField)
+    @EncodeDefault
     val requestContact: Boolean = true
 }
 
+/**
+ * Private chats only. When user will tap on this button, his location will be sent to the bot. You will be able
+ * to catch this location in updates and data using [dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onLocation] in
+ * case you are using Behaviour Builder OR with [dev.inmo.tgbotapi.updateshandlers.FlowsUpdatesFilter.messagesFlow]
+ * and [kotlinx.coroutines.flow.filterIsInstance] and filtering by type
+ * [dev.inmo.tgbotapi.types.message.abstracts.CommonMessage] and [dev.inmo.tgbotapi.extensions.utils.onlyLocationContentMessages]
+ */
 @Serializable
 data class RequestLocationKeyboardButton(
     override val text: String
 ) : KeyboardButton {
     @SerialName(requestLocationField)
+    @EncodeDefault
     val requestLocation: Boolean = true
 }
 
+/**
+ * Private chats only. When user will tap on this button, he will be asked for the poll with [requestPoll] options. You will be able
+ * to catch this poll in updates and data using [dev.inmo.tgbotapi.extensions.behaviour_builder.triggers_handling.onPoll] in
+ * case you are using Behaviour Builder OR with [dev.inmo.tgbotapi.updateshandlers.FlowsUpdatesFilter.messagesFlow]
+ * and [kotlinx.coroutines.flow.filterIsInstance] and filtering by type
+ * [dev.inmo.tgbotapi.types.message.abstracts.CommonMessage] and [dev.inmo.tgbotapi.extensions.utils.onlyPollContentMessages]
+ */
 @Serializable
 data class RequestPollKeyboardButton(
     override val text: String,

tgbotapi.core/src/commonMain/kotlin/dev/inmo/tgbotapi/types/buttons/KeyboardButtonPollType.kt

@@ -1,5 +1,6 @@
 package dev.inmo.tgbotapi.types.buttons
 
+import dev.inmo.micro_utils.common.Warning
 import dev.inmo.tgbotapi.types.*
 import dev.inmo.tgbotapi.utils.RiskFeature
 import kotlinx.serialization.KSerializer
@@ -9,19 +10,38 @@ import kotlinx.serialization.encoding.Decoder
 import kotlinx.serialization.encoding.Encoder
 import kotlinx.serialization.json.*
 
+/**
+ * Poll type for [RequestPollKeyboardButton]. Visit https://core.telegram.org/bots/api#keyboardbuttonpolltype for more
+ * info and see inheritors.
+ *
+ * @see KeyboardButtonPollTypeSerializer
+ */
 @Serializable(KeyboardButtonPollTypeSerializer::class)
 sealed interface KeyboardButtonPollType {
     val type: String
 }
 
 @Serializable
+@Warning("This type should be used only in cases you are sure that it is required")
 class UnknownKeyboardButtonPollType internal constructor(override val type: String): KeyboardButtonPollType
 
+/**
+ * Just a regular poll type
+ *
+ * @see dev.inmo.tgbotapi.types.polls.RegularPoll
+ * @see RequestPollKeyboardButton
+ */
 @Serializable
 object RegularKeyboardButtonPollType : KeyboardButtonPollType {
     override val type: String = regularPollType
 }
 
+/**
+ * Quiz poll type
+ *
+ * @see dev.inmo.tgbotapi.types.polls.QuizPoll
+ * @see RequestPollKeyboardButton
+ */
 @Serializable
 object QuizKeyboardButtonPollType : KeyboardButtonPollType {
     override val type: String = quizPollType

tgbotapi.core/src/commonMain/kotlin/dev/inmo/tgbotapi/utils/Matrix.kt

@@ -32,7 +32,7 @@ fun <T> flatMatrix(vararg elements: T): Matrix<T> {
 
 operator fun <T> RowBuilder<T>.plus(t: T) = add(t)
 
-class RowBuilder<T> {
+open class RowBuilder<T> {
     private val mutRow: MutableList<T> = ArrayList()
     val row: List<T>
         get() = mutRow
@@ -41,11 +41,12 @@ class RowBuilder<T> {
     operator fun T.unaryPlus() = add(this)
 }
 
-class MatrixBuilder<T> {
+open class MatrixBuilder<T> {
     private val mutMatrix: MutableList<List<T>> = ArrayList()
     val matrix: Matrix<T>
-        get() = mutMatrix
+        get() = mutMatrix.toList()
 
     fun add(t: List<T>) = mutMatrix.add(t)
     operator fun plus(t: List<T>) = add(t)
+    operator fun T.unaryPlus() = add(listOf(this))
 }