Merge pull request #4236 from epage/usage

feat: Allow turning off error-context, auto-help, and auto-usage

CHANGELOG.md

@@ -268,6 +268,7 @@ Behavior Changes
 - Allow resetting most builder methods
 - Can now pass runtime generated data to `Command`, `Arg`, `ArgGroup`, `PossibleValue`, etc without managing lifetimes with the `string` feature flag (#2150, #4223)
 - *(error)* `Error::apply` for changing the formatter for dropping binary size (#4111)
+- *(error)* New default `error-context` feature flag that can be turned off for smaller binaries
 - *(help)* Show `PossibleValue::help` in long help (`--help`) (#3312)
 - *(help)* New `{tab}` variable for `Command::help_template` (#4161)
 

Cargo.toml

@@ -57,6 +57,9 @@ pre-release-replacements = [
 default = [
   "std",
   "color",
+  "help",
+  "usage",
+  "error-context",
   "suggestions",
 ]
 debug = ["clap_derive/debug", "dep:backtrace"] # Enables debug messages
@@ -65,7 +68,10 @@ unstable-doc = ["derive", "cargo", "wrap_help", "env", "unicode", "string", "uns
 # Used in default
 std = [] # support for no_std in a backwards-compatible way
 color = ["dep:atty", "dep:termcolor"]
-suggestions = ["dep:strsim"]
+help = []
+usage = []
+error-context = []
+suggestions = ["dep:strsim", "error-context"]
 
 # Optional
 deprecated = ["clap_derive?/deprecated"] # Guided experience to prepare for next breaking release (at different stages of development, this may become default)
@@ -151,6 +157,7 @@ path = "examples/multicall-hostname.rs"
 [[example]]
 name = "repl"
 path = "examples/repl.rs"
+required-features = ["help"]
 
 [[example]]
 name = "01_quick"

clap_bench/Cargo.toml

@@ -11,7 +11,7 @@ publish = false
 release = false
 
 [dev-dependencies]
-clap = { path = "../", version = "4.0.0-alpha.0", default-features = false, features = ["std"] }
+clap = { path = "../", version = "4.0.0-alpha.0", default-features = false, features = ["std", "help"] }
 criterion = "0.3.2"
 lazy_static = "1"
 

clap_complete/Cargo.toml

@@ -52,7 +52,7 @@ unicode-xid = { version = "0.2.2", optional = true }
 snapbox = { version = "0.3", features = ["diff"] }
 # Cutting out `filesystem` feature
 trycmd = { version = "0.13", default-features = false, features = ["color-auto", "diff", "examples"] }
-clap = { path = "../", version = "4.0.0-alpha.0", default-features = false, features = ["std", "derive"] }
+clap = { path = "../", version = "4.0.0-alpha.0", default-features = false, features = ["std", "derive", "help"] }
 
 [[example]]
 name = "dynamic"

clap_complete_fig/Cargo.toml

@@ -44,3 +44,4 @@ clap_complete = { path = "../clap_complete", version = "4.0.0-alpha.0" }
 
 [dev-dependencies]
 snapbox = { version = "0.3", features = ["diff"] }
+clap = { path = "../", version = "4.0.0-alpha.0", default-features = false, features = ["std", "help"] }

clap_mangen/Cargo.toml

@@ -45,7 +45,7 @@ clap = { path = "../", version = "4.0.0-alpha.0", default-features = false, feat
 
 [dev-dependencies]
 snapbox = { version = "0.3", features = ["diff"] }
-clap = { path = "../", version = "4.0.0-alpha.0", default-features = false, features = ["std"] }
+clap = { path = "../", version = "4.0.0-alpha.0", default-features = false, features = ["std", "help"] }
 
 [features]
 default = []

src/_features.rs

@@ -6,6 +6,9 @@
 //!
 //! * **std**: _Not Currently Used._ Placeholder for supporting `no_std` environments in a backwards compatible manner.
 //! * **color**: Turns on colored error messages.
+//! * **help**: Auto-generate help output
+//! * **usage**: Auto-generate usage
+//! * **error-context**: Include contextual information for errors (which arg failed, etc)
 //! * **suggestions**: Turns on the `Did you mean '--myoption'?` feature for when users make typos.
 //!
 //! #### Optional features

src/builder/action.rs

@@ -2,7 +2,8 @@
 ///
 /// # Examples
 ///
-/// ```rust
+#[cfg_attr(not(feature = "help"), doc = " ```ignore")]
+#[cfg_attr(feature = "help", doc = " ```")]
 /// # use clap::Command;
 /// # use clap::Arg;
 /// let cmd = Command::new("mycmd")
@@ -211,7 +212,8 @@ pub enum ArgAction {
     ///
     /// # Examples
     ///
-    /// ```rust
+    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
+    #[cfg_attr(feature = "help", doc = " ```")]
     /// # use clap::Command;
     /// # use clap::Arg;
     /// let cmd = Command::new("mycmd")

src/builder/arg.rs

@@ -1107,7 +1107,8 @@ impl Arg {
     /// # ;
     /// ```
     ///
-    /// ```rust
+    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
+    #[cfg_attr(feature = "help", doc = " ```")]
     /// # use clap::{Command, Arg};
     /// let m = Command::new("prog")
     ///     .arg(Arg::new("config")
@@ -1168,7 +1169,8 @@ impl Arg {
     ///     .value_names(["fast", "slow"]);
     /// ```
     ///
-    /// ```rust
+    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
+    #[cfg_attr(feature = "help", doc = " ```")]
     /// # use clap::{Command, Arg};
     /// let m = Command::new("prog")
     ///     .arg(Arg::new("io")
@@ -1991,7 +1993,8 @@ impl Arg {
     /// Setting `help` displays a short message to the side of the argument when the user passes
     /// `-h` or `--help` (by default).
     ///
-    /// ```rust
+    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
+    #[cfg_attr(feature = "help", doc = " ```")]
     /// # use clap::{Command, Arg};
     /// let m = Command::new("prog")
     ///     .arg(Arg::new("cfg")
@@ -2040,7 +2043,8 @@ impl Arg {
     /// Setting `help` displays a short message to the side of the argument when the user passes
     /// `-h` or `--help` (by default).
     ///
-    /// ```rust
+    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
+    #[cfg_attr(feature = "help", doc = " ```")]
     /// # use clap::{Command, Arg};
     /// let m = Command::new("prog")
     ///     .arg(Arg::new("cfg")
@@ -2096,7 +2100,8 @@ impl Arg {
     ///
     /// # Examples
     ///
-    /// ```rust
+    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
+    #[cfg_attr(feature = "help", doc = " ```")]
     /// # use clap::{Command, Arg, ArgAction};
     /// let m = Command::new("prog")
     ///     .arg(Arg::new("a") // Typically args are grouped alphabetically by name.
@@ -2162,7 +2167,8 @@ impl Arg {
     ///
     /// # Examples
     ///
-    /// ```rust
+    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
+    #[cfg_attr(feature = "help", doc = " ```")]
     /// # use clap::{Command, Arg, ArgAction};
     /// let m = Command::new("prog")
     ///     .arg(Arg::new("opt")
@@ -2212,7 +2218,8 @@ impl Arg {
     ///
     /// Setting `Hidden` will hide the argument when displaying help text
     ///
-    /// ```rust
+    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
+    #[cfg_attr(feature = "help", doc = " ```")]
     /// # use clap::{Command, Arg};
     /// let m = Command::new("prog")
     ///     .arg(Arg::new("cfg")
@@ -2385,7 +2392,8 @@ impl Arg {
     ///
     /// Setting `hide_short_help(true)` will hide the argument when displaying short help text
     ///
-    /// ```rust
+    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
+    #[cfg_attr(feature = "help", doc = " ```")]
     /// # use clap::{Command, Arg};
     /// let m = Command::new("prog")
     ///     .arg(Arg::new("cfg")
@@ -2411,7 +2419,8 @@ impl Arg {
     ///
     /// However, when --help is called
     ///
-    /// ```rust
+    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
+    #[cfg_attr(feature = "help", doc = " ```")]
     /// # use clap::{Command, Arg};
     /// let m = Command::new("prog")
     ///     .arg(Arg::new("cfg")
@@ -2456,7 +2465,8 @@ impl Arg {
     ///
     /// Setting `hide_long_help(true)` will hide the argument when displaying long help text
     ///
-    /// ```rust
+    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
+    #[cfg_attr(feature = "help", doc = " ```")]
     /// # use clap::{Command, Arg};
     /// let m = Command::new("prog")
     ///     .arg(Arg::new("cfg")
@@ -2482,7 +2492,8 @@ impl Arg {
     ///
     /// However, when -h is called
     ///
-    /// ```rust
+    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
+    #[cfg_attr(feature = "help", doc = " ```")]
     /// # use clap::{Command, Arg};
     /// let m = Command::new("prog")
     ///     .arg(Arg::new("cfg")
@@ -4074,10 +4085,6 @@ impl Arg {
         }
     }
 
-    pub(crate) fn longest_filter(&self) -> bool {
-        self.is_takes_value_set() || self.long.is_some() || self.short.is_none()
-    }
-
     // Used for positionals when printing
     pub(crate) fn name_no_brackets(&self) -> String {
         debug!("Arg::name_no_brackets:{}", self.get_id());
@@ -4200,6 +4207,7 @@ impl Arg {
         self.is_multiple_values_set() || matches!(*self.get_action(), ArgAction::Append)
     }
 
+    #[cfg(feature = "help")]
     pub(crate) fn get_display_order(&self) -> usize {
         self.disp_ord.unwrap_or(999)
     }