From a746205e5909c5d4aa6a198fc213c22c4ff6b217 Mon Sep 17 00:00:00 2001 From: InsanusMokrassar Date: Sat, 10 Jun 2023 18:09:33 +0600 Subject: [PATCH] add default pages for krontab and kslog --- docs/krontab/index.md | 212 ++++++++++++++++++++++++++++++++++++++++++ docs/kslog/index.md | 91 +++++++++++++++++- mkdocs.yml | 1 + 3 files changed, 303 insertions(+), 1 deletion(-) create mode 100644 docs/krontab/index.md diff --git a/docs/krontab/index.md b/docs/krontab/index.md new file mode 100644 index 0000000..ddf7c85 --- /dev/null +++ b/docs/krontab/index.md @@ -0,0 +1,212 @@ +# krontab + +[![Maven Central](https://maven-badges.herokuapp.com/maven-central/dev.inmo/krontab/badge.svg)](https://maven-badges.herokuapp.com/maven-central/dev.inmo/krontab) + +[![Telegram Chat](https://img.shields.io/badge/Telegram%20Chat-0288D1?style=for-the-badge&logo=telegram&logoColor=white)](https://inmodev_chat.t.me) + +![JVM](https://img.shields.io/badge/JVM-red?style=for-the-badge&logo=openjdk&logoColor=white) +![Android](https://img.shields.io/badge/Android-green?style=for-the-badge&logo=android&logoColor=white) +![Js](https://img.shields.io/badge/JavaScript-323330?style=for-the-badge&logo=javascript&logoColor=F7DF1E) +![Linux x64](https://img.shields.io/badge/Linux%20x64-white?style=for-the-badge&logo=linux&logoColor=black) + +[![KDocs](https://img.shields.io/badge/KDocs-323330?style=for-the-badge&logo=Kotlin&logoColor=7F52FF)](https://insanusmokrassar.github.io/krontab/) + +Library was created to give oppotunity to launch some things from time to time according to some schedule in +runtime of applications. + +## How to use + +There are several ways to configure and use this library: + +* From some string +* From builder + +Anyway, to start some action from time to time you will need to use one of extensions/functions: + +```kotlin +val kronScheduler = /* creating of KronScheduler instance */; + +kronScheduler.doWhile { + // some action + true // true - repeat on next time +} +``` + +### Including in project + +If you want to include `krontab` in your project, just add next line to your +dependencies part: + +```groovy +implementation "dev.inmo:krontab:$krontab_version" +``` + +Next version is the latest currently for the library: + +[![Maven Central](https://maven-badges.herokuapp.com/maven-central/dev.inmo/krontab/badge.svg)](https://maven-badges.herokuapp.com/maven-central/dev.inmo/krontab) + +For old version of Gradle, instead of `implementation` word developers must use `compile`. + +### Config from string + +Developers can use more simple way to configure repeat times is string. String configuring +like a `crontab`, but with a little bit different meanings: + +``` +/--------------- Seconds +| /------------- Minutes +| | /----------- Hours +| | | /--------- Days of months +| | | | /------- Months +| | | | | /----- (optional) Year +| | | | | | /--- (optional) Timezone offset +| | | | | | | / (optional) Week days +* * * * * * 0o *w +``` + +It is different with original `crontab` syntax for the reason, that expected that in practice developers +will use seconds and minutes with more probability than months (for example) or even years. In fact, developers will use +something like: + +```kotlin +doWhile("/5 * * * *") { + println("Called") + true // true - repeat on next time +} +``` + +An other version: + +```kotlin +doInfinity("/5 * * * *") { + println("Called") +} +``` + +Both of examples will print `Called` message every five seconds. + +### Config via builder + +Also, this library currently supports DSL for creating the same goals: + +```kotlin +val kronScheduler = buildSchedule { + seconds { + from (0) every 5 + } +} +kronScheduler.doWhile { + println("Called") + true // true - repeat on next time +} +``` + +Or + +```kotlin +val kronScheduler = buildSchedule { + seconds { + 0 every 5 + } +} +kronScheduler.doWhile { + println("Called") + true // true - repeat on next time +} +``` + +Or + +```kotlin +val kronScheduler = buildSchedule { + seconds { + 0 every 5 + } +} +kronScheduler.doInfinity { + println("Called") +} +``` + +All of these examples will do the same things: print `Called` message every five seconds. + +### do\* functions + +With regular `doOnce`/`doWhile`/`doInfinity` there are two types of their variations: **local** and **timezoned**. Local +variations (`doOnceLocal`/`doWhileLocal`/`doInfinityLocal`) will pass `DateTime` as an argument into the block: + +```kotlin +doInfinityLocal("/5 * * * *") { + println(it) // will print current date time +} +``` + +Timezoned variations (`doOnceTz`/`doWhileTz`/`doInfinityTz`) will do the same thing but pass as an argument `DateTimeTz`: + +```kotlin +doInfinityTz("/5 * * * * 0o") { + println(it) // will print current date time in UTC +} +``` + +It is useful in cases when you need to get the time of calling and avoid extra calls to system time. + +#### Helpful table for + +| | No args | Local `DateTime` | Local `DateTimeTz` with offset of `KronScheduler` | +|---| ------- | ---------------- | ------------------------------------------------- | +| **Call only near time** | doOnce | doOnceLocal | doOnceTz | +| **Call while condition is true** | doWhile | doWhileLocal | doWhileTz | +| **Work infinity*** | doInfinity | doInfinityLocal | doInfinityTz | + +*Here there is an important notice, that `Work infinity` is not exactly `infinity`. Actually, that means that `do while +coroutine is alive` and in fact executing will be stopped when coroutine became cancelled. + +### KronScheduler as a Flow + +Any `KronScheduler`can e converted to a `Flow + // do your logging +} +``` + +**This library also supports native targets in experimental mode. By default, all native targets will use simple printing in the console** + +## How to use + +### Fast-travel + +Just use some boring extensions like: + +```kotlin +KSLog.i("Some message") +// OR +KSLog.i("Some tag", "Some message") +// OR +KSLog.i("Some tag", "Some message", IllegalArgumentException("So, that is exception :)")) +// OR +KSLog.i("Some optional tag", Exception("Optional")) { "Lazy inited message" } +// OR +KSLog.iS("Some optional tag", Exception("Optional")) { "Lazy inited message for suspendable calculation of text" } +// OR EVEN +KSLog.l(LogLevel.INFO, "Some tag", "Some message", IllegalArgumentException("So, that is exception :)")) +// OR +KSLog.l(LogLevel.INFO, "Some optional tag", IllegalArgumentException("So, that is exception :)")) { "And lazily inited message" } +``` + +### A little bit deeper + +There are several important "terms" in context of this library: + +* Default logger (available via `KSLog.default` or simply `KSLog`) +* Local logger (can be created via `KSLog` functions and passed anywhere as `KSLog`) +* Logging shortcuts like `KSLog.i`/`KSLog.info` +* Built-in extension `Any.logger` which allow you to create logger binded to the default with the tag based on the class of receiver + * __Be careful with the receivers: if you will use some extension like `apply`, the receiver will be different with your class inside of that `apply`__ + +Every logging extension (like `KSLog.i`) have its analog with lazy inited message text and the same one with suffix `S` (like `KSLog.iS`) for the suspendable message calculation. + +Default logger can be created by passing `defaultTag` and one of variants log level filters: set or minimal loggable level. In `JVM` you also may setup any logger as base logger for default realizations of `KSLog`. Besides, you may use your own callback (on **any target platform**) as output of logging: + +```kotlin +val logger = KSLog { logLevel, optionalTag, message, optionalThrowable -> + println("[$logLevel] $optionalTag - $message: $optionalThrowable.stackTraceToString()") +} +``` + +In the example above we will take the `logger` which will just print incoming data as common output. + +## Installation + +[![Maven Central](https://maven-badges.herokuapp.com/maven-central/dev.inmo/kslog/badge.svg)](https://maven-badges.herokuapp.com/maven-central/dev.inmo/kslog) + +### Gradle + +```groovy +implementation "dev.inmo:kslog:$kslog_version" +``` + +### Maven + +```xml + + dev.inmo + kslog + ${kslog_version} + +``` diff --git a/mkdocs.yml b/mkdocs.yml index dbb8ce0..f775108 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -23,6 +23,7 @@ nav: - Logic handling: 'tgbotapi/logic/' - DSLs: 'tgbotapi/dsls/' - 'Krontab': + - 'krontab/index.md' - Introduction: - 'krontab/introduction/including-in-project.md' - 'krontab/introduction/how-to-use.md'