From ab3c1427a7dd0a6915580b1d02838d10d1d716fe Mon Sep 17 00:00:00 2001 From: Lucas Colombo Date: Sun, 31 Mar 2024 02:03:55 -0300 Subject: [PATCH] =?UTF-8?q?docs(logger):=20=F0=9F=93=9D=20README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/img/logo-logger.svg | 11 +++++ README.md | 2 +- lib/cli/stylize/README.md | 2 +- lib/logger/README.md | 96 +++++++++++++++++++++++++++++++++++++ 4 files changed, 109 insertions(+), 2 deletions(-) create mode 100644 .github/img/logo-logger.svg create mode 100644 lib/logger/README.md diff --git a/.github/img/logo-logger.svg b/.github/img/logo-logger.svg new file mode 100644 index 0000000..40fdfe6 --- /dev/null +++ b/.github/img/logo-logger.svg @@ -0,0 +1,11 @@ + + + + + + \ No newline at end of file diff --git a/README.md b/README.md index b363cef..c5acd8f 100644 --- a/README.md +++ b/README.md @@ -14,4 +14,4 @@ # Features - [x] [cli/stylize](lib/cli/stylize) -- [ ] [logging](lib/logging) \ No newline at end of file +- [x] [logging](lib/logger) \ No newline at end of file diff --git a/lib/cli/stylize/README.md b/lib/cli/stylize/README.md index 5d36f5a..6c0a072 100644 --- a/lib/cli/stylize/README.md +++ b/lib/cli/stylize/README.md @@ -16,7 +16,7 @@ This crate is for internal use. It's only published privately. ```bash -cargo add lool --registry=lugit +cargo add lool --registry=lugit --features cli-stylize ``` # Usage diff --git a/lib/logger/README.md b/lib/logger/README.md new file mode 100644 index 0000000..c5e26f6 --- /dev/null +++ b/lib/logger/README.md @@ -0,0 +1,96 @@ +

+ +
+
+
+ +

lool ยป logger implements a basic console logger to use with the log crate. +

+ +
+
+
+ +# Installation + +This crate is for internal use. It's only published privately. + +```bash +cargo add lool --registry=lugit +``` + +# Setup + +The logger must be initialized before it can be used. The following code snippet shows how to initialize the logger with the default settings: + +```rs +use {log::Level, lool::logger::ConsoleLogger}; + +fn main() { + ConsoleLogger::default_setup(Level::Trace, "my-app").unwrap(); +} +``` + +The `default_setup` function takes two arguments: + +- The maximum log level to display. +- The name of the logger (usually, the name of the application). + + +# Usage + +The logger can be used with the `log` crate. The following code snippet shows how to use the logger: + +```rs +use log::{info, warn, error, trace, debug}; + +fn main() { + info!("This is an info message"); + warn!("This is a warning message"); + error!("This is an error message"); + debug!("This is a debug message"); + trace!("This is a trace message"); +} +``` + +Which will result in the following output: + +```log +[my-app] 2024-03-31 15:44:46 | INFO | main.rs:4 - This is an info message +[my-app] 2024-03-31 15:44:46 | WARN | main.rs:5 - This is a warning message +[my-app] 2024-03-31 15:44:46 | ERROR | main.rs:6 - This is an error message +[my-app] 2024-03-31 15:44:46 | DEBUG | main.rs:7 - This is a debug message +[my-app] 2024-03-31 15:44:46 | TRACE | main.rs:8 - This is a trace message +``` + +# About date and time + +The logger uses a custom datetime function that doesn't depend on any external crate. This was done +to avoid adding unnecessary dependencies, but it also means that the datetime is in the UTC +timezone. + +If we want to use a different timezone, we will need to create a custom implementation or to just +use a crate like `chrono` or `time`. + +That's why the logger provides a second setup function that allows us to pass a custom datetime +function. The custom function should receive no arguments and return a string with the current +datetime. + +```rs +use {log::Level, lool::logger::ConsoleLogger}; +use custom_implementation::custom_datetime_fn; + +fn main() { + ConsoleLogger::custom_setup(Level::Trace, "my-app", custom_datetime_fn).unwrap(); +} +``` + +The library also provides a convenient function in case we just don't want to display the datetime: + +```rs +use {log::Level, lool::logger::{ConsoleLogger, datetime::noop_datetime}}; + +fn main() { + ConsoleLogger::custom_setup(Level::Trace, "my-app", noop_datetime).unwrap(); +} +``` \ No newline at end of file