add colors

.fleet/run.json

@@ -18,5 +18,12 @@
             "program": "poetry",
             "args": ["run", "mkdocs", "serve"],
         },
+        {
+            "type": "command",
+            "name": "Generate MicroUtils",
+            "program": "kotlin",
+            "args": ["../../generate_from_template.kts"],
+            "workingDir": "./docs/micro_utils/",
+        },
     ]
 }

docs/micro_utils/colors.md

@@ -0,0 +1,37 @@
+# Colors [![Maven Central](https://maven-badges.herokuapp.com/maven-central/dev.inmo/colors.common/badge.svg)](https://maven-badges.herokuapp.com/maven-central/dev.inmo/colors.common)
+
+* `Group`: `dev.inmo`
+* `ArtifactId`: `colors.common`
+
+Adding dependency:
+
+```groovy
+implementation "dev.inmo:colors.common:latest"
+```
+
+> INFO:
+>
+> All the samples below will represent `HEXAColor` with `r==0xaa`, `g==0xff`, `b==0x00` and `a==0xff`
+
+This package contains mainly one file: [HEXAColor](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.colors.common/-h-e-x-a-color/index.html). This file
+contains unified color with HEXA format. It consumes `UInt` by default constructor and r/g/b/a parameters in other main constructors:
+
+```kotlin
+HEXAColor(0xaaff00ffu) // 0xRGBAu as UInt
+HEXAColor(r = 0xaa, g = 0xff, b = 0x00, a = 0xff)
+HEXAColor(r = 0xaa, g = 0xff, b = 0x00, aOfOne = 1f)
+```
+
+Besides, you may use one of converters:
+
+```kotlin
+HEXAColor.fromAhex(0xffaaff00u) // 0xARGBu as UInt
+HEXAColor.parse("rgba(aa, ff, 00, ff)")
+HEXAColor.parse("rgba(aa, ff, 00)")
+HEXAColor.parse("#af0")
+HEXAColor.parse("#af0f")
+HEXAColor.parse("#aaff00")
+HEXAColor.parse("#aaff00ff")
+```
+
+

docs/micro_utils/colors.template.md

@@ -0,0 +1,42 @@
+group=dev.inmo
+artifact=colors.common
+package=$group.$artifact
+central_package=$group/$artifact
+
+# Colors [![Maven Central](https://maven-badges.herokuapp.com/maven-central/${central_package}/badge.svg)](https://maven-badges.herokuapp.com/maven-central/${central_package})
+
+* `Group`: `$group`
+* `ArtifactId`: `$artifact`
+
+Adding dependency:
+
+```groovy
+implementation "$group:$artifact:latest"
+```
+
+> INFO:
+>
+> All the samples below will represent `HEXAColor` with `r==0xaa`, `g==0xff`, `b==0x00` and `a==0xff`
+
+This package contains mainly one file: [HEXAColor](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.colors.common/-h-e-x-a-color/index.html). This file
+contains unified color with HEXA format. It consumes `UInt` by default constructor and r/g/b/a parameters in other main constructors:
+
+```kotlin
+HEXAColor(0xaaff00ffu) // 0xRGBAu as UInt
+HEXAColor(r = 0xaa, g = 0xff, b = 0x00, a = 0xff)
+HEXAColor(r = 0xaa, g = 0xff, b = 0x00, aOfOne = 1f)
+```
+
+Besides, you may use one of converters:
+
+```kotlin
+HEXAColor.fromAhex(0xffaaff00u) // 0xARGBu as UInt
+HEXAColor.parse("rgba(aa, ff, 00, ff)")
+HEXAColor.parse("rgba(aa, ff, 00)")
+HEXAColor.parse("#af0")
+HEXAColor.parse("#af0f")
+HEXAColor.parse("#aaff00")
+HEXAColor.parse("#aaff00ff")
+```
+
+

docs/micro_utils/repos/index.md

