diff --git a/src/commonMain/kotlin/AutoLoggers.kt b/src/commonMain/kotlin/AutoLoggers.kt index 99128a2..1ada132 100644 --- a/src/commonMain/kotlin/AutoLoggers.kt +++ b/src/commonMain/kotlin/AutoLoggers.kt @@ -1,8 +1,20 @@ package dev.inmo.kslog.common +/** + * Creating base tag using class simple name of receiver + * + * @throws IllegalStateException If there is no opportunity to take simple name of receiver class + */ val Any.logTag get() = this::class.simpleName ?: error("Unable to retrieve log tag") + +/** + * Creating [TagLogger] with [logTag] as base tag + */ val Any.logger: KSLog get() = TagLogger(logTag) +/** + * Creating [TagLogger] using [logger] extension property with [tagBase] as `this` + */ fun taggedLogger(tagBase: Any): KSLog = tagBase.logger diff --git a/src/commonMain/kotlin/CallbackKSLog.kt b/src/commonMain/kotlin/CallbackKSLog.kt index 4a43b34..d785ea5 100644 --- a/src/commonMain/kotlin/CallbackKSLog.kt +++ b/src/commonMain/kotlin/CallbackKSLog.kt @@ -1,13 +1,22 @@ package dev.inmo.kslog.common +import kotlin.jvm.JvmInline + typealias SimpleKSLogCallback = (level: LogLevel, tag: String?, message: Any, throwable: Throwable?) -> Unit -class CallbackKSLog( +/** + * Creates simple [KSLog] which will pass all incoming [performLog] calls to [performLogCallback] + */ +@JvmInline +value class CallbackKSLog( private val performLogCallback: SimpleKSLogCallback ) : KSLog { override fun performLog(level: LogLevel, tag: String?, message: Any, throwable: Throwable?) = performLogCallback(level, tag, message, throwable) } +/** + * Creating [CallbackKSLog] using [performLogCallback] as an argument for constructor + */ fun KSLog( performLogCallback: SimpleKSLogCallback ) = CallbackKSLog(performLogCallback) diff --git a/src/commonMain/kotlin/DefaultKSLog.kt b/src/commonMain/kotlin/DefaultKSLog.kt index 823fd3d..fca0638 100644 --- a/src/commonMain/kotlin/DefaultKSLog.kt +++ b/src/commonMain/kotlin/DefaultKSLog.kt @@ -2,6 +2,15 @@ package dev.inmo.kslog.common import dev.inmo.kslog.common.filter.filtered +/** + * Logger based on [defaultLogging] or [logging] parameter + * + * @param defaultTag will be used in case when `tag` parameter in [performLog] omitted + * @param messageFormatter special formatter which creating [String] inside of [performLog] for each call. Defaults to + * [defaultMessageFormatter] + * @param logging target lambda which will be called with a result of [messageFormatter] logs formatting as a message + * and tag as tag if not `null` and [defaultTag] otherwise + */ class DefaultKSLog( private val defaultTag: String, private val messageFormatter: MessageFormatter = defaultMessageFormatter, diff --git a/src/commonMain/kotlin/KSLog.kt b/src/commonMain/kotlin/KSLog.kt index 3df22bb..c19df1a 100644 --- a/src/commonMain/kotlin/KSLog.kt +++ b/src/commonMain/kotlin/KSLog.kt @@ -14,15 +14,38 @@ enum class LogLevel { ASSERT, } +/** + * Base interface for any logger + * + * @see default + * + */ interface KSLog { + /** + * The only one function required to realization in any inheritor. All other [performLog] functions + * will call this one by default + */ fun performLog(level: LogLevel, tag: String?, message: Any, throwable: Throwable?) + + /** + * Calls default [performLog] with `tag` == `null` + */ fun performLog(level: LogLevel, message: Any, throwable: Throwable?) = performLog(level, null, message, throwable) + /** + * Calls default [performLog] with `message` built using [messageBuilder]. This method supposed to be overriden in + * case when logger supports lazy-loaded messages (like [dev.inmo.kslog.common.filter.FilterKSLog]) + */ fun performLog( level: LogLevel, tag: String?, throwable: Throwable?, messageBuilder: () -> Any ) = performLog(level, tag, messageBuilder(), throwable) + + /** + * Suspendable variant of [performLog] with [messageBuilder]. Uses default [performLog] with `message` built using + * [messageBuilder] by default + */ suspend fun performLogS( level: LogLevel, tag: String?, @@ -71,10 +94,16 @@ internal val printlnLogging: (level: LogLevel, tag: String, message: Any, throwa println(defaultMessageFormatter(l, t, m, e)) } +/** + * Simple builder for [DefaultKSLog] logger based on [defaultTag] + */ fun KSLog( defaultTag: String, ): KSLog = DefaultKSLog(defaultTag) +/** + * Simple builder for [DefaultKSLog] logger based on [defaultTag] and [messageFormatter] + */ fun KSLog( defaultTag: String, messageFormatter: MessageFormatter @@ -93,6 +122,10 @@ fun KSLog( messageFormatter ).filtered(filter) +/** + * Building logger using [KSLog] builder based on [defaultTag] and [messageFormatter]. This logger will also filter + * incoming levels: only levels passed in [levels] param will be logged + */ fun KSLog( defaultTag: String, levels: Iterable, @@ -104,6 +137,10 @@ fun KSLog( } } +/** + * Building logger using [KSLog] builder based on [defaultTag] and [messageFormatter]. This logger will also filter + * incoming levels: only levels passed in [firstLevel], [secondLevel] and [otherLevels] param will be logged + */ fun KSLog( defaultTag: String, firstLevel: LogLevel, @@ -112,6 +149,10 @@ fun KSLog( messageFormatter: MessageFormatter = defaultMessageFormatter, ): KSLog = KSLog(defaultTag, setOf(firstLevel, secondLevel, *otherLevels), messageFormatter) +/** + * Building logger using [KSLog] builder based on [defaultTag] and [messageFormatter]. This logger will also filter + * incoming levels: only levels above [minLoggingLevel] will be logged + */ fun KSLog( defaultTag: String, minLoggingLevel: LogLevel, @@ -123,5 +164,13 @@ fun KSLog( minLoggingLevel.ordinal <= l.ordinal } +/** + * Setting [KSLog.default] logger to [newDefault] + */ fun setDefaultKSLog(newDefault: KSLog) { KSLog.default = newDefault } -fun addDefaultKSLog(newDefault: KSLog) { KSLog.default = KSLog.default + newDefault } +/** + * Setting [KSLog.default] logger to new [CallbackKSLog] using [plus] operation + */ +fun addDefaultKSLog(newDefault: KSLog) { + KSLog.default += newDefault +} diff --git a/src/commonMain/kotlin/KSLogTypealiases.kt b/src/commonMain/kotlin/KSLogTypealiases.kt index 5660ae0..1d55ad4 100644 --- a/src/commonMain/kotlin/KSLogTypealiases.kt +++ b/src/commonMain/kotlin/KSLogTypealiases.kt @@ -1,7 +1,6 @@ package dev.inmo.kslog.common typealias MessageFormatter = (l: LogLevel, t: String?, m: Any, Throwable?) -> String -@Suppress("NOTHING_TO_INLINE") inline fun MessageFormatter(noinline formatter: MessageFormatter) = formatter typealias MessageFilter = (l: LogLevel, t: String?, Throwable?) -> Boolean val defaultMessageFormatter: MessageFormatter = { l, t, m, _ -> "[$l] ${t ?.let { "$it " } ?: ""}- $m" } diff --git a/src/commonMain/kotlin/TagLogger.kt b/src/commonMain/kotlin/TagLogger.kt index 123c5dd..278a75b 100644 --- a/src/commonMain/kotlin/TagLogger.kt +++ b/src/commonMain/kotlin/TagLogger.kt @@ -2,6 +2,9 @@ package dev.inmo.kslog.common import kotlin.jvm.JvmInline +/** + * Logger which will use [tag] as default one in cases when [performLog] have `null` tag + */ @JvmInline value class TagLogger(val tag: String) : KSLog { override fun performLog(level: LogLevel, tag: String?, message: Any, throwable: Throwable?) { diff --git a/src/commonMain/kotlin/filter/FilterKSLog.kt b/src/commonMain/kotlin/filter/FilterKSLog.kt index d369a6c..470dbf3 100644 --- a/src/commonMain/kotlin/filter/FilterKSLog.kt +++ b/src/commonMain/kotlin/filter/FilterKSLog.kt @@ -2,6 +2,10 @@ package dev.inmo.kslog.common.filter import dev.inmo.kslog.common.* +/** + * In its [performLog]/[performLogS] methods do logging only in cases when [messageFilter] returns true for incoming + * parameters + */ class FilterKSLog( private val fallbackLogger: KSLog, private val messageFilter: MessageFilter diff --git a/src/commonMain/kotlin/filter/FilteredExtension.kt b/src/commonMain/kotlin/filter/FilteredExtension.kt index 443ea50..94b085d 100644 --- a/src/commonMain/kotlin/filter/FilteredExtension.kt +++ b/src/commonMain/kotlin/filter/FilteredExtension.kt @@ -3,6 +3,9 @@ package dev.inmo.kslog.common.filter import dev.inmo.kslog.common.KSLog import dev.inmo.kslog.common.MessageFilter +/** + * Creates [FilterKSLog] with applying of [filter] to it + */ fun KSLog.filtered( filter: MessageFilter ) = FilterKSLog(this, filter) diff --git a/src/commonMain/kotlin/typed/TypedKSLog.kt b/src/commonMain/kotlin/typed/TypedKSLog.kt index eab822f..bd15239 100644 --- a/src/commonMain/kotlin/typed/TypedKSLog.kt +++ b/src/commonMain/kotlin/typed/TypedKSLog.kt @@ -3,6 +3,11 @@ package dev.inmo.kslog.common.typed import dev.inmo.kslog.common.* import kotlin.reflect.KClass +/** + * Uses [typedLoggers] [Map] to determine, where incoming __message__s should be sent. If there is no [KClass] key for + * incoming message in [typedLoggers], logger will use logger by `null` key if exists. If there is no default logger + * (by `null` key), logging will be skipped + */ class TypedKSLog( private val typedLoggers: Map?, KSLog> ) : KSLog { diff --git a/src/commonMain/kotlin/typed/TypedKSLogBuilder.kt b/src/commonMain/kotlin/typed/TypedKSLogBuilder.kt index ee93e4a..075cfe5 100644 --- a/src/commonMain/kotlin/typed/TypedKSLogBuilder.kt +++ b/src/commonMain/kotlin/typed/TypedKSLogBuilder.kt @@ -3,6 +3,9 @@ package dev.inmo.kslog.common.typed import dev.inmo.kslog.common.* import kotlin.reflect.KClass +/** + * Special builder for [TypedKSLog] + */ class TypedKSLogBuilder( private val preset: Map?, KSLog> = emptyMap() ) { @@ -22,6 +25,9 @@ class TypedKSLogBuilder( fun build() = TypedKSLog(loggers.toMap()) } +/** + * DSL for [TypedKSLogBuilder] + */ inline fun buildTypedLogger( preset: Map?, KSLog> = emptyMap(), block: TypedKSLogBuilder.() -> Unit diff --git a/src/commonMain/kotlin/utils/Combination.kt b/src/commonMain/kotlin/utils/Combination.kt index cee2897..543d121 100644 --- a/src/commonMain/kotlin/utils/Combination.kt +++ b/src/commonMain/kotlin/utils/Combination.kt @@ -3,6 +3,10 @@ package dev.inmo.kslog.common.utils import dev.inmo.kslog.common.CallbackKSLog import dev.inmo.kslog.common.KSLog +/** + * Will send [KSLog.performLog] of both [this] and [other] [KSLog] instances. In case when [this] will throw exception + * result logger will rethrow it. After it, if [other] will throw exception - will also rethrow it + */ infix operator fun KSLog.plus(other: KSLog) = CallbackKSLog { l, t, m, e -> val resultOfFirst = runCatching { this@plus.performLog(l, t, m, e)