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    /// <div class="warning">
10    ///
11    /// **NOTE:** This is the default behavior of `clap`.
12    ///
13    /// </div>
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    /// # Examples
31    ///
32    /// ```rust
33    /// # #[cfg(feature = "color")] {
34    /// # use clap_builder as clap;
35    /// # use clap::{Command, ColorChoice};
36    /// Command::new("myprog")
37    ///     .color(ColorChoice::Always)
38    ///     .get_matches();
39    /// # }
40    /// ```
41    Always,
42
43    /// Disables colored output no matter if the output is going to a terminal/TTY, or not.
44    ///
45    /// # Examples
46    ///
47    /// ```rust
48    /// # #[cfg(feature = "color")] {
49    /// # use clap_builder as clap;
50    /// # use clap::{Command, ColorChoice};
51    /// Command::new("myprog")
52    ///     .color(ColorChoice::Never)
53    ///     .get_matches();
54    /// # }
55    /// ```
56    Never,
57}
58
59impl ColorChoice {
60    /// Report all `possible_values`
61    pub fn possible_values() -> impl Iterator<Item = PossibleValue> {
62        Self::value_variants()
63            .iter()
64            .filter_map(ValueEnum::to_possible_value)
65    }
66}
67
68impl Default for ColorChoice {
69    fn default() -> Self {
70        Self::Auto
71    }
72}
73
74impl std::fmt::Display for ColorChoice {
75    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
76        self.to_possible_value()
77            .expect("no values are skipped")
78            .get_name()
79            .fmt(f)
80    }
81}
82
83impl std::str::FromStr for ColorChoice {
84    type Err = String;
85
86    fn from_str(s: &str) -> Result<Self, Self::Err> {
87        for variant in Self::value_variants() {
88            if variant.to_possible_value().unwrap().matches(s, false) {
89                return Ok(*variant);
90            }
91        }
92        Err(format!("invalid variant: {s}"))
93    }
94}
95
96impl ValueEnum for ColorChoice {
97    fn value_variants<'a>() -> &'a [Self] {
98        &[Self::Auto, Self::Always, Self::Never]
99    }
100
101    fn to_possible_value(&self) -> Option<PossibleValue> {
102        Some(match self {
103            Self::Auto => PossibleValue::new("auto"),
104            Self::Always => PossibleValue::new("always"),
105            Self::Never => PossibleValue::new("never"),
106        })
107    }
108}
clap_builder/util/color.rs

clap_builder/util/
color.rs
