diff --git a/docs/kslog/index.md b/docs/kslog/index.md new file mode 100644 index 0000000..4e7116a --- /dev/null +++ b/docs/kslog/index.md @@ -0,0 +1,3 @@ +# KSLog + +[KSLog](https://github.com/InsanusMokrassar/kslog) is a simple multiplatform tool for native logging. diff --git a/docs/kslog/logging.md b/docs/kslog/logging.md new file mode 100644 index 0000000..1d7b186 --- /dev/null +++ b/docs/kslog/logging.md @@ -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) +``` \ No newline at end of file diff --git a/docs/kslog/setup.md b/docs/kslog/setup.md new file mode 100644 index 0000000..9d8a6f2 --- /dev/null +++ b/docs/kslog/setup.md @@ -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 + + dev.inmo + kslog + ${kslog_version} + +``` + +## 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(baseLogger) // log all ints to the baseLogger + on { _, _, 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") +) +``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 45d220b..8d5e596 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -29,6 +29,10 @@ nav: - Describing: - 'krontab/describing/string-format.md' - 'krontab/describing/krontabscheduler.md' + - 'KSLog': + - 'kslog/index.md' + - 'kslog/setup.md' + - 'kslog/logging.md' use_directory_urls: false