@@ -48,9 +48,72 @@ Contains write-only operations, such as [create](https://microutils.inmo.dev/mic
 > By default, all mutating operations consumes `List`s of data (`List<New>` for `create`, `List<Pair<Id, New>>` for `update` and `List<Id>` for delete),
 > but all they have their extension function-variations with one/two args (like `create` with `New` arg)
 
-`create` operation consumes list of `New` variants of object and produces `Registered`s list. In most cases, `Registered` variant of object should have
+* `create` operation consumes list of `New` variants of object and produces `Registered`s list. In most cases, `Registered` variant of object should have
 `Id` of registered object, but it is not required for repo.
+* `update` operation consumes list of pairs with `Id` and `New` objects and produces list of `Registered` objects.
+* `deleteById` operation consumes list of `Id`s and do not consume anything except of notifying via `deletedObjectsIdsFlow`.
 
-`update` operation consumes list of pairs with `Id` and `New` objects and produces list of `Registered` objects.
+## KeyValue
 
-`deleteById` operation consumes list of `Id`s and do not consume anything except of notifying via `deletedObjectsIdsFlow`.
+Key-value repos has been created to support work with classic key-value stores, where keys are unique across all the repo when values are not unique.
+As well as all the others types of repos, this one have two basic types:
+[ReadKeyValueRepo](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.repos/-read-key-value-repo/index.html) and
+[WriteKeyValueRepo](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.repos/-write-key-value-repo/index.html)
+
+### ReadKeyValueRepo
+
+Read repo provides functions like: [contains](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.repos/-read-key-value-repo/contains.html),
+[get](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.repos/-read-key-value-repo/get.html) or
+[values](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.repos/-read-key-value-repo/values.html).
+
+### WritekeyValueRepo
+
+Contains write-only operations. This interface can be observed via its flows:
+
+* [onNewValue](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.repos/-write-key-value-repo/on-new-value.html) to retrieve newely set values and keys
+* [onValueRemoved](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.repos/-write-key-value-repo/on-value-removed.html) for the values removed from repo
+
+> INFO:
+>
+> By default, all mutating operations consumes some collections. For example, [set](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.repos/-write-key-value-repo/set.html)
+> require `Map` with `Key`s and `Value`s and do not returns anything. Instead, it will throw notification via `onNewValue` flow
+>
+> All the methods on `WriteKeyValueRepo` have their variances with `pairs` (for set) or plain `vararg`s.
+
+* `set` operation consumes map of `Key`s and their `Value`s, set them and produces updates via `onNewValue`
+* `unset` operation consumes list of `Key`s, removing `Value` by `Key` and produces updates via `onValueRemoved`
+* `unsetWithValues` consumes list of `Value`s, removing all `Key`s with the `Value`s equal to one of the input `Value`s, and then produces updates via `onValueRemoved`
+
+## KeyValues
+
+This type of repos contains muliple `Value`s by their unique `Key`. It is not guaranteed, that `Value`s list by any `Key` will contains only unique values,
+but in most cases `Value`s list will not contains copies/same objects.
+
+### [ReadKeyValuesRepo](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.repos/-read-key-values-repo/index.html)
+
+Contains operations for work with value/values getting and checking. For example:
+[count](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.repos/-read-key-values-repo/count.html) for checking of amount of all values in repo
+or values by key; [get](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.repos/-read-key-values-repo/get.html) for getting of values by
+`pagination`.
+
+### [WriteKeyValuesRepo](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.repos/-write-key-values-repo/index.html)
+
+Contains write-only operations. This interface can be observed via its flows:
+
+* [onNewValue](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.repos/-write-key-values-repo/on-new-value.html) will pass `Key` and `Value` when `Value` has been added to the `Key`
+* [onValueRemoved](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.repos/-write-key-values-repo/on-value-removed.html) will pass `Key` and `Value` when `Value` has been removed for the `Key`
+* [onDataCleared](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.repos/-write-key-values-repo/on-data-cleared.html) will pass `Key` when **all** its values has been
+removed by the `clear` operation
+
+> INFO:
+>
+> In difference with other repos, not all the methods of write key values repo require collections.
+>
+> All the methods on `WriteKeyValuesRepo` have their variances with `pairs` (for set) or plain `vararg`s.
+
+* `add` will add `Value`s to their `Key`s without any removing of data
+* `clear` removes all `Value`s by `Key` and `Key` itself from repo
+* `clearWithValue` removes all `Value` with full clear of all data by `Key`s with incoming `Value`
+* `remove` consumes `Map` of `Key`s and the `Value`s which should be removed for each `Key`
+* `removeWithValue` will remove only `Value` from all `Key`s collections without their full wipe
+* `set` consumes `Map` of `Key`s and the `Value`s and will **rewrite** currently exists list of `Value`s and set the `Value`s for their `Key`

docs/micro_utils/repos/inmemory.md

@@ -0,0 +1,20 @@
+# In memory
+
+In memory realizations contains several simple variants:
+
+* [MapCRUDRepo](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.repos/-map-c-r-u-d-repo/index.html)
+* [MapKeyValueRepo](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.repos/-map-key-value-repo/index.html)
+* [MapKeyValuesRepo](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.repos/-map-key-values-repo/index.html)
+
+Each realization contains `Write` and `Read` parents.
+
+There are several important moments:
+
+## [WriteMapCRUDRepo](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.repos/-write-map-c-r-u-d-repo/index.html) (and [MapCRUDRepo](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.repos/-map-c-r-u-d-repo/index.html))
+
+It is an abstract repo with abstract functions: `updateObject` and `createObject`. Both functions require from realization to create `Registered` variant from incoming data and
+both will be called within repo [locker.withWriteLock](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.coroutines/with-write-lock.html).
+
+You may use functions [MapCRUDRepo](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.repos/-map-c-r-u-d-repo.html) with
+passing the callbacks `updateObject` and `createObject` which will be used in their realizations of default [MapCRUDRepo](https://microutils.inmo.dev/micro_utils.dokka/dev.inmo.micro_utils.repos/-map-c-r-u-d-repo/index.html)
+variant

docs/tgbotapi/index.md

@@ -1,6 +1,6 @@
 # TelegramBotAPI
 
-[![Maven Central](https://maven-badges.herokuapp.com/maven-central/dev.inmo/tgbotapi/badge.svg)](https://maven-badges.herokuapp.com/maven-central/dev.inmo/tgbotapi) [![Supported version](https://img.shields.io/badge/Telegram%20Bot%20API-7.1-blue)](https://core.telegram.org/bots/api-changelog#february-16-2024)
+[![Maven Central](https://maven-badges.herokuapp.com/maven-central/dev.inmo/tgbotapi/badge.svg)](https://maven-badges.herokuapp.com/maven-central/dev.inmo/tgbotapi) [![Supported version](https://img.shields.io/badge/Telegram%20Bot%20API-7.2-blue)](https://core.telegram.org/bots/api-changelog#march-31-2024)
 
 <!--- [![Telegram Channel](./resources/tg_channel_qr.jpg)](https://t.me/ktgbotapi) --->
 

generate_from_template.kts

@@ -0,0 +1,54 @@
+import java.io.File
+
+val templateEnding = ".template.md"
+val singleArgumentRegex = Regex("^[\\w\\d]+$")
+val splitterRegex = Regex("[ ]*=[ ]*")
+
+val folder = File("./")
+
+fun String.replaceVariables(variables: Map<String, String>): String {
+    var currentLine = this
+    variables.forEach { (k, v) ->
+        currentLine = currentLine.replace("\${${k}}", v)
+        if (k.matches(singleArgumentRegex)) {
+            currentLine = currentLine.replace("\$${k}", v)
+        }
+    }
+    return currentLine
+}
+
+fun generateFromTemplate(file: File) {
+    val targetFile = File(folder, file.name.replace(templateEnding, ".md"))
+
+    val variables = mutableMapOf<String, String>()
+    var writeVariables = true
+    var text = ""
+    
+    file.readLines().forEach { line ->
+        when {
+            writeVariables && line.startsWith("#") -> {
+                writeVariables = false
+            }
+            writeVariables -> {
+                val splitted = line.split(splitterRegex)
+                if (splitted.size > 1) {
+                    val k = splitted[0]
+                    val v = splitted[1].replaceVariables(variables)
+                    variables[k] = v
+                }
+                return@forEach
+            }
+        }
+        text += line.let {
+            line.replaceVariables(variables) + "\n"
+        }
+    }
+    targetFile.writeText(text)
+    println("${targetFile.name} has been recreated")
+}
+
+folder.listFiles().forEach { file ->
+    if (file.name.endsWith(templateEnding)) {
+        generateFromTemplate(file)
+    }
+}

mkdocs.yml

@@ -10,9 +10,13 @@ nav:
     - Home: 'index.md'
     - 'MicroUtils':
           - 'micro_utils/index.md'
+          - KDocs: 'https://microutils.inmo.dev/index.html'
           - 'micro_utils/resources.md'
           - 'micro_utils/startup.md'
-          - 'micro_utils/repos/'
+          - 'micro_utils/colors.md'
+          - 'Repos':
+                - 'micro_utils/repos/index.md'
+                - 'micro_utils/repos/inmemory.md'
     - 'Telegram Bot API':
         - 'tgbotapi/index.md'
         - KDocs: 'https://tgbotapi.inmo.dev'
@@ -87,7 +91,7 @@ theme:
         - content.action.view
         - content.code.annotate
         - content.code.copy
-        # - content.tabs.link
+        - content.tabs.link
         - content.tooltips
         # - header.autohide
         # - navigation.expand