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}
117