From 631e54bc715ed2fa53d8457dc273a25b92d3b354 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Thu, 8 Aug 2024 10:31:27 -0500
Subject: [PATCH] docs(cookbook): Style cargo plugin

Inspired by part of the conversation at #3234
---
 Cargo.lock                       | 12 +++++++++++-
 Cargo.toml                       |  5 +++--
 examples/cargo-example-derive.rs | 11 +++++++++++
 examples/cargo-example.rs        | 11 +++++++++++
 src/_cookbook/mod.rs             |  1 +
 5 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index a04c3626a48..23fcfc4c0dc 100644
--- a/Cargo.lock
+++ b/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"
@@ -1432,7 +1442,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e310b3a6b5907f99202fcdb4960ff45b93735d7c7d96b760fcff8db2dc0e103d"
 dependencies = [
  "cfg-if",
- "windows-targets 0.48.5",
+ "windows-targets 0.52.6",
 ]
 
 [[package]]
diff --git a/Cargo.toml b/Cargo.toml
index d8706089b66..3d69c8a2daf 100644
--- a/Cargo.toml
+++ b/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"
diff --git a/examples/cargo-example-derive.rs b/examples/cargo-example-derive.rs
index f9105ea2f81..80ad93fac8f 100644
--- a/examples/cargo-example-derive.rs
+++ b/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 {
diff --git a/examples/cargo-example.rs b/examples/cargo-example.rs
index 11733651440..ecf74e58480 100644
--- a/examples/cargo-example.rs
+++ b/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);
diff --git a/src/_cookbook/mod.rs b/src/_cookbook/mod.rs
index 9753d37a059..364e43b1195 100644
--- a/src/_cookbook/mod.rs
+++ b/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: