support clap help message

Cargo.toml

@@ -1,8 +1,8 @@
 [package]
 name = "hyperparameter"
-version = "0.5.8"
+version = "0.5.9"
 license = "Apache-2.0"
-description = " Hyperparameter, Make configurable AI applications.Build for Python hackers. "
+description = "A high performance configuration system for Rust and Python."
 homepage = "https://reiase.github.io/hyperparameter/"
 readme = "README.md"
 repository = "https://github.com/reiase/hyperparameter"
@@ -16,10 +16,11 @@ exclude = [
 ]
 
 [features]
-default = ["json", "toml", "ini"]
+default = ["json", "toml", "ini", "clap"]
 json = ["config/json"]
 toml = ["config/toml"]
 ini = ["config/ini"]
+clap = ["dep:linkme", "dep:clap"]
 
 [lib]
 name = "hyperparameter"
@@ -33,9 +34,9 @@ signal-hook = "0.3.17"
 tokio = { version = "1.31.0", features = ["full"] }
 xxhash-rust = { version = "0.8.7", features = ["xxh3", "xxh64", "const_xxh64"] }
 const-str = "0.5.6"
-nu-ansi-term = "0.49.0"
-local-ip-address = "0.5.6"
-config = "0.13.3"
+config = "0.14.0"
+linkme = {version = "0.3", optional = true}
+clap = {version = "4.4.7", optional = true}
 
 [dev-dependencies]
 proptest = "1.2.0"

examples/clap_app.rs

@@ -2,7 +2,6 @@ use clap::Parser;
 use hyperparameter::*;
 
 fn foo() {
-    println!("in function foo");
     with_params! {
         get param1 = example.param1 or 1; // read param `example.param1` or use default value `1`
         get param2 = example.param2 or String::from("2"); // read param `example.param2` or use default value `2`
@@ -11,16 +10,15 @@ fn foo() {
         println!("param1={}", param1);
         println!("param2={}", param2);
         println!("param3={}", param3);
+        println!("param4={}", get_param!(param4, 1, "help message for param4")); // leave a help msg when reading params
+        println!("param4={}", get_param!(param4, 1, "another help for param4")); // leave another help msg
     }
 }
 
-fn bar() {
-    println!("in function bar");
-    foo()
-}
-
 #[derive(Parser, Debug)]
+#[command(after_long_help=generate_params_help())]
 struct DeriveArgs {
+    /// define hyperparameters
     #[arg(short = 'D', long)]
     define: Vec<String>,
 }
@@ -30,6 +28,6 @@ fn main() {
     with_params! {
         params ParamScope::from(&args.define);
 
-        bar()
+        foo()
     }
 }

src/api.rs

@@ -172,6 +172,20 @@ macro_rules! get_param {
         THREAD_STORAGE.with(|ts| ts.borrow_mut().get_or_else(CONST_HASH, $default))
         // ParamScope::default().get_or_else(CONST_HASH, $default)
     }};
+
+    ($name:expr, $default:expr, $help: expr) => {{
+        const CONST_KEY: &str = const_str::replace!(stringify!($name), ";", "");
+        const CONST_HASH: u64 = xxhash_rust::const_xxh64::xxh64(CONST_KEY.as_bytes(), 42);
+        // ParamScope::default().get_or_else(CONST_HASH, $default)
+        {
+            const CONST_HELP: &str = $help;
+            #[::linkme::distributed_slice(PARAMS)]
+            static help: (&str, &str) = (
+                CONST_KEY, CONST_HELP
+            );
+        }
+        THREAD_STORAGE.with(|ts| ts.borrow_mut().get_or_else(CONST_HASH, $default))
+    }};
 }
 
 /// Define or use `hyperparameters` in a code block.

src/cli.rs

@@ -0,0 +1,48 @@
+use std::collections::{HashMap, HashSet};
+
+use clap::builder::Styles;
+
+#[::linkme::distributed_slice]
+pub static PARAMS: [(&str, &str)];
+
+pub fn generate_params_help() -> String {
+    let mut params: HashMap<String, HashSet<String>> = HashMap::default();
+    for kv in PARAMS {
+        params
+            .entry(kv.0.to_string())
+            .and_modify(|s| {
+                s.insert(kv.1.to_string());
+            })
+            .or_insert(HashSet::from([kv.1.to_string()]));
+    }
+    let mut params: Vec<_> = params
+        .iter()
+        .map(|kv| {
+            let mut descs = Vec::from_iter(kv.1.iter().map(|x| x.clone()));
+            descs.sort();
+            (kv.0.clone(), descs.join("\n\t"))
+        })
+        .collect();
+    params.sort_by_key(|x| x.0.clone());
+
+    let styles = Styles::default();
+    let header = styles.get_header();
+    let literal = styles.get_literal();
+    format!(
+        "{}Hyperparameters:{}\n",
+        header.render(),
+        header.render_reset()
+    ) + &params
+        .iter()
+        .map(|kv| {
+            format!(
+                "  {}{}{}\n\t{}",
+                literal.render(),
+                kv.0,
+                literal.render_reset(),
+                kv.1
+            )
+        })
+        .collect::<Vec<String>>()
+        .join("\n\n")
+}

src/lib.rs

@@ -21,3 +21,9 @@ pub mod api;
 pub mod cfg;
 pub mod ffi;
 pub mod xxh;
+
+// #[cfg(clap)]
+pub mod cli;
+// #[cfg(clap)]
+pub use crate::cli::PARAMS;
+pub use crate::cli::generate_params_help;

tests/test_cli.rs

@@ -0,0 +1,16 @@
+use hyperparameter::PARAMS;
+use linkme::distributed_slice;
+
+#[test]
+fn test_cli() {
+    #[distributed_slice(PARAMS)]
+    static param1: (&str, &str) = (
+        "key1", "val1"
+    );
+
+    assert!(PARAMS.len()==1);
+
+    for kv in PARAMS {
+        println!("{} => {}", kv.0, kv.1);
+    }
+}