feat(cli::args): VerbosityLevel

VerbosityLevel lets you easily get a loglevel from repeated -v and -q
flags. Documentation included.

Refs: #84

members/libpt-cli/Cargo.toml

@@ -14,7 +14,7 @@ categories.workspace = true
 
 [features]
 default = ["log"]
-log = ["dep:libpt-log"]
+log = ["dep:libpt-log", "dep:log"]
 
 [dependencies]
 anyhow.workspace = true
@@ -24,3 +24,4 @@ console = "0.15.8"
 dialoguer = "0.11.0"
 indicatif = "0.17.8"
 libpt-log = { workspace = true, optional = true }
+log = { version = "0.4.21", optional = true }

members/libpt-cli/src/args.rs

@@ -1,5 +1,10 @@
+//! Utilities for parsing options and arguments on the start of a CLI application
+
 use clap::Parser;
+#[cfg(feature = "log")]
 use libpt_log::Level;
+#[cfg(feature = "log")]
+use log;
 
 /// Custom help template for displaying command-line usage information
 ///
@@ -50,17 +55,52 @@ pub const HELP_TEMPLATE: &str = r#"{about-section}
 Author: {author-with-newline}
 "#;
 
-#[derive(Parser, Debug, Clone, PartialEq, Eq, Hash)]
+/// Transform -v and -q flags to some kind of loglevel
-#[command(help_template = HELP_TEMPLATE)]
-pub struct DefaultArguments {
-    /// get a [tracing] log level
 ///
-    /// set the verbosity with repeated '-q' and '-v' flags
+/// # Example
-    #[command(flatten)]
+///
-    verbose: VerbosityLevel,
+/// Include this into your [clap] derive struct like this:
-}
+///
-
+/// ```
+/// use libpt_cli::args::VerbosityLevel;
+/// use clap::Parser;
+///
+/// #[derive(Parser, Debug)]
+/// pub struct Opts {
+///     #[command(flatten)]
+///     pub verbose: VerbosityLevel,
+///     #[arg(short, long)]
+///     pub mynum: usize,
+/// }
+///
+/// ```
+///
+/// Get the loglevel like this:
+///
+/// ```no_run
+/// # use libpt_cli::args::VerbosityLevel;
+/// use libpt_log::Level;
+/// # use clap::Parser;
+/// use log;
+///
+/// # #[derive(Parser, Debug)]
+/// # pub struct Opts {
+/// #     #[command(flatten)]
+/// #     pub verbose: VerbosityLevel,
+/// # }
+///
+/// fn main() {
+///     let opts = Opts::parse();
+///
+///     // Level might be None if the user wants no output at all.
+///     // for the 'tracing' level:
+///     let level: Option<Level> = opts.verbose.level();
+///     // for the 'log' level:
+///     let llevel: Option<log::Level> = opts.verbose.level_for_log_crate();
+/// }
+/// ```
 #[derive(Parser, Clone, PartialEq, Eq, Hash)]
+#[cfg(feature = "log")]
 pub struct VerbosityLevel {
     /// make the output more verbose
     #[arg(
@@ -116,6 +156,23 @@ impl VerbosityLevel {
             _ => return None,
         })
     }
+
+    /// get the [log::Level] for that VerbosityLevel
+    ///
+    /// This is the method for the [log] crate, which I use less often.
+    ///
+    /// [None] means that absolutely no output is wanted (completely quiet)
+    #[inline]
+    pub fn level_for_log_crate(&self) -> Option<log::Level> {
+        self.level().map(|ll| match ll {
+            Level::TRACE => log::Level::Trace,
+            Level::DEBUG => log::Level::Debug,
+            Level::INFO => log::Level::Info,
+            Level::WARN => log::Level::Warn,
+            Level::ERROR => log::Level::Error,
+        })
+    }
+
     #[inline]
     fn level_value(level: Level) -> i8 {
         match level {
@@ -129,6 +186,7 @@ impl VerbosityLevel {
 }
 
 impl std::fmt::Debug for VerbosityLevel {
+    #[inline]
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         write!(f, "{:?}", self.level())
     }

members/libpt-cli/src/printing.rs

@@ -1,4 +1,4 @@
-//! Utilities for formatting, bordering, aligning and printing text content.
+//! Utilities for formatting, bordering, aligning and printing text content
 //!
 //! This module provides functions for formatting content with borders and colors, printing them to the console.
 //! The functions in this module are designed to simplify the process of creating visually appealing