docs(builder): Provide styling examples

clap-rs · Jul 17, 2023 · 31d4fd9 · 31d4fd9
1 parent e31768b
commit 31d4fd9
Show file tree

Hide file tree

Showing 3 changed files with 33 additions and 3 deletions.
diff --git a/clap_builder/src/builder/command.rs b/clap_builder/src/builder/command.rs
@@ -1111,9 +1111,14 @@ impl Command {
     ///
     /// ```no_run
     /// # use clap_builder as clap;
-    /// # use clap::{Command, ColorChoice, builder::Styles};
+    /// # use clap::{Command, ColorChoice, builder::styling};
+    /// let styles = styling::Styles::styled()
+    ///     .header(styling::AnsiColor::Green.on_default() | styling::Effects::BOLD)
+    ///     .usage(styling::AnsiColor::Green.on_default() | styling::Effects::BOLD)
+    ///     .literal(styling::AnsiColor::Blue.on_default() | styling::Effects::BOLD)
+    ///     .placeholder(styling::AnsiColor::Cyan.on_default());
     /// Command::new("myprog")
-    ///     .styles(Styles::styled().usage(Default::default()))
+    ///     .styles(styles)
     ///     .get_matches();
     /// ```
     #[cfg(feature = "color")]

diff --git a/clap_builder/src/builder/styling.rs b/clap_builder/src/builder/styling.rs
@@ -5,6 +5,21 @@ pub use anstyle::*;
 /// Terminal styling definitions
 ///
 /// See also [`Command::styles`][crate::Command::styles].
+///
+/// # Example
+///
+/// clap v3 styling
+/// ```rust
+/// # #[cfg(feature = "unstable-styles")] {
+/// # use clap_builder as clap;
+/// # use clap::builder::styling::*;
+/// let styles = Styles::styled()
+///     .header(AnsiColor::Yellow.on_default())
+///     .usage(AnsiColor::Green.on_default())
+///     .literal(AnsiColor::Green.on_default())
+///     .placeholder(AnsiColor::Green.on_default());
+/// # }
+/// ```
 #[derive(Clone, Debug)]
 #[allow(missing_copy_implementations)] // Large enough type that I want an explicit `clone()` for now
 pub struct Styles {

diff --git a/src/bin/stdio-fixture.rs b/src/bin/stdio-fixture.rs
@@ -1,5 +1,5 @@
 fn main() {
-    let cmd = clap::Command::new("stdio-fixture")
+    let mut cmd = clap::Command::new("stdio-fixture")
         .version("1.0")
         .long_version("1.0 - a2132c")
         .arg_required_else_help(true)
@@ -11,5 +11,15 @@ fn main() {
                 .action(clap::ArgAction::SetTrue)
                 .long_help("more log"),
         );
+    #[cfg(feature = "unstable-styles")]
+    {
+        use clap::builder::styling;
+        let styles = styling::Styles::styled()
+            .header(styling::AnsiColor::Green.on_default() | styling::Effects::BOLD)
+            .usage(styling::AnsiColor::Green.on_default() | styling::Effects::BOLD)
+            .literal(styling::AnsiColor::Blue.on_default() | styling::Effects::BOLD)
+            .placeholder(styling::AnsiColor::Cyan.on_default());
+        cmd = cmd.styles(styles);
+    }
     cmd.get_matches();
 }