migrate kslog docs

This commit is contained in:
InsanusMokrassar 2023-06-10 13:45:23 +06:00
parent 089d0cebac
commit e25c832543
4 changed files with 286 additions and 0 deletions

3
docs/kslog/index.md Normal file
View File

@ -0,0 +1,3 @@
# KSLog
[KSLog](https://github.com/InsanusMokrassar/kslog) is a simple multiplatform tool for native logging.

126
docs/kslog/logging.md Normal file
View File

@ -0,0 +1,126 @@
# Logging
> NOTE: **Message type notice**
> On this page all the messages will be just simple `String`, but you may pass any object as the message
As has been said in the [setup](setup.md) section, this library contains next levels of logging with their default representations on each platform:
| Weight (by order) | LogLevel name | JS | JVM Loggers | Android |
| -: | :- | :- | :- | :- |
| 0 | DEBUG | console.log | Level.FINEST | Log.d |
| 1 | VERBOSE | console.info | Level.FINE | Log.v |
| 2 | INFO | console.info | Level.INFO | Log.i |
| 3 | WARNING | console.warn | Level.WARNING | Log.w |
| 4 | ERROR | console.error | Level.SEVERE | Log.e |
| 5 | ASSERT | console.error | Level.SEVERE | Log.wtf |
Each of these levels have fullname and shortname shortcat extensions:
* `KSLog.debug`/`KSLog.d`/`KSLog.dS`
* `KSLog.verbose`/`KSLog.v`/`KSLog.vS`
* `KSLog.info`/`KSLog.i`/`KSLog.iS`
* `KSLog.warning`/`KSLog.w`/`KSLog.wS`
* `KSLog.error`/`KSLog.e`/`KSLog.eS`
* `KSLog.assert`/`KSLog.wtf`/`KSLog.wtfS`
And any of these shortcuts may accept one of several arguments combinations:
* Tag (Optional), Throwable (Optional), Message Builder (simple inline callback for lazy creating of log message). This type of arguments is duplicated with `S` suffix for `suspendable` messages creating, for example
* Message, Throwable (Optional)
* Tag, Message, Throwable (Optional)
So, when you want to log some expected exception, there are three common ways to do it:
```kotlin
val logger = KSLog.default
// with callback
logger.info(tag, throwable) {
"Some your message for this event"
}
// with suspendable callback
logger.infoS(tag, throwable) {
withContext(Dispatchers.Default) {
"Some your message for this event"
}
}
// Just with message
logger.info("Some your message for this event", throwable)
// With message and tag as strings
logger.info(tag, "Some your message for this event", throwable)
```
Of course, any of this calls can be shortenned:
```kotlin
val logger = KSLog.default
// with callback
logger.i(tag, throwable) {
"Some your message for this event"
}
// with suspendable callback
logger.iS(tag, throwable) {
withContext(Dispatchers.Default) {
"Some your message for this event"
}
}
// Just with message
logger.i("Some your message for this event", throwable)
// With message and tag as strings
logger.i(tag, "Some your message for this event", throwable)
```
There is special shortcat - for base `performLog`. In that case the only change is that you will require to pass the `LogLevel` more obviously:
```kotlin
val logger = KSLog.default
// with callback
logger.log(LogLevel.INFO, tag, throwable) {
"Some your message for this event"
}
// with suspendable callback
logger.logS(LogLevel.INFO, tag, throwable) {
withContext(Dispatchers.Default) {
"Some your message for this event"
}
}
// Just with message
logger.log(LogLevel.INFO, "Some your message for this event", throwable)
// With message and tag as strings
logger.log(LogLevel.INFO, tag, "Some your message for this event", throwable)
```
OR
```kotlin
val logger = KSLog.default
// with callback
logger.l(LogLevel.INFO, tag, throwable) {
"Some your message for this event"
}
// with suspendable callback
logger.lS(LogLevel.INFO, tag, throwable) {
withContext(Dispatchers.Default) {
"Some your message for this event"
}
}
// Just with message
logger.l(LogLevel.INFO, "Some your message for this event", throwable)
// With message and tag as strings
logger.l(LogLevel.INFO, tag, "Some your message for this event", throwable)
```

153
docs/kslog/setup.md Normal file
View File

@ -0,0 +1,153 @@
# Setup
## Dependency 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)
```groovy
implementation "dev.inmo:kslog:$kslog_version"
```
### Gradle (Kotlin Script)
```kotlin
implementation("dev.inmo:kslog:$kslog_version")
```
### Maven (pom)
```xml
<dependency>
<groupId>dev.inmo</groupId>
<artifactId>kslog</artifactId>
<version>${kslog_version}</version>
</dependency>
```
## Setup in code
The main point in setup in your code is to setup default logger:
```kotlin
KSLog.default = KSLog("defaultTag")
```
You may use custom `messageFormatter` in any of `KSLog` factory to customize output of `KSLog` logging. For example:
```kotlin
KSLog(
"loggingWithCustomFormat",
messageFormatter = { level, tag, message, throwable ->
println("[$level] $tag - $message: $throwable")
}
)
```
Additionally you may use one of several different settings:
* `minLoggingLevel` - minimal logging level for the log which will be logged. The order of log level is next:
* DEBUG
* VERBOSE
* INFO
* WARNING
* ERROR
* ASSERT
* `levels` - and iterable with the levels which should be logged
* `firstLevel`,`secondLevel`,`otherLevels` - as `levels`, but `vararg` :)
In case you are passing `minLoggingLevel`, the **level and more important levels** will be passed to logs. For example, when you are settings up your logger as in next snippet:
```kotlin
val logger = KSLog(
"exampleTag",
minLoggingLevel = LogLevel.INFO
)
```
The next levels will be logged with `logger`:
* `INFO`
* `WARNING`
* `ERROR`
* `ASSERT`
## Special loggers
### CallbackKSLog
It is logger which will call incoming `performLogCallback` on each logging. This logger can be create simply with one callback:
```kotlin
KSLog { level, tag, message, throwable ->
println("[$level] $tag - $message: $throwable")
}
```
### TagLogger
It is simple value class which can be used for zero-cost usage of some tag and calling for `KSLog.default`. For example, if you will create tag logger with next code:
```kotlin
val logger = TagLogger("tagLoggerTag")
```
The `logger` will call `KSLog.default` with the tag `tagLoggerTag` on each calling of logging.
### FilterKSLog
This pretty simple logger will call its `fallbackLogger` only in cases when incoming `messageFilter` will return true for logging:
```kotlin
val baseLogger = KSLog("base") // log everything with the tag `base` if not set other
val filtered = baseLogger.filtered { _, t, _ ->
t == "base"
}
```
In the example above `baseLogger` will perform logs in two ways: when it has been called directly or when we call log performing with the tag `"base"` or `null`. Besides, you can see there extension `filtered` which allow to create `FilterKSLog` logger with simple lambda.
### TypedKSLog
This logger accepts map of types with the target loggers. You may build this logger with the special simple DSL:
```kotlin
val baseLogger = KSLog("base") // log everything with the tag `base` if not set other
val typed = buildTypedLogger {
on<Int>(baseLogger) // log all ints to the baseLogger
on<Float> { _, _, message, _ ->// log all floats to the passed logger
println(message.toString()) // just print all floats
}
default { level, tag, message, throwable ->
KSLog.performLog(level, tag, message, throwable)
}
}
```
### Automatical loggers
There are two things which can be useful in your code: `logger` and `logTag` extensions. `logTag` is the autocalculated by your object classname tag. `logger` extension can be used with applying to any object like in the next snippet:
```kotlin
class SomeClass {
init {
logger.i("inited")
}
}
```
The code above will trigger calling of logging in `KSLog.default` with level `LogLevel.INFO` using tag `SomeClass` and message `"inited"`. As you could have guessed, `logger` is using `TagLogger` with `logTag` underhood and the most expensive operation here is automatical calculation of `logTag`.
* Extension `logger`
## JVM specific setup
For JVM you may setup additionally use java loggers as the second parameter of `KSLog` factory. For example:
```kotlin
KSLog(
"yourTag"
Logger.getLogger("YourJavaLoggerName")
)
```

View File

@ -29,6 +29,10 @@ nav:
- Describing: - Describing:
- 'krontab/describing/string-format.md' - 'krontab/describing/string-format.md'
- 'krontab/describing/krontabscheduler.md' - 'krontab/describing/krontabscheduler.md'
- 'KSLog':
- 'kslog/index.md'
- 'kslog/setup.md'
- 'kslog/logging.md'
use_directory_urls: false use_directory_urls: false