Merge pull request #5638 from epage/cargo

docs(cookbook): Style cargo plugin

Cargo.lock

@@ -413,6 +413,7 @@ name = "clap"
 version = "4.5.13"
 dependencies = [
  "automod",
+ "clap-cargo",
  "clap_builder 4.5.13",
  "clap_derive",
  "humantime",
@@ -423,6 +424,15 @@ dependencies = [
  "trycmd",
 ]
 
+[[package]]
+name = "clap-cargo"
+version = "0.14.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23b2ea69cefa96b848b73ad516ad1d59a195cdf9263087d977f648a818c8b43e"
+dependencies = [
+ "anstyle",
+]
+
 [[package]]
 name = "clap_bench"
 version = "0.0.0"

Cargo.toml

@@ -187,6 +187,7 @@ humantime = "2.1.0"
 snapbox = "0.6.16"
 shlex = "1.3.0"
 automod = "1.0.14"
+clap-cargo = { version = "0.14.1", default-features = false }
 
 [[example]]
 name = "demo"
@@ -194,11 +195,11 @@ required-features = ["derive"]
 
 [[example]]
 name = "cargo-example"
-required-features = ["cargo"]
+required-features = ["cargo", "color"]
 
 [[example]]
 name = "cargo-example-derive"
-required-features = ["derive"]
+required-features = ["derive", "color"]
 
 [[example]]
 name = "escaped-positional"

examples/cargo-example-derive.rs

@@ -3,10 +3,21 @@ use clap::Parser;
 #[derive(Parser)] // requires `derive` feature
 #[command(name = "cargo")]
 #[command(bin_name = "cargo")]
+#[command(styles = CLAP_STYLING)]
 enum CargoCli {
     ExampleDerive(ExampleDeriveArgs),
 }
 
+// See also `clap_cargo::style::CLAP_STYLING`
+pub const CLAP_STYLING: clap::builder::styling::Styles = clap::builder::styling::Styles::styled()
+    .header(clap_cargo::style::HEADER)
+    .usage(clap_cargo::style::USAGE)
+    .literal(clap_cargo::style::LITERAL)
+    .placeholder(clap_cargo::style::PLACEHOLDER)
+    .error(clap_cargo::style::ERROR)
+    .valid(clap_cargo::style::VALID)
+    .invalid(clap_cargo::style::INVALID);
+
 #[derive(clap::Args)]
 #[command(version, about, long_about = None)]
 struct ExampleDeriveArgs {

examples/cargo-example.rs

@@ -1,6 +1,7 @@
 fn main() {
     let cmd = clap::Command::new("cargo")
         .bin_name("cargo")
+        .styles(CLAP_STYLING)
         .subcommand_required(true)
         .subcommand(
             clap::command!("example").arg(
@@ -16,3 +17,13 @@ fn main() {
     let manifest_path = matches.get_one::<std::path::PathBuf>("manifest-path");
     println!("{manifest_path:?}");
 }
+
+// See also `clap_cargo::style::CLAP_STYLING`
+pub const CLAP_STYLING: clap::builder::styling::Styles = clap::builder::styling::Styles::styled()
+    .header(clap_cargo::style::HEADER)
+    .usage(clap_cargo::style::USAGE)
+    .literal(clap_cargo::style::LITERAL)
+    .placeholder(clap_cargo::style::PLACEHOLDER)
+    .error(clap_cargo::style::ERROR)
+    .valid(clap_cargo::style::VALID)
+    .invalid(clap_cargo::style::INVALID);

src/_cookbook/mod.rs

@@ -15,6 +15,7 @@
 //! - Topics:
 //!   - Subcommands
 //!   - Cargo plugins
+//!   - custom terminal [styles][crate::Command::styles] (colors)
 //!
 //! find-like interface: [builder][find]
 //! - Topics: