Added formatting code documentation

.github/formatting_codes.md

@@ -0,0 +1,60 @@
+# Formatting codes
+
+When formatting a message you can use arguments in the form of `{{name}}`. Following arguments are available by default:
+
+| Name        | Description                                                                                                                                                           | Example               |
+| :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------- |
+| `message`   | Log message                                                                                                                                                           | `My message`          |
+| `level`     | Uppercase level name. Will have colors attached to it if the output is stdout or stderr                                                                               | `ERROR`               |
+| `timestamp` | UTC timestamp the log function was called (Technically the time the format function was called). Can be formatted using the `timestamp_format` field of the formatter | `2023-11-27 20:49:47` |
+| `path`      | Relative path to the caller of the log macro                                                                                                                          | `src\main.rs`         |
+
+Users can also specify custom arguments by either supplying a `Vec<(&str, String)>` of key-value pairs of the argument name and value or using the fields in the macros:
+
+```rust,ignore
+logging_rs::log!(logger, "My message with {{arg}}", "arg" = "my arguments")
+```
+
+## ASCII format characters
+
+Most terminals support special ASCII characters.
+
+| Name                   | Description                                         |
+| :--------------------- | :-------------------------------------------------- |
+| `end`                  | Escapes any previously started escape sequences     |
+| `bold`                 | Makes the text bold                                 |
+| `italic`               | Makes the text italic                               |
+| `underline`            | Underlines the text                                 |
+| `overline`             | Overlines the text (Not supported by all terminals) |
+| `color.black`          | Makes the text black                                |
+| `color.red`            | Makes the text red                                  |
+| `color.green`          | Makes the text green                                |
+| `color.yellow`         | Makes the text yellow                               |
+| `color.blue`           | Makes the text blue                                 |
+| `color.magenta`        | Makes the text magenta                              |
+| `color.cyan`           | Makes the text cyan                                 |
+| `color.white`          | Makes the text white                                |
+| `color.bright_black`   | Makes the text bright black                         |
+| `color.bright_red`     | Makes the text bright red                           |
+| `color.bright_green`   | Makes the text bright green                         |
+| `color.bright_yellow`  | Makes the text bright yellow                        |
+| `color.bright_blue`    | Makes the text bright blue                          |
+| `color.bright_magenta` | Makes the text bright magenta                       |
+| `color.bright_cyan`    | Makes the text bright cyan                          |
+| `color.bright_white`   | Makes the text bright white                         |
+| `back.black`           | Makes the text background black                     |
+| `back.red`             | Makes the text background red                       |
+| `back.green`           | Makes the text background green                     |
+| `back.yellow`          | Makes the text background yellow                    |
+| `back.blue`            | Makes the text background blue                      |
+| `back.magenta`         | Makes the text background magenta                   |
+| `back.cyan`            | Makes the text background cyan                      |
+| `back.white`           | Makes the text background white                     |
+| `back.bright_black`    | Makes the text background bright black              |
+| `back.bright_red`      | Makes the text background bright red                |
+| `back.bright_green`    | Makes the text background bright green              |
+| `back.bright_yellow`   | Makes the text background bright yellow             |
+| `back.bright_blue`     | Makes the text background bright blue               |
+| `back.bright_magenta`  | Makes the text background bright magenta            |
+| `back.bright_cyan`     | Makes the text background bright cyan               |
+| `back.bright_white`    | Makes the text background bright white              |

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "logging-rs"
 description = "logging-rs helps you add logging to your projects using simple macros."
-version = "1.0.0"
+version = "1.1.0"
 authors = [
 	"ElBe-Plaq <elbe.dev.plaq@gmail.com>"
 ]
