add a lot of kdocs

This commit is contained in:
InsanusMokrassar 2023-11-18 17:15:23 +06:00
parent 7a8bd035f5
commit 81b32b0119
11 changed files with 106 additions and 3 deletions

View File

@ -1,8 +1,20 @@
package dev.inmo.kslog.common 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 val Any.logTag
get() = this::class.simpleName ?: error("Unable to retrieve log tag") get() = this::class.simpleName ?: error("Unable to retrieve log tag")
/**
* Creating [TagLogger] with [logTag] as base tag
*/
val Any.logger: KSLog val Any.logger: KSLog
get() = TagLogger(logTag) get() = TagLogger(logTag)
/**
* Creating [TagLogger] using [logger] extension property with [tagBase] as `this`
*/
fun taggedLogger(tagBase: Any): KSLog = tagBase.logger fun taggedLogger(tagBase: Any): KSLog = tagBase.logger

View File

@ -1,13 +1,22 @@
package dev.inmo.kslog.common package dev.inmo.kslog.common
import kotlin.jvm.JvmInline
typealias SimpleKSLogCallback = (level: LogLevel, tag: String?, message: Any, throwable: Throwable?) -> Unit 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 private val performLogCallback: SimpleKSLogCallback
) : KSLog { ) : KSLog {
override fun performLog(level: LogLevel, tag: String?, message: Any, throwable: Throwable?) = performLogCallback(level, tag, message, throwable) 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( fun KSLog(
performLogCallback: SimpleKSLogCallback performLogCallback: SimpleKSLogCallback
) = CallbackKSLog(performLogCallback) ) = CallbackKSLog(performLogCallback)

View File

@ -2,6 +2,15 @@ package dev.inmo.kslog.common
import dev.inmo.kslog.common.filter.filtered 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( class DefaultKSLog(
private val defaultTag: String, private val defaultTag: String,
private val messageFormatter: MessageFormatter = defaultMessageFormatter, private val messageFormatter: MessageFormatter = defaultMessageFormatter,

View File

@ -14,15 +14,38 @@ enum class LogLevel {
ASSERT, ASSERT,
} }
/**
* Base interface for any logger
*
* @see default
*
*/
interface KSLog { 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?) 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) 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( fun performLog(
level: LogLevel, level: LogLevel,
tag: String?, tag: String?,
throwable: Throwable?, throwable: Throwable?,
messageBuilder: () -> Any messageBuilder: () -> Any
) = performLog(level, tag, messageBuilder(), throwable) ) = performLog(level, tag, messageBuilder(), throwable)
/**
* Suspendable variant of [performLog] with [messageBuilder]. Uses default [performLog] with `message` built using
* [messageBuilder] by default
*/
suspend fun performLogS( suspend fun performLogS(
level: LogLevel, level: LogLevel,
tag: String?, tag: String?,
@ -71,10 +94,16 @@ internal val printlnLogging: (level: LogLevel, tag: String, message: Any, throwa
println(defaultMessageFormatter(l, t, m, e)) println(defaultMessageFormatter(l, t, m, e))
} }
/**
* Simple builder for [DefaultKSLog] logger based on [defaultTag]
*/
fun KSLog( fun KSLog(
defaultTag: String, defaultTag: String,
): KSLog = DefaultKSLog(defaultTag) ): KSLog = DefaultKSLog(defaultTag)
/**
* Simple builder for [DefaultKSLog] logger based on [defaultTag] and [messageFormatter]
*/
fun KSLog( fun KSLog(
defaultTag: String, defaultTag: String,
messageFormatter: MessageFormatter messageFormatter: MessageFormatter
@ -93,6 +122,10 @@ fun KSLog(
messageFormatter messageFormatter
).filtered(filter) ).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( fun KSLog(
defaultTag: String, defaultTag: String,
levels: Iterable<LogLevel>, levels: Iterable<LogLevel>,
@ -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( fun KSLog(
defaultTag: String, defaultTag: String,
firstLevel: LogLevel, firstLevel: LogLevel,
@ -112,6 +149,10 @@ fun KSLog(
messageFormatter: MessageFormatter = defaultMessageFormatter, messageFormatter: MessageFormatter = defaultMessageFormatter,
): KSLog = KSLog(defaultTag, setOf(firstLevel, secondLevel, *otherLevels), messageFormatter) ): 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( fun KSLog(
defaultTag: String, defaultTag: String,
minLoggingLevel: LogLevel, minLoggingLevel: LogLevel,
@ -123,5 +164,13 @@ fun KSLog(
minLoggingLevel.ordinal <= l.ordinal minLoggingLevel.ordinal <= l.ordinal
} }
/**
* Setting [KSLog.default] logger to [newDefault]
*/
fun setDefaultKSLog(newDefault: KSLog) { KSLog.default = 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
}

View File

@ -1,7 +1,6 @@
package dev.inmo.kslog.common package dev.inmo.kslog.common
typealias MessageFormatter = (l: LogLevel, t: String?, m: Any, Throwable?) -> String typealias MessageFormatter = (l: LogLevel, t: String?, m: Any, Throwable?) -> String
@Suppress("NOTHING_TO_INLINE")
inline fun MessageFormatter(noinline formatter: MessageFormatter) = formatter inline fun MessageFormatter(noinline formatter: MessageFormatter) = formatter
typealias MessageFilter = (l: LogLevel, t: String?, Throwable?) -> Boolean typealias MessageFilter = (l: LogLevel, t: String?, Throwable?) -> Boolean
val defaultMessageFormatter: MessageFormatter = { l, t, m, _ -> "[$l] ${t ?.let { "$it " } ?: ""}- $m" } val defaultMessageFormatter: MessageFormatter = { l, t, m, _ -> "[$l] ${t ?.let { "$it " } ?: ""}- $m" }

View File

@ -2,6 +2,9 @@ package dev.inmo.kslog.common
import kotlin.jvm.JvmInline import kotlin.jvm.JvmInline
/**
* Logger which will use [tag] as default one in cases when [performLog] have `null` tag
*/
@JvmInline @JvmInline
value class TagLogger(val tag: String) : KSLog { value class TagLogger(val tag: String) : KSLog {
override fun performLog(level: LogLevel, tag: String?, message: Any, throwable: Throwable?) { override fun performLog(level: LogLevel, tag: String?, message: Any, throwable: Throwable?) {

View File

@ -2,6 +2,10 @@ package dev.inmo.kslog.common.filter
import dev.inmo.kslog.common.* import dev.inmo.kslog.common.*
/**
* In its [performLog]/[performLogS] methods do logging only in cases when [messageFilter] returns true for incoming
* parameters
*/
class FilterKSLog( class FilterKSLog(
private val fallbackLogger: KSLog, private val fallbackLogger: KSLog,
private val messageFilter: MessageFilter private val messageFilter: MessageFilter

View File

@ -3,6 +3,9 @@ package dev.inmo.kslog.common.filter
import dev.inmo.kslog.common.KSLog import dev.inmo.kslog.common.KSLog
import dev.inmo.kslog.common.MessageFilter import dev.inmo.kslog.common.MessageFilter
/**
* Creates [FilterKSLog] with applying of [filter] to it
*/
fun KSLog.filtered( fun KSLog.filtered(
filter: MessageFilter filter: MessageFilter
) = FilterKSLog(this, filter) ) = FilterKSLog(this, filter)

View File

@ -3,6 +3,11 @@ package dev.inmo.kslog.common.typed
import dev.inmo.kslog.common.* import dev.inmo.kslog.common.*
import kotlin.reflect.KClass 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( class TypedKSLog(
private val typedLoggers: Map<KClass<*>?, KSLog> private val typedLoggers: Map<KClass<*>?, KSLog>
) : KSLog { ) : KSLog {

View File

@ -3,6 +3,9 @@ package dev.inmo.kslog.common.typed
import dev.inmo.kslog.common.* import dev.inmo.kslog.common.*
import kotlin.reflect.KClass import kotlin.reflect.KClass
/**
* Special builder for [TypedKSLog]
*/
class TypedKSLogBuilder( class TypedKSLogBuilder(
private val preset: Map<KClass<*>?, KSLog> = emptyMap() private val preset: Map<KClass<*>?, KSLog> = emptyMap()
) { ) {
@ -22,6 +25,9 @@ class TypedKSLogBuilder(
fun build() = TypedKSLog(loggers.toMap()) fun build() = TypedKSLog(loggers.toMap())
} }
/**
* DSL for [TypedKSLogBuilder]
*/
inline fun buildTypedLogger( inline fun buildTypedLogger(
preset: Map<KClass<*>?, KSLog> = emptyMap(), preset: Map<KClass<*>?, KSLog> = emptyMap(),
block: TypedKSLogBuilder.() -> Unit block: TypedKSLogBuilder.() -> Unit

View File

@ -3,6 +3,10 @@ package dev.inmo.kslog.common.utils
import dev.inmo.kslog.common.CallbackKSLog import dev.inmo.kslog.common.CallbackKSLog
import dev.inmo.kslog.common.KSLog 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 -> infix operator fun KSLog.plus(other: KSLog) = CallbackKSLog { l, t, m, e ->
val resultOfFirst = runCatching { val resultOfFirst = runCatching {
this@plus.performLog(l, t, m, e) this@plus.performLog(l, t, m, e)