feat: min_usage_version (#166)

cli/Cargo.toml

@@ -42,7 +42,7 @@ serde = { version = "1", features = ["derive"] }
 serde_json = "1.0"
 strum = { version = "0.26", features = ["derive"] }
 tera = "1"
-thiserror = "1"
+thiserror = "2"
 usage-lib = { workspace = true, features = ["clap", "docs"] }
 xx = "1"
 

docs/spec/reference/index.md

@@ -6,6 +6,7 @@ bin "mycli"          # the name of the binary
 version "1.0.0"      # the version of the CLI
 author "nobody"      # the author of the CLI
 license "MIT"        # SPDX license the CLI is released under
+min_usage_version "1.0.0" # the minimum version of usage this CLI supports
 
 # help for -h
 before_help "before about"

examples/example.sh

@@ -5,7 +5,8 @@
 #USAGE flag "--bar <bar>" help="Option value"
 #USAGE flag "--defaulted <defaulted>" default="mydefault" help="Defaulted value"
 #USAGE arg "baz" help="Positional values"
-set -euo pipefail
+#USAGE min_usage_version "1"
+set -eo pipefail
 
 echo foo: $usage_foo
 echo bar: $usage_bar

lib/Cargo.toml

@@ -29,12 +29,13 @@ kdl = "4"
 log = "0.4"
 miette = "5"
 once_cell = "1"
+regex = "1"
 serde = { version = "1", features = ["derive"] }
 strum = { version = "0.26", features = ["derive"] }
 tera = { version = "1", optional = true }
-thiserror = "1"
+thiserror = "2"
+versions = "6"
 xx = "1"
-regex = "1"
 
 [features]
 default = ["docs"]

lib/src/spec/mod.rs

@@ -11,7 +11,7 @@ pub mod mount;
 
 use indexmap::IndexMap;
 use kdl::{KdlDocument, KdlEntry, KdlNode, KdlValue};
-use log::info;
+use log::{info, warn};
 use serde::Serialize;
 use std::fmt::{Display, Formatter};
 use std::iter::once;
@@ -42,6 +42,7 @@ pub struct Spec {
     pub about_long: Option<String>,
     pub about_md: Option<String>,
     pub disable_help: Option<bool>,
+    pub min_usage_version: Option<String>,
 }
 
 impl Spec {
@@ -121,6 +122,11 @@ impl Spec {
                     schema.complete.insert(complete.name.clone(), complete);
                 }
                 "disable_help" => schema.disable_help = Some(node.arg(0)?.ensure_bool()?),
+                "min_usage_version" => {
+                    let v = node.arg(0)?.ensure_string()?;
+                    check_usage_version(&v);
+                    schema.min_usage_version = Some(v);
+                }
                 "include" => {
                     let file = node
                         .props()
@@ -186,10 +192,29 @@ impl Spec {
         if other.disable_help.is_some() {
             self.disable_help = other.disable_help;
         }
+        if other.min_usage_version.is_some() {
+            self.min_usage_version = other.min_usage_version;
+        }
         self.cmd.merge(other.cmd);
     }
 }
 
+fn check_usage_version(version: &str) {
+    let cur = versions::Versioning::new(env!("CARGO_PKG_VERSION")).unwrap();
+    match versions::Versioning::new(version) {
+        Some(v) => {
+            if cur < v {
+                warn!(
+                    "This usage spec requires at least version {}, but you are using version {} of usage",
+                    version,
+                    cur
+                );
+            }
+        }
+        _ => warn!("Invalid version: {}", version),
+    }
+}
+
 fn split_script(file: &Path) -> Result<(String, String), UsageErr> {
     let full = file::read_to_string(file)?;
     if full.starts_with("#!")
@@ -293,6 +318,11 @@ impl Display for Spec {
             node.push(KdlEntry::new(disable_help));
             nodes.push(node);
         }
+        if let Some(min_usage_version) = &self.min_usage_version {
+            let mut node = KdlNode::new("min_usage_version");
+            node.push(KdlEntry::new(min_usage_version.clone()));
+            nodes.push(node);
+        }
         if !self.usage.is_empty() {
             let mut node = KdlNode::new("usage");
             node.push(KdlEntry::new(self.usage.clone()));