From 802ad8e45f3ad5d88eb3964c4cca79fa8eecc142 Mon Sep 17 00:00:00 2001
From: Cedrick Cooke <development@cedrickc.net>
Date: Fri, 10 Sep 2021 12:34:26 -0700
Subject: [PATCH] Fix `FilterLogger` minimum log level; update readme for
 filtering

---
 README.md                                     | 46 ++++++++++++++++++-
 logging/src/commonMain/kotlin/FilterLogger.kt |  3 ++
 2 files changed, 48 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 4e1b2284..3aca26de 100644
--- a/README.md
+++ b/README.md
@@ -48,7 +48,8 @@ Logging can be initialized via [`install`]:
 Log.dispatcher.install(ConsoleLogger)
 ```
 
-Custom loggers can be created by implementing the [`Logger`] interface.
+If no [`Logger`] is installed, then log blocks are not called at runtime. Custom loggers can be created by
+implementing the [`Logger`] interface.
 
 #### Android (Logcat)
 
@@ -134,6 +135,46 @@ enum class Sample {
 }
 ```
 
+### Filtering
+
+Tuulbox implements log filtering by decorating [`Logger`]s. 
+
+#### Log Level Filters
+
+Log level filters are installed with [`Logger.withMinimumLogLevel`]. Because the filtering is based on which log call is
+made, instead of the content of the log call, these can be used as an optimization: if all [`Logger`]s installed in the
+root [`DispatchLogger`] have a minimum log level higher than the log call being made, then the log block is never called.
+
+```kotlin
+Log.dispatcher.install(
+    ConsoleLogger
+        .withMinimumLogLevel(LogLevel.Warn)
+)
+
+Log.debug { "This is not called." }
+Log.warn { "This still gets called." }
+```
+
+#### Log Content Filters
+
+Log content filters are installed with [`Logger.withFilter`], and have full access to the content of a log.
+
+
+```kotlin
+Log.dispatcher.install(
+    ConsoleLogger
+        .withFilter { tag, message, metadata, throwable ->
+            metadata[Sensitivity] == Sensitivity.NotSensitive
+        }
+)
+
+Log.debug { "This block is evaluated, but does not get printed to the console." }
+Log.warn { metadata ->
+    metadata[Sensitivity] = Sensitivity.NotSensitive
+    "This is also evaluated, and does print to the console."
+}
+```
+
 ## [Functional](https://juullabs.github.io/tuulbox/functional/index.html)
 
 ![badge-ios]
@@ -361,6 +402,9 @@ limitations under the License.
 [`WriteMetadata`]: https://juullabs.github.io/tuulbox/logging/logging/com.juul.tuulbox.logging/-write-metadata/index.html
 [`ReadMetadata`]: https://juullabs.github.io/tuulbox/logging/logging/com.juul.tuulbox.logging/-read-metadata/index.html
 [`Key`]: https://juullabs.github.io/tuulbox/logging/logging/com.juul.tuulbox.logging/-key/index.html
+[`Logger.withMinimumLogLevel`]: https://juullabs.github.io/tuulbox/logging/logging/com.juul.tuulbox.logging/with-minimum-log-level.html
+[`DispatchLogger`]: https://juullabs.github.io/tuulbox/logging/logging/com.juul.tuulbox.logging/-dispatch-logger/index.html
+[`Logger.withFilter`]: https://juullabs.github.io/tuulbox/logging/logging/com.juul.tuulbox.logging/with-filter.html
 [`runTest`]: https://juullabs.github.io/tuulbox/test/test/com.juul.tuulbox.test/run-test.html
 [`assertContains`]: https://juullabs.github.io/tuulbox/test/test/com.juul.tuulbox.test/assert-contains.html
 [`assertSimilar`]: https://juullabs.github.io/tuulbox/test/test/com.juul.tuulbox.test/assert-similar.html
diff --git a/logging/src/commonMain/kotlin/FilterLogger.kt b/logging/src/commonMain/kotlin/FilterLogger.kt
index 9c5014ff..05c422d6 100644
--- a/logging/src/commonMain/kotlin/FilterLogger.kt
+++ b/logging/src/commonMain/kotlin/FilterLogger.kt
@@ -13,6 +13,9 @@ private class FilterLogger(
     private val inner: Logger,
 ) : Logger {
 
+    override val minimumLogLevel: LogLevel
+        get() = inner.minimumLogLevel
+
     override fun verbose(tag: String, message: String, metadata: ReadMetadata, throwable: Throwable?) {
         if (filter.canLog(tag, message, metadata, throwable)) {
             inner.verbose(tag, message, metadata, throwable)