clap_builder/util/
color.rs

1use crate::builder::PossibleValue;
2use crate::derive::ValueEnum;
3
4/// Represents the color preferences for program output
5#[derive(Debug, Copy, Clone, Eq, PartialEq)]
6pub enum ColorChoice {
7    /// Enables colored output only when the output is going to a terminal or TTY.
8    ///
9    /// **NOTE:** This is the default behavior of `clap`.
10    ///
11    /// # Platform Specific
12    ///
13    /// This setting only applies to Unix, Linux, and macOS (i.e. non-Windows platforms).
14    ///
15    /// # Examples
16    ///
17    /// ```rust
18    /// # #[cfg(feature = "color")] {
19    /// # use clap_builder as clap;
20    /// # use clap::{Command, ColorChoice};
21    /// Command::new("myprog")
22    ///     .color(ColorChoice::Auto)
23    ///     .get_matches();
24    /// # }
25    /// ```
26    Auto,
27
28    /// Enables colored output regardless of whether or not the output is going to a terminal/TTY.
29    ///
30    /// # Platform Specific
31    ///
32    /// This setting only applies to Unix, Linux, and macOS (i.e. non-Windows platforms).
33    ///
34    /// # Examples
35    ///
36    /// ```rust
37    /// # #[cfg(feature = "color")] {
38    /// # use clap_builder as clap;
39    /// # use clap::{Command, ColorChoice};
40    /// Command::new("myprog")
41    ///     .color(ColorChoice::Always)
42    ///     .get_matches();
43    /// # }
44    /// ```
45    Always,
46
47    /// Disables colored output no matter if the output is going to a terminal/TTY, or not.
48    ///
49    /// # Platform Specific
50    ///
51    /// This setting only applies to Unix, Linux, and macOS (i.e. non-Windows platforms)
52    ///
53    /// # Examples
54    ///
55    /// ```rust
56    /// # #[cfg(feature = "color")] {
57    /// # use clap_builder as clap;
58    /// # use clap::{Command, ColorChoice};
59    /// Command::new("myprog")
60    ///     .color(ColorChoice::Never)
61    ///     .get_matches();
62    /// # }
63    /// ```
64    Never,
65}
66
67impl ColorChoice {
68    /// Report all `possible_values`
69    pub fn possible_values() -> impl Iterator<Item = PossibleValue> {
70        Self::value_variants()
71            .iter()
72            .filter_map(ValueEnum::to_possible_value)
73    }
74}
75
76impl Default for ColorChoice {
77    fn default() -> Self {
78        Self::Auto
79    }
80}
81
82impl std::fmt::Display for ColorChoice {
83    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
84        self.to_possible_value()
85            .expect("no values are skipped")
86            .get_name()
87            .fmt(f)
88    }
89}
90
91impl std::str::FromStr for ColorChoice {
92    type Err = String;
93
94    fn from_str(s: &str) -> Result<Self, Self::Err> {
95        for variant in Self::value_variants() {
96            if variant.to_possible_value().unwrap().matches(s, false) {
97                return Ok(*variant);
98            }
99        }
100        Err(format!("invalid variant: {s}"))
101    }
102}
103
104impl ValueEnum for ColorChoice {
105    fn value_variants<'a>() -> &'a [Self] {
106        &[Self::Auto, Self::Always, Self::Never]
107    }
108
109    fn to_possible_value(&self) -> Option<PossibleValue> {
110        Some(match self {
111            Self::Auto => PossibleValue::new("auto"),
112            Self::Always => PossibleValue::new("always"),
113            Self::Never => PossibleValue::new("never"),
114        })
115    }
116}
clap_builder/util/color.rs

clap_builder/util/
color.rs