@@ -18,4 +18,4 @@ categories = [
 publish = true
 
 [dependencies]
-# chrono = "0.4.31"
+chrono = "0.4.31"

examples/main.rs

@@ -9,4 +9,11 @@ fn main() {
     logging_rs::error!(logger, "Error!");
     logging_rs::fatal!(logger, "Fatal error!");
     logging_rs::log!(logger, "Log message");
+
+    logging_rs::debug!(logger, "Debug message with {{more_info}}", "more_info" = "additional information");
+    logging_rs::info!(logger, "Info and {{details}}", "details" = "more stuff");
+    logging_rs::warn!(logger, "Warning: {{name}} is bad", "name" = "War");
+    logging_rs::error!(logger, "Error! {{stuff}} went wrong", "stuff" = "Everything");
+    logging_rs::fatal!(logger, "Fatal error! Code {{code}}", "code" = "404");
+    logging_rs::log!(logger, "Log message and {{more}}", "more" = "more");
 }

src/errors.rs

@@ -1,6 +1,6 @@
 #![doc = include_str!("../.github/errors.md")]
 // logging-rs errors
-// Version: 1.0.0
+// Version: 1.1.0
 
 // Copyright (c) 2023-present ElBe Development.
 

src/lib.rs

@@ -1,6 +1,6 @@
 #![doc = include_str!("../.github/README.md")]
-// Logging-rs.
+// Logging-rs
-// Version: 1.0.0
+// Version: 1.1.0
 
 // Copyright (c) 2023-present I Language Development.
 
@@ -36,7 +36,7 @@ pub mod errors;
 use std;
 use std::io::Write;
 
-// use chrono;
+use chrono;
 
 
 ////////////////
@@ -62,25 +62,6 @@ pub enum Level {
 }
 
 
-//////////////////
-// HTTP METHODS //
-//////////////////
-
-// HTTP methods
-/*#[derive(Copy, Clone, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
-pub enum HTTPMethod {
-    /// GET request. The default value
-    #[default]
-    GET,
-    /// POST request
-    POST,
-    /// PUT request
-    PUT,
-    /// PATCH request
-    PATCH
-}*/
-
-
 /////////////////
 // OUTPUT TYPE //
 /////////////////
@@ -97,12 +78,7 @@ pub enum Output {
     FILE {
         /// File path
         path: String
-    },
+    }
-    // Web request (not currently implemented)
-    /*REQUEST {
-        method: HTTPMethod,
-        url: String
-    }*/
 }
 
 
