1 use crate::builder::PossibleValue;
2 use crate::derive::ValueEnum;
3 
4 /// Represents the color preferences for program output
5 #[derive(Debug, Copy, Clone, Eq, PartialEq)]
6 pub 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 
67 impl ColorChoice {
68     /// Report all `possible_values`
possible_values() -> impl Iterator<Item = PossibleValue>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 
76 impl Default for ColorChoice {
default() -> Self77     fn default() -> Self {
78         Self::Auto
79     }
80 }
81 
82 impl std::fmt::Display for ColorChoice {
fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result83     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 
91 impl std::str::FromStr for ColorChoice {
92     type Err = String;
93 
from_str(s: &str) -> Result<Self, Self::Err>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 
104 impl ValueEnum for ColorChoice {
value_variants<'a>() -> &'a [Self]105     fn value_variants<'a>() -> &'a [Self] {
106         &[Self::Auto, Self::Always, Self::Never]
107     }
108 
to_possible_value(&self) -> Option<PossibleValue>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 }
117