mirror of
https://github.com/InsanusMokrassar/docs.git
synced 2024-11-22 16:24:00 +00:00
add default pages for krontab and kslog
This commit is contained in:
parent
7e76249dbb
commit
a746205e59
212
docs/krontab/index.md
Normal file
212
docs/krontab/index.md
Normal file
@ -0,0 +1,212 @@
|
|||||||
|
# krontab
|
||||||
|
|
||||||
|
[](https://maven-badges.herokuapp.com/maven-central/dev.inmo/krontab)
|
||||||
|
|
||||||
|
[](https://inmodev_chat.t.me)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
[](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:
|
||||||
|
|
||||||
|
[](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<DateTime` using extension `asFlow`:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
val kronScheduler = buildSchedule {
|
||||||
|
seconds {
|
||||||
|
0 every 1
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
val flow = kronScheduler.asFlow()
|
||||||
|
```
|
||||||
|
|
||||||
|
So, in this case any operations related to flow are available and it is expected that they will work correctly. For
|
||||||
|
example, it is possible to use this flow with `takeWhile`:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
flow.takeWhile {
|
||||||
|
condition()
|
||||||
|
}.collect {
|
||||||
|
action()
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Offsets
|
||||||
|
|
||||||
|
Offsets in this library works via passing parameter ending with `o` in any place after `month` config. Currently
|
||||||
|
there is only one format supported for offsets: minutes of offsets. To use time zones you will need to call `next`
|
||||||
|
method with `DateTimeTz` argument or `nextTimeZoned` method with any `KronScheduler` instance, but in case if this
|
||||||
|
scheduler is not instance of `KronSchedulerTz` it will work like you passed just `DateTime`.
|
||||||
|
|
||||||
|
Besides, in case you wish to use time zones explicitly, you will need to get `KronSchedulerTz`. It is possible by:
|
||||||
|
|
||||||
|
* Using `createSimpleScheduler`/`buildSchedule`/`KrontabTemplate#toSchedule`/`KrontabTemplate#toKronScheduler` methods
|
||||||
|
with passing `defaultOffset` parameter
|
||||||
|
* Using `SchedulerBuilder#build`/`createSimpleScheduler`/`buildSchedule`/`KrontabTemplate#toSchedule`/`KrontabTemplate#toKronScheduler`
|
||||||
|
methods with casting to `KronSchedulerTz` in case you are pretty sure that it is timezoned `KronScheduler`
|
||||||
|
* Creating your own implementation of `KronSchedulerTz`
|
||||||
|
|
||||||
|
### Note about week days
|
||||||
|
|
||||||
|
Unlike original CRON, here week days:
|
||||||
|
|
||||||
|
* Works as `AND`: cron date time will search first day which will pass requirement according all parameters including
|
||||||
|
week days
|
||||||
|
* You may use any related to numbers syntax with week days: `0-3w`, `0,1,2,3w`, etc.
|
||||||
|
* Week days (like years and offsets) are optional and can be placed anywhere after `month`
|
||||||
@ -1,3 +1,92 @@
|
|||||||
# KSLog
|
# KSLog
|
||||||
|
|
||||||
[KSLog](https://github.com/InsanusMokrassar/kslog) is a simple multiplatform tool for native logging.
|
It is simple and easy-to-use tool for logging on the most popular platforms in Kotlin Multiplatform:
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
[](https://insanusmokrassar.github.io/KSLog/)
|
||||||
|
|
||||||
|
By default, KSLog is using built-in tools for logging on each supported platform:
|
||||||
|
|
||||||
|
* `java.util.logging.Logger` for `JVM`
|
||||||
|
* `android.util.Log` for `Android`
|
||||||
|
* `Console` for `JS`
|
||||||
|
|
||||||
|
But you always may create your logger and customize as you wish:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
KSLog.default = KSLog { level: LogLevel, tag: String?, message: Any, throwable: Throwable? ->
|
||||||
|
// 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
|
||||||
|
|
||||||
|
[](https://maven-badges.herokuapp.com/maven-central/dev.inmo/kslog)
|
||||||
|
|
||||||
|
### Gradle
|
||||||
|
|
||||||
|
```groovy
|
||||||
|
implementation "dev.inmo:kslog:$kslog_version"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Maven
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<dependency>
|
||||||
|
<groupId>dev.inmo</groupId>
|
||||||
|
<artifactId>kslog</artifactId>
|
||||||
|
<version>${kslog_version}</version>
|
||||||
|
</dependency>
|
||||||
|
```
|
||||||
|
|||||||
@ -23,6 +23,7 @@ nav:
|
|||||||
- Logic handling: 'tgbotapi/logic/'
|
- Logic handling: 'tgbotapi/logic/'
|
||||||
- DSLs: 'tgbotapi/dsls/'
|
- DSLs: 'tgbotapi/dsls/'
|
||||||
- 'Krontab':
|
- 'Krontab':
|
||||||
|
- 'krontab/index.md'
|
||||||
- Introduction:
|
- Introduction:
|
||||||
- 'krontab/introduction/including-in-project.md'
|
- 'krontab/introduction/including-in-project.md'
|
||||||
- 'krontab/introduction/how-to-use.md'
|
- 'krontab/introduction/how-to-use.md'
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user