@@ -208,7 +184,7 @@ impl Formatter {
     ///     logging_rs::Output::default(),
     ///     logging_rs::Level::default(),
     ///     "Some message with an {{argument}}",
-    ///     vec![("argument", "replaced value")]
+    ///     vec![("argument", "replaced value".to_string())]
     /// );
     /// ```
     ///
@@ -217,90 +193,78 @@ impl Formatter {
     /// - [`Formatter`]
     /// - [`Output`]
     /// - [`Level`]
-    pub fn format<'a>(&self, output: Output, level: Level, message: &'a str, mut arguments: Vec<(&str, &'a str)>) -> String {
+    #[doc = include_str!("../.github/formatting_codes.md")]
-        // TODO (ElBe): Make timestamps work. None of chrono, time or humantime have the things I want
+    pub fn format<'a>(&self, output: Output, level: Level, message: &'a str, mut extra_arguments: Vec<(&str, String)>) -> String {
-        let timestamp: &str = "TIMESTAMP";
+        let mut arguments: Vec<(&str, String)> = vec![];
-
+        let mut colors: Vec<(&str, String)> = vec![
-        // let time = chrono::Utc::now();
-        //let _timestamp = time.format("%Y-%m-%d %H:%M:%S").to_string(); //chrono::format::DelayedFormat<chrono::format::StrftimeItems<'_>>
-        //let parsed = chrono::NaiveDateTime::parse_from_str(&_timestamp.to_string(), "%Y-%m-%d %H:%M:%S").expect("Bad");
-
-        //let borrowed = &_timestamp;
-
-        //println!("{}", _timestamp);
-        //println!("{}", parsed.to_string().as_str());
-
-        // arguments.push(("timestamp", &time.format("%Y-%m-%d %H:%M:%S").to_string()));
-
-        let mut colors: Vec<(&str, &str)> = vec![
             // Formatting codes
-            ("end", "\x1b[0m"),
+            ("end", "\x1b[0m".to_string()),
-            ("bold", "\x1b[1m"),
+            ("bold", "\x1b[1m".to_string()),
-            ("italic", "\x1b[3m"),
+            ("italic", "\x1b[3m".to_string()),
-            ("underline", "\x1b[4m"),
+            ("underline", "\x1b[4m".to_string()),
-            ("overline", "\x1b[53m"),
+            ("overline", "\x1b[53m".to_string()),
 
             // Foreground colors
-            ("color.black", "\x1b[30m"),
+            ("color.black", "\x1b[30m".to_string()),
-            ("color.red", "\x1b[31m"),
+            ("color.red", "\x1b[31m".to_string()),
-            ("color.green", "\x1b[32m"),
+            ("color.green", "\x1b[32m".to_string()),
-            ("color.yellow", "\x1b[33m"),
+            ("color.yellow", "\x1b[33m".to_string()),
-            ("color.blue", "\x1b[34m"),
+            ("color.blue", "\x1b[34m".to_string()),
-            ("color.magenta", "\x1b[35m"),
+            ("color.magenta", "\x1b[35m".to_string()),
-            ("color.cyan", "\x1b[36m"),
+            ("color.cyan", "\x1b[36m".to_string()),
-            ("color.white", "\x1b[37m"),
+            ("color.white", "\x1b[37m".to_string()),
 
             // Bright foreground colors
-            ("color.bright_black", "\x1b[90m"),
+            ("color.bright_black", "\x1b[90m".to_string()),
-            ("color.bright_red", "\x1b[91m"),
+            ("color.bright_red", "\x1b[91m".to_string()),
-            ("color.bright_green", "\x1b[92m"),
+            ("color.bright_green", "\x1b[92m".to_string()),
-            ("color.bright_yellow", "\x1b[93m"),
+            ("color.bright_yellow", "\x1b[93m".to_string()),
-            ("color.bright_blue", "\x1b[94m"),
+            ("color.bright_blue", "\x1b[94m".to_string()),
-            ("color.bright_magenta", "\x1b[95m"),
+            ("color.bright_magenta", "\x1b[95m".to_string()),
-            ("color.bright_cyan", "\x1b[96m"),
+            ("color.bright_cyan", "\x1b[96m".to_string()),
-            ("color.bright_white", "\x1b[97m"),
+            ("color.bright_white", "\x1b[97m".to_string()),
 
             // Background colors
-            ("back.black", "\x1b[40m"),
+            ("back.black", "\x1b[40m".to_string()),
-            ("back.red", "\x1b[41m"),
+            ("back.red", "\x1b[41m".to_string()),
-            ("back.green", "\x1b[42m"),
+            ("back.green", "\x1b[42m".to_string()),
-            ("back.yellow", "\x1b[43m"),
+            ("back.yellow", "\x1b[43m".to_string()),
-            ("back.blue", "\x1b[44m"),
+            ("back.blue", "\x1b[44m".to_string()),
-            ("back.magenta", "\x1b[45m"),
+            ("back.magenta", "\x1b[45m".to_string()),
-            ("back.cyan", "\x1b[46m"),
+            ("back.cyan", "\x1b[46m".to_string()),
-            ("back.white", "\x1b[47m"),
+            ("back.white", "\x1b[47m".to_string()),
 
             // Bright background colors
-            ("back.bright_black", "\x1b[100m"),
+            ("back.bright_black", "\x1b[100m".to_string()),
-            ("back.bright_red", "\x1b[101m"),
+            ("back.bright_red", "\x1b[101m".to_string()),
-            ("back.bright_green", "\x1b[102m"),
+            ("back.bright_green", "\x1b[102m".to_string()),
-            ("back.bright_yellow", "\x1b[103m"),
+            ("back.bright_yellow", "\x1b[103m".to_string()),
-            ("back.bright_blue", "\x1b[104m"),
+            ("back.bright_blue", "\x1b[104m".to_string()),
-            ("back.bright_magenta", "\x1b[105m"),
+            ("back.bright_magenta", "\x1b[105m".to_string()),
-            ("back.bright_cyan", "\x1b[106m"),
+            ("back.bright_cyan", "\x1b[106m".to_string()),
-            ("back.bright_white", "\x1b[107m"),
+            ("back.bright_white", "\x1b[107m".to_string()),
         ];
 
-        let level_string: (&str, &str) = ("level", match level {
+        let level_string: (&str, String) = ("level", match level {
             Level::DEBUG => "DEBUG",
             Level::INFO => "INFO",
             Level::WARN => "WARNING",
             Level::ERROR => "ERROR",
             Level::FATAL => "FATAL",
             Level::MESSAGE => "MESSAGE"
-        });
+        }.to_string());
-        let colored_level_string: (&str, &str) = ("level", match level {
+        let colored_level_string: (&str, String) = ("level", match level {
             Level::DEBUG => "DEBUG",
             Level::INFO => "{{color.blue}}INFO{{end}}",
             Level::WARN => "{{color.yellow}}WARNING{{end}}",
             Level::ERROR => "{{color.red}}ERROR{{end}}",
             Level::FATAL => "{{color.red}}FATAL{{end}}",
             Level::MESSAGE => "{{color.blue}}MESSAGE{{end}}"
-        });
+        }.to_string());
 
-        arguments.push(("message", message));
+        arguments.push(("message", message.to_string()));
-        arguments.push(("timestamp", timestamp));
+        arguments.push(("timestamp", chrono::Utc::now().format(&self.timestamp_format).to_string()));
-        //arguments.push(("timestamp", chrono::Utc::now().format("%Y-%m-%d %H:%M:%S").to_string().to_owned().as_str()));
+        arguments.append(&mut extra_arguments);
 
         let mut result: String = match output {
             Output::STDOUT | Output::STDERR => {
@@ -316,7 +280,7 @@ impl Formatter {
         arguments.append(&mut colors);
 
         for (key, value) in arguments {
-            result = result.replace(("{{".to_owned() + key + "}}").as_str(), value);
+            result = result.replace(("{{".to_owned() + key + "}}").as_str(), &value);
         }
 
         return result.clone();
@@ -399,6 +363,7 @@ impl Logger {
     /// - `message`: The message to log
     /// - `level`: The log [`Level`] to use for logging
     /// - `path`: The path of the calling file
+    /// - `arguments`: A list of arguments to use when formatting the message
     ///
     /// # Returns
     ///
@@ -412,7 +377,8 @@ impl Logger {
     /// logger.log(
     ///     "Some message",
     ///     logging_rs::Level::default(),
-    ///     "src/lib.rs"
+    ///     "src/lib.rs",
+    ///     vec![]
     /// );
     /// ```
     ///
@@ -426,9 +392,10 @@ impl Logger {
     /// - [`log!()`]
     /// - [`Logger`]
     /// - [`Level`]
-    pub fn log(&self, message: &str, level: Level, path: &str) {
+    pub fn log(&self, message: &str, level: Level, path: &str, mut arguments: Vec<(&str, String)>) {
+        arguments.push(("path", path.to_string()));
         for writable in self.writable_list.clone() {
-            let formatted: String = self.formatter.format(writable.clone(), level, message, vec![("path", path)]);
+            let formatted: String = self.formatter.format(writable.clone(), level, message, arguments.clone());
 
             match writable {
                 Output::STDOUT => println!("{}", formatted),
@@ -444,16 +411,7 @@ impl Logger {
                     if let Err(error) = write {
                         errors::Error::new("Writing error", "The file could not be edited", 2).raise(format!("File: {}\nText: {}\nError: {}", path, formatted, error).as_str());
                     }
-                },
+                }
-                // TODO (ElBe): Add HTTP support
-                /*Output::REQUEST { ref method, ref url } => {
-                    match method {
-                        HTTPMethod::GET => {},
-                        HTTPMethod::POST => {},
-                        HTTPMethod::PUT => {},
-                        HTTPMethod::PATCH => {},
-                    }
-                }*/
             }
         }
     }
@@ -477,6 +435,7 @@ impl Logger {
 /// # use logging_rs;
 /// # let logger: logging_rs::Logger = logging_rs::Logger::default();
 /// logging_rs::debug!(logger, "A message");
+/// logging_rs::debug!(logger, "A message with more {{details}}", "details" = "stuff");
 /// ```
 ///
 /// # See also
@@ -491,7 +450,19 @@ impl Logger {
 macro_rules! debug {
     ($logger:expr, $message:expr) => {
         {
-            $logger.log($message, $crate::Level::DEBUG, std::panic::Location::caller().file());
+            $logger.log($message, $crate::Level::DEBUG, std::panic::Location::caller().file(), vec![]);
+        }
+    };
+
+    ($logger:expr, $message:expr, $($argument_name:literal = $argument_value:literal),* $(,)?) => {
+        {
+            let mut arguments: Vec<(&str, String)> = vec![];
+
+            $(
+                arguments.push(($argument_name, $argument_value.to_string()));
+            )*
+
+            $logger.log($message, $crate::Level::DEBUG, std::panic::Location::caller().file(), arguments);
         }
     };
 }
@@ -509,6 +480,7 @@ macro_rules! debug {
 /// # use logging_rs;
 /// # let logger: logging_rs::Logger = logging_rs::Logger::default();
 /// logging_rs::info!(logger, "A message");
+/// logging_rs::info!(logger, "A message with more {{details}}", "details" = "stuff");
 /// ```
 ///
 /// # See also
@@ -523,9 +495,21 @@ macro_rules! debug {
 macro_rules! info {
     ($logger:expr, $message:expr) => {
         {
-            $logger.log($message, $crate::Level::INFO, std::panic::Location::caller().file());
+            $logger.log($message, $crate::Level::INFO, std::panic::Location::caller().file(), vec![]);
         }
     };
+
+    ($logger:expr, $message:expr, $($argument_name:literal = $argument_value:literal),* $(,)?) => {
+        {
+            let mut arguments: Vec<(&str, String)> = vec![];
+
+            $(
+                arguments.push(($argument_name, $argument_value.to_string()));
+            )*
+
+            $logger.log($message, $crate::Level::INFO, std::panic::Location::caller().file(), arguments);
+        }
+    }
 }
 
 /// Logs the given message with logging level [`Level::WARN`].
@@ -541,6 +525,7 @@ macro_rules! info {
 /// # use logging_rs;
 /// # let logger: logging_rs::Logger = logging_rs::Logger::default();
 /// logging_rs::warn!(logger, "A message");
+/// logging_rs::warn!(logger, "A message with more {{details}}", "details" = "stuff");
 /// ```
 ///
 /// # See also
@@ -555,9 +540,21 @@ macro_rules! info {
 macro_rules! warn {
     ($logger:expr, $message:expr) => {
         {
-            $logger.log($message, $crate::Level::WARN, std::panic::Location::caller().file());
+            $logger.log($message, $crate::Level::WARN, std::panic::Location::caller().file(), vec![]);
         }
     };
+
+    ($logger:expr, $message:expr, $($argument_name:literal = $argument_value:literal),* $(,)?) => {
+        {
+            let mut arguments: Vec<(&str, String)> = vec![];
+
+            $(
+                arguments.push(($argument_name, $argument_value.to_string()));
+            )*
+
+            $logger.log($message, $crate::Level::WARN, std::panic::Location::caller().file(), arguments);
+        }
+    }
 }
 
 /// Logs the given message with logging level [`Level::ERROR`].
@@ -573,6 +570,7 @@ macro_rules! warn {
 /// # use logging_rs;
 /// # let logger: logging_rs::Logger = logging_rs::Logger::default();
 /// logging_rs::error!(logger, "A message");
+/// logging_rs::error!(logger, "A message with more {{details}}", "details" = "stuff");
 /// ```
 ///
 /// # See also
@@ -587,9 +585,21 @@ macro_rules! warn {
 macro_rules! error {
     ($logger:expr, $message:expr) => {
         {
-            $logger.log($message, $crate::Level::ERROR, std::panic::Location::caller().file());
+            $logger.log($message, $crate::Level::ERROR, std::panic::Location::caller().file(), vec![]);
         }
     };
+
+    ($logger:expr, $message:expr, $($argument_name:literal = $argument_value:literal),* $(,)?) => {
+        {
+            let mut arguments: Vec<(&str, String)> = vec![];
+
+            $(
+                arguments.push(($argument_name, $argument_value.to_string()));
+            )*
+
+            $logger.log($message, $crate::Level::ERROR, std::panic::Location::caller().file(), arguments);
+        }
+    }
 }
 
 /// Logs the given message with logging level [`Level::FATAL`].
@@ -605,6 +615,7 @@ macro_rules! error {
 /// # use logging_rs;
 /// # let logger: logging_rs::Logger = logging_rs::Logger::default();
 /// logging_rs::fatal!(logger, "A message");
+/// logging_rs::fatal!(logger, "A message with more {{details}}", "details" = "stuff");
 /// ```
 ///
 /// # See also
@@ -619,9 +630,21 @@ macro_rules! error {
 macro_rules! fatal {
     ($logger:expr, $message:expr) => {
         {
-            $logger.log($message, $crate::Level::FATAL, std::panic::Location::caller().file());
+            $logger.log($message, $crate::Level::FATAL, std::panic::Location::caller().file(), vec![]);
         }
     };
+
+    ($logger:expr, $message:expr, $($argument_name:literal = $argument_value:literal),* $(,)?) => {
+        {
+            let mut arguments: Vec<(&str, String)> = vec![];
+
+            $(
+                arguments.push(($argument_name, $argument_value.to_string()));
+            )*
+
+            $logger.log($message, $crate::Level::FATAL, std::panic::Location::caller().file(), arguments);
+        }
+    }
 }
 
 /// Logs the given message with logging level [`Level::MESSAGE`].
@@ -637,6 +660,7 @@ macro_rules! fatal {
 /// # use logging_rs;
 /// # let logger: logging_rs::Logger = logging_rs::Logger::default();
 /// logging_rs::log!(logger, "A message");
+/// logging_rs::log!(logger, "A message with more {{details}}", "details" = "stuff");
 /// ```
 ///
 /// # See also
@@ -651,7 +675,19 @@ macro_rules! fatal {
 macro_rules! log {
     ($logger:expr, $message:expr) => {
         {
-            $logger.log($message, $crate::Level::MESSAGE, std::panic::Location::caller().file());
+            $logger.log($message, $crate::Level::MESSAGE, std::panic::Location::caller().file(), vec![]);
         }
     };
+
+    ($logger:expr, $message:expr, $($argument_name:literal = $argument_value:literal),* $(,)?) => {
+        {
+            let mut arguments: Vec<(&str, String)> = vec![];
+
+            $(
+                arguments.push(($argument_name, $argument_value.to_string()));
+            )*
+
+            $logger.log($message, $crate::Level::MESSAGE, std::panic::Location::caller().file(), arguments);
+        }
+    }
 }

tests/errors.rs

@@ -1,5 +1,5 @@
 // logging-rs error tests
-// Version: 1.0.0
+// Version: 1.1.0
 
 // Copyright (c) 2023-present ElBe Development.
 

tests/lib.rs

@@ -1,5 +1,5 @@
 // logging-rs tests
-// Version: 1.0.0
+// Version: 1.1.0
 
 // Copyright (c) 2023-present ElBe Development.
 
@@ -25,6 +25,8 @@
 // IMPORTS AND USE STATEMENTS //
 ////////////////////////////////
 
+#[allow(unused_imports)]
+use chrono;
 #[allow(unused_imports)]
 use logging_rs;
 
@@ -85,7 +87,7 @@ mod tests {
 
         assert_eq!(
             formatter.format(logging_rs::Output::default(), logging_rs::Level::default(), "Test", vec![]),
-            "[\x1b[94mTIMESTAMP\x1b[0m] [DEBUG] {{path}}: Test"
+            format!("[\x1b[94m{}\x1b[0m] [DEBUG] {{{{path}}}}: Test", chrono::Local::now().format(&logging_rs::Formatter::default().timestamp_format))
         );
     }